Reference Documentation¶

This library defines mix-ins that record application metrics. Each mix-in implements the same interface:

class sprockets.mixins.metrics.Mixin¶

SETTINGS_KEY¶: Key in self.application.settings that contains this particular mix-in’s configuration data.

record_timing(duration, *path)

Parameters:	duration (float) – number of seconds to record path – timing path to record

self.record_timing(self.request.request_time(), 'request', 'lookup')

increase_counter(*path, amount=1)

Parameters:	path – counter path to increment amount (int) – value to increase the counter by

self.increase_counter('db', 'query', 'foo')

execution_timer(*path)

Parameters:	path – timing path to record

This method returns a context manager that records a timing metric to the specified path.

with self.execution_timer('db', 'query', 'foo'):
    rows = yield self.session.query('SELECT * FROM foo')

Statsd Implementation¶

class sprockets.mixins.metrics.statsd.StatsdMixin[source]¶

Mix this class in to record metrics to a Statsd server.

execution_timer(*path)[source]¶

Record the time it takes to perform an arbitrary code block.

Parameters:	path – elements of the metric path to record

This method returns a context manager that records the amount of time spent inside of the context and submits a timing metric to the specified path using (record_timing()).

increase_counter(*path, **kwargs)[source]¶

Increase a counter.

This method increases a counter within the application’s namespace. Each element of path is converted to a string and normalized before joining the elements by periods. The normalization process is little more than replacing periods with dashes.

Parameters:	path – elements of the metric path to incr amount (int) – amount to increase the counter by. If omitted, the counter is increased by one.

on_finish()[source]¶

Records the time taken to process the request.

This method records the amount of time taken to process the request (as reported by request_time()) under the path defined by the class’s module, it’s name, the request method, and the status code. The record_timing() method is used to send the metric, so the configured namespace is used as well.

record_timing(duration, *path)[source]¶

Record a timing.

This method records a timing to the application’s namespace followed by a calculated path. Each element of path is converted to a string and normalized before joining the elements by periods. The normalization process is little more than replacing periods with dashes.

Parameters:	duration (float) – timing to record in seconds path – elements of the metric path to record

class sprockets.mixins.metrics.statsd.StatsDCollector(host, port, protocol='udp', namespace='sprockets', prepend_metric_type=True)[source]¶

Collects and submits stats to StatsD.

This class should be constructed using the install() function. When installed, it is attached to the Application instance for your web application.

Parameters:	host (str) – The StatsD host port (str) – The StatsD port protocol (str) – The StatsD protocol. May be either `udp` or `tcp`. namespace (str) – The StatsD bucket to write metrics into. prepend_metric_type (bool) – Optional flag to prepend bucket path with the StatsD metric type

close()[source]¶: Gracefully close the socket.

send(path, value, metric_type)[source]¶

Send a metric to Statsd.

Parameters:	path (list) – The metric path to record value (mixed) – The value to record metric_type (str) – The metric type

Application Functions¶

Before you can use the mixin, you have to install the client by calling the install function on your application instance.

sprockets.mixins.metrics.statsd.install(application, **kwargs)[source]¶

Call this to install StatsD for the Tornado application.

Parameters:	application (tornado.web.Application) – the application to install the collector into. kwargs – keyword parameters to pass to the `StatsDCollector` initializer.
Returns:	`True` if the client was installed successfully, or `False` otherwise.

host The StatsD host. If host is not specified, the

STATSD_HOST environment variable, or default 127.0.0.1, will be pass into the StatsDCollector.
port The StatsD port. If port is not specified, the

STATSD_PORT environment variable, or default 8125, will be pass into the StatsDCollector.
namespace The StatsD bucket to write metrics into.

sprockets.mixins.metrics.statsd.get_client(application)[source]¶

Fetch the statsd client if it is installed.

Return type:	StatsDCollector

Testing Helpers¶

So who actually tests that their metrics are emitted as they expect?

Usually the answer is no one. Why is that? The testing module contains some helper that make testing a little easier.

class sprockets.mixins.metrics.testing.FakeStatsdServer(iol, protocol='udp')[source]¶

Implements something resembling a statsd server.

Parameters:	iol (tornado.ioloop.IOLoop) – the loop to attach to protocol (str) – The StatsD protocol. May be either `udp` or `tcp`.

Create an instance of this class in your asynchronous test case attached to the IOLoop and configure your application to send metrics to it. The received datagrams are available in the datagrams attribute for validation in your tests.

sockaddr¶: The socket address that the server is listening on. This is a tuple returned from socket.socket.getsockname().

datagrams¶: A list of datagrams that have been received by the server.

find_metrics(prefix, metric_type)[source]¶

Yields captured datagrams that start with prefix.

Parameters:	prefix (str) – the metric prefix to search for metric_type (str) – the statsd metric type (e.g., ‘ms’, ‘c’)
Returns:	yields (path, value, metric_type) tuples for each captured metric that matches
Raises:	AssertionError – if no metrics match.

handle_stream(stream, address)[source]¶

Override to handle a new .IOStream from an incoming connection.

This method may be a coroutine; if so any exceptions it raises asynchronously will be logged. Accepting of incoming connections will not be blocked by this coroutine.

If this TCPServer is configured for SSL, handle_stream may be called before the SSL handshake has completed. Use .SSLIOStream.wait_for_handshake if you need to verify the client’s certificate or use NPN/ALPN.

Changed in version 4.2: Added the option for this method to be a coroutine.