Define the data types used in Statsd. Each data type is defined as a class, supported data types are:
~metrics.Counter
~metrics.Timer
~metrics.Gauge
~metrics.Set
~metrics.GaugeDelta
Note
The metric classes and helper functions are available from the package directly, but internally they are defined in metrics
module. So there is no need to import the metrics
module direcly, unless you're trying to access those objects that are not used reguraly and hence are not exported, like the ~metrics.AbstractMetric
class.
Each metric requires a name and a value.
from statsdmetrics import Counter, Timer
counter = Counter('event.login', 1)
timer = Timer('db.query.user', 10)
An optional sample rate can be specified for the metrics. Sample rate is used by the client and the server to help to reduce network traffic, or reduce the load on the server.
>>> from statsdmetrics import Counter
>>> counter = Counter('event.login', 1, 0.2)
>>> counter.name
'event.login'
>>> counter.count
1
>>> counter.sample_rate
0.2
All metrics have ~metrics.AbstractMetric.name
and ~metrics.AbstractMetric.sample_rate
properties, but they store their value in different properties.
Metrics provide ~metrics.AbstractMetric.to_request
method to create the proper value used to send the metric to the server.
>>> from statsdmetrics import Counter, Timer, Gauge, Set, GaugeDelta
>>> counter = Counter('event.login', 1, 0.2)
>>> counter.to_request()
'event.login:1|c|@0.2'
>>> timer = Timer('db.query.user', 10, 0.5)
>>> timer.to_request()
'db.query.user:10|ms|@0.5'
>>> gauge = Gauge('memory', 20480)
>>> gauge.to_request()
'memory:20480|g'
>>> set_ = Set('unique.users', 'first')
>>> set_.to_request()
'unique.users:first|s'
>>> delta = GaugeDelta('memory', 128)
>>> delta.to_request()
'memory:+128|g'
>>> delta.delta = -256
>>> delta.to_request()
'memory:-256|g'
metrics
Farzad Ghanei
Abstract class that all metric classes would extend from
name
the name of the metric
sample_rate
the rate of sampling that the client considers when sending metrics
to_request() -> str
return the string that is used in the Statsd request to send the metric
A metric to count events
count
current count of events being reporeted via the metric
A metric for timing durations, in milliseconds.
milliseconds
number of milliseconds for the duration
Any arbitrary value, like the memory usage in bytes.
value
the value of the metric
A set of unique values counted on the server side for each sampling period. Techincally the value could be anything that can be serialized to a string (to be sent on the request).
value
the value of the metric
A value change in a gauge, could be a positive or negative numeric value.
delta
the difference in the value of the gauge
normalize_metric_name(name) -> str
normalize a metric name, removing characters that might not be welcome by common backends.
>>> from statsdmetrics import normalize_metric_name
>>> normalize_metric_name("will replace some, and $remove! others*")
'will_replace_some_and_remove_others'
If passed argument is not a string, an TypeError
is raised.
parse_metric_from_request(request) -> str
parse a metric object from a request string.
>>> from statsdmetrics import parse_metric_from_request
>>> metric = parse_metric_from_request("memory:2048|g")
>>> type(metric)
<class 'statsdmetrics.metrics.Gauge'>
>>> metric.name, metric.value, metric.sample_rate
('memory', 2048.0, 1)
>>> metric = parse_metric_from_request('event.connections:-2|c|@0.6')
>>> type(metric)
<class 'statsdmetrics.metrics.Counter'>
>>> metric.name, metric.count, metric.sample_rate
('event.connections', -2, 0.6)
If the request is invalid, a ValueError
is raised.