Skip to main content
Version: 4.10.0

StatsD

The N|Solid Agent is able to periodically send a suite of metrics directly to a StatsD-compatible data collector endpoint. As this functionality is built directly into the nsolid executable, you do not need to be connected to the N|Solid Console server in order to use it. Independent nsolid processes can be configured to talk to StatsD collectors using environment variables when starting your application.

Consult the Metrics in Detail section for a complete list of metrics that are sent to the StatsD collector for your N|Solid processes.

Consult the Using StatsD or AppDynamics without connecting to Console section for instructions on configuring a license token, if your N|Solid processes are not connected to the N|Solid Console server.

Supported backends

StatsD is a standardized protocol that is supported by many data collection databases and services. Supported backends include AWS CloudWatch, DataDog, ElasticSearch, Graphite, InfluxDB, MongoDB, OpenTSDB, StackDriver, Zabbix and many more. See the StatsD documentation for a more complete list.

Connection options

Supply the NSOLID_STATSD environment variable when starting an N|Solid process to have the Agent attempt to connect to an endpoint. The format of this value is "host:port". If unspecified, the default host is localhost and port is 8125. The host can be specified as a hostname string, an IPv4 or IPv6 address.

Once connected, a suite of metrics will be sent to the collector using the StatsD protocol. The NSOLID_INTERVAL environment variable can be used to adjust the default reporting interval of 3 seconds. Be aware that this will also change the reporting interval for the N|Solid Console connection if connected via the NSOLID_COMMAND environment variable.

StatsD buckets

StatsD metrics are reported using "buckets". A bucket is the full name, or key, of the entry being reported. Buckets need to be descriptive enough to clearly identify the process, host and metric type being reported. It is important that you have enough granularity to be able to inspect the data at the level you require, while also retaining the ability to group metrics for aggregate reporting in your frontend using bucket wildcard mechanisms. This will depend somewhat on your reporting frontend and may require some experimentation.

By default, N|Solid creates bucket names prefixed with "nsolid.<env>.<app>.<hostname>.<shortId>.", followed by the name of the metric. In this string:

  • env is the value of the NSOLID_ENV environment variable if it exists, or the "env" property of the "nsolid" section in package.json if it exists. Defaults to "prod" if not otherwise supplied.
  • app is the value of the NSOLID_APP environment variable if it exists, or the "app" property of the "nsolid" section in package.json if it exists, or the "name" property in package.json if it exists, or process.title if it has been set. Defaults to "untitled application" if not otherwise supplied.
  • hostname is the value of the NSOLID_HOSTNAME environment variable if it exists, or the "hostname" property of the "nsolid" section in package.json if it exists. Otherwise, the value of os.hostname() is used.
  • shortId is the first 7 characters of the random alphanumeric ID created by the N|Solid Agent at startup. This can be used to uniquely identify your processes. The full 40 character string is also available as id if required.

To override the default StatsD metric bucket strings, provide a string via the NSOLID_STATSD_BUCKET environment variable to be used as the full prefix. ${key} style variables can be used to insert any of the above values. The default bucket prefix would be specified as follows: "nsolid.${env}.${app}.${hostname}.${shortId}".

Your StatsD data, by default, will be formatted like so when sent to the collector:

nsolid.prod.myapp.nodehost.803bbd5.uptime:314.4|g
nsolid.prod.myapp.nodehost.803bbd5.rss:28401664|g
nsolid.prod.myapp.nodehost.803bbd5.heapTotal:8425472|g
nsolid.prod.myapp.nodehost.803bbd5.heapUsed:5342488|g
...

StatsD tags

Some backends, such as DataDog support "tags" for metric reporting. By default, N|Solid does not append any tags to its metrics. If required, you can supply your own tags to be appended to all reported metrics from an individual process.

Using the NSOLID_STATSD_TAGS environment variable, or the statsdTags property of the nsolid section in package.json, supply a string with the same variable substitution format as for the buckets above. In addition to env, app, hostname, shortId and id variables, you can also make use of tags to insert the N|Solid tags that have been supplied for the process.

StatsD tags should be a comma-separated list of strings that your backend can decode. Refer to your backend documentation for how these values are made use of for reporting and whether their use will be suitable for your deployment.