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: - namespace (str) – The root key to prefix all metrics with.
- endpoint (baseplate.config.EndpointConfiguration) – The endpoint to
send metrics to or
None
. IfNone
, the returned client will discard all metrics.
Returns: A configured client.
Return type: See also
-
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
-
-
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 automaticallyflush()
.-
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
-
Metrics¶
-
class
baseplate.metrics.
Counter
¶ A counter for counting events over time.
-
increment
(delta=1, sample_rate=1.0)¶ Increment the counter.
Parameters:
-
decrement
(delta=1, sample_rate=1.0)¶ Decrement the counter.
This is equivalent to
increment()
with delta negated.
-
-
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 willstart()
and when exited, the timer will automaticallystop()
.-
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.
-