Welcome to Statsd Metrics’s documentation!¶

Metric Classes¶

class metrics.AbstractMetric¶

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

class metrics.Counter(name, count[, sample_rate])¶

A metric to count events

count¶

current count of events being reporeted via the metric

class metrics.Timer(name, milliseconds[, sample_rate])¶

A metric for timing durations, in milliseconds.

milliseconds¶

number of milliseconds for the duration

class metrics.Gauge(name, value[, sample_rate])¶

Any arbitrary value, like the memory usage in bytes.

value¶

the value of the metric

class metrics.Set(name, value[, sample_rate])¶

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

class metrics.GaugeDelta(name, delta[, sample_rate])¶

A value change in a gauge, could be a positive or negative numeric value.

delta¶

the difference in the value of the gauge

Module functions¶

metrics.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.

metrics.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.

Examples¶

from statsdmetrics.client import Client
client = Client("stats.example.org")
client.increment("login")
client.timing("db.search.username", 3500)
client.prefix = "other"
client.gauge_delta("memory", -256)
client.decrement(name="connections", count=2)

from statsdmetrics.client import Client

client = Client("stats.example.org")
with client.batch_client() as batch_client:
    batch_client.increment("login")
    batch_client.decrement(name="connections", count=2)
    batch_client.timing("db.search.username", 3500)
# now all metrics are flushed automatically in batch requests

class client.BatchClient(host, port=8125, prefix='', batch_size=512)¶

Statsd client that buffers all metrics and sends them in batch requests over UDP when instructed to flush the metrics explicitly.

Each UDP request might contain multiple metrics, but limited to a certain batch size to avoid UDP fragmentation.

The size of batch requests is not the fixed size of the requests, since metrics can not be broken into multiple requests. So if adding a new metric overflows this size, then that metric will be sent in a new batch request.

batch_size¶

Size of each batch request. This property is readonly.

clear()¶

Clear buffered metrics

flush()¶

Send the buffered metrics in batch requests.

unit_client()¶

Create a Client object, using the same configurations of current batch client to send the metrics on each request. The client uses the same resources as the batch client.

from statsdmetrics.client import BatchClient

client = BatchClient("stats.example.org")
client.set("unique.ip_address", "10.10.10.1")
client.gauge("memory", 20480)
client.flush() # sends one UDP packet to remote server, carrying both metrics

Examples¶

from statsdmetrics.client.tcp import TCPClient
client = TCPClient("stats.example.org")
client.increment("login")
client.timing("db.search.username", 3500)
client.prefix = "other"
client.gauge_delta("memory", -256)
client.decrement(name="connections", count=2)

from statsdmetrics.client.tcp import TCPClient

client = TCPClient("stats.example.org")
with client.batch_client() as batch_client:
    batch_client.increment("login")
    batch_client.decrement(name="connections", count=2)
    batch_client.timing("db.search.username", 3500)
# now all metrics are flushed automatically in batch requests

class client.tcp.TCPBatchClient(host, port=8125, prefix='', batch_size=512)¶

Statsd client that buffers all metrics and sends them in batch requests over TCP when instructed to flush the metrics explicitly.

Provides the same interface as BatchClient.

from statsdmetrics.client.tcp import TCPBatchClient

client = TCPBatchClient("stats.example.org")
client.set("unique.ip_address", "10.10.10.1")
client.gauge("memory", 20480)
client.flush() # sends one TCP packet to remote server, carrying both metrics

Examples¶

from time import time, sleep
from statsdmetrics.client import Client
from statsdmetrics.client.timing import Chronometer

start_time = time()
client = Client("stats.example.org")
chronometer = Chronometer(client)
chronometer.since("instantiate", start_time)

def wait(secs):
    sleep(secs) # or any timed operation

chronometer.time_callable("waited", wait, args=(0.56,))

@chronometer.wrap("wait_decorated")
def another_wait(secs):
    sleep(secs) # or any timed operation

another_wait(0.23) # sends the "wait_decorated" Timer metric
chronometer.since("overall", start_time)

If a batch client (like client.BatchClient or client.tcp.TCPBatchClient) is used, then the behavior of the client requires an explicit flush() call.

from datetime import datetime
from statsdmetrics.client.tcp import TCPBatchCPClient
from statsdmetrics.client.timing import Chronometer

start_time = datetime.now()
client = TCPBatchClient("stats.example.org")
chronometer = Chronometer(client)
chronometer.since("instantiate", start_time)

def wait_with_kwargs(name, key=val):
    sleep(1) # or any timed operation

chronometer.time_callable("waited", wait_with_kwargs, kwargs=dict(name="foo", key="bar"))
client.flush()

class client.timing.Stopwatch(client, name, rate=1, reference=None)¶

Stopwatch calculates duration passed from a given reference time (by default uses the instantiation time) for a specific metric name. So time passed since the reference time can be sent multiple times. Normally these is no need to instantiate this class directly, but you can call client.Client.stopwatch() on any client, to get a configured Chronometer.

client¶

The client used to send the timing metrics. This can be any client from client package.

name¶

The name for the metric sent by the stopwatch.

rate¶

The default sample rate for metrics to send. Should be a float between 0 and 1. This is the same as used in all clients.

reference¶

The time reference that duration is calculated from. It’s a float value of seconds passed since epoch, same as time.time().

reset()¶

Reset the stopwatch, updating the reference with current time. Returns a self reference for method chaining.

send(rate=None)¶

Calculate time passed since reference and send the metric. A sampling rate can be specified, or None (default) uses the default sampling rate of the stopwatch. Returns a self reference for method chaining.

Examples¶

from time import time, sleep
from statsdmetrics.client import Client
from statsdmetrics.client.timing import Stopwatch

start_time = time()
client = Client("stats.example.org")
stopwatch = Stopwatch(client, "process", start_time)

sleep(2) # do stuff
stopwatch.send()
sleep(1) # do other stuff
stopwatch.send()

If a batch client (like client.BatchClient or client.tcp.TCPBatchClient) is used, then the behavior of the client requires an explicit flush() call.

from datetime import datetime
from statsdmetrics.client.tcp import TCPBatchCPClient
from statsdmetrics.client.timing import Stopwatch

start_time = time()
client = TCPBatchClient("stats.example.org")
stopwatch = Stopwatch(client, "process", start_time)

sleep(3) # do stuff
stopwatch.send()
sleep(1) # do other stuff
stopwatch.send()

client.flush()

Stopwatch is a context manager, so can be used to measure duration of a with block

from time import time, sleep
from statsdmetrics.client import Client
from statsdmetrics.client.timing import Stopwatch

client = Client("stats.example.org")
with client.stopwatch("some_block"):
    sleep(3) # do stuff in the context

# now a Timer metric named "some_block" is sent, whose value is the duration of the block