util.statistics

This module allows you to gather various metrics inside the prosody process easily. It does not keep time time series data, only instant data, thus keeping memory use in check.

It is the reference implementation for a Statistics Backend and the documentation of this module shall serve as a reference of what interface a Statistics Backend needs to provide.

Statistics Backends are used by core.statsmanager to provide the metric() API for use within the Prosody core. It is also used to provide the module:metric() Module API for extension developers.

Creating a Statistics Backend

local backend = require \"util.statistics\".new();

This creates the a backend from the reference implementation. The reference implementation buffers the current metric values in-memory for use with periodic (such as Graphite/Carbon or InfluxDB) or pull-based exposition (such as Prometheus).

Note: For a reference implementation for a push-based backend (in this case StatsD), see util.statsd.

Statistics Backend API

Statistics Backends need to provide the following API.

backend.metric_registry

This is a OpenMetrics metric family registry. It is the entrypoint to declare new metrics in the backend for exposition.

backend:cork()

Halt pushing of any metrics.

This is seen by the backend as a hint to improve performance (think TCP corking) and not as a strict rule. Backends may choose to implement corking only up to a limited number of pending changes or restrict it to certain metric types.

While the output is corked, no metrics are pushed in a push-based backend. Pull-based or periodic backends may still transmit metrics.

The use case is to batch multiple small changes to metrics, avoiding many incremental updates from flooding a backend and causing many unnecessary syscalls.

This method is optional and may be left undefined (nil).

Note: The reference implementation in util.statistics does not provide corking, as it is not a push-based backend.

backend:uncork()

Resume pushing of any metrics to the backend.

This is the inverse of :cork(). It is safe to call :uncork() even if :cork() was not called before.

Calling :uncork() flushes all pending metric updates immediately.

This method is optional and may be left undefined (nil).

Note: The reference implementation in util.statistics does not provide corking, as it is not a push-based backend.