Collectors¶

opnsense2otel runs 65 sub-collectors on independent background schedules, each targeting a specific OPNsense subsystem. Poll results are stored in memory; Prometheus scrapes replay that snapshot and make no OPNsense API calls.

Poll and replay flow¶

flowchart LR
    T[Per-collector timers] --> P[Scheduled collector polls]
    P --> A[OPNsense API]
    P --> S[Atomic in-memory snapshots]
    H[Independent health poll] --> A
    H --> S
    M[Prometheus /metrics request] --> R[Replay selected snapshots]
    O[OTLP metrics bridge] --> R
    S --> R
    R --> E[Emit metrics without API calls]

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, so check the cardinality cost 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.