UNMS Exporter for Prometheus
Small daemon offering UNMS device statistics as Prometheus metrics.
Deployment
Premade Docker Images are available at quay.io.
docker pull quay.io/ffddorf/unms-exporter
Configuration
Options
Config can be specified via a YAML file, as args or from environment variables.
Listen Address
- Config:
listen
- Args:
--listen
or -l
- Env:
UNMS_EXPORTER_SERVER_ADDR
Address the exporter should listen on. Defaults to [::]:9806
.
Config File Location
Location of the YAML config file to load.
Log Verbosity
- Config:
log_level
- Env:
UNMS_EXPORTER_LOG_LEVEL
Log verbosity level. Defaults to info
. Use debug
to get more details.
UNMS API Tokens
- Config:
token
- Env:
UNMS_EXPORTER_TOKEN
- use a comma-separated list of
instance=token
values
Configures an API token per UNMS instance.
Example: config file (click to open)
# config.yaml
token:
my-unms-instance.example.org: "my token"
unms.example.com: "token123"
$ unms-exporter --config config.yaml
Example: environment variable (click to open)
$ UNMS_EXPORTER_TOKEN="my-unms-instance.example.org=my token,unms.example.com=token123" \
unms-exporter
- Config:
extra_metrics
(as Array)
- Args:
--extra-metrics
(as comma-separated list)
- Env:
UNMS_EXPORTER_EXTRA_METRICS
(as comma-separated list)
Enable additional metrics to be exported. These metrics may require extra
HTTP requests, usually one per device, so they are disabled by default.
Example: config file (click to open)
# config.yaml
extras:
- ping
$ unms-exporter --config config.yaml
Example: environment variable (click to open)
$ UNMS_EXPORTER_EXTRA_METRICS="ping" \
unms-exporter
Example: command line argument (click to open)
$ unms-exporter --extra-metrics="ping"
Available metrics
Further data is available, but not currently exported (see the API
documentation for the /devices/{id}/statistics
endpoint on your UNMS
installation to get an overview). Feel free to open a new issue to
inquire whether an integration into the exporter is feasable.
Prometheus Scrape Setup
The exporter follows the convention for exporters. The UNMS instance to target should be specified using the target
query parameter.
Here is how to achieve this using a static prometheus config:
scrape_configs:
- job_name: exporters
static_configs:
- exporter.example.org:9806 # UNMS exporter
- exporter.example.org:9100 # node exporter
- ...
- job_name: unms_exporter
# for a static target "unms.example.org", rewrite it to
# "exporter.example.org:9806/metrics?target=unms.example.org",
# but keep "unms.example.org" as instance label
relabel_configs:
- source_labels: [__address__]
target_label: instance
- source_labels: [__address__]
target_label: __param_target
- replacement: 'exporter.example.org:9806'
target_label: __address__
static_configs:
- targets:
- my-unms-instance.example.org
Upgrade from v0.1.2 or earlier (click to open)
Previous versions did expose the UNMS metrics under any path on the exporter,
i.e. the following URLs were handled identically:
http://localhost:9806/?target=my-unms-instance.example.org
http://localhost:9806/metrics?target=my-unms-instance.example.org
http://localhost:9806/this/is/all/ignored?target=my-unms-instance.example.org
Additionally, the UNMS exporter has returned a mixed set of internal and
instance-specific metrics.
This has changed and now follows best practices. All UNMS-specific metrics
are now available only on the following URL:
http://localhost:9806/metrics?target=my-unms-instance.example.org
Additionally, internal metrics (e.g. Go runtime statistics) can be retrieved
by omitting the target
parameter:
http://localhost:9806/metrics
Available Metrics
Device wide
device_cpu
: CPU load average in percent
device_ram
: RAM usage in percent
device_enabled
: Indicating if device is enabled in UNMS
device_maintenance
: Indicating if device is in maintenance mode (useful for muting alerts)
device_uptime
: Uptime in seconds
device_last_seen
: Last seen as unix timestamp
device_last_backup
: Time of last backup as unix timestamp
Per Interface
interface_enabled
: Indicating if interface is enabled
interface_plugged
: Indicating if interface has a cable plugged
interface_up
: Indicating if interface is considered up
interface_dropped
: Number of packets dropped
interface_errors
: Number of interface errors
interface_rx_bytes
: Bytes received since last reset
interface_tx_bytes
: Bytes transmitted since last reset
interface_rx_rate
: Bytes received rate (momentarily)
interface_tx_rate
: Bytes transmitted rate (momentarily)
interface_poe_power
: POE power consumption
WAN Interface
If an interface is marked as the WAN interface, these metrics are populated.
wan_rx_bytes
: Bytes received since last reset
wan_tx_bytes
: Bytes transmitted since last reset
wan_rx_rate
: Bytes received rate (momentarily)
wan_tx_rate
: Bytes transmitted rate (momentarily)