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)[source]#

Bases: object

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


the elapsed time at the point of completion




Start the timer


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)[source]#

Bases: object

Initialize a client to send metrics to a StatsD server.

  • 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


This class also supports the following environment variables:


Override the default host of the statsd server


Override the default port of the statsd server


Tags to attach to every metric reported. Example value:


gauge(metric, value, tags=None, sample_rate=1)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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

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

# Is equivalent to ...
start = time.monotonic()
    statsd.timing('user.query.time', time.monotonic() - start)
set(metric, value, tags=None, sample_rate=1)[source]#

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 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)

Flush the buffer and switch back to single metric packets.


Closes connected socket if connected.

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

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:
        # ...
        # ...