Monitoring
VyOS supports exporting metrics to external monitoring systems through the Telegraf collector agent and through standalone Prometheus exporters. Telegraf can also forward system logs to Loki, Grafana Labs’ log aggregation system.
Telegraf
Telegraf collects host and system metrics every 15 seconds through a predefined set of input plugins, covering CPU, memory, disk and disk I/O, network and network statistics, processes, kernel and interrupt counters, systemd unit state, conntrack, per-interface link statistics, and time synchronization. It also receives the VyOS system log through its syslog input plugin.
The collected data is written to output plugins. Each plugin delivers it to a different backend in that backend’s format and protocol:
Azure Data Explorer: Writes metrics to an Azure Data Explorer cluster.
Prometheus client: Exposes metrics on a
/metricsHTTP endpoint that a Prometheus server periodically pulls.Splunk: Sends metrics to the Splunk HTTP Event Collector.
InfluxDB: Writes metrics to a bucket on an InfluxDB v2 server.
Loki: Sends the VyOS system log to a Grafana Loki server.
Configuration
General options
Run the Telegraf service in the specified VRF instance.
The VRF must already be configured under set vrf name <name>.
Example:
set service monitoring telegraf vrf mgmt
Azure Data Explorer
A configuration for this plugin is committable only when
authentication client-id, authentication client-secret,
authentication tenant-id, database, and url are all configured.
client-id, client-secret, and tenant-id are credentials
associated with a single application registration in Microsoft Entra ID
(Azure AD), Microsoft’s cloud identity service. Telegraf presents these
credentials to Entra ID to obtain an access token, then uses that token
to authorize its writes to the Azure Data Explorer cluster, Microsoft’s
cloud analytics database. Create the application registration and
obtain these values from the Azure portal.
Configure the client ID of the Telegraf application registration.
Example:
set service monitoring telegraf azure-data-explorer authentication client-id a0b1c2d3-e4f5-0123-4567-89abcdef0123
Configure the client secret of the Telegraf application registration.
Example:
set service monitoring telegraf azure-data-explorer authentication client-secret MY-CLIENT-SECRET
Configure the tenant ID of the Telegraf application registration.
Example:
set service monitoring telegraf azure-data-explorer authentication tenant-id b1c2d3e4-f5a6-7890-1234-56789abcdef0
Configure the cloud-hosted database into which Telegraf writes metrics.
The database must already exist. Telegraf does not create it.
Example:
set service monitoring telegraf azure-data-explorer database vyos-metrics
Configure how Telegraf groups metrics into tables in the configured database:
single-table: All metrics are written to the single table configured withtable. Ifsingle-tableis chosen,tablebecomes required.table-per-metric: Metrics are grouped by metric name, and each group is written to its own table.
The default is table-per-metric.
Example:
set service monitoring telegraf azure-data-explorer group-metrics single-table
Configure the destination table for Telegraf metrics when
group-metrics is set to single-table.
When group-metrics is set to table-per-metric, this setting has no
effect.
Example:
set service monitoring telegraf azure-data-explorer table vyos
Configure the endpoint URL of the Azure Data Explorer cluster.
Example:
set service monitoring telegraf azure-data-explorer url https://vyos-cluster.westeurope.kusto.windows.net
Prometheus client
The Prometheus client plugin is the Telegraf output plugin for exposing metrics to Prometheus. For standalone Prometheus exporters, see the Prometheus section.
Example:
set service monitoring telegraf prometheus-client
Restrict access to the metrics endpoint to clients whose source address is within the specified IPv4 or IPv6 prefix.
Repeat the command to allow multiple prefixes.
When unset, the endpoint accepts queries from any IP address.
Example:
set service monitoring telegraf prometheus-client allow-from 192.0.2.0/24
set service monitoring telegraf prometheus-client allow-from 2001:db8::/32
Configure the username for HTTP Basic authentication on the metrics endpoint.
Example:
set service monitoring telegraf prometheus-client authentication username prometheus
Configure the password for HTTP Basic authentication on the metrics endpoint.
HTTP Basic authentication is enabled only when both username and
password are configured.
Example:
set service monitoring telegraf prometheus-client authentication password mysecurepassword
Configure a local IP address on which the Prometheus client plugin accepts incoming connections.
When unset, the plugin accepts incoming connections on all local IP addresses.
Example:
set service monitoring telegraf prometheus-client listen-address 192.0.2.1
Configure the metric mapping version used to translate Telegraf metrics to the Prometheus format.
The default is 2.
Example:
set service monitoring telegraf prometheus-client metric-version 1
Configure the TCP port on which the Prometheus client plugin accepts incoming connections.
The default is 9273.
Example:
set service monitoring telegraf prometheus-client port 9274
After enabling the plugin, the metrics endpoint can be queried with
curl:
vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system
cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556
cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915
cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655
Splunk
A configuration for this plugin is committable only when
authentication token and url are configured.
Disable TLS certificate chain and host name verification for connections to the Splunk HTTP Event Collector.
Example:
set service monitoring telegraf splunk authentication insecure
Configure the token used to authorize requests to the Splunk HTTP Event Collector.
Example:
set service monitoring telegraf splunk authentication token xxxxf5b8-xxxx-452a-xxxx-43828911xxxx
Configure the URL of the Splunk HTTP Event Collector endpoint.
Example:
set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector'
InfluxDB
A configuration for this plugin is committable only when
authentication organization, authentication token, and url are
configured.
Configure the name of the organization that owns the bucket on the remote InfluxDB v2 server.
Example:
set service monitoring telegraf influxdb authentication organization vyos
Configure the API token used to authenticate to the remote InfluxDB v2 server.
The token must be in the standard InfluxDB v2 Base64-encoded format.
Example:
set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...=='
Configure the name of the InfluxDB v2 bucket that receives metrics.
The default is main.
Example:
set service monitoring telegraf influxdb bucket bucket_vyos
Configure the TCP port of the remote InfluxDB v2 server.
The default is 8086.
Example:
set service monitoring telegraf influxdb port 8087
Configure the URL of the remote InfluxDB v2 server.
VyOS appends the configured port to this URL, so specify the URL without a port number.
Example:
set service monitoring telegraf influxdb url 'http://r1.influxdb2.local'
Example
The following example configures Telegraf to write metrics to an
InfluxDB v2 server at r1.influxdb2.local on port 8087, storing them
in the bucket_vyos bucket of the vyos organization, authenticating
to the InfluxDB v2 server with the configured API token.
set service monitoring telegraf influxdb authentication organization 'vyos'
set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...=='
set service monitoring telegraf influxdb bucket 'bucket_vyos'
set service monitoring telegraf influxdb port '8087'
set service monitoring telegraf influxdb url 'http://r1.influxdb2.local'
Loki
A configuration for this plugin is committable only when url is
configured.
Configure the TCP port of the remote Loki server.
The default is 3100.
Example:
set service monitoring telegraf loki port 3101
Configure the URL of the remote Loki server.
VyOS appends the configured port to the host part of this URL. If the URL contains a path, the path is used as the endpoint of the Loki write API.
Example:
set service monitoring telegraf loki url 'http://192.0.2.20'
Configure the username for HTTP Basic authentication to the Loki server.
Example:
set service monitoring telegraf loki authentication username loki
Configure the password for HTTP Basic authentication to the Loki server.
If either username or password is configured, both are required.
Otherwise, the commit fails.
Example:
set service monitoring telegraf loki authentication password mysecurepassword
Configure the label used to identify log streams from the VyOS system log in Loki.
The default is __name.
Example:
set service monitoring telegraf loki metric-name-label syslog
Prometheus
In addition to the Telegraf prometheus-client output plugin, VyOS can
run the following standalone Prometheus exporters:
Node Exporter
FRR Exporter
Blackbox Exporter
Node Exporter
Prometheus node_exporter exposes hardware and operating system metrics such as CPU, memory, disk I/O, filesystem usage, and network interface statistics.
Configure a local IP address on which Node Exporter accepts incoming connections.
Repeat the command to configure multiple addresses.
When unset, Node Exporter accepts incoming connections on all local IP addresses.
Example:
set service monitoring prometheus node-exporter listen-address 192.0.2.1
Configure the TCP port on which Node Exporter accepts incoming connections.
The default is 9100.
Example:
set service monitoring prometheus node-exporter port 9101
Run Node Exporter in the specified VRF instance.
The VRF must already be configured under set vrf name <name>.
Example:
set service monitoring prometheus node-exporter vrf mgmt
Enable the Node Exporter textfile collector, which exports custom
metrics from files placed in /run/node_exporter/collector.
Example:
set service monitoring prometheus node-exporter collectors textfile
FRR Exporter
The Prometheus frr_exporter exposes routing protocol metrics from FRRouting (FRR). By default, the exporter collects metrics for BGP (IPv4 and IPv6), OSPF, BFD, and the routing table. Use the options below to enable additional metric collection or add extra labels to the exported data.
Configure a local IP address on which FRR Exporter accepts incoming connections.
Repeat the command to configure multiple addresses.
When unset, FRR Exporter accepts incoming connections on all local IP addresses.
Example:
set service monitoring prometheus frr-exporter listen-address 192.0.2.1
Configure the TCP port on which FRR Exporter accepts incoming connections.
The default is 9342.
Example:
set service monitoring prometheus frr-exporter port 9343
Run FRR Exporter in the specified VRF instance.
The VRF must already be configured under set vrf name <name>.
Example:
set service monitoring prometheus frr-exporter vrf mgmt
BGP collector options
Export the counts of accepted and filtered prefixes per BGP peer.
Example:
set service monitoring prometheus frr-exporter collector bgp accept-filtered-prefixes
Export the count of prefixes advertised to each BGP peer.
Example:
set service monitoring prometheus frr-exporter collector bgp advertised-prefixes
Add the BGP peer description as a label on that peer’s metrics:
json: Parses the peer description as a JSON object and extracts the value of thedesckey to use as the label.plain-text: Uses the unparsed peer description string as the label.
When unset, the peer description is not added as a label.
Example:
set service monitoring prometheus frr-exporter collector bgp peer-description plain-text
Add the peer group name of a BGP peer as a label on that peer’s metrics.
Example:
set service monitoring prometheus frr-exporter collector bgp peer-group
Add the hostname of a BGP peer as a label on that peer’s metrics.
Example:
set service monitoring prometheus frr-exporter collector bgp peer-hostname
Export the number of established BGP peers per type.
The type is read from the type key of the JSON-formatted peer
description.
Example:
set service monitoring prometheus frr-exporter collector bgp peer-type
Other collector options
Example:
set service monitoring prometheus frr-exporter collector bgp-l2-vpn
Example:
set service monitoring prometheus frr-exporter collector pim
Export metrics for the OSPF instance with the given ID.
Repeat the command to export metrics for multiple OSPF instances.
Example:
set service monitoring prometheus frr-exporter collector ospf-instance 100
set service monitoring prometheus frr-exporter collector ospf-instance 200
Export a route count for each route type.
Example:
set service monitoring prometheus frr-exporter collector detailed-routes
Blackbox Exporter
Prometheus blackbox_exporter probes network endpoints and exposes the probe results as metrics. VyOS supports the DNS and ICMP probes.
Configure a local IP address on which Blackbox Exporter accepts incoming connections.
Repeat the command to configure multiple addresses.
When unset, Blackbox Exporter accepts incoming connections on all local IP addresses.
Example:
set service monitoring prometheus blackbox-exporter listen-address 192.0.2.1
Configure the TCP port on which Blackbox Exporter accepts incoming connections.
The default is 9115.
Example:
set service monitoring prometheus blackbox-exporter port 9116
Run Blackbox Exporter in the specified VRF instance.
The VRF must already be configured under set vrf name <name>.
Example:
set service monitoring prometheus blackbox-exporter vrf mgmt
Blackbox Exporter modules
Blackbox Exporter probes are organized into named modules. A module defines a probe type and its settings. Configure a DNS or ICMP module with the commands below.
Configure the domain name that the specified DNS module queries.
This setting is mandatory for every DNS module. Otherwise, the commit fails.
Example:
set service monitoring prometheus blackbox-exporter modules dns name my-dns-module query-name example.com
Configure the DNS record type that the specified DNS module queries,
for example A or AAAA.
The default is ANY.
Example:
set service monitoring prometheus blackbox-exporter modules dns name my-dns-module query-type AAAA
The following options apply to both DNS and ICMP modules.
Configure which IP protocol the module prefers when probing the target.
When unset, IPv6 is preferred.
Example:
set service monitoring prometheus blackbox-exporter modules dns name my-dns-module preferred-ip-protocol ipv4
Allow the module to fall back to the other IP protocol if the preferred one is not usable.
When unset, fallback is disabled.
Example:
set service monitoring prometheus blackbox-exporter modules icmp name my-icmp-module ip-protocol-fallback
Configure how long a single probe may run before it times out, in seconds.
The default is 5.
Example:
set service monitoring prometheus blackbox-exporter modules dns name my-dns-module timeout 10
Examples
DNS module
The following example defines a DNS module named dns4 that looks up
the A record for vyos.io, using IPv4 to reach the DNS server.
set service monitoring prometheus blackbox-exporter modules dns name dns4 preferred-ip-protocol ipv4
set service monitoring prometheus blackbox-exporter modules dns name dns4 query-name vyos.io
set service monitoring prometheus blackbox-exporter modules dns name dns4 query-type A
ICMP module
The following example defines an ICMP module named ping6 that pings a
target over IPv6, falls back to IPv4 if IPv6 is not usable, and times
out after 3 seconds.
set service monitoring prometheus blackbox-exporter modules icmp name ping6 preferred-ip-protocol ipv6
set service monitoring prometheus blackbox-exporter modules icmp name ping6 ip-protocol-fallback
set service monitoring prometheus blackbox-exporter modules icmp name ping6 timeout 3