https://github.com/WoLpH/python-statsd
Python Client for the Etsy NodeJS Statsd Server
https://github.com/WoLpH/python-statsd
Last synced: 5 months ago
JSON representation
Python Client for the Etsy NodeJS Statsd Server
- Host: GitHub
- URL: https://github.com/WoLpH/python-statsd
- Owner: wolph
- License: bsd-3-clause
- Created: 2011-05-25T23:38:03.000Z (over 14 years ago)
- Default Branch: develop
- Last Pushed: 2019-02-15T17:19:30.000Z (almost 7 years ago)
- Last Synced: 2024-10-12T00:56:43.621Z (about 1 year ago)
- Language: Python
- Homepage: http://readthedocs.org/docs/python-statsd/en/latest/
- Size: 114 KB
- Stars: 110
- Watchers: 6
- Forks: 39
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-python-cn - python-statsd
- fucking_awesome_python - python-statsd - Python Client for the [statsd](https://github.com/etsy/statsd/) server. (Debugging Tools)
- awesome-python-cn - python-statsd
README
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.