core.statsmanager

Configuration

See our documentation configuring statistics.

core.statsmanager relies on a Statistics Backend to provide its functionality. The API which needs to be offered by a Statistics Backend as well as a reference implementation is offered by util.statistics.

Reporting statistics

Reporting statistics from plugins is preferably done using the module:metric() Module API method. The module:metric() API has the same signature as the metric() API described below.

-- The final metric will be called
-- `prosody_mod_foo__inbound_connections_accepted_total` in accordance with
-- the OpenMetrics standard.
local metric = module:metric("counter", "inbound_connections_accepted", "", {"host"});
metric:with_labels("localhost"):add(1); -- adds 1 to the inbound_connections_accepted counter for host=localhost

To gain more control over the name used or to report metrics from other core modules, the statsmanager API can be used directly:

local custom_metric = require "core.statsmanager".metric;
-- The metric will be called `process_cpu_seconds_total` in accordance
-- with the OpenMetrics standard; note that no `prosody_` or `mod_` prefix
-- is added.
local cpu_time = custom_metric("counter", "process_cpu", "seconds"):with_labels();
cpu_time:set(os.clock())

To learn more about the OpenMetrics API offered in Prosody, see util.openmetrics.

To learn more about OpenMetrics general, please see openmetrics.io or the corresponding current Internet Draft.

metric(type_, name, unit, description, labels, extra)

Declare and return new metric (family).

Please see the module:metric() API documentation for details on the arguments. This low-level (statsmanager) API does not prefix the metric name, while that module API does (which is the key difference between the two).

In OpenMetrics terminology, this creates a new MetricFamily or reuses an existing one with the same name and signature.

Returns the declared MetricFamily.

Examples:

local custom_metric = require "core.statsmanager".custom_metric
local cpu_elapsed = custom_metric("counter", "process_cpu", "seconds", "CPU time used by Prosody")
local event_durations = custom_metric("histogram", "prosody_event_durations", "seconds", "Time taken in the respective events", { "event_type" }, { buckets = {0.0001, 0.1, 1.0, 10.0, 100.0 } })
local stanza_sizes = custom_metric("histogram", "stanza_sizes", "bytes", "Sizes of stanzas as received by prosody", { "host", "session_type" }, { buckets = {64, 1024, 65535, 1048576} })

-- example uses
cpu_elapsed:with_labels():set(os.clock())

-- record that server-started took 23.42s
event_durations:with_labels("server-started"):sample(23.42)

-- record a stanza of 1024 bytes on "localhost" in an "c2s" session
stanza_sizes:with_labels("localhost", "c2s"):sample(1024)

cork()

Enable inhibition of emission of metrics for push-based backends.

This should be taken as a hint. A backend may not implement corking for all metric types or at all.

This function is safe to call even if the backend does not implement corking.

uncork()

Disable inhibition of emission of metrics for push-based backends.

All metrics which were written and held back due to corking will be emitted immediately.

This function is safe to call without calling cork() first and on backends which do not support corking.

measure(stat_type, name, conf)

Declare a high-level metric and return the function which allows to sample the measurement.

Please see module:measure() for arguments, but mind that the type and name arguments are flipped.

Retrieving statistics

The function get_metric_registry() returns the OpenMetrics registry of the current statistics plugin. See the OpenMetrics API documentation for details.

Note: Statistics backends which are not internal may not support querying the current value of metrics or have other API limitations.

It is also possible to listen for the openmetrics-updated event to get notified about every completed metric collection run. The event receives the metric registry as metric_registry event table key.