Repository files navigation

statsd is a client for Etsy's statsd server, a front end/proxy for theGraphite stats collection and graphing server.

• 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

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:

>>>import statsd>>>>>> timer= statsd.Timer('MyApplication')>>>>>> timer.start()>>># do something here>>> timer.stop('SomeTimer')

>>>import statsd>>>>>> counter= statsd.Counter('MyApplication')>>># do something here>>> counter+=1

>>>import statsd>>>>>> gauge= statsd.Gauge('MyApplication')>>># do something here>>> gauge.send('SomeName', value)

Raw strings should be e.g. pre-summarized data or other data that willget passed directly to carbon. This can be used as a time andbandwidth-saving mechanism sending a lot of samples could use a lot ofbandwidth (more b/w is used in udp headers than data for a gauge, forinstance).

>>>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 (thestandard unix timestamp, e.g. the output of "date +%s"), but if you leave it out orprovide None it will provide the current time as part of the message

>>>import statsd>>>>>> average= statsd.Average('MyApplication', connection)>>># do something here>>> average.send('SomeName','somekey:%d'.format(value))

If you need some settings other than the defaults for yourConnection,you can useConnection.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 youspecify, unless you explicitly create a differentConnection to use(described below).

Defaults:

• host ='localhost'
• port =8125
• sample_rate =1
• disabled =False

>>>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)>>>>>>classSomeClass(object):...def__init__(self):...# Create a client specific for this class...self.statsd_client= statsd_client.get_client(...self.__class__.__name__)......defdo_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 turnOFF the service and avoid sending UDP messages,theConnection 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 theConnection object will inform it isnot sending UDP messages anymore.