python-statsd

python-statsd is a client for Etsy's statsd server, a front end and proxy for the Graphite stats collection and graphing server. It supports Python 3.10 and newer, and it has no dependencies.

pip install python-statsd

import statsd

counter = statsd.Counter('app')
counter += 1

with statsd.Timer('app').time('render'):
    pass  # the work you are measuring

Two metrics, two UDP packets, nothing blocking. A statsd server that is down costs you graphs rather than requests.

What goes on the wire

Every line under udp :8125 < in this recording is a packet the client sent, caught by a real listener on the other end:

Note the last one. At sample_rate=0.5 four increments produced a single packet, and it carries |@0.5 so the server knows to multiply back up.

The metric types

import statsd

counter = statsd.Counter('app')
counter.increment('requests')  # app.requests:1|c

gauge = statsd.Gauge('app')
gauge.send('queue_depth', 42)  # app.queue_depth:42|g

average = statsd.Average('app')
average.send('batch', 123)  # app.batch:123|a

raw = statsd.Raw('app')
raw.send('summary', 42, timestamp=1234567890)  # app.summary:42|r|1234567890

Timers come in three forms, and the context manager is the one to reach for, because it reports the block that raised as well as the block that did not:

import statsd

timer = statsd.Timer('app')

with timer.time('render'):
    pass  # the work you are measuring


@timer.decorate
def render_page():  # sends app.render_page
    pass

Names build themselves when you nest clients, which keeps the string formatting out of your call sites:

import statsd

app = statsd.Client('app')
queries = app.get_client('database').get_client('queries', statsd.Counter)

queries.increment()  # app.database.queries:1|c

See it working

The repository ships a compose file with statsd, Graphite and Grafana, so you can watch a metric arrive instead of taking anyone's word for it:

docker compose up -d
uv run python examples/send_metrics.py --seconds 120

Then open http://localhost:3000. Grafana comes up with the datasource configured and this dashboard loaded, no login in the way:

That screenshot is the stack in this repository, fed by examples/send_metrics.py through this client. The local stack guide covers how statsd renames your metrics on the way through, and what to check when nothing shows up.

Configuration

Set the defaults once at startup and every client built afterwards follows:

import statsd

statsd.Connection.set_defaults(host='localhost', port=8125, sample_rate=1)

Or build connections yourself when one destination is not enough:

import statsd

connection = statsd.Connection(host='statsd-1', port=8125, sample_rate=0.1)
statsd.Counter('app.requests', connection).increment()

One trap worth knowing before it costs you an afternoon: a falsy argument means "use the default", so Connection(sample_rate=0) sends everything. Pass disabled=True to send nothing.

Documentation

Full documentation is at python-statsd.readthedocs.io.

• Metrics: the five types, how to choose, and the exact bytes each one writes
• Connections: destinations, sampling, disabling, failure behaviour, threads and forks
• Patterns: naming, cardinality, client trees, WSGI and Celery integration
• Local stack: docker compose, and how to debug a metric that never arrives

For Django, use django-statsd, the sister project built on this client. It times views and reports the queries per request without you writing any of it.

Note on the package name

This project is published on PyPI as python-statsd and installs a module called statsd. A different project, jsocol's client, is published as statsd and installs a module called statsd as well. Installing both in one environment leaves you with whichever was written last, so pick one.

Contributing

Bug reports and patches are welcome, and CONTRIBUTING.md covers the development setup: uv sync --all-extras, uv run pytest, and uv run tox -p auto to run everything CI runs. Every code sample in this README and in the documentation is executed by the test suite, so a change in behaviour tends to tell you which paragraph it just made wrong.

Links

• Source: https://github.com/WoLpH/python-statsd
• Issues: https://github.com/WoLpH/python-statsd/issues
• Statsd: https://github.com/etsy/statsd
• Graphite: https://graphiteapp.org/