TCG 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 related blog postings:
fas fa-blog Application Monitoring with the Prometheus Client and GroundWork Monitor

fas fa-blog Application Monitoring with Spring Boot, Prometheus, and GroundWork Monitor

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. 

Setting Up TCG

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 as a Container in GroundWork

The simplest way is to add the APM connector 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.override.yml file, after "services:":

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

   CODE

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

   CODE

Setting Up the Connector

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

1. Sign in to your GroundWork server as an administrative user.

2. Go to Configuration > Connectors.

3. Click the Add fas fa-plus-square icon and select the APM connector from the menu.

4. Enter the following information:

   • Connector Name: Provide a unique display name

   • TCG Host Address: Enter a 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.

   • Interval: You can specify an interval for metrics gathering, down to 1 minute, and other parameters as with all connectors. 

   • Resources: You may 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 http://172.17.0.1:2222/metrics, make sure to press enter after typing the resource name or it will not be saved. 

     

     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 don't absolutely need a resource. If you are using the push option for your APM connection, you don't need to put anything in the resource section. The connector is listening for metrics to be posted by default. This is an advanced option, however. Please see the example application for details at https://github.com/gwos/tcg/tree/master/examples/apm/pull/go. 

     • Optionally you can set Headers for your resource, used to connect to it with the http protocol. Headers supplied can include needed tokens and key values if your resource requires authentication, for example, or needs specific headers to be allowed through a proxy or other connection requirements. Just click the Headers button on your resource to open the dialog and add your header name-value pairs.
     • Optionally you can set a default Host Group and Host Name to use for this resource. Just click on the Defaults button to expose the dialog. If you don't supply one, this resource will add a host in the "Servers" Host Group named "APM-Host".
5. 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",
  })

When labeling your metrics, you can optionally control where the results show up in the GroundWork system. The following table summarizes the labels ant their effect. 

resource

group

status

message

service

device

warning

critical

unitType

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 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
8. Now you can create a connection to this running connector, and configure it as in the Setting Up the Connector section above. Note 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

• Page:
  Elasticsearch Monitoring
• Page:
  Kubernetes Monitoring
• Page:
  Microsoft 365 Monitoring
• Page:
  SNMP Monitoring
• Page:
  TCG Connectors