Skip to content

StatsD agent

Zenoss Cloud supports integration with a StatsD agent for streaming data to Zenoss Cloud, the Zenoss backend for the Atlassian gostatsd server.

The Zenoss backend takes advantage of the tags feature of gostatsd to add information to incoming metric data. Primarily, tags are used to uniquely identify the entity supplying metric data and to provide important metadata about the metrics or entity. Optionally, tags can be used to associate an entity with other entities that affect it (model data). Some tags can be applied to all entities, by configuring gostatsd, while other tags must be applied to specific entities, by modifying application code. The modifications are lightweight, and Zenoss provides examples for the most popular programming languages.

Agent design

If your application supports the StatsD protocol, you can quickly deploy the Zenoss backend for the gostatsd server to monitor the application with Zenoss Cloud. If it does not, you can either configure the gostatsd server to supply the information Zenoss Cloud requires, or make some lightweight modifications to your application code. Zenoss provides application code examples for 5 widely-used programming languages.

Info

Events are written to STDOUT (dropped).

StatsD metric types

The Zenoss backend supports the StatsD gauge metric type directly, while the other metric types (counter, set, and timing) are converted to gauge equivalents.

For more information about StatsD metric types, refer to the StatsD documentation.

Counter (count and rate)

The StatsD counter metric syntax:

 <counter-name>:<value>|c|@<rate>

The Zenoss backend converts counter metrics into two separate metrics:

 <counter-name>.total = <value>
 <counter-name>.rate = <rate>

Gauge (arbitrary value)

The StatsD gauge metric syntax:

 <gauge-name>:<value>|g

The Zenoss backend converts gauge metrics into one metric:

 <gauge-name> = <value>

Set (unique occurrences since last flush)

The StatsD set metric syntax:

 <set-name>:<value>|s

In the Zenoss backend, the number of elements in the set is the value:

 <set-name> = <value>

Timing (milliseconds)

The syntax of the StatsD timing metric varies by the type of calculation gostatsd performs. The Zenoss backend converts the timing metrics it receives into separate metrics for each enabled subtype:

 <timer-name>.lower (lower boundary)
 <timer-name>.upper (upper boundary)
 <timer-name>.count
 <timer-name>.count_ps (count per second)
 <timer-name>.mean
 <timer-name>.median
 <timer-name>.std (standard deviation)
 <timer-name>.sum
 <timer-name>.sum_squares
 <timer-name>.<percentile> (for each enabled percentile)

Configuration variables

The configuration variables for the Zenoss backend for the gostatsd server

  • configure the server for interaction with Zenoss Cloud
  • specify tags that create a Zenoss Cloud entity to represent the server
  • specify tags that associate the server's internal metrics with the server's entity

For information about general gostatsd server configuration settings, refer to the gostatsd README file.

Note

For the Zenoss backend for the gostatsd server, the value of the reserved tag name source-type must be com.atlassian.gostatsd. For more information, see Understanding entities.

Variables for interaction with Zenoss Cloud

Zenoss API endpoint

The Zenoss API endpoint. Replace the default with the endpoint for your organization, if necessary. For the list of alternate endpoints, see Zenoss API endpoints.

Configuration variable address
Environment variable ZENOSS_ADDRESS
Required Yes
Default api.zenoss.io:443

Authentication key

The authentication key for this server.

Configuration variable api-key
Environment variable ZENOSS_API_KEY
Required Yes
Default (none)

TLS

Control TLS. Use one or both of these variables when a proxy server is required in your environment.

Configuration variables disable-tls,
insecure-tls
Environment variables ZENOSS_DISABLE_TLS,
ZENOSS_INSECURE_TLS
Required No
Default false

Metrics per batch

The number of metrics in a batch. In testing, values greater than the default increased the error rate.

Configuration variable metrics-per-batch
Environment variable ZENOSS_METRICS_PER_BATCH
Required No
Default 1000

Models per batch

The number of entity models in a batch. In testing, values greater than the default increased the error rate.

Configuration variable models-per-batch
Environment variable ZENOSS_MODELS_PER_BATCH
Required? No
Default 100

Entity dimensions

The names of entity dimension tags, which uniquely identify the entity that represents the server.

Configuration variable model-dimension-tags
Environment variable ZENOSS_MODEL_DIMENSION_TAGS
Required No
Default (none)

Entity metadata

The names of entity metadata tags.

Configuration variable model-metadata-tags
Environment variable ZENOSS_MODEL_METADATA_TAGS
Required No
Default (none)

Metric dimensions

The names of metric dimension tags. This value must match the value assigned to the model-dimension-tags variable.

Configuration variable metric-dimension-tags
Environment variable ZENOSS_METRIC_DIMENSION_TAGS
Required Yes
Default (none)

Metric metadata

The names of metric metadata tags.

Configuration variable metric-metadata-tags
Environment variable ZENOSS_METRIC_METADATA_TAGS
Required No
Default (none)

Installing the agent

Use one of the following methods to download and install the Zenoss-built gostatsd server:

  • Download the amd64 (Linux) binary from Zenoss Delivery.

    You need permission to download files from the server, which customers can request by filing a ticket at the Zenoss Support site.

  • Pull the zenoss/gostatsd:1.0.0 image from Docker Hub.

    The image is public, so no permissions are required.

You can deploy the server as you wish: As a regular Linux server, or as a service in an application managed by Docker Compose or Kubernetes. (Note that a gostatsd server running any backend must be configured in standalone mode, not forwarder mode.)