Monitoring StatsD

Instana offers comprehensive monitoring of your applications and services that use the StatsD protocol. The Instana agent itself acts as a StatsD collector daemon and receives metrics in the same way as a real StatsD daemon. So you don't need to 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 information

Supported operating system

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:

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 will prevent the agent from listening on these ports. Run only the agent, which will act as 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 (where 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 host is where the agent receives the metric data.

The StatsD sensor can collect a maximum of 1000 metrics for each 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 specific 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 the StatsD documentation.

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

  • metric name:value:

    For example, the following script increases a counter 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