swh.core.statsd module

swh.core.statsd.random() → x in the interval [0, 1).

class swh.core.statsd.TimedContextManagerDecorator(statsd, metric=None, error_metric=None, tags=None, sample_rate=1)

Bases: object

A context manager and a decorator which will report the elapsed time in the context OR in a function call.

elapsed

elapsed time (in ms) during the last call or context execution.

Type:

float

total_elapsed

total time (in ms) spent in a function, or in a context if the context instance is reused.

Type:

float

start()

Start the timer

stop()

Stop the timer, send the metric value

class swh.core.statsd.Statsd(*, host=None, port=None, max_buffer_size=50, namespace=None, constant_tags=None)

Bases: object

Initialize a client to send metrics to a StatsD server.

Parameters:

• host (str) – the host of the StatsD server. Defaults to localhost.

• port (int) – the port of the StatsD server. Defaults to 8125.

• max_buffer_size (int) – Maximum number of metrics to buffer before sending to the server if sending metrics in batch

• namespace (str) – Namespace to prefix all metric names

• constant_tags (Dict[str, str]) – Tags to attach to all metrics

Note

This class also supports the following environment variables:

STATSD_HOST

Override the default host of the statsd server

STATSD_PORT

Override the default port of the statsd server

STATSD_TAGS

Tags to attach to every metric reported. Example value:

“label:value,other_label:other_value”

gauge(metric, value, tags=None, sample_rate=1)

Record the value of a gauge, optionally setting a list of tags and a sample rate.

>>> statsd.gauge('users.online', 123)
>>> statsd.gauge('active.connections', 1001, tags={"protocol": "http"})

increment(metric, value=1, tags=None, sample_rate=1)

Increment a counter, optionally setting a value, tags and a sample rate.

>>> statsd.increment('page.views')
>>> statsd.increment('files.transferred', 124)

decrement(metric, value=1, tags=None, sample_rate=1)

Decrement a counter, optionally setting a value, tags and a sample rate.

>>> statsd.decrement('files.remaining')
>>> statsd.decrement('active.connections', 2)

histogram(metric, value, tags=None, sample_rate=1)

Sample a histogram value, optionally setting tags and a sample rate.

>>> statsd.histogram('uploaded.file.size', 1445)
>>> statsd.histogram('file.count', 26, tags={"filetype": "python"})

timing(metric, value, tags=None, sample_rate=1)

Record a timing, optionally setting tags and a sample rate.

>>> statsd.timing("query.response.time", 1234)

timed(metric=None, error_metric=None, tags=None, sample_rate=1)

A decorator or context manager that will measure the distribution of a function’s/context’s run time. Optionally specify a list of tags or a sample rate. If the metric is not defined as a decorator, the module name and function name will be used. The metric is required as a context manager.

@statsd.timed('user.query.time', sample_rate=0.5)
def get_user(user_id):
    # Do what you need to ...
    pass

# Is equivalent to ...
with statsd.timed('user.query.time', sample_rate=0.5):
    # Do what you need to ...
    pass

# Is equivalent to ...
start = time.monotonic()
try:
    get_user(user_id)
finally:
    statsd.timing('user.query.time', time.monotonic() - start)

set(metric, value, tags=None, sample_rate=1)

Sample a set value.

>>> statsd.set('visitors.uniques', 999)

property socket

Return a connected socket.

Note: connect the socket before assigning it to the class instance to avoid bad thread race conditions.

open_buffer(max_buffer_size=50)

Open a buffer to send a batch of metrics in one packet.

You can also use this as a context manager.

>>> with Statsd() as batch:
...     batch.gauge('users.online', 123)
...     batch.gauge('active.connections', 1001)

close_buffer()

Flush the buffer and switch back to single metric packets.

close_socket()

Closes connected socket if connected.

status_gauge(metric_name: str, statuses: Collection[str], tags: Dict[str, str] | None = None)

Context manager to keep track of status changes as a gauge

In addition to the metric_name and tags arguments, it expects a list of statuses to declare which statuses are possible, and returns a callable as context manager. This callable takes ones of the possible statuses as argument. Typical usage would be:

>>> with statsd.status_gauge(
            "metric_name", ["starting", "processing", "waiting"]) as set_status:
        set_status("starting")
        # ...
        set_status("waiting")
        # ...