SIP-exporter

EN | RU

sip-exporter is an open-source eBPF sensor that turns SIP signaling and correlated RTP observed on a Linux host into Prometheus metrics and Grafana dashboards, without storing packet payloads.

Scope and limitations: Requires a privileged Linux deployment on a host that observes IPv4/UDP SIP signaling and the correlated RTP/RTCP path. It does not store packets or audio and is not a packet-search UI. QoE metrics describe traffic visible at the sensor, not guaranteed end-to-end subscriber quality.

• Key Features
• Grafana Dashboard
• Quick Start
• Installation Verification
• Core Technology
• Architecture
• Performance
• Install
• Deployment Topology
• Metrics
• Fraud Detection
• Security
• Development
• Contributing
• Benchmark
• Alerting
• Metrics Storage Compatibility
• Support
• License
• Changelog

• 🌐 Multi-interface monitoring — capture SIP/RTP from multiple NICs simultaneously, each tagged with an iface label
• ⚡ Kernel filtering — an eBPF socket filter selects relevant traffic before userspace parsing
• 🐳 Single container deployment — no external dependencies
• 🔧 Configurable SIP ports — monitor custom ports via environment variables
• 📈 Prometheus native — standard /metrics endpoint for scraping
• 🏷️ Per-carrier metrics — CIDR-based carrier resolution for SIP metric families with carrier context
• 🏷️ Per-device-type metrics — User-Agent classification for SIP metric families with device context
• 🌍 Geo-enrichment — source_country (GeoIP) and destination_country (E.164 prefix) labels on SIP metrics
• 🔀 Traffic direction — inbound/outbound label on SIP and RTP traffic metrics derived from kernel pkttype
• 📞 Voice quality (RFC 6035) — MOS scores, jitter, packet loss from SIP PUBLISH/NOTIFY
• 🎧 RTP media analysis — jitter, packet loss, MOS (E-model G.107), and per-packet Packet Delay Variation (PDV) from RTP streams correlated with SIP dialogs
• 📊 RTCP endpoint-reported quality — loss, jitter, and round-trip time (RTT) from RTCP SR/RR (RFC 3550), correlated by SSRC; supports rtcp-mux (RFC 5761), explicit a=rtcp (RFC 3605), and legacy port+1
• 🛡️ Fraud detection — registration scan, INVITE burst, account-takeover (country change), and False Answer Supervision (FAS) signals (docs/fraud-detection.md)

Real dashboard output from deterministic SIP/RTP lab traffic. Select a preview to open it full size.

Overview	SIP health	RTP quality

View all 11 dashboard sections.

Copy the pinned production Compose example to your host. Set SIP_EXPORTER_INTERFACE to the host interface that carries both SIP signaling and RTP media.

cp examples/docker-compose.production.yml docker-compose.yml
SIP_EXPORTER_INTERFACE=eth0 docker compose up -d
curl http://localhost:10047/metrics

The example includes a pinned release image, restart policy, healthcheck, read-only filesystem, and every runtime setting listed below with its default value.

Access metrics at http://localhost:10047/metrics. A /health endpoint is also exposed (returns 200 OK when alive, 503 otherwise) — used by the Dockerfile HEALTHCHECK and suitable for orchestrator liveness/readiness probes.

Port migration: new installations use 10047. Existing deployments may keep the previous port by setting SIP_EXPORTER_HTTP_PORT=2112 and keeping their scrape and healthcheck URLs aligned.

First useful dashboard: follow the installation verification runbook to check health, scrape status, SIP, SDP/RTP visibility and drops before importing Grafana.

This service uses eBPF (extended Berkeley Packet Filter) attached to AF_PACKET sockets to select IPv4 SIP packets over UDP (default port 5060) at L4. SIP over TCP or TLS is not captured. Selected packets are delivered to userspace via the socket for Go processing.

SIP + RTP Traffic → NIC → eBPF socket filter → AF_PACKET socket → Go poller → SIP parser + RTP tracker → Prometheus

The release-verified envelope includes full-call traffic at 1,000 CPS under 1 CPU / 128 MiB, full-call traffic with concurrent Prometheus scrapes at 1,800 CPS under 2 CPU / 256 MiB, and a ten-minute soak at 500 CPS under 1 CPU / 128 MiB. These are profile-specific acceptance results, not universal production sizing guarantees.

See the measured scenarios, integrity gates, environment and reproduction commands in docs/BENCHMARK.md.

docker pull frzq/sip-exporter:1.11.0

Environment variables:

• SIP_EXPORTER_INTERFACE - one or more network interfaces, comma-separated (required). Examples: eth0, eth0,eth1,eth2.
• SIP_EXPORTER_HTTP_PORT - http port for prometheus (default 10047)
• SIP_EXPORTER_LOGGER_LEVEL - log level: error, info, or debug (default info). Debug logs include raw SIP payloads; use only in controlled environments. Any other value currently enables debug logging.
• SIP_EXPORTER_SIP_PORTS - one or more SIP ports, comma-separated (default 5060; up to 3 per interface). Use ; for per-interface sets: 5060,5062;5060,5061.
• SIP_EXPORTER_OBJECT_FILE_PATH - path to eBPF object file (default /usr/local/bin/sip.o)
• SIP_EXPORTER_CARRIERS_CONFIG - path to carriers YAML config (optional, see examples/carriers.yaml)
• SIP_EXPORTER_USER_AGENTS_CONFIG - path to user-agents YAML config (optional, see examples/user_agents.yaml)
• SIP_EXPORTER_RTP_STREAM_TTL - idle RTP stream expiry, RFC 3550 §6.3.5 timeout (default 30s)
• SIP_EXPORTER_IGNORE_OUTGOING - loopback/test only: suppress duplicate TX packets on lo (default false, do NOT enable in production)
• SIP_EXPORTER_GEOIP_COUNTRY_DB - path to MaxMind GeoLite2-Country.mmdb for source_country label (optional)
• SIP_EXPORTER_LOCAL_COUNTRY_CODE - ISO alpha-2 country code for domestic phone-number fallback in destination_country (optional, e.g. RU)
• SIP_EXPORTER_HOST_LABELS - enable caller_host/called_host labels on INVITE metrics (default false; opt-in — unbounded cardinality, enable only on trusted/bounded deployments)
• SIP_EXPORTER_SESSIONS_LIMITS - path to sessions limits YAML config (optional, per-carrier concurrent-session caps and utilization metrics)
• SIP_EXPORTER_FRAUD_REGISTER_SCAN_THRESHOLD - registration scan: unique accounts (AoR) registered (200 OK) from one source IP to trigger the signal (default 10)
• SIP_EXPORTER_FRAUD_REGISTER_SCAN_WINDOW - registration scan rolling window (default 60s)
• SIP_EXPORTER_FRAUD_INVITE_BURST_THRESHOLD - INVITE burst fraud: INVITEs from one source to trigger the signal (default 100)
• SIP_EXPORTER_FRAUD_INVITE_BURST_WINDOW - INVITE burst rolling window (default 60s)
• SIP_EXPORTER_FRAUD_FAS_THRESHOLD - False Answer Supervision: base sweep-path wait after a 200 OK without answer-side RTP (default 10s; the BYE path uses an independent 3s floor)
• SIP_EXPORTER_TELEMETRY - anonymous usage telemetry, opt-out with false (default true)

The container must run with --privileged and --network host (eBPF requires CAP_BPF and access to the network interface). See Security for details on why this is safe.

⚠️ Multi-interface caveat: do not specify interfaces that see the same traffic (bond parent + child, bridge + member, VLAN parent + subinterface, duplicate SPAN ports). Doing so will double-count metrics. When in doubt, list only physical NICs.

Install sip-exporter on the host where both SIP signaling and RTP media pass through. It captures packets from the network interface it is attached to, and the direction label relies on the kernel seeing packets as addressed to that host — so the host must own those IPs, not receive them via a mirror.

Coverage depends on what the host actually sees:

• SIP only (signaling passes through, media does not) → SIP metrics only; RTP metrics stay empty.
• RTP only (media passes through, signaling does not) → the exporter cannot correlate streams to dialogs, because it learns RTP endpoints from the SDP carried inside SIP messages. Place it where signaling is also visible.
• SIP + RTP → full metrics.

All metrics are exposed at /metrics in Prometheus exposition format. Most SIP metrics include carrier, ua_type, source_country, and direction; specialized fraud, capacity, traffic, RTP/RTCP, and self-monitoring families use the exact schemas documented in the metrics label matrix. Raw INVITE metrics additionally carry destination_country, opt-in caller_host/called_host, and the capture-interface iface. The exporter provides:

• Traffic counters — SIP request types (INVITE, re-INVITE, BYE, REGISTER, etc.) and response status codes (100–606)
• Active sessions — real-time count of active SIP dialogs
• RFC 6076 performance metrics — SER, SEER, ISA, SCR, ASR, NER, RRD, SPD, TTR, PDD, PBD
• RFC 6035 voice quality metrics — NLR, JDR, BLD, GLD, RTD, ESD, IAJ, MAJ, MOSLQ, MOSCQ, RLQ, RCQ, RERL
• RTP media metrics — sip_exporter_rtp_packets_total, sip_exporter_rtp_packets_lost_total, sip_exporter_rtp_jitter_milliseconds, sip_exporter_rtp_pdv_milliseconds (per-packet Packet Delay Variation), sip_exporter_rtp_mos_score, sip_exporter_rtp_active_streams (labels: carrier,ua_type,codec,source_country,direction)
• RTCP quality metrics — quality histograms and cumulative loss use carrier,ua_type,codec,source_country,direction; sip_exporter_rtcp_reports_total replaces codec with type, and sip_exporter_rtcp_orphan_reports_total has no labels
• Fraud signals — sip_exporter_fas_calls_total (False Answer Supervision: 200 OK with no RTP within threshold), sip_exporter_register_scan_total, sip_exporter_invite_burst_total, sip_exporter_register_country_change_total
• Diagnostics — sip_exporter_sip_retransmission_total (SIP Timer A retransmissions), sip_exporter_rtp_out_of_order_total (out-of-sequence RTP packets), sip_exporter_short_calls_total (calls shorter than 20/60/180 seconds)

Full reference with formulas, examples, and RFC section mapping: docs/METRICS.md

If your SIP infrastructure handles traffic from multiple operators (telecom providers, SIP trunks, PBX clusters), you need to see metrics per operator, not in aggregate.

The carrier feature solves this by mapping IP subnets to operator names. Call metrics such as INVITE count, SER, active sessions, and RRD latency get a carrier label, so you can build separate Grafana dashboards and alerts for each operator.

How it works:

The exporter looks at the source IP of every SIP request and matches it against CIDR subnets in a YAML config. When UAC at 10.1.5.20 sends an INVITE, the exporter finds that 10.1.5.20 falls within 10.1.0.0/16 defined for carrier "telecom-alpha", and tags all metrics for this call — the INVITE itself, the 200 OK response, the BYE, even the dialog expiry — with carrier="telecom-alpha".

This means:

• INVITE from 10.1.5.20 → metrics labeled carrier="telecom-alpha"
• INVITE from 192.168.11.3 → metrics labeled carrier="telecom-beta"
• INVITE from 8.8.8.8 (not in any subnet) → metrics labeled carrier="other"

Setup:

Add a read-only mount for your carrier configuration to the production Compose file and set SIP_EXPORTER_CARRIERS_CONFIG=/etc/sip-exporter/carriers.yaml.

# carriers.yaml — map your operators' IP subnets
carriers:
  - name: "telecom-alpha"
    cidrs:
      - "10.1.0.0/16"
  - name: "telecom-beta"
    cidrs:
      - "192.168.10.0/24"
      - "192.168.11.0/24"

After that, metrics look like:

sip_exporter_invite_total{carrier="telecom-alpha",ua_type="other",source_country="unknown",direction="inbound",destination_country="unknown",caller_host="",called_host="",iface="ens3"} 1523
sip_exporter_ser{carrier="telecom-alpha",ua_type="other",source_country="unknown",direction="inbound"} 95.2
sip_exporter_ser{carrier="telecom-beta",ua_type="other",source_country="unknown",direction="inbound"} 87.4
sip_exporter_ser{carrier="other",ua_type="other",source_country="unknown",direction="inbound"} 0.0

Things to know:

• Carrier is determined at request time (INVITE/REGISTER/OPTIONS), not response time. If carrier-A sends INVITE and carrier-B answers 200 OK, all metrics still go to carrier-A — the operator who initiated the call
• If source IP doesn't match any CIDR, destination IP is tried. If neither matches → carrier="other"
• When CIDRs overlap, first match wins — list specific subnets before broad ones
• Without the config file, metrics carrying carrier use carrier="other" — nothing breaks
• Each carrier can have multiple CIDRs, and multiple carriers can be defined
• CIDR notation is required — plain IPs without / are rejected. Use /32 for a single host, e.g. "10.226.97.5/32" instead of "10.226.97.5"

Full config reference with examples: examples/carriers.yaml

If you need to see metrics per SIP device type — IP phones vs softphones vs SBCs — the User-Agent classification feature adds ua_type to metric families with device context.

The exporter reads the User-Agent SIP header from each request and matches it against regex patterns in a YAML config. Call metrics such as INVITE count, SER, active sessions, and SPD duration get a ua_type label, so you can build separate Grafana dashboards and alerts for each device family.

How it works:

The exporter parses the User-Agent header of every SIP request and matches it against regex patterns in a YAML config. When a phone with User-Agent: Yealink SIP-T46S 66.15.0.10 sends an INVITE, the exporter matches ^Yealink and tags all metrics for this call with ua_type="yealink".

This means:

• INVITE from Yealink phone → metrics labeled ua_type="yealink"
• INVITE from Grandstream phone → metrics labeled ua_type="grandstream"
• INVITE with unknown User-Agent → metrics labeled ua_type="other"

Setup:

Add a read-only mount for your User-Agent configuration to the production Compose file and set SIP_EXPORTER_USER_AGENTS_CONFIG=/etc/sip-exporter/user_agents.yaml.

# user_agents.yaml — map User-Agent patterns to device types
user_agents:
  - regex: '(?i)^Yealink'
    label: yealink
  - regex: '(?i)^Grandstream'
    label: grandstream
  - regex: '(?i)^Cisco/SPA'
    label: cisco_spa
  - regex: '(?i)^Kamailio'
    label: kamailio
  - regex: '(?i)^Asterisk'
    label: asterisk

After that, metrics look like:

sip_exporter_invite_total{carrier="telecom-alpha",ua_type="yealink",source_country="unknown",direction="inbound",destination_country="unknown",caller_host="",called_host="",iface="ens3"} 1523
sip_exporter_ser{carrier="telecom-alpha",ua_type="yealink",source_country="unknown",direction="inbound"} 95.2
sip_exporter_ser{carrier="telecom-alpha",ua_type="grandstream",source_country="unknown",direction="inbound"} 87.4
sip_exporter_ser{carrier="telecom-alpha",ua_type="other",source_country="unknown",direction="inbound"} 0.0

Things to know:

• UA type is determined at request time (INVITE/REGISTER/OPTIONS), using the same tracker mechanism as carrier. Responses inherit ua_type from the request tracker, not from the response's own headers
• The User-Agent header is extracted from all SIP packets, but SIP responses typically use the Server header, so in practice only requests provide meaningful classification
• If no pattern matches → ua_type="other"
• When patterns overlap, first match wins — list specific patterns before broad ones
• Without the config file, metrics carrying ua_type use ua_type="other" — nothing breaks
• Patterns are case-insensitive when using (?i) prefix
• Works together with carrier — base and call-level SIP metrics carry both labels for two-dimensional analysis

Combined carrier + ua_type queries:

# SER for Yealink phones on a specific carrier
sip_exporter_ser{carrier="telecom-alpha",ua_type="yealink"}

# Active sessions by device type (across all carriers)
sum by (ua_type) (sip_exporter_sessions)

# INVITE rate per carrier per device type
sum by (carrier, ua_type) (rate(sip_exporter_invite_total[5m]))

Full config reference with examples: examples/user_agents.yaml

The exporter adds geographic context to SIP metrics via two labels:

source_country resolution:

1. carrier.country — optional field in carriers.yaml, overrides GeoIP (operator-curated)
2. GeoIP(srcIP) — MaxMind GeoLite2-Country database lookup
3. "unknown" — fallback when neither is available

destination_country requires no database — the prefix table is embedded in the binary (Google libphonenumber, Apache 2.0). Set SIP_EXPORTER_LOCAL_COUNTRY_CODE for domestic numbers without international prefix.

caller_host / called_host are off by default (SIP_EXPORTER_HOST_LABELS=false). They expose the host part of the SIP From/To URI on invite_total / invite_200_total. Since distinct endpoint identifiers are unbounded, they are opt-in: enable (SIP_EXPORTER_HOST_LABELS=true) only on trusted deployments where the endpoint count is bounded, otherwise they can grow Prometheus memory. See Security > Data Exposed in Prometheus Labels.

Setup:

Follow the GeoIP setup guide to add the read-only database mount and SIP_EXPORTER_GEOIP_COUNTRY_DB to the production Compose file.

Full reference with formulas and PromQL examples: docs/METRICS.md > Geo-Enrichment Labels

Step-by-step setup (how to get and connect the MaxMind database): docs/geoip.md

# SER for calls to Russia
sum(rate(sip_exporter_invite_200_total{destination_country="RU"}[5m]))
  / sum(rate(sip_exporter_invite_total{destination_country="RU"}[5m])) * 100

# INVITE rate by destination country
sum by (destination_country) (rate(sip_exporter_invite_total[5m]))

In addition to SIP signaling, the exporter captures RTP media streams to estimate transport quality at the capture point (jitter, sequence gaps, and E-model MOS). RTP streams are correlated with SIP dialogs: when a 200 OK to INVITE carries SDP, the exporter registers the negotiated media endpoints and tracks the matching RTP flows until BYE (or Session-Expires expiry). This means RTP metrics inherit the dialog's carrier, ua_type, source_country, and direction labels, plus the negotiated codec.

Metrics produced:

Privacy: RTP packets are copied to userspace in snapshots capped at 64 bytes, so a small prefix of payload can accompany the headers. The application parses only the fixed 12-byte RTP header and does not inspect or persist audio. Matched RTCP compounds are copied up to the Ethernet MTU so their report blocks can be parsed.

RTP capture is always enabled. RTP without a correlated SIP dialog (no SDP exchange seen) is dropped, so only media for monitored calls is counted.

The eBPF filter uses SDP-driven RTP detection: media endpoints (IP:port) learned from INVITE 200 OK SDP are inserted into a BPF LRU hash map. Only UDP packets matching a registered endpoint pass the kernel filter — all other UDP is dropped. This eliminates false positives from random UDP traffic on public IPs.

How to interpret QoE: RTP loss, jitter, PDV, and MOS are observations of packets that reached this sensor; they are not a subscriber's subjective score or proof of end-to-end impairment. RTCP SR/RR adds the receiver's own RTP statistics for a correlated SSRC, but still covers only reports and media visible to the sensor. Before acting on QoE alerts, verify sip_exporter_socket_packets_dropped_total, sip_exporter_rtp_dropped_total, and the deployment topology above.

# Average MOS over the last 5m (per codec)
sum by (codec) (rate(sip_exporter_rtp_mos_score_sum[5m]))
  / sum by (codec) (rate(sip_exporter_rtp_mos_score_count[5m]))

# Packet loss ratio by carrier
sum by (carrier) (rate(sip_exporter_rtp_packets_lost_total[5m]))
  / (
      sum by (carrier) (rate(sip_exporter_rtp_packets_total[5m]))
      + sum by (carrier) (rate(sip_exporter_rtp_packets_lost_total[5m]))
    )

See docs/METRICS.md for the full RTP reference, formulas, and label resolution.

The exporter emits signals for common toll-fraud patterns, exposed as Prometheus counters/gauges:

• Registration scan — many unique accounts (AoR) registered (200 OK) from one source IP in a short window (tunable via SIP_EXPORTER_FRAUD_REGISTER_SCAN_THRESHOLD / _WINDOW)
• INVITE burst — abnormal INVITE rate from one source (tunable via SIP_EXPORTER_FRAUD_INVITE_BURST_THRESHOLD / _WINDOW)
• Account takeover — the same AOR successfully re-registers from a country different from its active registration

Full setup, metrics reference, and alerting guidance: docs/fraud-detection.md

Before contributing, read the Contributing Guide and Code of Conduct. Report vulnerabilities privately through the Security Policy.

• Go 1.26.6+
• Clang/LLVM (for eBPF compilation)
• golangci-lint v2.9.0 and goimports (for make lint / make imports)
• Linux kernel with eBPF support
• Root privileges (required for eBPF and packet socket)

Coverage changes with the test suite and is not pinned in this document. Generate current package coverage with go test -cover ./internal/... ./pkg/....

Test suite:

• Unit tests — MC/DC-oriented coverage of business logic
• Table-driven E2E tests — real SIP traffic via SIPp + testcontainers-go, covering RFC 6076, RFC 6035, RTP, RTCP, fraud, and multi-interface behavior
• Load tests — PPS throughput, VQ reports, concurrent sessions, memory stability, GC pauses, and scrape latency

See BENCHMARK.md for the release-verified load envelope, methodology, acceptance gates and scope limitations.

The repository includes a Grafana dashboard and documented Prometheus alert-rule examples.

Grafana dashboard — import manually:

1. Grafana → Dashboards → Import
2. Upload examples/grafana-dashboard.json
3. Select your Prometheus or VictoriaMetrics datasource

The dashboard includes: traffic counters, SIP request/response breakdowns, active sessions, RFC 6076 performance metrics (SER, SEER, ISA, SCR, NER), registrations (active count, success ratio, failures by code, fraud signals), RTP media analysis (active streams, packet rate, loss rate, MOS, jitter by codec), voice quality metrics (RFC 6035: MOS, jitter, packet loss), delay histograms (RRD, TTR, PDD, SPD, ORD, LRD, PBD), session quality metrics (ISS, ASR, SDC), diagnostics (SIP retransmissions, short calls), and system errors.

Full alerting guide with Prometheus rules, Alertmanager configs (Slack/PagerDuty/Email), and threshold tuning: docs/ALERTING.md

SIP-Exporter exports metrics in Prometheus exposition format, compatible with:

• Prometheus — pull-based monitoring
• VictoriaMetrics — Prometheus-compatible time-series database
• Grafana Cloud — cloud-based observability
• Any Prometheus-compatible scraper — the /metrics endpoint follows the standard format

For support, bug reports, and feature requests, use GitHub Issues. Report suspected vulnerabilities privately through the Security Policy.

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE for full text.

• MaxMind GeoLite2 (source_country) — users download the database separately. Use, attribution, redistribution, and update obligations are governed by the GeoLite EULA and the incorporated CC BY-SA 4.0 terms.
• Google libphonenumber (destination_country) — Apache License 2.0. E.164 prefix data embedded in the binary at compile time.

• ✅ Free for personal and educational use
• ✅ Free for commercial use with conditions
• ⚠️ If you modify the program and let users interact with that modified version over a network, AGPL-3.0 §13 requires offering its Corresponding Source to those users
• 📧 For commercial licensing without AGPL requirements, contact the author

See the GitHub Releases for version history.