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.)