This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

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 History

This version
History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
statsdmetrics-1.0.0-py2.py3-none-any.whl (28.7 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Nov 16, 2016
statsdmetrics-1.0.0.tar.gz (20.7 kB) Copy SHA256 Checksum SHA256 Source Nov 16, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting