Collectors¶

The OPNsense Exporter runs 26 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