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)[source]¶ 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.
-
class
baseplate.lib.metrics.
Client
(transport, namespace)[source]¶ A client for StatsD.
-
batch
()[source]¶ 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
-
counter
(name, tags=None)¶ Return a Counter with the given name.
The sample rate is currently up to your application to enforce.
-
gauge
(name, tags=None)¶ Return a Gauge with the given name.
-
histogram
(name, tags=None)¶ Return a Histogram with the given name.
-
-
class
baseplate.lib.metrics.
Batch
(transport, namespace)[source]¶ 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 automaticallyflush()
.-
counter
(name, tags=None)[source]¶ 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
-
gauge
(name, tags=None)¶ Return a Gauge with the given name.
-
histogram
(name, tags=None)¶ Return a Histogram with the given name.
-
Metrics¶
-
class
baseplate.lib.metrics.
Counter
(transport, name, tags=None)[source]¶ A counter for counting events over time.
-
decrement
(delta=1.0, sample_rate=1.0)[source]¶ Decrement the counter.
This is equivalent to
increment()
with delta negated.- Return type
-
-
class
baseplate.lib.metrics.
Timer
(transport, name, tags=None)[source]¶ 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 willstart()
and when exited, the timer will automaticallystop()
.
-
class
baseplate.lib.metrics.
Gauge
(transport, name, tags=None)[source]¶ 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.
-
class
baseplate.lib.metrics.
Histogram
(transport, name, tags=None)[source]¶ 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
.