Skip to main content

A simple statsd client.

Project description

statsd is a friendly front-end to Graphite. This is a Python client for the statsd daemon.

To use:

>>> import statsd
>>> c = statsd.StatsClient('localhost', 8125)
>>> c.incr('foo')  # Increment the 'foo' counter.
>>> c.timing('stats.timed', 320)  # Record a 320ms 'stats.timed'.

You can also add a prefix to all your stats:

>>> import statsd
>>> c = statsd.StatsClient('localhost', 8125, prefix='foo')
>>> c.incr('bar')  # Will be '' in statsd/graphite.


The easiest way to install statsd is with pip!

You can install from PyPI:

$ pip install statsd

Or GitHub:

$ pip install -e git+

Or from source:

$ git clone
$ cd statsd
$ python install

In Django

If you’re lucky enough to be using statsd in Django, you can configure a default client in your settings module with two values. The defaults are:

STATSD_HOST = 'localhost'

Then instead of instantiating a new client every time, you can just grab:

>>> from statsd import statsd
>>> statsd.incr('foo')

You can even set a prefix (optionally):


This can help differentiate between environments, like dev, staging, and production.

Context Manager

You can use a StatsClient instance as a context manager to easily time sections of code with the timer() method:

>>> from statsd import statsd
>>> with statsd.timer('bar'):
...     func()
...     func()

When the managed block exits, the client will automatically send the time it took to statsd.

If you’d like to catpure the elapsed time, add a variable to the with block:

>>> from statsd import statsd
>>> with statsd.timer('bar') as timer:
...     func()
>>> print  # Elapsed time in milliseconds.


You can also use a StatsClient instance as a decorator, also with the timer() method:

>>> from statsd import statsd
>>> @statsd.timer('bar')
... def foo():
...     pass

Every time foo() is called, timing information will be sent to the stat bar.

Sample Rates

All methods support an optional rate (kw)arg. This is a float between 0 and 1 that specifies what fraction of data to send through (for a specific call). Sample rates are recorded by statsd.

For example, here foo will be incremented approximately 50% of the time:

>>> from statsd import statsd
>>> statsd.incr('foo', 1, rate=0.5)

Statsd understands that this is a 50% sample rate and will adjust accordingly.

Similarly with decr() and timings:

>>> from statsd import statsd
>>> statsd.decr('foo', 1, rate=0.5)
>>> statsd.timing('foo', 320, rate=0.25)
>>> with statsd.timer('bar', rate=0.1):
...    pass
>>> @statsd.timer('bar', rate=0.5)
... def foo():
...     pass

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for statsd, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size statsd-0.3.0.tar.gz (5.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page