skip to navigation
skip to content

statsdmetrics 1.0.0

Statsd metrics classes and clients

Metric classes for Statsd, and Statsd clients (each metric in a single request, or send batch requests).

Metric classes represent the data used in Statsd protocol excluding the IO, to create, represent and parse Statsd requests. So any Statsd server and client regardless of the IO implementation can use them to send/receive Statsd requests.

The library also comes with a rich set of Statsd clients using the same metric classes, and Python standard library socket module.

Metric Classes

  • Counter
  • Timer
  • Gauge
  • Set
  • GaugeDelta
from statsdmetrics import Counter, Timer

counter = Counter('event.login', 1, 0.2)
counter.to_request() # returns event.login:1|c|@0.2

timer = Timer('', 27.4)
timer.to_request() # returns|ms

Parse metrics from a Statsd request

from statsdmetrics import parse_metric_from_request

event_login = parse_metric_from_request('event.login:1|c|@.2')
# event_login is a Counter object with count = 1 and sample_rate = 0.2

mem_usage = parse_metric_from_request('resource.memory:2048|g')
# mem_usage is a Gauge object with value = 2028

Statsd Clients

  • client.Client: Default client, sends request on each call using UDP
  • client.BatchClient: Buffers metrics and flushes them in batch requests using UDP
  • client.tcp.TCPClient: Sends request on each call using TCP
  • client.tcp.TCPBatchClient: Buffers metrics and flushes them in batch requests using TCP

Send Statsd requests

from statsdmetrics.client import Client

# default client, send metrics over UDP
client = Client("")
client.decrement("connections", 2)
client.timing("", 3500)
client.gauge("memory", 20480)
client.gauge_delta("memory", -256)
client.set("unique.ip_address", "")

# helpers for timing operations
chronometer = client.chronometer()
chronometer.time_callable("func1_duration", func1)

# decorate functions to send timing metrics for the duration of their running time
def func2():

# send timing for duration of a with block
with client.stopwatch("with_block_duration"):

Sending multiple metrics in batch requests by BatchClient, either by using an available client as the context manager:

from statsdmetrics.client import Client

client = Client("")
with client.batch_client() as batch_client:
    batch_client.decrement("connections", 2)
    batch_client.timing("", 3500)
# now all metrics are flushed automatically in batch requests

or by creating a BatchClient object explicitly:

from statsdmetrics.client import BatchClient

client = BatchClient("")
client.set("unique.ip_address", "")
client.gauge("memory", 20480)
client.flush() # sends one UDP packet to remote server, carrying both metrics

# timing helpers are available on all clients
chronometer = client.chronometer()
chronometer.time_callable("func1_duration", func1)

def func2():

with client.stopwatch("with_block_duration"):



pip install statsdmetrics

The only dependencies are Python 2.7+ and setuptools. CPython 2.7, 3.2, 3.3, 3.4, 3.5, 3.6-dev, PyPy 2.6 and PyPy3 2.4, and Jython 2.7 are tested)

However on development (and test) environment mock is required, typing and distutilazy are recommended.

# on dev/test env
pip install -r requirements-dev.txt



If you have make available

make test

You can always use the file

python test

Integration tests are available, bringing up dummy servers (but actually listening on network socket) to capture requests instead of processing them. Then send some metrics and assert if the captured requests match the expected.

python tests/
python tests/


Statsd metrics is released under the terms of the MIT license.

File Type Py Version Uploaded on Size
statsdmetrics-1.0.0-py2.py3-none-any.whl (md5, pgp) Python Wheel py2.py3 2016-11-16 28KB
statsdmetrics-1.0.0.tar.gz (md5, pgp) Source 2016-11-16 20KB