Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

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

Project description

Test Status Coverage Status

statsd is a client for Etsy’s statsd server, a front end/proxy for the Graphite stats collection and graphing server.

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.

Project details


Release history Release notifications

This version
History Node

2.1.0

History Node

2.0.0

History Node

1.7.2

History Node

1.7.1

History Node

1.7.0

History Node

1.6.4

History Node

1.6.3

History Node

1.6.2

History Node

1.6.1

History Node

1.6.0

History Node

1.5.8

History Node

1.5.7

History Node

1.5.6

History Node

1.5.5

History Node

1.5.4

History Node

1.5.3

History Node

1.5.2

History Node

1.5.1

History Node

1.4.3

History Node

1.4.2

History Node

1.4.1

History Node

1.4

History Node

1.3

History Node

1.2

History Node

1.1

History Node

1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
python_statsd-2.1.0-py2.py3-none-any.whl (14.5 kB) Copy SHA256 hash SHA256 Wheel 2.7 Sep 5, 2017
python-statsd-2.1.0.tar.gz (10.8 kB) Copy SHA256 hash SHA256 Source None Sep 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page