Collectors¶

The OPNsense Exporter runs 47 sub-collectors concurrently via goroutines, each targeting a specific OPNsense subsystem. On every Prometheus scrape, all enabled collectors fan out in parallel, query the OPNsense REST API, and emit their metrics.

Scrape flow¶

graph LR
    A[Prometheus scrape] --> B[Collector.Collect]
    B --> C[Health check]
    C --> D{opnsense_up?}
    D -->|Yes| E[Fan out to sub-collectors]
    D -->|No| F[Return opnsense_up=0]
    E --> G1[ARP table]
    E --> G2[Gateways]
    E --> G3[Interfaces]
    E --> G4[...]
    E --> G5[PF Stats]
    G1 --> H[Merge metrics]
    G2 --> H
    G3 --> H
    G4 --> H
    G5 --> H
    H --> I[Return to Prometheus]

Auto-registration pattern¶

Sub-collectors register themselves via init() functions that append to a global collectorInstances slice. Adding a new collector requires only creating the file with an init() function -- no manual registration is needed. See Adding a Collector for details.

Top-level exporter metrics¶

These metrics are always emitted regardless of which sub-collectors are enabled:

Collector reference¶

Enabled by default¶

Disabled by default (opt-in)¶

High-cardinality detail metrics¶

These produce one time series per item and should be evaluated carefully before enabling:

Service running metrics¶

Several collectors include a service_running gauge (1 = running, 0 = stopped/disabled) for their respective services:

• Unbound DNS: opnsense_unbound_dns_service_running
• Dnsmasq: opnsense_dnsmasq_service_running
• IPsec: opnsense_ipsec_service_running
• WireGuard: opnsense_wireguard_service_running
• Syslog: opnsense_syslog_service_running
• Tailscale: opnsense_tailscale_service_running
• Kea: opnsense_kea_service_running

Tailscale collector scope¶

The Tailscale collector is complementary to tailscale2otel, which covers control-plane/fleet data from the Tailscale API. This exporter deliberately emits only signals that exist solely on the firewall itself: per-peer rx/tx traffic as seen from this node, and local WireGuard session state derived purely from handshakes (peer_session_active, peers_with_active_session, direct-vs-DERP path for established sessions, last-handshake timestamps), plus the plugin/backend service state. The coordination-server Online flag is intentionally never parsed or exported — it is fleet data relayed to the node, not a local observation, and it lives in tailscale2otel along with peer last-seen and exit-node inventory. Per-peer metrics are opt-in via --exporter.enable-tailscale-peer-details.