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

Statsd metrics classes and clients

Project description

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.

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


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
statsdmetrics-1.0.0-py2.py3-none-any.whl (28.7 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Nov 16, 2016
statsdmetrics-1.0.0.tar.gz (20.7 kB) Copy SHA256 hash SHA256 Source None Nov 16, 2016

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