statsdmetrics 0.3.0

Metric classes for Statsd

Metric classes for Statsd and and functionality to create, parse and send Statsd requests (each metric in a single request, or send batch requests).

Metric Classes

Available metrics:

• 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('db.search.username', 27.4)
timer.to_request() # returns db.search.username:27.4|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 Client

• 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

client = Client("stats.example.org")
client.increment("login")
client.decrement("connections", 2)
client.timing("db.search.username", 3500)
client.gauge("memory", 20480)
client.gauge_delta("memory", -256)
client.set("unique.ip_address", "10.10.10.1")

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

from statsdmetrics.client import Client

client = Client("stats.example.org")
with client.batch_client() as batch_client:
    batch_client.increment("login")
    batch_client.decrement("connections", 2)
    batch_client.timing("db.search.username", 3500)
# now all metrics are flushed automatically in batch requests

or by creating a BatchClient object explicitly:

from statsdmetrics.client import BatchClient

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

Installation

pip install statsdmetrics

There are no specific dependencies, it runs on Python 2.7+ (CPython 2.7, 3.2, 3.3 3.4 and 3.5, PyPy 2.6 and PyPy3 2.4, and Jython 2.7 are tested)

However on development (and test) environment mock is required, and distutilazy (or setuptools as a fallback) is used to run the tests.

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

Development

• Code is on GitHub

• Documentations are on Read The Docs

Tests

If you have make available

make test

You can always use the setup.py file

python setup.py 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/integration_test_upd.py
python tests/integration_test_tcp.py

License

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