Skip to main content

A set of decorators and helper methods for adding statsd metrics to applications.

Project description


Software License Build Status

A set of decorators and helper methods for adding statsd metrics to applications.


You can use pip to install statsdecor:

pip install statsdecor


You must use statsdecor.configure to configure the internal statsd client before calling other methods:

import statsdecor

statsdecor.configure(host='localhost', prefix='superapp.')

Configuration is generally setup during your application's bootstrap. Once set configuration values are re-used in all clients that statsdecor creates.


You can track metrics with either the module functions, or decorators. Incrementing and decrementing counters looks like:

Metric functions

import statsdecor

statsdecor.gauge('', 9001)

Counters and timers can also be set through decorators:

import statsdecor.decorators as stats

def save(self):

def attempt():

def perform_request(self, req)

When using decorators, metrics are only tracked if the decorated function does not raise an error.


Statsdecor includes a context manager that can help measure latency and volume while using metric tags to classify their success & failure. For example, suppose you are making a call to a remote service and wish to write a wrapper that collects latency, volume and failure metrics.

With our knowledge about how the client library indicates errors we can make a context manager based on StatsContext:

from statsdecor.context import StatsContext

class FoobarClientMetrics(StatsContext):
    def __init__(self, tags=None):
        tags = list(tags or [])
        tags += ['caller:example_1']
        super(ThingyStatsContext, self).__self__('thingy_client', tags=tags)

    def exit_hook(self, exc_type, exc_val, exc_tb):
        if exc_val is not None:

        # Bonus: since we have the exception, classify the error type
        if isinstance(exc_val, PermissionDenied):
        elif isinstance(exc_val, TimeOut):
        elif exc_val is not None:

Now writing wrapper functions with metrics is simple:

def foobar_get_clients(**args):
    with FoobarClientMetrics(tags=['method:get_clients']) as stats:
        result = call_foobar_get_client(**args)

        # We know all foo methods return result['status_code'] so let's
        # add a status_code tag!
        return result

def foobar_add_client(**args):
    with FoobarClientMetrics(tags=['method:add_client']) as stats:
        result = call_foobar_add_client(**args)
        return result

Now we can graph:

  • volume of calls grouped by the method tag
  • average response time, excluding errors (timeouts will no longer skew the average)
  • volume of errors grouped by method, and/or type


Testing and coverage

make test
make coverage

You can track metrics with either the module functions, or decorators. Incrementing


statsdecor uses semver for version numbers. Before tagging, check for all changes since the last tag for breaking changes, new features, and/or bugfixes.

  1. edit VERSION
  2. commit/pr/merge bump to VERSION
  3. make tag
  4. make test-release (requires TestPyPI creds in ~/.pypirc as testpypi)
  5. make release (requires PyPI creds in ~/.pypirc as pypi)

Project details

Download files

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

Source Distribution

statsdecor-0.4.1.tar.gz (11.6 kB view hashes)

Uploaded source

Built Distribution

statsdecor-0.4.1-py2.py3-none-any.whl (7.5 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page