statsd-client 1.0.7

Basic

Setup is easy. By default, the client will connect to localhost on the default statsd port (8125).

import statsd
statsd.incr('processed') # Increment processed bucket by 1
statsd.incr('processed', 5) # This time by 5
statsd.incr('processed', sample_rate=0.9) # Increment with a sample rate of .9
statsd.timing('pipeline', 2468.34) # Pipeline took 2468.34 ms to execute

Want to connect to a non-local statsd? Use statsd.init_statsd(settings). Settings is a dict with any of these keys:

STATSD_HOST (Default 'localhost'): String host name.
STATSD_PORT (Default 8125): Integer port number.
STATSD_SAMPLE_RATE (Default None (same as 1.0)): Integer/Float between 0 and 1.
STATSD_BUCKET_PREFIX (Default None): String prefix added to all buckets. The code will handle dotting them together.

If you do not want to use init_statsd, you can always pass in your settings when you create the clients, timers or counters:

from statsd import StatsdClient
client = StatsdClient(host='127.0.0.1', port=9999, prefix='app', sample_rate=0.9)

Counters

Want to count things? Use StatsdCounter:

import statsd
statsd.init_statsd({'STATSD_BUCKET_PREFIX': 'photos'})
counter = statsd.StatsdCounter('processed')
# calls on counter will send updates to bucket named 'photos.processed'
counter += 1 # equivalent to counter.incr() or counter.incr(1)
counter += 5 # equivalent to counter.incr(5)
counter -= 10 # equivalent to counter.decr(10)

Timing

Interested in timing? Check out all the ways you can time things:

import statsd
statsd.init_statsd({'STATSD_BUCKET_PREFIX': 'photos'})
timer = statsd.StatsdTimer('pipeline')
timer.start()
# Do stuff
timer.split('stage1') # Sends timing data for bucket 'photos.pipeline.stage1'
# Do more stuff
timer.split('stage2') # Sends timing data for bucket 'photos.pipeline.stage2'
# Do even more stuff
timer.stop() # Sends timing data for bucket 'photos.pipeline.total'

Timers can be used as decorators too:

from statsd import StatsdTimer
@StatsdTimer.wrap('pipeline')
def process():
    pass
process() # Sends timing data for bucket 'pipeline.total'

Fancy with statement usage!

from statsd import StatsdTimer
with StatsdTimer('photos'):
    pass # Do stuff

Even fancier:

from statsd import StatsdTimer
with StatsdTimer('photos') as t:
    # Do stuff
    t.split('stage1')
    # Do more stuff
    t.split('stage2')
    # Finish up

Using timers with decorators or the with statement will still sends stats if an exception is raised in the code block:

from statsd import StatsdTimer
class Foo(object):
    @StatsdTimer('photos')
    def proc(self):
            # Do stuff
            raise ValueError('Whoops')
f = Foo()
f.proc() # Raises exception, but sends timing data for bucket 'photos.total-except'