When generating metric values using expression evaluation, there are new
use-cases for more than one configuration for each sensor value.
Expressions are more flexible than aggregation rules in Prometheus, so
it makes sense to derive multiple metrics from the same sensor input.
This change adds the new metric config option `expression` which can
define a complex expression to calculate the final metric value. The
expression is evaluated using github.com/antonmedv/expr as the engine,
see expr-lang.org/docs/v1.9/Language-Definition for a language overview.
In addition, some basic functions are available during evaluation: now,
int, float, round, ceil, floor, abs, min, max.
For each evaluation, the expression gets:
- the current MQTT value
- the last MQTT value
- the result of the last evaluation
- the elapsed time since the last evaluation
Expressions allow more flexibility to derive metrics from sensor inputs
which are very hard or even impossible to do in Prometheus, for example,
integrate continuous values over time, filter extreme or zero values, or
non-linear scaling. The last value, result, and timestamp are preserved
even between restarts of mqtt2prometheus. This means that expressions
can be used to produce continuous time series over a long time range.
To make upstream integration easier, the code depends on the rather old
v1.8.9 of github.com/antonmedv/expr, which is available in the main repo
of all supported Debian versions.
This change adds the new option `force_monotonicy` to metric
configurations. It is intended for almost-but-not-really monotinic
sources, such as counters which reset when the sensor is restarted.
When this option is set to `true`, the source metric value is regularly
written to disk. This allows us to detect and compensate counter resets
even between restarts. When a reset is detected, the last value before
the reset becomes the new offset, which is added to the metric value
going forth. The result is a strictly monotonic time series, like an
ever increasing counter.
This commit reorganizes the logic in parseMetric to have it take in a MetricConfig so that the extractor can find the config and properly handle the case when there's no config found.
This commit allows to extract the metric name from the topic path. Now
it can be configured if all metrics are in a object in a certain topic
or if every topic contains exactly one metric. However, currently these
modes can not be mixed.
This should solve !26
TODO:
* Update documentation
* Add unit tests
