python-statsd 2.1.0
statsd is a client for Etsy's node-js statsd server. A proxy for the Graphite stats collection and graphing server.
License: BSD

Introduction
============

.. 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.

Links
-----

 - The source: https://github.com/WoLpH/python-statsd
 - Project page: https://pypi.python.org/pypi/python-statsd
 - Reporting bugs: https://github.com/WoLpH/python-statsd/issues
 - Documentation: http://python-statsd.readthedocs.io/en/latest/
 - My blog: http://w.wol.ph/
 - Statsd: https://github.com/etsy/statsd
 - Graphite: http://graphite.wikidot.com

Install
-------

To install simply execute `python setup.py install`.
If you want to run the tests first, run `python setup.py nosetests`


Usage
-----

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.