Configuration¶

The OPNsense Exporter follows standard Prometheus ecosystem conventions. It can be configured using command-line flags, environment variables, or a combination of both. Environment variables take the prefix OPNSENSE_EXPORTER_ unless noted otherwise.

The flag tables on this page are generated from the exporter's own flag definitions by make docs, so they always match the binary. The definitions themselves live in internal/options/ on GitHub.

OPNsense connection¶

These settings control how the exporter connects to the OPNsense API.

File-based secrets¶

In containers and orchestrated environments, credentials can be read from files:

Exporter settings¶

Poll intervals and the response cache¶

Two different caches sit between the firewall and a scrape, and they do not overlap:

• The poll snapshot removes API work from the scrape path. Each collector polls on its own interval (--collector.poll-interval, its built-in tier, or a --collector.poll-interval-override) into an in-memory snapshot; /metrics and the OTLP bridge replay that snapshot and never call the firewall. Scrape as often as you like - it costs the box nothing.
• The response cache (--exporter.cache-ttl, --exporter.firmware-cache-ttl) removes API work from the poll path, for the handful of endpoints whose payload only changes on an admin action. A collector on the 15-minute tier would otherwise ask the box four times an hour for a certificate inventory that changes once a quarter.

Because the response cache is consumed by polls, set its TTL longer than the poll interval of the collectors that use it - a TTL below the poll interval can never serve a hit and just adds a lookup. Poll intervals are clamped to a 15-minute ceiling, so both defaults (1h and 12h) are above the slowest possible poll. Setting either to 0 disables that cache and sends every poll to the firewall.

A plugin-gated endpoint's 404 is remembered separately, under the same --exporter.cache-ttl. That is a fact about the route (the plugin is not installed), not about payload freshness, so it applies regardless of how a collector polls.

Health endpoints & scrape filtering¶

The exporter serves two probe endpoints alongside /metrics:

Note: if you configure basic_auth_users in the exporter-toolkit web config file (--web.config.file), authentication applies to all endpoints including /-/healthy and /-/ready - Kubernetes probes cannot easily send basic-auth credentials, so prefer network-level protection over basic auth when probes are in use.

/metrics supports node_exporter-style per-scrape collector filtering:

curl 'http://localhost:8080/metrics?collect[]=gateways&collect[]=interfaces'
curl 'http://localhost:8080/metrics?exclude[]=firewall_rule'

collect[] and exclude[] are mutually exclusive (400 if both are given); unknown collector names return 400 listing the valid names (the subsystem names of the collectors enabled in this instance). The always-on metrics (opnsense_up, health/status, opnsense_exporter_*) are emitted regardless of filtering.

Prometheus's scrape timeout bounds only the /metrics HTTP request. The request replays the latest in-memory collector snapshots and never starts OPNsense API calls. Background polls have their own intervals, request timeout, and concurrency limit; use the poll freshness, duration, and success metrics to diagnose a slow firewall endpoint.

Continuous profiling (Pyroscope)¶

The exporter can push continuous profiles to Grafana Cloud Pyroscope using the pyroscope-go SDK. Profiling is disabled by default and activates only when --pyroscope.server-address (env OPNSENSE_EXPORTER_PYROSCOPE_SERVER_ADDRESS) is set. There are no unauthenticated /debug/pprof/* endpoints.

File-based secrets¶

Like the OPNsense API credentials, the auth user and password can be read from files instead of flags/env vars: set PYROSCOPE_AUTH_USER_FILE and/or PYROSCOPE_AUTH_PASSWORD_FILE to a path whose first line holds the value. The file value takes precedence over the corresponding flag/env var when present and non-empty.

Profiles are tagged with instance (the resolved instance label) and version.

OTLP metrics export¶

In addition to the /metrics pull endpoint, the exporter can push the exact same metrics to an OpenTelemetry (OTLP) endpoint. A Prometheus-bridge producer reads the existing registry on each export tick, so OTLP metric names, labels and values are identical to what /metrics exposes (no native renaming) - existing dashboards keep working against either backend. Export is disabled by default and activates only when --otlp.enabled (env OPNSENSE_EXPORTER_OTLP_ENABLED) is set. The pull endpoint is unaffected whether or not OTLP is enabled.

--otlp.endpoint, --otlp.headers and --otlp.service-name fall through to the corresponding standard OpenTelemetry environment variable when left empty (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME), and OTEL_RESOURCE_ATTRIBUTES is read natively by the OTEL SDK. Explicit --otlp.* flags take precedence over those env vars.

OTEL_EXPORTER_OTLP_PROTOCOL and OTEL_METRIC_EXPORT_INTERVAL are not consulted. --otlp.protocol and --otlp.export-interval always carry a value (an empty protocol is rejected at startup rather than defaulted), so the exporter passes both explicitly and those two env vars never apply - set the flags instead.

The metric set exported over OTLP is the same as the Prometheus catalogue (see the metrics reference), with one addition described below: a synthetic up series.

Delivery health¶

--otlp.enabled starting cleanly proves nothing about delivery: the OTLP exporter connects lazily, so the "otlp metrics export enabled" log line is written before any network I/O happens. A wrong endpoint, an expired credential or a backend outage can therefore deliver zero metrics indefinitely.

Four self-metrics make that visible on /metrics and on the operator console: opnsense_exporter_otlp_exports_total{result="success"|"error"}, opnsense_exporter_otlp_consecutive_failures, opnsense_exporter_otlp_last_success_timestamp_seconds and opnsense_exporter_otlp_enabled. Note that otlp_enabled = 1 means the pipeline is running, not that it is working - the outage signal is a rising consecutive_failures.

These cannot reach a pure-OTLP backend during an outage, because an exporter cannot ship its own failure through the path that is failing. On a pure-push deployment they are for the local console and for post-recovery forensics; the in-band symptom at the backend is data staleness. Where /metrics is also scraped, they alert normally.

Construction failure is fatal. If --otlp.enabled is set and the exporter cannot be built, the process exits rather than serving /metrics behind a permanently dead push pipeline. Export failures after startup are not fatal - they are counted, logged (rate-limited) and retried, so a flaky backend never takes down the pull endpoint.

Two-speed export (--otlp.fast-export-interval)¶

Collectors already poll on data-volatility tiers, but OTLP exports the whole snapshot on one interval. Setting --otlp.export-interval=15s to get responsive gateway and interface graphs therefore re-sends every cold and medium series four times a minute as well, even though almost none of them changed.

--otlp.fast-export-interval adds an optional second export lane carrying only the fast-tier collectors, while everything else stays on --otlp.export-interval. It is off by default (0s), and the default configuration builds exactly one reader, byte-for-byte as before. It must be shorter than --otlp.export-interval; a fast lane that is not faster is rejected at startup rather than silently doubling export calls.

Measured on a live deployment (7,226 total series, of which 494 are fast-tier):

Fast-tier membership follows each collector's effective poll interval, so a --collector.poll-interval-override moves a collector between lanes in either direction. The two lanes are disjoint by construction - the base lane carries every non-fast collector plus the health, up and exporter self-metrics, the fast lane carries fast-tier collectors only - so no series is ever exported twice. Per-collector scheduler metrics travel with their collector, keeping them at the same resolution as the data they describe.

The trade-off to understand is backend staleness: non-fast series now arrive only once per --otlp.export-interval, exactly as before, so a dashboard mixing a fast series with a cold one will show the cold one stepping at the base interval. That is already true of the underlying poll tiers - a 15m-tier collector cannot be fresher than 15m no matter how often it is exported - so exporting it more often only inflates cost, never resolution.

Liveness (up) in push mode¶

When Prometheus scrapes /metrics it synthesizes an up series per target for free - 1 when the scrape succeeded, 0/absent when the exporter was unreachable - and liveness alerts (up == 0, absent(up)) key off it. In OTLP push mode there is no scraper, so nothing generates that series and those alerts silently stop working.

To keep them working, the exporter emits its own up series, but only over OTLP: a gauge fixed at 1 while the exporter is running and exporting, labelled with opnsense_instance. When the exporter stops, it stops pushing and the series goes stale/absent - exactly the signal an absent(up) (or staleness) alert needs. This mirrors Prometheus target-up semantics: up reports whether the exporter is alive, not whether the firewall behind it is healthy (that is opnsense_up, which reflects OPNsense API reachability).

The synthetic up is deliberately not exposed at /metrics: a literal up there would collide with the up a Prometheus server generates for the scrape target. It therefore exists in the pushed OTLP stream alone, and does not appear in the metrics reference (which catalogues the pull endpoint).

Grafana Cloud shortcut¶

Setting --otlp.grafana-cloud-instance-id, --otlp.grafana-cloud-token and --otlp.grafana-cloud-endpoint together synthesizes the Authorization: Basic base64(instanceID:token) header and uses the gateway URL as the endpoint, so you do not have to assemble the basic-auth header yourself. An explicit --otlp.endpoint or Authorization header always wins over the shortcut. The instance ID and token also support *_FILE secret variants (OPNSENSE_EXPORTER_OTLP_GRAFANA_CLOUD_INSTANCE_ID_FILE, OPNSENSE_EXPORTER_OTLP_GRAFANA_CLOUD_TOKEN_FILE), whose file contents take precedence over the flag/env value, mirroring the OPNsense API credentials.

Temporality¶

Exported metrics are always cumulative, and this is not configurable. They are sourced from the Prometheus registry via a bridge producer, so they arrive already aggregated as cumulative (Prometheus' model) and are exported as-is - exactly the temporality Grafana Cloud's metrics backend (Mimir) and Prometheus' OTLP ingest require. An exporter-side temporality selector cannot re-aggregate producer-supplied metrics, so no delta option is offered.

Resource attributes and service_version¶

The exporter puts service.name and service.instance.id on the OTLP resource for metrics, alongside whatever the SDK's detectors and OTEL_RESOURCE_ATTRIBUTES contribute. None of them are copied onto individual datapoints: under the OTLP→Prometheus convention a resource attribute stays on the resource, and the backend decides what to make of it. Conventionally that means service.name(+service.namespace) becomes job, service.instance.id becomes instance, and everything else lands on the target_info series.

service.version is deliberately left off the metrics resource. Backends deviate from that convention, and Grafana Cloud in particular promotes a fixed list of resource attributes to a label on every series - service.version among them. An attribute that is absent cannot be promoted, so omitting it is what keeps service_version off the metric surface; the alternative would be asking Grafana Support to change the list per tenant.

The consequence being avoided: with the label present, every build is a distinct series, so for a few minutes after each redeploy a rate-based aggregation sees the old build's series decaying alongside the new one's and over-reports. Aggregating the label away does not help - that sums both series, which is the same thing. It bites hardest on per-commit builds, but it also grows active-series cardinality by the number of versions ever seen. Because the attribute is now absent, target_info carries no service_version either.

Shipped logs keep service.version on their resource, which is a different trade: log records are never summed and have no per-series label surface, so the version is free there and (unless a tenant promotes it) arrives as structured metadata for per-record version attribution.

Read the version back from the exporter's own info metric, which carries it on every backend, pull or push:

opnsense_exporter_build_info{opnsense_instance="my-firewall"}

Attribute other series to a build by joining against it:

opnsense_up * on(opnsense_instance) group_left(version) opnsense_exporter_build_info

Collector switches¶

All collectors are enabled by default unless noted otherwise. Each can be individually disabled or enabled using CLI flags or environment variables.

Enabled by default (disable with flag)¶

Disabled by default (opt-in with flag)¶

These collectors are disabled by default because each scheduled poll adds API calls or expensive work on OPNsense. Enable them only if you need the data.

High-cardinality detail options¶

These flags enable per-item detail metrics that can produce a large number of time series. Each unique label combination creates a separate time series in Prometheus.

Full flag reference¶

Every flag the exporter accepts, generated from the binary's own flag definitions (--help shows the same set):