Timers <timer-type>
are an incredibly powerful tool for tracking application performance. Statsd provides a number of ways to use them to instrument your code.
There are four ways to use timers.
The simplest way to use a timer is to record the time yourself and send it manually, using the timing
method:
import time
from statsd import StatsClient
statsd = StatsClient()
start = time.time()
time.sleep(3)
# You must convert to milliseconds:
dt = int((time.time() - start) * 1000)
statsd.timing('slept', dt)
Each StatsClient
instance contains a timer
attribute that can be used as a context manager or a decorator. When used as a context manager, it will automatically report the time taken for the inner block:
from statsd import StatsClient
statsd = StatsClient()
with statsd.timer('foo'):
# This block will be timed.
for i in xrange(0, 100000):
i ** 2
# The timing is sent immediately when the managed block exits.
The timer
attribute decorates your methods in a thread-safe manner. Every time the decorated function is called, the time it took to execute will be sent to the statsd server.
from statsd import StatsClient
statsd = StatsClient()
@statsd.timer('myfunc')
def myfunc(a, b):
"""Calculate the most complicated thing a and b can do."""
# Timing information will be sent every time the function is called.
myfunc(1, 2)
myfunc(3, 7)
2.1
:pystatsd.client.Timer
objects function as context managers and as decorators, but they can also be used directly. (Flat is, after all, better than nested.)
from statsd import StatsClient
statsd = StatsClient()
foo_timer = statsd.timer('foo')
foo_timer.start()
# Do something fun.
foo_timer.stop()
When :pystatsd.client.Timer.stop
is called, a timing stat
<timer-type>
_ will automatically be sent to StatsD. You can over ride this behavior with the send=False
keyword argument to stop()
:
foo_timer.stop(send=False)
foo_timer.send()
Use :pystatsd.client.Timer.send
to send the stat when you're ready.
Note
This use of timers is compatible with Pipelines
<pipeline-chapter>
_ but be careful with the send()
method. It must be called for the stat to be included when the Pipeline finally sends data, but send()
will not immediately cause data to be sent in the context of a Pipeline. For example:
- with statsd.pipeline() as pipe:
foo_timer = pipe.timer('foo').start() # Do something... pipe.incr('bar') foo_timer.stop() # Will be sent when the managed block exits.
- with statsd.pipeline() as pipe:
foo_timer = pipe.timer('foo').start() # Do something... pipe.incr('bar') foo_timer.stop(send=False) # Will not be sent. foo_timer.send() # Will be sent when the managed block exits. # Do something else...