Monitoring StatsD

Instana offers comprehensive monitoring of your applications and services that use the StatsD protocol. The Instana agent acts as a StatsD collector daemon and receives metrics in the same way as a real StatsD daemon. You need not deploy another StatsD daemon. You can view metrics that are related to your applications and services in the Instana UI after you configure the StatsD sensor as outlined in the Configuring section.

Supported operating systems

The supported operating systems of the StatsD sensor are consistent with host agent requirements. For more information, see supported operating systems in Installing host agents.

Configuring StatsD sensor

By default, the StatsD sensor is disabled. To enable the sensor, edit the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml as shown in the following example:

com.instana.plugin.statsd:
  enabled: true
  ports:
    udp: 8125
    mgmt: 8126
  bind-ip: "0.0.0.0" # all IPs by default
  flush-interval: 10 # in seconds

Do not run the regular statsd service, it prevents the agent from listening on these ports. Run only the agent, which acts as a statsd server.

Before you begin

Check whether the UDP port is open to the Instana StatsD sensor by completing the following steps:

  1. Disable the StatsD sensor.
  2. Run the following command on the host on which the Instana agent with activated StatsD sensor is installed:
    nc -l -u 8125
  3. From any other computer, send a command, such as:
    echo -n "custom.metric.name-test:1|c" | 34.135.37.172 8125
  4. Check the output of the listener that is running on the port 8125. The output is displayed on the console of the host where the Instana agent is installed.

If the metric is displayed in the output of the listener, then the connection to StatsD is established. If not, then the UDP port is not open on the host.

Viewing metrics

When the standard StatsD protocol of any client library is used to send data to the Instana agent through the StatsD sensor, the host dashboard displays up to 3000 custom metrics. The agent receives the metric data on the host.

The StatsD sensor can collect a maximum of 1000 metrics for every metric type: counters, gauges, and timers.

To view the metrics, complete the following steps:

  1. From the navigation menu in the Instana UI, select Infrastructure.
  2. Click a monitored host.

You can see a host dashboard with all the collected metrics. Metrics are sent to the configured UDP port in the StatsD format through UDP. For more information about the format, see StatsD Metric Types.

The sensor accepts the metrics that are sent in the following StatsD formats:

  • metric name:value:

    For example, the following script increases a counter that is called hits by one:

    echo "hits:1|c" | nc -u -w0 127.0.0.1 8125

  • \n as a separator for sending multiple metrics through UDP to the configured UDP port:

    echo "hits:1|c\nlatency:320|ms\nvisits:333|g\nresponse time:765|s" | nc -u -w0 127.0.0.1 8125

  • # tags:

    echo "host.network_receive_errs_total:10|c|#collector:network,device:utun2,host:testmachine" | nc -u -w0 127.0.0.1 8125