Python Client for the Etsy NodeJS Statsd Server
BSD-3-CLAUSE License
.. image:: https://travis-ci.org/WoLpH/python-statsd.svg?branch=master :alt: Test Status :target: https://travis-ci.org/WoLpH/python-statsd
.. image:: https://coveralls.io/repos/WoLpH/python-statsd/badge.svg?branch=master :alt: Coverage Status :target: https://coveralls.io/r/WoLpH/python-statsd?branch=master
statsd
is a client for Etsy's statsd server, a front end/proxy for the
Graphite stats collection and graphing server.
To install simply execute python setup.py install
.
If you want to run the tests first, run python setup.py nosetests
To get started real quick, just try something like this:
Basic Usage
Timers
^^^^^^
>>> import statsd
>>>
>>> timer = statsd.Timer('MyApplication')
>>>
>>> timer.start()
>>> # do something here
>>> timer.stop('SomeTimer')
Counters
^^^^^^^^
>>> import statsd
>>>
>>> counter = statsd.Counter('MyApplication')
>>> # do something here
>>> counter += 1
Gauge
^^^^^
>>> import statsd
>>>
>>> gauge = statsd.Gauge('MyApplication')
>>> # do something here
>>> gauge.send('SomeName', value)
Raw
^^^
Raw strings should be e.g. pre-summarized data or other data that will
get passed directly to carbon. This can be used as a time and
bandwidth-saving mechanism sending a lot of samples could use a lot of
bandwidth (more b/w is used in udp headers than data for a gauge, for
instance).
>>> import statsd
>>>
>>> raw = statsd.Raw('MyApplication', connection)
>>> # do something here
>>> raw.send('SomeName', value, timestamp)
The raw type wants to have a timestamp in seconds since the epoch (the
standard unix timestamp, e.g. the output of "date +%s"), but if you leave it out or
provide None it will provide the current time as part of the message
Average
^^^^^^^
>>> import statsd
>>>
>>> average = statsd.Average('MyApplication', connection)
>>> # do something here
>>> average.send('SomeName', 'somekey:%d'.format(value))
Connection settings
^^^^^^^^^^^^^^^^^^^
If you need some settings other than the defaults for your ``Connection``,
you can use ``Connection.set_defaults()``.
>>> import statsd
>>> statsd.Connection.set_defaults(host='localhost', port=8125, sample_rate=1, disabled=False)
Every interaction with statsd after these are set will use whatever you
specify, unless you explicitly create a different ``Connection`` to use
(described below).
Defaults:
- ``host`` = ``'localhost'``
- ``port`` = ``8125``
- ``sample_rate`` = ``1``
- ``disabled`` = ``False``
Advanced Usage
--------------
>>> import statsd
>>>
>>> # Open a connection to `server` on port `1234` with a `50%` sample rate
>>> statsd_connection = statsd.Connection(
... host='server',
... port=1234,
... sample_rate=0.5,
... )
>>>
>>> # Create a client for this application
>>> statsd_client = statsd.Client(__name__, statsd_connection)
>>>
>>> class SomeClass(object):
... def __init__(self):
... # Create a client specific for this class
... self.statsd_client = statsd_client.get_client(
... self.__class__.__name__)
...
... def do_something(self):
... # Create a `timer` client
... timer = self.statsd_client.get_client(class_=statsd.Timer)
...
... # start the measurement
... timer.start()
...
... # do something
... timer.intermediate('intermediate_value')
...
... # do something else
... timer.stop('total')
If there is a need to turn *OFF* the service and avoid sending UDP messages,
the ``Connection`` class can be disabled by enabling the disabled argument::
>>> statsd_connection = statsd.Connection(
... host='server',
... port=1234,
... sample_rate=0.5,
... disabled=True
... )
If logging's level is set to debug the ``Connection`` object will inform it is
not sending UDP messages anymore.