API Reference¶
Decorators¶
- @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>
.
- @metricmethod¶
Like
@metric
, but the name of the Statsd metric is<class module>.<class name>.<method name>
.
- class Metric(stat=None, rate=1, method=False, count=True, timing=True)[source]¶
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 themethod
parameter is true, the default metric name is based on the method’s class name rather than the module name. Settingcount
to False disables the counter statistics sent to Statsd. Settingtiming
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 ofmetric
ormetricmethod
. 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
andmetric_rate
attributes that can be changed to alter its behaviour.
Functions¶
- 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.
- set_statsd_client(client_or_uri)[source]¶
Set the global StatsdClient.
The
client_or_uri
can be a StatsdClient, astatsd://
URI, or None.Note that when the perfmetrics module is imported, it looks for the
STATSD_URI
environment variable and callsset_statsd_client
if that variable is found.
- statsd_client_from_uri(uri)[source]¶
Create and return
perfmetrics.statsd.StatsdClient
.A typical URI is
statsd://localhost:8125
. An optional query parameter isprefix
. 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 IStatsdClient[source]¶
Interface to communicate with a StatsD server.
Most of the methods below have optional
rate
,rate_applied
, andbuf
parameters. Therate
parameter, when set to a value less than 1, causes StatsdClient to send a random sample of packets rather than every packet. Therate_applied
parameter, if true, informsStatsdClient
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 thebuf
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.
New in version 3.0.
- decr(stat, count=1, rate=1, buf=None, rate_applied=False)¶
Decrement a counter.
This is the opposite of
incr()
.
- 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.
- sendbuf(buf)¶
Send a UDP packet containing string lines.
buf is a sequence of strings.
- 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.
New in version 3.1.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.
There are three implementations of this interface:
- class StatsdClient(host='localhost', port=8125, prefix='')[source]¶
Bases:
object
Send packets to statsd.
Default implementation of
perfmetrics.interfaces.IStatsdClient
.Derived from statsd.py by Steve Ivy <steveivy@gmail.com>.
- close()[source]¶
See
perfmetrics.interfaces.IStatsdClient.close()
.New in version 3.0.
- class StatsdClientMod(wrapped, format)[source]¶
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__
.
Pyramid Integration¶
WSGI Integration¶
- make_statsd_app(nextapp, _globals=None, statsd_uri='')[source]¶
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.