metricq-combinator
This tool is a MetricQ transformer that produces new, user-defined metrics (called combined metrics) as arithmetic combinations of existing metrics (called input metrics).
Building
Build using cmake
:
$ mkdir build && cd build $ cmake .. $ make
Usage
Basic setup (MetricQ management server, token etc) is configured via command line; for more information, issue:
$ metricq-combinator --help
The actual information on how to combine new metrics is provided as a JSON object by the management server, mapping the names of metrics-to-be-combined to their configuration:
{ "metrics": { <name of combined metric>: { "expression": <expression>, "metadata": { ... } }, ... } }
For each combined metric, the key "expression"
is mandatory and describes
this metric as a tree of operations and input metrics/constants:
<expression> ::= "<input metric>" <expression> ::= <constant value (float/integer)> <expression> ::= { "operation": ("+" | "-" | "*" | "/"), "left": <expression>, "right": <expression> } <expression> ::= { "operation": ("min" | "max" | "sum"), "inputs": [<expression>, ...] } <expression> ::= { "operation": "throttle", "cooldown_period": "<duration>", "input": <expression> }
where <duration>
is of the form <value><unit>
, e.g. 2s
or
500 milliseconds
.
The key "metadata"
is optional and maps to a JSON object containing
arbitrary metadata for this combined metric. These are sent to the manager when
declaring the new metric. Commonly used metadata-keys are:
"unit"
- A string containing the SI unit symbol in which this metric reports values.
"description"
- A string containing the human-readable description of what this metric reports.
"display_expression"
- A string containing a human-readable version of this metrics
"expression"
-key, i.e. a short description on how this metric is derived from its inputs, in infix-notation. "rate"
- A number describing the rate (in Hz) at which this metric is expected to
produce values. For example, a metric with
"rate": 0.2
should report a new value every ~5 seconds, i.e. at a rate of 1/5 Hz.
Examples
Report the total power consumption of two systems foo and bar as a new metric
foobar.power
:"foobar.power": { "expression": { "left": "foo.power", "operation": "+" "right": "bar.power", }, "metadata": { "unit": "W", "description": "Total power consumption of foo and bar", "display_expression": "foo.power + bar.power", } }
Provide a temperature reading in a different unit:
"RoomA15.temperature.imperial": { "expression": { "left": { "left": "RoomA15.temperature", "right": 1.8, "operation": "*" }, "right": 32, "operation": "+" }, "metadata": { "unit": "°F", "description": "Room A15 temperature reading, in degrees Fahrenheit" "display_expression": "(RoomA15.temperature * 9/5) + 32" } }
License
Combine new MetricQ metrics in a flexible way Copyright (C) 2019 Technische Universität Dresden This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.