Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Python client for statsd
Python

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
statsd
.gitignore
.travis.yml
AUTHORS
CHANGES
LICENSE
MANIFEST.in
README.rst
requirements.txt
setup.py

README.rst

A Python statsd client

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 'foo.bar' in statsd/graphite.

Installing

The easiest way to install statsd is with pip!

You can install from PyPI:

$ pip install statsd

Or GitHub:

$ pip install -e git+https://github.com/jsocol/pystatsd#egg=statsd

Or from source:

$ git clone https://github.com/jsocol/pystatsd
$ cd statsd
$ python setup.py 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'
STATSD_PORT = 8125

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):

STATSD_PREFIX = 'foo'

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 timer.ms  # Elapsed time in milliseconds.

Decorator

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
Something went wrong with that request. Please try again.