baseplate.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 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.metrics.make_client(namespace, endpoint)

Return a configured client.

Parameters:
Returns:

A configured client.

Return type:

baseplate.metrics.Client

class baseplate.metrics.Client

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)

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)

Return a Gauge with the given name.

Parameters:name (str) – The name the gauge should have.
Return type:Gauge
histogram(name)

Return a Histogram with the given name.

Parameters:name (str) – The name the histogram should have.
Return type:Histogram
timer(name)

Return a Timer with the given name.

Parameters:name (str) – The name the timer should have.
Return type:Timer
class baseplate.metrics.Batch

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.

counter(name)

Return a BatchCounter 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)

Return a Gauge with the given name.

Parameters:name (str) – The name the gauge should have.
Return type:Gauge
histogram(name)

Return a Histogram with the given name.

Parameters:name (str) – The name the histogram should have.
Return type:Histogram
timer(name)

Return a Timer with the given name.

Parameters:name (str) – The name the timer should have.
Return type:Timer

Metrics

class baseplate.metrics.Counter

A counter for counting events over time.

increment(delta=1, 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].
decrement(delta=1, sample_rate=1.0)

Decrement the counter.

This is equivalent to increment() with delta negated.

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].
class baseplate.metrics.Timer

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()

Record the current time as the start of the timer.

stop()

Stop the timer and record the total elapsed time.

class baseplate.metrics.Gauge

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.
class baseplate.metrics.Histogram

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.