baseplate.lib.metrics

Application metrics via StatsD.

A client for the application metrics aggregator StatsD. Metrics sent to StatsD are aggregated and written to graphite. StatsD is generally used for whole-system health monitoring and insight into usage patterns.

Basic example usage:

from baseplate.lib.metrics import metrics_client_from_config

client = metrics_client_from_config(app_config)
client.counter("events.connect").increment()
client.gauge("workers").replace(4)

with client.timer("something.todo"):
    do_something()
    do_something_else()

If you have multiple metrics to send, you can batch them up for efficiency:

with client.batch() as batch:
    batch.counter("froozles").increment()
    batch.counter("blargs").decrement(delta=3)

    with batch.timer("something"):
        do_another_thing()

and the batch will be sent in as few packets as possible when the with block ends.

Clients

baseplate.lib.metrics.metrics_client_from_config(raw_config)

Configure and return a metrics client.

This expects two configuration options:

metrics.namespace

The root key to prefix all metrics in this application with.

metrics.endpoint

A host:port pair, e.g. localhost:2014. If an empty string, a client that discards all metrics will be returned.

metrics.log_if_unconfigured`

Whether to log metrics when there is no unconfigured endpoint. Defaults to false.

metrics.swallow_network_errors`

When false, network errors during sending to metrics collector will cause an exception to be thrown. When true, those exceptions are logged and swallowed instead. Defaults to false.

Parameters:

raw_config (Dict[str, str]) – The application configuration which should have settings for the metrics client.

Return type:

Client

Returns:

A configured client.

class baseplate.lib.metrics.Client(transport, namespace)

A client for StatsD.

batch()

Return a client-like object which batches up metrics.

Batching metrics can reduce the number of packets that are sent to the stats aggregator.

Return type:

Batch

counter(name, tags=None)

Return a Counter with the given name.

The sample rate is currently up to your application to enforce.

Parameters:

name (str) – The name the counter should have.

Return type:

Counter

gauge(name, tags=None)

Return a Gauge with the given name.

Parameters:

name (str) – The name the gauge should have.

Return type:

Gauge

histogram(name, tags=None)

Return a Histogram with the given name.

Parameters:

name (str) – The name the histogram should have.

Return type:

Histogram

timer(name, tags=None)

Return a Timer with the given name.

Parameters:

name (str) – The name the timer should have.

Return type:

Timer

class baseplate.lib.metrics.Batch(transport, namespace)

A batch of metrics to send to StatsD.

The batch also supports the context manager protocol, for use with Python’s with statement. When the context is exited, the batch will automatically flush().

flush()

Immediately send the batched metrics.

Return type:

None

counter(name, tags=None)

Return a BatchCounter with the given name.

The sample rate is currently up to your application to enforce. :type name: str :param name: The name the counter should have.

Return type:

Counter

gauge(name, tags=None)

Return a Gauge with the given name.

Parameters:

name (str) – The name the gauge should have.

Return type:

Gauge

histogram(name, tags=None)

Return a Histogram with the given name.

Parameters:

name (str) – The name the histogram should have.

Return type:

Histogram

timer(name, tags=None)

Return a Timer with the given name.

Parameters:

name (str) – The name the timer should have.

Return type:

Timer

Metrics

class baseplate.lib.metrics.Counter(transport, name, tags=None)

A counter for counting events over time.

increment(delta=1.0, sample_rate=1.0)

Increment the counter.

Parameters:

• delta (float) – The amount to increase the counter by.

• sample_rate (float) – What rate this counter is sampled at. [0-1].

Return type:

None

decrement(delta=1.0, sample_rate=1.0)

Decrement the counter.

This is equivalent to increment() with delta negated.

Return type:

None

send(delta, sample_rate)

Send the counter to the backend.

Parameters:

• delta (float) – The amount to increase the counter by.

• sample_rate (float) – What rate this counter is sampled at. [0-1].

Return type:

None

class baseplate.lib.metrics.Timer(transport, name, tags=None)

A timer for recording elapsed times.

The timer also supports the context manager protocol, for use with Python’s with statement. When the context is entered the timer will start() and when exited, the timer will automatically stop().

start(sample_rate=1.0)

Record the current time as the start of the timer.

Return type:

None

stop()

Stop the timer and record the total elapsed time.

Return type:

None

send(elapsed, sample_rate=1.0)

Directly send a timer value without having to stop/start.

This can be useful when the timing was managed elsewhere and we just want to report the result. :type elapsed: float :param elapsed: The elapsed time in seconds to report.

Return type:

None

class baseplate.lib.metrics.Gauge(transport, name, tags=None)

A gauge representing an arbitrary value.

Note

The StatsD protocol supports incrementing/decrementing gauges from their current value. We do not support that here because this feature is unpredictable in face of the StatsD server restarting and the “current value” being lost.

replace(new_value)

Replace the value held by the gauge.

This will replace the value held by the gauge with no concern for its previous value.

Note

Due to the way the protocol works, it is not possible to replace gauge values with negative numbers.

Parameters:

new_value (float) – The new value to store in the gauge.

Return type:

None

class baseplate.lib.metrics.Histogram(transport, name, tags=None)

A bucketed distribution of integer values across a specific range.

Records data value counts across a configurable integer value range with configurable buckets of value precision within that range.

Configuration of each histogram is managed by the backend service, not by this interface. This implementation also depends on histograms being supported by the StatsD backend. Specifically, the StatsD backend must support the h key, e.g. metric_name:320|h.

add_sample(value)

Add a new value to the histogram.

This records a new value to the histogram; the bucket it goes in is determined by the backend service configurations.

Return type:

None