Prometheus Metrics - NormB/sipnab GitHub Wiki

sipnab exposes Prometheus-compatible metrics, enabled with the api feature flag (served on the REST API's port) or the metrics feature (a standalone server on --metrics). Both emit the same families.

This is a different surface from the REST API, which returns what sipnab SAW — dialogs, streams, messages. These are numbers ABOUT sipnab: what it captured, what it lost, and what it could not read. They also authenticate differently — see Authentication.

It is also easy to confuse with HEP, the Homer Encapsulation Protocol, because both are how sipnab fits into a monitoring estate — and they answer opposite questions. HEP is a TRANSPORT FOR SIP MESSAGES: sipnab receives them with --hep-listen or forwards them with --hep-send, and Homer stores the signaling itself. Prometheus carries no SIP at all. A scrape tells you sipnab dropped 4,000 packets. It never tells you which call. Wire both — they are complements, not alternatives.

Prometheus-compatible metrics endpoint. Returns metrics in the Prometheus text exposition format (text/plain; version=0.0.4).

curl:

curl -s -H "Authorization: Bearer $SIPNAB_API_KEY" \
  http://127.0.0.1:8080/metrics

Python:

import requests

resp = requests.get(
    "http://127.0.0.1:8080/metrics",
    headers={"Authorization": "Bearer my-secret-token"},
)
print(resp.text)  # Prometheus text format

Go:

req, _ := http.NewRequest("GET", "http://127.0.0.1:8080/metrics", nil)
req.Header.Set("Authorization", "Bearer my-secret-token")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

JavaScript (Node.js):

const resp = await fetch("http://127.0.0.1:8080/metrics", {
  headers: { Authorization: "Bearer my-secret-token" },
});
console.log(await resp.text()); // Prometheus text format

Response (text/plain):

# HELP sipnab_dialogs_total Total dialogs by state
# TYPE sipnab_dialogs_total counter
sipnab_dialogs_total{state="completed"} 1180
sipnab_dialogs_total{state="failed"} 32
sipnab_dialogs_total{state="incall"} 23
# HELP sipnab_rtp_streams_total RTP streams by status
# TYPE sipnab_rtp_streams_total counter
sipnab_rtp_streams_total{status="established"} 43
sipnab_rtp_streams_total{status="orphaned"} 3
...

Metric names emitted by src/output/prometheus.rs:

Two shapes of counter share that table, and an alert rule has to know which one it reads. sipnab_capture_packets_total, sipnab_reassembly_timeouts_total, sipnab_kill_responses_sent_total, sipnab_capture_backpressure_blocks_total, sipnab_capture_undecodable_frames_total, sipnab_capture_snapped_frames_total, the two MCP counters (sipnab_mcp_tool_calls_total, sipnab_mcp_tool_response_bytes_total) and the three capture-quality counters (sipnab_capture_kernel_dropped_packets_total, sipnab_capture_interface_dropped_packets_total, sipnab_capture_invalid_timestamps_total) count events since the process started and only ever climb, so rate() and increase() over them mean what they say. The rest — dialogs, messages, responses, streams, diagnosis findings, and the four NAT gauges — describe what sipnab tracks right now, and every one of them falls as well as rises: dialogs and streams age out of their stores, a late STUN answer clears an unanswered request, a TURN Refresh unsays a lapsed allocation. Alert on the current value or on a ratio there, never on increase().

sipnab_security_alerts_total{type} reads differently from the rest, and the difference matters to an alert rule. AlertEngine::fire records each alert under its rule name, so the family carries only the types that have actually fired and stays absent from the scrape entirely until the first one does. An absent series therefore means "no alert of that type has fired since this process started", not "the metric is unavailable". firing_an_alert_moves_the_metric in tests/metrics_alert_wiring_test.rs holds the recording call to that behavior.

sipnab publishes these numbers two ways, and the two do not carry the same series. The api feature serves /metrics on the REST API's port. The metrics feature runs a standalone server on --metrics. A scalar gauge or counter always prints, at 0 where the server behind it never fills the value, so a panel aimed at the wrong target renders a flat line rather than an error.

Both targets publish the same series. Scrape either one. A rule tuned against --api holds against --metrics, and a dashboard needs only one of them.

That is new as of 0.5.158. The two doors each assembled the scrape themselves, and the six differences that produced are worth naming, because a reader who tuned a rule against the old behavior needs to know what moved:

both_scrape_doors_publish_identical_exposition compares the formatted text the two produce for one capture, so a future difference fails the build rather than reaching a dashboard.

# prometheus.yml
scrape_configs:
  - job_name: sipnab
    bearer_token: your-api-key
    static_configs:
      - targets: ['127.0.0.1:8080']
    scrape_interval: 15s

The metrics endpoint is lightweight and suitable for 5–15 second scrape intervals. A sample Grafana dashboard JSON ships in the repo at contrib/grafana/sipnab-dashboard.json.