API Reference

Decorators

@perfmetrics.metric

Notifies Statsd every time the function is called.

Sends both call counts and timing information. The name of the metric sent to Statsd is <module>.<function name>.

@perfmetrics.metricmethod

Like @metric, but the name of the Statsd metric is <class module>.<class name>.<method name>.

class perfmetrics.Metric(stat=None, rate=1, method=False, count=True, timing=True)

Bases: object

A decorator or context manager with options.

stat is the name of the metric to send; set it to None to use the name of the function or method. rate lets you reduce the number of packets sent to Statsd by selecting a random sample; for example, set it to 0.1 to send one tenth of the packets. If the method parameter is true, the default metric name is based on the method’s class name rather than the module name. Setting count to False disables the counter statistics sent to Statsd. Setting timing to False disables the timing statistics sent to Statsd.

Sample use as a decorator:

@Metric('frequent_func', rate=0.1, timing=False)
def frequent_func():
    "Do something fast and frequently."

Sample use as a context manager:

def do_something():
    with Metric('doing_something'):
        pass

If perfmetrics sends packets too frequently, UDP packets may be lost and the application performance may be affected. You can reduce the number of packets and the CPU overhead using the Metric decorator with options instead of metric or metricmethod. The decorator example above uses a sample rate and a static metric name. It also disables the collection of timing information.

When using Metric as a context manager, you must provide the stat parameter or nothing will be recorded.

Changed in version 3.0: When used as a decorator, set __wrapped__ on the returned object, even on Python 2.

Changed in version 3.0: When used as a decorator, the returned object has metric_timing, metric_count and metric_rate attributes that can be changed to alter its behaviour.

class perfmetrics.MetricMod(format)

Bases: object

Decorator/context manager that modifies the name of metrics in context.

format is a format string such as ‘XYZ.%s’.

Functions

perfmetrics.statsd_client()

Return the current StatsdClient for the thread.

Returns the thread-local client if there is one, or the global client if there is one, or None.

perfmetrics.set_statsd_client(client_or_uri)

Set the global StatsdClient.

The client_or_uri can be a StatsdClient, a statsd:// URI, or None.

Note that when the perfmetrics module is imported, it looks for the STATSD_URI environment variable and calls set_statsd_client if that variable is found.

perfmetrics.statsd_client_from_uri(uri)

Create and return perfmetrics.statsd.StatsdClient.

A typical URI is statsd://localhost:8125. An optional query parameter is prefix. The default prefix is an empty string.

StatsdClient Methods

Python code can send custom metrics by first getting the current IStatsdClient using the statsd_client() function. Note that statsd_client() returns None if no client has been configured.

interface perfmetrics.interfaces.IStatsdClient

Interface to communicate with a StatsD server.

Most of the methods below have optional rate, rate_applied, and buf parameters. The rate parameter, when set to a value less than 1, causes StatsdClient to send a random sample of packets rather than every packet. The rate_applied parameter, if true, informs StatsdClient that the sample rate has already been applied and the packet should be sent regardless of the specified sample rate.

If the buf parameter is a list, StatsdClient appends the packet contents to the buf list rather than send the packet, making it possible to send multiple updates in a single packet. Keep in mind that the size of UDP packets is limited (the limit varies by the network, but 1000 bytes is usually a good guess) and any extra bytes will be ignored silently.

close()

Release resources (sockets) held by this object.

Added in version 3.0.

timing(stat, value, rate=1, buf=None, rate_applied=False)

Log timing information in milliseconds.

stat is the name of the metric to record and value is the timing measurement in milliseconds. Note that Statsd maintains several data points for each timing metric, so timing metrics can take more disk space than counters or gauges.

gauge(stat, value, rate=1, buf=None, rate_applied=False)

Update a gauge value.

stat is the name of the metric to record and value is the new gauge value. A gauge represents a persistent value such as a pool size. Because gauges from different machines often conflict, a suffix is usually applied to gauge names; this may be done manually or with MetricMod.

incr(stat, count=1, rate=1, buf=None, rate_applied=False)

Increment a counter by count.

Note that Statsd clears all counter values every time it sends the metrics to Graphite, which usually happens every 10 seconds. If you need a persistent value, it may be more appropriate to use a gauge instead of a counter.

decr(stat, count=1, rate=1, buf=None, rate_applied=False)

Decrement a counter.

This is the opposite of incr().

set_add(stat, value, rate=1, buf=None, rate_applied=False)

Add a value to the set named by stat.

A StatsD set counts the unique occurrences of events (values) between flushes.

For example, if you wanted to count the number of different users logging in to an application within the sampling period, you could use something like:

def on_login(user_id):
    client.set_add("logged_in_users", user_id)

While this method accepts the rate parameter, it may be less useful here since the point is to let the StatsD server collect unique events automatically, and it can’t do that if some events are dropped, making it only an estimate.

Added in version 3.1.0.

sendbuf(buf)

Send a UDP packet containing string lines.

buf is a sequence of strings.

There are three implementations of this interface:

class perfmetrics.statsd.StatsdClient(host='localhost', port=8125, prefix='')

Bases: object

Send packets to statsd.

Default implementation of perfmetrics.interfaces.IStatsdClient.

Derived from statsd.py by Steve Ivy <steveivy@gmail.com>.

_send(data)

Send a UDP packet containing a string.

close()

See perfmetrics.interfaces.IStatsdClient.close().

Added in version 3.0.

decr(stat, count=1, rate=1, buf=None, rate_applied=False)

See perfmetrics.interfaces.IStatsdClient.decr().

gauge(stat, value, rate=1, buf=None, rate_applied=False)

See perfmetrics.interfaces.IStatsdClient.gauge().

incr(stat, count=1, rate=1, buf=None, rate_applied=False)

See perfmetrics.interfaces.IStatsdClient.incr().

sendbuf(buf)

See perfmetrics.interfaces.IStatsdClient.sendbuf().

set_add(stat, value, rate=1, buf=None, rate_applied=False)

See perfmetrics.interfaces.IStatsdClient.set_add().

timing(stat, value, rate=1, buf=None, rate_applied=False)

See perfmetrics.interfaces.IStatsdClient.timing().

class perfmetrics.statsd.StatsdClientMod(wrapped, format)

Bases: object

Wrap StatsdClient, modifying all stat names in context.

Changed in version 3.0: The wrapped object’s attributes are now accessible on this object.

This object now uses __slots__.

class perfmetrics.statsd.NullStatsdClient

Bases: object

No-op statsd client.

close()

Does nothing.

decr(stat, *args, **kw)

Does nothing.

gauge(stat, *args, **kw)

Does nothing.

incr(stat, *args, **kw)

Does nothing.

sendbuf(buf)

Does nothing

set_add(stat, value, *args, **kw)

Does nothing.

timing(stat, *args, **kw)

Does nothing.

Pyramid Integration

perfmetrics.includeme(config)

Pyramid configuration hook: activate the perfmetrics tween.

A statsd_uri should be in the settings.

perfmetrics.tween(handler, registry)

Pyramid tween that sets up a Statsd client for each request.

WSGI Integration

perfmetrics.make_statsd_app(nextapp, _globals=None, statsd_uri='')

Create a WSGI filter app that sets up Statsd for each request.

If no statsd_uri is given, returns nextapp unchanged.

Changed in version 3.0: The returned app callable makes the statsd client that it uses available at the statsd_client attribute.