Skip to content
Get packs

Guide · Open source

How to use StatsD: install, send metrics and run it with Graphite

Updated · written with AI from the project's own documentation and checked against our catalogue data

StatsD is an open-source network daemon, written for Node.js, that listens for simple numeric measurements such as counters and timers sent by your applications. It groups them into buckets, aggregates them over a flush interval and forwards the results to backend services such as Graphite. This guide walks through installing it, sending your first metric and understanding the basic settings so you can start tracking how your software behaves.

StatsDstatsd/statsd · ★ 18.1k · MIT

Quick start

  1. 1Install Node.js. Install a Current or LTS version of Node.js, which the README says StatsD supports.
  2. 2Clone the project. Run git clone on the statsd/statsd repository to get the source code.
  3. 3Create a config file. Make a config file based on exampleConfig.js and save it in a location you can reference.
  4. 4Start the daemon. Run node stats.js with the path to your config file.
  5. 5Send a test metric. Use the echo and nc command from the README to send foo:1|c over UDP to localhost port 8125.
  6. 6Connect a backend. Point StatsD at a backend such as Graphite, following the Graphite integration documentation linked from the README.

What StatsD does and how it works

StatsD listens for statistics sent over UDP or TCP and sends aggregates to one or more pluggable backend services, for example Graphite.

Each stat lives in its own bucket. Buckets are not predefined anywhere; they can be named anything that will translate to Graphite, where periods make folders. Each stat has a value, and how that value is interpreted depends on modifiers. In general, values should be integers.

  • Buckets: named containers for each stat, created as you send data.
  • Values: numbers whose meaning depends on the metric type modifier.
  • Flush: after the flush interval (config.flushInterval, default 10 seconds), stats are aggregated and sent to an upstream backend.

Install StatsD with Node.js

The README documents a manual installation that needs Node.js. All Current and LTS Node.js versions are supported. Clone the project, create a config file from exampleConfig.js and place it somewhere you can reach.

The README also lists Docker options: the official image on GitHub Container Registry, the official image on DockerHub, or building the image from the bundled Dockerfile.

  • Install Node.js (Current or LTS).
  • Clone the project.
  • Create a config file from exampleConfig.js and put it somewhere.
git clone https://github.com/statsd/statsd.git

Start the daemon with your config file

Start StatsD by passing the path to your config file to stats.js. The README gives this form of the command.

node stats.js /path/to/config

Send your first metric using the line protocol

The basic line protocol expects metrics in the format <metricname>:<value>|<type>. If StatsD is running with the default UDP server on localhost, you can send a test counter from the command line with netcat.

  • Format: <metricname>:<value>|<type>
  • Default UDP server on localhost listens on port 8125 in the README example.
echo "foo:1|c" | nc -u -w0 127.0.0.1 8125

Configure debugging options

The README lists two config variables for debugging. Use them when you need more diagnostic output, and check exampleConfig.js for more information.

  • debug: log exceptions and print more diagnostic info.
  • dumpMessages: print debug info on incoming messages.

Where to go next

The README links to further documentation on metric types, Graphite integration, supported servers and backends, the admin TCP interface, metric namespacing and a cluster proxy. Read these before relying on a feature the basic README does not describe.

  • Metric Types
  • Graphite Integration
  • Supported Servers and Supported Backends
  • Admin TCP Interface
  • Metric Namespacing
  • StatsD Cluster Proxy

What people use it for

  • Counting events in an application, such as how often a feature is used, using counter metrics.
  • Timing operations inside your software and sending the timings to StatsD for aggregation.
  • Relaying metrics from several applications on a server you control to a Graphite backend for charting.
  • Running a lightweight Node.js-based metrics relay with Docker or a manual install.

Frequently asked questions

Is StatsD free to use?

StatsD is released under the MIT licence, according to the project's listing. You run the daemon yourself on a server you control, so you are responsible for hosting it.

What do I need to run StatsD?

The README says you need Node.js, and that all Current and LTS versions are supported. You can also run it with Docker using the official images or the bundled Dockerfile.

How do I install StatsD?

Clone the statsd/statsd repository, create a config file from exampleConfig.js, and start the daemon with node stats.js followed by your config path. Docker is an alternative route.

Why are my metrics not showing up?

Check that your application sends data in the <metricname>:<value>|<type> format to the correct address and port. Turning on the debug and dumpMessages config options prints diagnostic information about incoming messages.

What is the flush interval in StatsD?

The flush interval is set by config.flushInterval and defaults to 10 seconds. At each flush, stats are aggregated and sent to the upstream backend.

How does StatsD compare to Telegraf, Prometheus or collectd?

The source material does not compare these tools in detail, so this guide cannot rank them. It only notes that Telegraf, Prometheus, the Datadog agent and collectd are comparable projects to evaluate against your own requirements.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

StatsD suits developers and teams who want a small, self-run Node.js daemon that aggregates counters and timings and forwards them to a backend such as Graphite. It is not a good fit if you need a hosted monitoring service, cannot run Node.js, or need metric types the basic README does not document.

Install options & downloads