Statistics: Rewrite statistics backends to use OpenMetrics
The metric subsystem of Prosody has had some shortcomings from
the perspective of the current state-of-the-art in metric
observability.
The OpenMetrics standard [0] is a formalization of the data
model (and serialization format) of the well-known and
widely-used Prometheus [1] software stack.
The previous stats subsystem of Prosody did not map well to that
format (see e.g. [2] and [3]); the key reason is that it was
trying to do too much math on its own ([2]) while lacking
first-class support for "families" of metrics ([3]) and
structured metric metadata (despite the `extra` argument to
metrics, there was no standard way of representing common things
like "tags" or "labels").
Even though OpenMetrics has grown from the Prometheus world of
monitoring, it maps well to other popular monitoring stacks
such as:
- InfluxDB (labels can be mapped to tags and fields as necessary)
- Carbon/Graphite (labels can be attached to the metric name with
dot-separation)
- StatsD (see graphite when assuming that graphite is used as
backend, which is the default)
The util.statsd module has been ported to use the OpenMetrics
model as a proof of concept. An implementation which exposes
the util.statistics backend data as Prometheus metrics is
ready for publishing in prosody-modules (most likely as
mod_openmetrics_prometheus to avoid breaking existing 0.11
deployments).
At the same time, the previous measure()-based API had one major
advantage: It is really simple and easy to use without requiring
lots of knowledge about OpenMetrics or similar concepts. For that
reason as well as compatibility with existing code, it is preserved
and may even be extended in the future.
However, code relying on the `stats-updated` event as well as
`get_stats` from `statsmanager` will break because the data
model has changed completely; in case of `stats-updated`, the
code will simply not run (as the event was renamed in order
to avoid conflicts); the `get_stats` function has been removed
completely (so it will cause a traceback when it is attempted
to be used).
Note that the measure_*_event methods have been removed from
the module API. I was unable to find any uses or documentation
and thus deemed they should not be ported. Re-implementation is
possible when necessary.
[0]: https://openmetrics.io/
[1]: https://prometheus.io/
[2]: #959
[3]: #960
--[[
This module implements a subset of the OpenMetrics Internet Draft version 00.
URL: https://tools.ietf.org/html/draft-richih-opsawg-openmetrics-00
The following metric types are supported:
- Counter
- Gauge
- Histogram
- Summary
It is used by util.statsd and util.statistics to provite the OpenMetrics API.
To understand what this module is about, it is useful to familiarize oneself
with the terms MetricFamily, Metric, LabelSet, Label and MetricPoint as
defined in the I-D linked above.
--]]
-- metric constructor interface:
-- metric_ctor(..., family_name, labels, extra)
local time = require "util.time".now;
local select = select;
local array = require "util.array";
local log = require "util.logger".init("util.openmetrics");
local new_multitable = require "util.multitable".new;
local iter_multitable = require "util.multitable".iter;
-- BEGIN of Utility: "metric proxy"
-- This allows to wrap a MetricFamily in a proxy which only provides the
-- `with_labels` and `with_partial_label` methods. This allows to pre-set one
-- or more labels on a metric family. This is used in particular via
-- `with_partial_label` by the moduleapi in order to pre-set the `host` label
-- on metrics created in non-global modules.
local metric_proxy_mt = {}
metric_proxy_mt.__index = metric_proxy_mt
local function new_metric_proxy(metric_family, with_labels_proxy_fun)
return {
_family = metric_family,
with_labels = function(self, ...)
return with_labels_proxy_fun(self._family, ...)
end;
with_partial_label = function(self, label)
return new_metric_proxy(self._family, function(family, ...)
return family:with_labels(label, ...)
end)
end
}
end
-- END of Utility: "metric proxy"
local function render_histogram_le(v)
if v == 1/0 then
-- I-D-00: 4.1.2.2.1:
-- Exposers MUST produce output for positive infinity as +Inf.
return "+Inf"
end
return string.format("%g", v)
end
-- BEGIN of generic MetricFamily implementation
local metric_family_mt = {}
metric_family_mt.__index = metric_family_mt
local function histogram_metric_ctor(orig_ctor, buckets)
return function(family_name, labels, extra)
return orig_ctor(buckets, family_name, labels, extra)
end
end
local function new_metric_family(backend, type_, family_name, unit, description, label_keys, extra)
local metric_ctor = assert(backend[type_], "statistics backend does not support "..type_.." metrics families")
local labels = label_keys or {}
local user_labels = #labels
if type_ == "histogram" then
local buckets = extra and extra.buckets
if not buckets then
error("no buckets given for histogram metric")
end
buckets = array(buckets)
buckets:push(1/0) -- must have +inf bucket
metric_ctor = histogram_metric_ctor(metric_ctor, buckets)
end
local data
if #labels == 0 then
data = metric_ctor(family_name, nil, extra)
else
data = new_multitable()
end
local mf = {
family_name = family_name,
data = data,
type_ = type_,
unit = unit,
description = description,
user_labels = user_labels,
label_keys = labels,
extra = extra,
_metric_ctor = metric_ctor,
}
setmetatable(mf, metric_family_mt);
return mf
end
function metric_family_mt:new_metric(labels)
return self._metric_ctor(self.family_name, labels, self.extra)
end
function metric_family_mt:clear()
for _, metric in self:iter_metrics() do
metric:reset()
end
end
function metric_family_mt:with_labels(...)
local count = select('#', ...)
if count ~= self.user_labels then
error("number of labels passed to with_labels does not match number of label keys")
end
if count == 0 then
return self.data
end
local metric = self.data:get(...)
if not metric then
local values = table.pack(...)
metric = self:new_metric(values)
values[values.n+1] = metric
self.data:set(table.unpack(values, 1, values.n+1))
end
return metric
end
function metric_family_mt:with_partial_label(label)
return new_metric_proxy(self, function (family, ...)
return family:with_labels(label, ...)
end)
end
function metric_family_mt:iter_metrics()
if #self.label_keys == 0 then
local done = false
return function()
if done then
return nil
end
done = true
return {}, self.data
end
end
local searchkeys = {};
local nlabels = #self.label_keys
for i=1,nlabels do
searchkeys[i] = nil;
end
local it, state = iter_multitable(self.data, table.unpack(searchkeys, 1, nlabels))
return function(_s)
local label_values = table.pack(it(_s))
if label_values.n == 0 then
return nil, nil
end
local metric = label_values[label_values.n]
label_values[label_values.n] = nil
label_values.n = label_values.n - 1
return label_values, metric
end, state
end
-- END of generic MetricFamily implementation
-- BEGIN of MetricRegistry implementation
-- Helper to test whether two metrics are "equal".
local function equal_metric_family(mf1, mf2)
if mf1.type_ ~= mf2.type_ then
return false
end
if #mf1.label_keys ~= #mf2.label_keys then
return false
end
-- Ignoring unit here because in general it'll be part of the name anyway
-- So either the unit was moved into/out of the name (which is a valid)
-- thing to do on an upgrade or we would expect not to see any conflicts
-- anyway.
--[[
if mf1.unit ~= mf2.unit then
return false
end
]]
for i, key in ipairs(mf1.label_keys) do
if key ~= mf2.label_keys[i] then
return false
end
end
return true
end
-- If the unit is not empty, add it to the full name as per the I-D spec.
local function compose_name(name, unit)
local full_name = name
if unit and unit ~= "" then
full_name = full_name .. "_" .. unit
end
-- TODO: prohibit certain suffixes used by metrics if where they may cause
-- conflicts
return full_name
end
local metric_registry_mt = {}
metric_registry_mt.__index = metric_registry_mt
local function new_metric_registry(backend)
local reg = {
families = {},
backend = backend,
}
setmetatable(reg, metric_registry_mt)
return reg
end
function metric_registry_mt:register_metric_family(name, metric_family)
local existing = self.families[name];
if existing then
if not equal_metric_family(metric_family, existing) then
-- We could either be strict about this, or replace the
-- existing metric family with the new one.
-- Being strict is nice to avoid programming errors /
-- conflicts, but causes issues when a new version of a module
-- is loaded.
--
-- We will thus assume that the new metric is the correct one;
-- That is probably OK because unless you're reaching down into
-- the util.openmetrics or core.statsmanager API, your metric
-- name is going to be scoped to `prosody_mod_$modulename`
-- anyway and the damage is thus controlled.
--
-- To make debugging such issues easier, we still log.
log("debug", "replacing incompatible existing metric family %s", name)
-- Below is the code to be strict.
--error("conflicting declarations for metric family "..name)
else
return existing
end
end
self.families[name] = metric_family
return metric_family
end
function metric_registry_mt:gauge(name, unit, description, labels, extra)
name = compose_name(name, unit)
local mf = new_metric_family(self.backend, "gauge", name, unit, description, labels, extra)
mf = self:register_metric_family(name, mf)
return mf
end
function metric_registry_mt:counter(name, unit, description, labels, extra)
name = compose_name(name, unit)
local mf = new_metric_family(self.backend, "counter", name, unit, description, labels, extra)
mf = self:register_metric_family(name, mf)
return mf
end
function metric_registry_mt:histogram(name, unit, description, labels, extra)
name = compose_name(name, unit)
local mf = new_metric_family(self.backend, "histogram", name, unit, description, labels, extra)
mf = self:register_metric_family(name, mf)
return mf
end
function metric_registry_mt:summary(name, unit, description, labels, extra)
name = compose_name(name, unit)
local mf = new_metric_family(self.backend, "summary", name, unit, description, labels, extra)
mf = self:register_metric_family(name, mf)
return mf
end
function metric_registry_mt:get_metric_families()
return self.families
end
-- END of MetricRegistry implementation
-- BEGIN of general helpers for implementing high-level APIs on top of OpenMetrics
local function timed(metric)
local t0 = time()
local submitter = assert(metric.sample or metric.set, "metric type cannot be used with timed()")
return function()
local t1 = time()
submitter(metric, t1-t0)
end
end
-- END of general helpers
return {
new_metric_proxy = new_metric_proxy;
new_metric_registry = new_metric_registry;
render_histogram_le = render_histogram_le;
timed = timed;
}