About 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. 

Also see a related blog posting 

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. As of 8.1.3, this can be done in a container on the GroundWork server itself. 

Installation

If you are running the connector as a standalone Go application, you will need to download and install the connector, and run it. If you want to run it on the GroundWork host as a container, you don't need to download it explicitly, as the container will automatically download when you start it (though you need Internet access from your GroundWork Server to do this). You can also run it as a Linux service on the GroundWork host or another host, your choice.

Running the APM Connector as a Container in GroundWork

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"]
    
    

    and, at the bottom of the file, make sure the volume is enabled globally: 

    volumes:
      tcg-var:

    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
    CODE
    docker-compose up -d
    CODE

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 +ADD 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/metrics

      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. 

  1. 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 you can use the sample app we have provided:

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.

Running the APM Connector as a Linux Service

To run the APM connector as a standalone Go program is fine for experimental purposes, but in production you will want to run it as a Linux service. Here's how to do so on an Ubuntu system:

Requirements

You will need a Linux host that you can connect to on port 8099 from the GroundWork server. It can be the GroundWork server itself, if you like. 

Download the Connector

Assuming you have Internet access from your server, you can download the connector directly to the server where you want to run it. If not, just download it first and then transfer it, and start at step 3 below. 

  1. On the Downloads page, copy the link for the latest version of the APM Connector.
  2. Log in to your Ubuntu system and download the connector, for example: 

    wget https://support8.gwos.com/gw/gw8/files/8.1.3/27729688/27729687/1/1607729558712/apm-connector-8.1.3-GA.tgz
  3. Expand the tar in a directory of your choice:

    tar zxvf apm-connector-8.1.3-GA.tgz

    This will make an "apm" subdirectory. 

  4. Modify the tcg-apm.service file to point to your apm subdirectory, and (at least on Ubuntu) include the Install section as noted below. For example if you expanded it in /home/ubuntu, the file will need to look like this: 

    [Unit]
    Description= TCG APM Service
    Documentation= https://support8.gwos.com/gw/doc/latest/monitoring-methods/application-performance-monitoring
    
    [Service]
    # Configure to match TCG installation
    WorkingDirectory=/home/ubuntu/apm
    Group=docker
    
    # Set environment (path)
    Environment= 'TCG_CONFIG=/home/ubuntu/apm/tcg_config.yml
    
    # TCG up
    ExecStart= /home/ubuntu/apm/apm-connector
    
    # TCG down
    ExecStop=/bin/kill -2 $MAINPID
    
    [Install]
    WantedBy=multi-user.target
  5. Copy the tcg-apm.service file into the systemd directory: 

    sudo cp tcg-apm.service /etc/systemd/system/
    CODE
  6. Enable the service: 

    sudo systemctl enable tcg-apm
    CODE
  7. Start the service: 

    sudo systemctl start tcg-apm
    CODE

Now you can create a connection to this running connector, and configure it as in the Connection section above. Note that the hostname will need to be supplied, and of course you will need to be able to connect to that host on port 8099.

Related Resources