What is StatsD?​

StatsD is a system for collecting metrics from applications. Your applications send metrics to StatsD, usually via non-blocking UDP communication, and StatsD servers collect these metrics, perform simple calculations, and push them to time-series databases.

Learn more about the StatsD protocol.

Overview​

Supported Metric Types Summary​

How StatsD Works with Netdata​

Netdata as a StatsD Server​

Netdata comes with a fully-featured StatsD server built in. You can:

• Collect StatsD-formatted metrics
• Visualize them on the Netdata dashboard
• Store them in Netdata's database for long-term retention

Since StatsD is embedded in Netdata, you effectively have a StatsD server on every system where Netdata is installed.

Pre-configured StatsD Applications​

Netdata includes synthetic chart definitions to automatically present application metrics consistently. These are defined in configuration files that you can use as-is or customize.

For synthetic charts, you can set up alerts just like with any other metric or chart.

Currently available applications:

• K6 load testing tool
  • Description: k6 is a developer-centric, free, and open-source load testing tool for performance testing
  • Documentation
  • Configuration
• Asterisk
  • Description: Asterisk is an Open Source PBX and telephony toolkit
  • Documentation
  • Configuration

Supported Metric Types​

Netdata fully supports the StatsD protocol and extends it for more advanced use cases. All StatsD client libraries are compatible with Netdata.

Advanced Features​

Configuration​

You can find the StatsD configuration in /etc/netdata/netdata.conf:

[statsd]
	# enabled = yes
	# decimal detail = 1000
	# update every (flushInterval) = 1s
	# udp messages to process at once = 10
	# create private charts for metrics matching = *
	# max private charts hard limit = 1000
	# cleanup obsolete charts after = 0
	# private charts memory mode = save
	# private charts history = 3996
	# histograms and timers percentile (percentThreshold) = 95.00000
	# add dimension for number of events received = no
	# gaps on gauges (deleteGauges) = no
	# gaps on counters (deleteCounters) = no
	# gaps on meters (deleteMeters) = no
	# gaps on sets (deleteSets) = no
	# gaps on histograms (deleteHistograms) = no
	# gaps on timers (deleteTimers) = no
	# listen backlog = 4096
	# default port = 8125
	# bind to = udp:localhost:8125 tcp:localhost:8125

Configuration Architecture​

How the StatsD Configuration Works​

Netdata's StatsD chart system uses three key sections in its configuration:

The diagram shows how the configuration flows:

1. The central statsd.d config connects to three main components:

   • The application configuration
   • The dictionary system
   • Chart definitions

2. Each of these components serves a specific purpose:

   • The app component handles metric filtering
   • The dictionary manages renaming metrics for display
   • Chart definitions determine properties like family, context, units, and priorities

This structure allows for flexible and powerful metric configuration within Netdata's StatsD implementation.

Key Configuration Options​

• enabled = yes|no - Controls whether StatsD is enabled
• default port = 8125 - The default port if not specified in binding
• bind to = udp:localhost tcp:localhost - Space-separated list of IPs and ports to listen on
• update every (flushInterval) = 1s - How often StatsD updates Netdata charts
• decimal detail = 1000 - Controls decimal precision in gauges and histograms

StatsD Charts​

Netdata can visualize StatsD collected metrics in two ways:

1. Private charts - Each metric gets its own chart (default, no configuration needed)
2. Synthetic charts - Combine multiple metrics into custom charts (requires configuration)

Private Metric Charts​

Private charts are controlled with create private charts for metrics matching = *. This setting accepts a space-separated list of simple patterns. By default, Netdata creates private charts for all metrics.

Private Chart Naming Convention​

When querying StatsD metrics via the Netdata API, you must use the chart identifier that Netdata constructs from the metric name — not the raw metric name you sent to StatsD. The chart identifier is built as follows:

• Chart type = statsd_<first_word> — where <first_word> is the portion of the metric name before the first . or _.
• Chart id = <remaining>_<metric_type> — where <remaining> is the portion after the first . or _, and <metric_type> is one of: gauge, counter, meter, timer, histogram, set, or dictionary. If the metric name has no . or _, the chart id is just the <metric_type>.
• Full chart reference = <chart_type>.<chart_id> — use this as the chart parameter in API queries.

curl http://localhost:19999/api/v1/charts

curl "http://localhost:19999/api/v1/data?chart=statsd_test.metric_counter&after=-10&before=now"

Example: To create charts for all myapp.* metrics except myapp.*.badmetric:

create private charts for metrics matching = !myapp.*.badmetric myapp.*

You can configure a different memory mode specifically for StatsD charts:

• private charts memory mode
• private charts history

Storage Optimization​

For performance reasons, Netdata limits private charts. The max private charts hard limit (default: 1000) controls this. Metrics above this limit can still be used in synthetic charts.

For ephemeral metrics, use set charts as obsolete after and cleanup obsolete charts after to automatically clean up charts that haven't received data recently.

Synthetic StatsD Charts​

Use synthetic charts to create dedicated sections on the dashboard to render your StatsD charts.

Synthetic charts are organized in:

• Application - Section in Netdata Dashboard
• Charts for each application - Family/submenu in the Dashboard
• StatsD metrics for each chart - Charts and context in the Dashboard

Basic Configuration Structure​

For example, to monitor the application myapp using StatsD and Netdata, create the file /etc/netdata/statsd.d/myapp.conf:

[app]
	name = myapp
	metrics = myapp.*
	private charts = no
	gaps when not collected = no
	history = 60

[dictionary]
 m1 = metric1
 m2 = metric2

# Chart definition with ID 'mychart'
# The chart will be named: myapp.mychart
[mychart]
	name = mychart
	title = my chart title
	family = my family
	context = chart.context
	units = tests/s
	priority = 91000
	type = area
	dimension = myapp.metric1 m1
	dimension = myapp.metric2 m2

Using this configuration, myapp gets its own dashboard section with one chart containing two dimensions.

When you send metrics like myapp.metric1:10|g and myapp.metric2:20|g, you'll see both private charts and your synthetic chart. These metric names must match the pattern defined in the [app] section (e.g., myapp.*) for them to appear in your synthetic charts.

Application Section Options​

The [app] section defines the application and has these options:

Dictionary Section​

[dictionary] defines name-value pairs for renaming metrics in synthetic charts. This allows you to:

• Define dimension names globally for the whole app
• Rename dimensions when using patterns
• Create more human-readable names for technical metrics

The dictionary can be empty or omitted if not needed.

Chart Definitions​

Each chart starts with [id] and will be named app_name.id. Key settings for charts:

Dimension Format​

Add metrics to charts using dimension lines with this format:

dimension = [pattern] METRIC NAME TYPE MULTIPLIER DIVIDER OPTIONS

Where:

1. METRIC - The metric name as collected (must match the metrics pattern)
2. NAME - The dimension name to display (can use dictionary for renaming)
3. TYPE - (Optional) Value selector like events, last, min, max, etc.
4. MULTIPLIER - (Optional) Value to multiply the metric by
5. DIVIDER - (Optional) Value to divide the metric by
6. OPTIONS - (Optional) Flags like hidden to include but not display a dimension

Scope of StatsD Chart Configuration​

All chart and dimension configuration directives in /etc/netdata/statsd.d/*.conf control local agent behavior only — they define how the local Netdata agent processes, names, and visualizes statsd metrics it receives.

The dimension TYPE field (see Dimension Format above) selects which computed value of a metric a single agent displays. It does not control how that metric is combined across multiple Netdata instances.

Cross-node aggregation — how metrics from multiple agents are combined in Netdata Cloud dashboards — is governed by the Cloud query engine, not by statsd configuration files. To choose Sum, Average, or another aggregation for a chart in Netdata Cloud, use the aggregate function on that chart. There is no aggregation = SUM or aggregation = AVG directive in statsd.d configuration.

Using StatsD with Different Languages​

Step-by-Step Guide: Monitoring K6 with StatsD​

This guide demonstrates how to use Netdata's StatsD to visualize metrics from k6, an open-source load testing tool.