• EnglishEspañol日本語한국어Português
  • Log inStart now

StatsD monitoring integration

Our StatsD integration lets you easily get StatsD-format data into New Relic. You can also add any arbitrary tags (key-value pairs) to your data. Once your metrics are in New Relic, you can query your data and create custom charts and dashboards.

Want to try out our StatsD integration? Create a New Relic account for free! No credit card required.


This integration uses our Metric API and our Event API to ingest data. To use these APIs, you'll need a .

The integration adheres to the Metric API requirements and data limits. To see if you might be hitting the rate limit, run the following NRQL query of the NrIntegrationError event:

SELECT count(*) FROM NrIntegrationError
WHERE newRelicFeature = 'Metrics'
FACET category, message
LIMIT 100 SINCE 1 day ago

The integration is available as a linux container image in DockerHub for amd64 and arm64 architectures.


This section will explain how to do a standard install. If you want to run StatsD in Kubernetes, see Kubernetes install.

To install the StatsD integration, run the following command and include your New Relic account ID and . This generates a TOML configuration file used by gostatsd.

docker run \
-d --restart unless-stopped \
--name newrelic-statsd \
-h $(hostname) \
-p 8125:8125/udp \

If your organization is in the EU data center region, add this to the above command:

-e NR_EU_REGION=true \

After installing, you can:

Install for Kubernetes

Here are examples of Kubernetes manifests for deployment and service objects:

Did this doc help with your installation?


In the install procedure, you run nri-statsd with environment variables, and this generates a TOML configuration file. Additionally, you can set these configuration options:

Configuration options




If a metric is not updated for this amount of time, we stop reporting that metric. Default is 5m.

If you want to send the metrics only if the value was updated between the flush intervals, configure this to 1ms. To never expire metrics, set it to 0.


list of integers

Specifies the percentiles used for metrics aggregation. Default: 90.



Indicates address on which to listen for metrics. Default: :8125. From nri-statsd v2.3.0 (goStatsD v34.2.1), connection via Unix Domain Socket (UDS) is supported. Use metrics-addr=/some/path/newrelic-statsd.socket instead of [host]:port in the configuration.


To ensure FedRAMP compliance when using the StatsD integration you must define the following endpoints in the custom configuration:

address = 'https://gov-insights-collector.newrelic.com/v1/accounts/$NR_ACCOUNT_ID/events'
address-metrics = 'https://gov-infra-api.newrelic.com/metric/v1'

Here are some examples of customizing configuration by overwriting the default configuration:

Metric format

The integration receives metrics using the StatsD protocol. Optionally, the sample rate can be configured and tags can be added.

Here's the metric data format we use:

<metric name>:<value>|<type>|@<sample rate>|#<tags>

Here are explanations of these fields:

Field name


<metric name>


Required. Name of the metric.



Required. The metric type:

  • c = counter
  • g = gauge
  • ms = timer

@<sample rate>


Optional for simple counters or timer counters. When many metrics must be sent, you can use sampling to reduce network traffic. The downside is a reduction in the resolution of the data.

An example of how this would work for sample rates below 1: If you set this to 0.1, the counter would send a measurement one out of every 10 times.



Optional. Tags attached to your metrics are converted into attributes (key-value pairs). For more on tagging options, see Tags.

Metric types

Here are the types of metrics and how to format them:

Add tags (attributes)

You can add tags to your data, which we save as attributes (key-value pairs). There are two options for adding tags:

  • Add default tags that apply to all metrics: These apply to all metrics. They are fixed and don't change over time.
  • Add metric-level tags: These apply to specific metrics and allow the value to be changed between two submits.

Here's an example NRQL query that includes a custom tag:

SELECT count(*) FROM Metric WHERE environment = 'production'

Create alerts

You can alert on StatsD data using NRQL alert conditions.

Find and use data

To query your data, you'd use any New Relic query option. For example, you might run a NRQL query like:

SELECT count(*) FROM Metric WHERE metricName = 'myMetric' and environment = 'production'

For more on how to query the Metric data type, see Query metric data.



You've followed the steps to run the StatsD integration but still need to see the expected metrics in New Relic.


Follow the steps below to troubleshoot your configuration:

  • Ensure the contains your 40 hexadecimal character license key, and it's a valid license for the selected New Relic account ID.
  • Ensure the right data center, US or EU, has been selected for your New Relic account. Tip: If the license_key starts with "eu" then you must use the NR_EU_REGION=true flag.
  • Ensure there are no NrIntegrationError related to the StatsD integration.
  • Verbose logs can be enabled using the environment variable NR_STATSD_VERBOSE, modify the docker run command adding the following variable: -e NR_STATSD_VERBOSE=true.
  • A test metric can be pushed to confirm the integration is sending metrics that are expected. Example using the NetCat nc utility:
    • echo "example.gauge:123|g" | nc -u -w0 8125 (update with running container IP/address).

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.