APM Connector

GroundWork Monitor, as of 8.1.2, includes an Application Performance Monitoring (APM) connector you can use to send metrics to GroundWork Monitor directly from your running applications. This article will explain how to enable this connector and get started using it, with examples in Golang. 

Since GroundWork uses the Prometheus client, many other languages can be used in similar ways. 

Requirements

You will need a GroundWork 8.1.2 or above system, an application you can add code to, and a place to run the APM connector. 

Installation

First you will need to download and install the connector, and run it. This can be done on the GroundWork host as a container, or as a Linux service on the GroundWork host or another host, your choice. The simplest way is to add it as a container to the GroundWork host. To do so, follow these steps:

1. Un-comment (or, if you have upgraded, add) the following lines in the gw8/docker-compose.overrides.yml file, after "services:":

     tcg-apm:
       image: groundworkdevelopment/tcg:${TAG}
       volumes:
   
       tcg-var:/tcg
       entrypoint: ["/app/docker_cmd.sh", "apm-connector"]
   
   

   Note the indentation has to line up exactly with the other entries under "services:", as this is a yaml file. If your GroundWork server doesn't have Internet access, please contact GroundWork Support for download options for tcg containers. They are free and open source. 

2.  Restart GroundWork:

   docker-compose down
   docker-compose up -d

Connection

Next, you will add the connector configuration to your GroundWork server. 

1. Login as a user with the Admin role, and browse to Configuration > Connectors.
2. Click the "+" icon to add a connector and choose the APM Connector.

3. Create a connection. You need to specify a display name and location. If you decided to run the connector as a container on the GroundWork host, the location will be: 

   tcg-apm:8099

   This location is controlled in the tcg-config.yaml file in the connector installation.
   
   

   You also need a Resource, which is one or more applications that are publishing data with the Prometheus client on a URL and optionally a specific port. The example application referenced below does this on port 2222. If you run it on the GroundWork host, you can use the address of: 

   http://172.17.0.1:2222

   You need to specify the protocol (http or https), and the location. In this example 172.17/0.1 is the host address from the point of view of the containerized connector. The port is what the application publishes the metrics on. If you don't have an instrumented application up yet, just save the connection and come back to it later, when you know the URL and optional port to point it at. You can add several resources to a single connector (we recommend no more than 4, depending on how many metrics you plan to post).  

   You can also specify an interval for metrics gathering, down to 1 minute. 
4. Save the connection. If all is well, you will see the connection status turn green. If not, you will see an error message and will need to resolve the error before moving on. 

Sending data from an application

You will need to include the Prometheus client library in a Golang program. For example:

import (
  "github.com/prometheus/client_golang/prometheus"
  "github.com/prometheus/client_golang/prometheus/promhttp"

Here is a minimal example of creating a counter metric, only requiring the counter metric name: 

simpleCounter = prometheus.NewCounter(
   prometheus.CounterOpts{
     Name: "request_counter",
  })

For further details, you can see this working with a useable example of a go program that connects to the APM connector, https://github.com/gwos/tcg/tree/master/examples/apm/pull/go.