Ask a Media Relay About Itself - NormB/sipnab GitHub Wiki
A media relay keeps its own counters: the packets it relayed, the sessions it holds, and its own loss and jitter. sipnab can ask an rtpengine relay for them, and put them beside what sipnab measured on the wire.
Use this page when you suspect the relay itself:
- calls sound bad and the relay may be dropping packets;
- the relay may be holding sessions that nobody released;
- you want the relay's count for one call beside your capture's.
Every answer here is the relay's own claim, labeled relay_reported. sipnab
never adds it to, or subtracts it from, a number it measured. To name the
calls behind the media on a relay, see
Let sipnab name rtpengine's media instead.
-
The relay is rtpengine. sipnab asks over rtpengine's
ngcontrol protocol. sipnab sends rtpproxy nothing, so none of these requests apply to rtpproxy (Let sipnab name rtpproxy's media). -
No change to rtpengine. sipnab asks on the control address rtpengine
already listens on, its
listen-ngsetting. Every request only reads:statistics,listandquery. Nothing here can create, change or delete a call. - No change on any other system. The SIP proxy, Homer and the phones stay as they are.
-
The control address must be reachable from sipnab. rtpengine's control
protocol has no authentication, so run sipnab on the relay's own machine, or
on a host your firewall already lets reach
listen-ng. -
A live source. Asking transmits, so sipnab asks only on a run that
captures an interface (
-d) or listens for HEP (-L). A run that reads a capture file never asks. -
Privileges. Capturing an interface needs root or the capture
capabilities
sudo sipnab --setup-capsgrants once. -
Build. Every release binary can ask. A source build needs the
nativefeature, which the default build includes. The REST routes needapiand the MCP tools needmcp;sipnab --versionlists both when the binary carries them.
The examples use 127.0.0.1:22222 for the relay's listen-ng address and
eth0 for the interface. Replace them with yours. The output on this page
came from sipnab 0.5.232 against rtpengine 12.5.1 (the Debian 13 package),
with the relay's address written as 127.0.0.1 and the SIP test clients'
address as 192.0.2.21.
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats --duration 1sipnab asks once, prints the answer, and captures for --duration seconds.
The answer is long: rtpengine 12.5.1 reports 303 counters. The header names
the relay, when it answered, and the tier:
Relay statistics (rtpengine at 127.0.0.1:22222, asked 2026-11-03T15:38:21Z) — relay_reported counts
result ok
statistics.currentstatistics.sessionsown 1
statistics.totalstatistics.managedsessions 6
statistics.totalstatistics.relayedpacketerrors 0
statistics.totalstatistics.relayedpackets 51643
statistics.totalstatistics.timeoutsessions 1
statistics.totalstatistics.uptime 85077
That is a few lines of the answer. Keep only the lines you want with grep:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats --duration 1 2>/dev/null \
| grep -E 'sessionsown|relayedpackets |packets_lost|uptime' statistics.currentstatistics.sessionsown 0
statistics.interfaces.0.packets_lost 0
statistics.totalstatistics.relayedpackets 51451
statistics.totalstatistics.uptime 85061
statistics.voip_metrics.packets_lost 0
Read these first:
| Counter | What it says |
|---|---|
statistics.currentstatistics.sessionsown |
Calls the relay holds now |
statistics.totalstatistics.relayedpackets |
Packets relayed since the relay started |
statistics.totalstatistics.relayedpacketerrors |
Packets the relay failed to relay |
statistics.interfaces.0.packets_lost |
Loss the relay counted on its first interface |
statistics.totalstatistics.uptime |
Seconds since the relay started |
The counters are cumulative and reset when rtpengine restarts. A small
relayedpackets can mean a quiet relay or one that restarted a minute ago.
uptime tells them apart.
The names depend on the rtpengine version. Ask for the names alone:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats-list --duration 1 2>/dev/null | head -3Statistics rtpengine at 127.0.0.1:22222 knows (303 names, asked 2026-11-03T15:19:04Z) — the relay listed these in a statistics reply
result
statistics.controlstatistics.proxies.0.answercount
The header says how sipnab learned the names: the relay listed them. sipnab holds no table of its own.
Give a Call-ID the relay holds:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats-call '[email protected]' --duration 1 2>/dev/null \
| grep -E '^Relay|totals'Relay statistics (rtpengine at 127.0.0.1:22222, call [email protected], asked 2026-11-03T15:19:03Z) — relay_reported counts
totals.RTCP.bytes 0
totals.RTCP.errors 0
totals.RTCP.packets 0
totals.RTP.bytes 530104
totals.RTP.errors 0
totals.RTP.packets 3082
Without the grep, the answer also lists each side of the call by its tag:
the codec, the relay's port, and the packets and bytes per SSRC.
One answer is a snapshot. To see a counter move, poll on a timer:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats-interval 2 --duration 5 2>/dev/null \
| grep -E '^Relay|sessionsown|relayedpackets |uptime'Relay statistics (rtpengine at 127.0.0.1:22222, polled 2026-11-03T15:19:22Z, every 2s) — relay_reported counts
statistics.currentstatistics.sessionsown 2
statistics.totalstatistics.relayedpackets 14117
statistics.totalstatistics.uptime 83938
Relay statistics (rtpengine at 127.0.0.1:22222, polled 2026-11-03T15:19:24Z, every 2s) — relay_reported counts
statistics.currentstatistics.sessionsown 2
statistics.totalstatistics.relayedpackets 14517
statistics.totalstatistics.uptime 83940
- Each reading says
polledand names the interval. - The interval is 1 to 3600 seconds. Nothing polls unless you give one.
- sipnab sends the next request only after the previous answer, so a slow relay slows the cadence rather than piling up requests. A poll whose round trip takes longer than the interval logs a warning that the cadence has slipped.
- A cumulative counter that is lower than at the previous poll logs a warning that the relay probably restarted. The counters after it start from an unknown point.
- Only the command line polls. REST and MCP do not offer it.
--json prints one object per answer, on one line. Here grep picks out its
envelope and two of its counters:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-stats --json --duration 1 2>/dev/null \
| tail -1 \
| grep -oE '"(obtained_at|origin|relay)":"[^"]*"|\{"name":"statistics\.(currentstatistics\.sessionsown|totalstatistics\.uptime)","tier":"[a-z_]*","value":"[^"]*"\}'"obtained_at":"2026-11-03T19:13:24Z"
"origin":"asked"
"relay":"rtpengine at 127.0.0.1:22222"
{"name":"statistics.currentstatistics.sessionsown","tier":"relay_reported","value":"0"}
{"name":"statistics.totalstatistics.uptime","tier":"relay_reported","value":"97979"}
The object carries relay, origin (asked, or polled under
--relay-stats-interval), obtained_at, refusals, and statistics: one
entry per counter, with its name, its tier and its value as the relay
wrote it.
To see which calls the relay is carrying right now, without capturing anything:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-holdings 2>/dev/nullHoldings of relay (rtpengine at 127.0.0.1:22222), asked 2026-11-03T15:18:50.189704516+00:00
1 call held.
Call-ID
----------------
[email protected]
- sipnab sends one
listrequest, prints the answer and exits 0. It reads no packet. - The relay returns at most 32 Call-IDs unless you raise the limit with
--relay-holdings-max <CALLS>, up to 1024. When it returns as many as you asked for, the answer says the relay may hold more. See Choose how many held calls one ask covers. -
--jsonprints the bodyGET /v1/relay/holdingsreturns, with"truncated"true or false.
A leaked session is one the relay still holds after its call ended. Compare
this list with the calls your SIP proxy still has up. A Call-ID the relay
holds and the proxy does not is a candidate. rtpengine removes a session
whose media stopped only after its RTP timeout setting has passed, so a
call that ended a short time ago can still appear.
For each call the relay holds, sipnab can say per direction whether the relay is receiving that party's media. Use it during a "no audio" or "one-way audio" incident: it names the party whose media never reached the relay, from one answer of the relay's and on the relay's own clock.
-
On the relay: nothing to change. sipnab sends rtpengine's
listandqueryon itslisten-ngaddress. Neither creates, changes or deletes a call. -
--rtpengine-control <listen-ng address>on the sipnab command line, and a live source (-dor-L), as for every request on this page. -
For REST, start the server with
--api-allow-relay-query. For MCP, start it with--mcp-allow-relay-query. Without the opt-in the request sends nothing. -
To mark a hung-up call
ended, sipnab must see that call's SIP: a TUI, REST or MCP run that captures the signaling. A--relay-sessionsrun asks before it reads any packet, so it can only say that the relay may still list a call for about 30 s after it ends.
The output in this section came from this build of sipnab against the
harness relay, rtpengine 12.5.1 in userspace, with calls placed by SIPp
through OpenSIPS. This page writes the relay's address as 192.0.2.11 and
the SIP test clients' as 192.0.2.21.
sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.11:22222 --relay-sessions 2>/dev/null-L 127.0.0.1:0 is a HEP listener that receives nothing. It is enough to
make the run live, so it needs no privileges. sipnab sends one list, then
one query per held call, up to --relay-holdings-max (32 by default, at
most 1024), prints the answer and exits 0:
Sessions of relay (rtpengine at 192.0.2.11:22222), asked 2026-11-04T16:01:54.067925771+00:00 (relay_reported)
reachable; 2 calls listed; queried 2 of 2 (scan)
Note: a relay keeps a call it was told to delete for its delete delay (30 s by default) and its answer does not mark it; a call sipnab did not see end in SIP may have ended up to about 30 s ago.
Note: stalled means no packet for more than 2 s while another socket of the same call received one; silence suppression, comfort noise, hold and loss bursts were not measured and can also produce it.
[email protected] from 104SIPpTag001: never received; from 1SIPpTag0110: flowing
[email protected] from 105SIPpTag091: flowing; from 1SIPpTag0111: flowing
Call [email protected] (relay_reported)
sipnab did not see its SIP dialog end; the relay may still list a call for about 30 s after it ends.
from 104SIPpTag001 to 192.0.2.11:30038: never received
from 1SIPpTag0110 to 192.0.2.11:30000: flowing
Tag Relay socket Kind In pkts In bytes In errs Out pkts Out bytes Out errs Last packet Forwarding
-------------------------------------------------------------------------------------------------------------------------
104SIPpTag001 192.0.2.11:30038 rtp 0 0 0 243 41796 0 1793808109 userspace
104SIPpTag001 192.0.2.11:30039 rtcp 0 0 0 0 0 0 1793808109 userspace
1SIPpTag0110 192.0.2.11:30000 rtp 245 42140 0 0 0 0 1793808114 userspace
1SIPpTag0110 192.0.2.11:30001 rtcp 0 0 0 0 0 0 1793808109 userspace
The first call's caller sent no media, and the answer says so: the relay counted 0 packets in on that party's socket and never confirmed it. The second call's media reaches the relay both ways. Each call's table, the second one's included, follows.
How to read a direction:
| Verdict | Meaning |
|---|---|
flowing |
packets are arriving on that party's RTP socket |
never received |
the socket counted 0 packets in, and the relay never marked it confirmed
|
no packet for N s (stalled) |
its last packet is more than 2 s behind the newest one of any RTP socket of the same call, in the same answer |
not reported by this relay version (not_reported) |
the relay's answer lacked the counters, the last-packet time or the flags |
-
stalledcompares sockets of one call. When every socket of a call stops together, none trails another, so the call still readsflowing. TheLast packetcolumn is the relay's own time in seconds. - A call with an early media branch (a parallel fork that sent early media) shows its counters and no verdict. rtpengine can count the answered party's media on the early branch's socket, and a verdict per socket would call a live party silent.
-
Forwardingiskernelwhen the relay flags the socketkernelizedwithoutno kernel support, anduserspaceotherwise. -
Absent is not zero. A counter the relay did not report reads
not reported, and the JSON leaves it out.
To ask about one call only, with one list and one query:
sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.11:22222 --relay-sessions --relay-sessions-call [email protected] --json 2>/dev/null--json prints one object on one line, the body of GET /v1/relay/sessions.
Here it is pretty-printed and shortened to one tag and one socket:
{
"calls": [
{
"call_id": "[email protected]",
"directions": [
{
"from_tag": "105SIPpTag091",
"local_address": "192.0.2.11",
"local_port": 30014,
"media_index": 1,
"verdict": "flowing"
},
{
"from_tag": "1SIPpTag0111",
"local_address": "192.0.2.11",
"local_port": 30048,
"media_index": 1,
"verdict": "flowing"
}
],
"outcome": "ok",
"sip_dialog": "not_seen_ended",
"tags": [
{
"in_dialogue_with": [
"1SIPpTag0111"
],
"is_media_subscriber": false,
"sockets": [
{
"egress": {
"bytes": 135020,
"errors": 0,
"packets": 785
},
"endpoint": "192.0.2.21:6000",
"ingress": {
"bytes": 135020,
"errors": 0,
"packets": 785
},
"kernel": "userspace",
"kind": "rtp",
"last_packet": 1793808124,
"local_address": "192.0.2.11",
"local_port": 30014,
"media_index": 1
}
],
"tag": "105SIPpTag091"
}
]
}
],
"cap": 32,
"held": 2,
"list_limit": 32,
"not_queried": [
{
"call_id": "[email protected]",
"sip_dialog": "not_seen_ended"
}
],
"notes": [
"a relay keeps a call it was told to delete for its delete delay (30 s by default) and its answer does not mark it; a call sipnab did not see end in SIP may have ended up to about 30 s ago",
"stalled means no packet for more than 2 s while another socket of the same call received one; silence suppression, comfort noise, hold and loss bursts were not measured and can also produce it"
],
"obtained_at": "2026-11-04T16:02:04.870332099+00:00",
"outcome": "ok",
"reach": "ok",
"relay": "relay (rtpengine at 192.0.2.11:22222)",
"scan": false,
"stall_seconds": 2,
"tier": "relay_reported",
"truncated": false
}not_queried names the held calls this answer did not ask about, so a call
never drops out of the answer. truncated is true when list returned as
many Call-IDs as it asked for, and the relay may then hold more.
Start a server with both opt-ins:
sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.11:22222 \
--api 127.0.0.1:18731 --api-allow-relay-query \
--mcp --mcp-transport http --mcp-bind 127.0.0.1:18732 --mcp-allow-relay-queryGET /v1/relay/sessions takes call_id (one call to query), scan=true
(every held call, up to the cap) and max_calls (the cap, or without it
--relay-holdings-max, or 32). Without scan, sipnab asks only list and
call_id:
curl -s "http://127.0.0.1:18731/v1/relay/[email protected]" | jq '.calls[0].directions'[
{
"from_tag": "104SIPpTag001",
"local_address": "192.0.2.11",
"local_port": 30038,
"media_index": 1,
"verdict": "never_received"
},
{
"from_tag": "1SIPpTag0110",
"local_address": "192.0.2.11",
"local_port": 30000,
"media_index": 1,
"verdict": "flowing"
}
]Over MCP, call query_relay with {"sessions": true, "scan": true}. The
answer has "asked": "sessions", "outcome": "sessions", and the same
snapshot under sessions. The two calls above came back as:
[email protected] [('104SIPpTag001', 'never_received'), ('1SIPpTag0110', 'flowing')]
[email protected] [('105SIPpTag091', 'flowing'), ('1SIPpTag0111', 'flowing')]
That listing is each calls[] entry's call_id and its directions, read
from the tool's JSON.
rtpengine keeps a hung-up call for its delete delay, 30 s by default, and answers for it as it did while the call was up. Asked a few seconds after the first call above hung up, the relay still listed it:
[email protected] from 104SIPpTag001: never received; from 1SIPpTag0110: flowing
Its callee still reads flowing: that socket was the newest of its call, so
nothing trailed it.
A run that sees the SIP marks such a call. Start the server capturing the bridge the SIP crosses:
sudo sipnab -N -d br-0b7ba286bc5b --rtpengine-control 192.0.2.11:22222 --api 127.0.0.1:18741 --api-allow-relay-queryThen a 5 s call, asked about after its BYE, reads:
curl -s "http://127.0.0.1:18741/v1/relay/[email protected]" | jq '.calls[0] | {call_id, sip_dialog, directions}'{
"call_id": "[email protected]",
"sip_dialog": "ended",
"directions": [
{
"from_tag": "114SIPpTag001",
"local_address": "192.0.2.11",
"local_port": 30040,
"media_index": 1,
"verdict": "never_received"
},
{
"from_tag": "1SIPpTag0112",
"local_address": "192.0.2.11",
"local_port": 30036,
"media_index": 1,
"verdict": "flowing"
}
]
}br-0b7ba286bc5b is the harness's Docker bridge. Replace it with the
interface your SIP crosses.
Open the relay view with S, then press H:
┌ Relay sessions — what the relay holds
│Sessions of relay (rtpengine at 192.0.2.11:22222), asked 2026-11-04T16:03:55.240602811+00:00 (relay_reported)
│reachable; 1 call listed; queried 1 of 1
│Note: a relay keeps a call it was told to delete for its delete delay (30 s by default) and its answer does not mark it; a call sipnab did not see end in SIP
│may have ended up to about 30 s ago.
│Note: stalled means no packet for more than 2 s while another socket of the same call received one; silence suppression, comfort noise, hold and loss bursts
│were not measured and can also produce it.
│
│> [email protected] from 121SIPpTag091: flowing; from 1SIPpTag0113: flowing
│
│Enter opens the call under the cursor; a asks every held call once (up to the cap).
- While the view is open it asks for the list and the call under the cursor
every
--relay-stats-intervalseconds, or every 2 s without it (DEFAULT_REFRESH_SECS(2) insrc/tui/relay_sessions.rs). It asks nothing once you close it. -
aasks about every held call once, up to--relay-holdings-max(32 by default). Up and Down move the cursor, and Enter opens that call's directions and socket table. - In one call's view,
Ksets each relay socket's counts beside what this capture saw on it for that call, two tiers named and never subtracted. Captured on the harness bridge, starting partway through the call:
Call [email protected]: relay sockets beside this capture
relay_reported is what the relay counted; sipnab_measured is what this capture saw.
121SIPpTag091 192.0.2.11:30010 (rtp)
in: relay_reported 2023 sipnab_measured 768
out: relay_reported 2023 sipnab_measured 768
121SIPpTag091 192.0.2.11:30011 (rtcp)
in: relay_reported 0 sipnab_measured not captured
out: relay_reported 0 sipnab_measured not captured
The relay counts from the start of the call and the capture from when it
started, so the two differ. not captured means this capture has no
stream of this call to or from that socket. On a run that captures no
media, such as -L, every socket reads not captured.
sipnab_measured counts only the streams sipnab linked to this Call-ID.
rtpengine gives a port to a new call once an old call has released it, so
in a long capture one relay socket can have carried several calls. The count
leaves out streams linked to another Call-ID. K shows streams on the socket
that sipnab linked to no dialog after the count, apart from it and never
added to it, as not linked to a dialog N: nothing ties them to this call, and
they can belong to an earlier call on the same port.
sipnab -N -L 127.0.0.1:0 --rtpengine-control 127.0.0.1:22222 --relay-sessions 2>/dev/null; echo "exit $?"-
--relay-sessionsexits 0, so the last line isexit 0, and its second line startsreachable;. - Every call the relay holds is in the answer, as a row with verdicts or as
not queried. - On a call with audio both ways, both directions read
flowing. If they do not, read the troubleshooting list below before suspecting the relay.
-
--relay-sessions will not ask a relay on a run that reads a file: asking transmits. Ask from a live source (-d <device> or -L <addr>).and exit 2. The run reads a capture file, and sends nothing. -
--relay-sessions: unreachable: relay (rtpengine at 192.0.2.11:22299) did not answer (no reply from 192.0.2.11:22299 within 2s); asked, nothing came backand exit 1. No relay answers at that address. Use the relay'slisten-ngvalue. sipnab sends noqueryafter an unansweredlist. -
error: the following required arguments were not provided: --rtpengine-control <ADDR>.--relay-sessionsand--relay-sessions-callneed the relay's address. -
not_permittedfromGET /v1/relay/sessions. The server lacks--api-allow-relay-query, or reads a capture file. It sent nothing. -
A call that hung up still reads
flowing. The relay keeps it for its delete delay. Ask from a run that sees the SIP, which marks itended. -
A direction reads
no packet for N son a call with audio. The sending phone may suppress silence or send comfort noise, or the call may be on hold. Those cases were not measured, and can make a live party trail by more than 2 s. - A call shows its counters and "early media branch". The call forked and one branch sent early media; read the socket table instead of a verdict.
-
A held call reads
not queried. The scan stops at the cap, 32 by default, the selected call included. Raise it with--relay-holdings-maxormax_calls, or ask about that call with--relay-sessions-call. -
Asked for 5000 calls; the ceiling is 1024, so at most 1024 were asked for.(cap_clampedunder--json, REST and MCP.) The cap you named is above the ceiling. sipnab asked for 1024 and answered. Ask about the calls you need by Call-ID. -
max_calls: the number of calls must be at least 1. A REST 400 or an MCPinvalid_paramserror formax_calls=0. sipnab sent nothing. -
Kshowsnot linked to a dialog Nafter the count. The capture holds streams on that relay socket that sipnab linked to no dialog. They are not counted for this call. A stream links to a dialog when sipnab sees the SDP that names its address, or asks the relay about the stream.
One number bounds every relay ask about the held calls: the Call-IDs a
list asks for, and the calls a sessions scan queries, the selected call
included. A scan costs the relay one list and one query per call it
covers, so this number is what one ask costs it. The same rule applies to
--relay-holdings, --relay-sessions, the TUI sessions view, GET /v1/relay/holdings, GET /v1/relay/sessions and the MCP query_relay
tool:
| You give | The cap |
|---|---|
| nothing | 32 |
--relay-holdings-max N |
N, for every surface of the run |
max_calls=N on REST or MCP |
N, for that ask |
| a number above 1024, either way | 1024, and the answer says so |
0, either way |
refused, and sipnab sends nothing |
Prerequisites: --rtpengine-control on the command line, as for every ask on
this page. sipnab refuses --relay-holdings-max without it. sipnab sends a
list above 32 over TCP to the same address, because the answer may not fit
in one UDP datagram, so a cap above 32 needs rtpengine's listen-tcp-ng on
that address. Without it the list fails and the answer reads
unreachable.
To raise the TUI's and the servers' default to 200:
sudo sipnab -d eth0 --rtpengine-control 192.0.2.11:22222 \
--api 127.0.0.1:18731 --api-allow-relay-query --relay-holdings-max 200To ask for more than that in one REST request:
curl -s "http://127.0.0.1:18731/v1/relay/sessions?scan=true&max_calls=500" | jq '{cap, cap_clamped}'Check that it worked: the answer's cap is the number you gave, and its
first status line says queried N of M, with N at most the cap. A cap
of 5000 reads "cap": 1024 with "cap_clamped": {"requested": 5000, "ceiling": 1024}, and the text answer says the ceiling is 1024. The
troubleshooting list above covers the refusals.
For one call, put the relay's RTP packet count beside the count sipnab measured. The capture must see the call's media, so run it where the media passes, here on the relay's own machine:
sudo sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 --relay-compare '[email protected]' --duration 5 2>/dev/null \
| grep -A3 '^Relay vs capture'Relay vs capture for call [email protected] (rtpengine at 127.0.0.1:22222, asked 2026-11-03T16:11:40Z) — differ
relay 818 [relay_reported totals.RTP.packets]
sipnab 996 [sipnab_measured]
note: the relay counted fewer; a capture that sees both sides of a relay counts each packet more than once -- once arriving at the relay and once leaving it -- so a point upstream AND downstream of the relay reads about twice the relay's own count. A window that does not line up or a relay restart mid-call also gaps them. To compare like for like, capture one leg, or read the relay's per-stream counts.
sipnab asks after the capture ends, so its own count is final. A capture on the relay's machine sees each packet arrive and leave, so here sipnab counted more than the relay. The note names the cause. When the call was up before the capture began, the gap runs the other way and the note says so: the relay counted packets the capture never saw.
Read it with the three loss figures apart:
- the relay's own count (
relay_reported), for its sockets since it started; - sipnab's count (
sipnab_measured), for what reached the capture point; - the far end's RTCP report (
endpoint_reported), which nobody can check.
Never subtract one from another. They count different sockets over different windows. Quote the tier with the number: "the relay reports 40 lost, our capture measured 3 gaps".
The REST server answers the same questions on six routes. They transmit, so
they are off unless you add --api-allow-relay-query:
sudo env SIPNAB_API_KEY="$SIPNAB_API_KEY" sipnab -N -d eth0 --rtpengine-control 127.0.0.1:22222 \
--api 127.0.0.1:8080 --api-allow-relay-queryAUTH="Authorization: Bearer $SIPNAB_API_KEY"curl -s -H "$AUTH" http://127.0.0.1:8080/v1/relay/holdings{"call_ids":["[email protected]","[email protected]","[email protected]"],"kind":"calls","obtained_at":"2026-11-03T15:19:51.410109408+00:00","origin":"asked","outcome":"ok","relay":"relay (rtpengine at 127.0.0.1:22222)","truncated":false}| Route | Answers |
|---|---|
GET /v1/relay/stats |
the relay's counters, as --relay-stats
|
GET /v1/relay/stats/names |
the names it knows, as --relay-stats-list
|
GET /v1/relay/stats/call/{call_id} |
one call's counters, as --relay-stats-call
|
GET /v1/relay/compare/{call_id} |
the comparison, as --relay-compare
|
GET /v1/relay/holdings |
the Call-IDs it holds, as --relay-holdings; ?max_calls= raises the limit |
GET /v1/relay/holdings/{call_id} |
one call's tags, ports, SSRCs and codec |
Every answer is HTTP 200 with an outcome field. Branch on it first: ok,
or one of not_configured, not_permitted, unreachable, refused and
suspect. The comparison carries its two counts and the verdict under
packets.
Without --api-allow-relay-query, every route refuses. /v1/relay/holdings
answers:
{"detail":"this run may not query the relay; it needs a live capture source and --api-allow-relay-query","outcome":"not_permitted","responsibility":"invocation"}The REST API reference gives each route's full response.
The MCP server has three tools that ask the relay. All three transmit, so
they need the same three things: --mcp-allow-relay-query,
--rtpengine-control, and a live source.
sudo sipnab --mcp -N -d eth0 --rtpengine-control 127.0.0.1:22222 --mcp-allow-relay-query --quiet| Tool | Arguments | Answers |
|---|---|---|
query_relay |
none, or call_id
|
the Call-IDs the relay holds, or one call's tags and streams |
relay_stats |
none, call_id, or names_only: true
|
the relay's counters, one call's, or the names it knows |
relay_compare |
call_id |
the relay's count beside sipnab's, with a verdict and a note |
relay_compare { "call_id": "[email protected]" }
answers, trimmed:
{"call_id":"[email protected]","delivery_trust":"asked","outcome":"compared","relay_address":"127.0.0.1:22222","relay_reported":{"name":"totals.RTP.packets","value":2112},"sipnab_measured":1188,"schema_version":1}delivery_trust: "asked" means sipnab asked the relay over its control
socket, so no third party could have answered. decode_ng needs none of the
three opt-ins: it decodes a relay control message already in the capture
(rtpengine relay attribution).
The relay tool reference gives each tool's full response.
A dashboard or an agent can read the relay's counters without asking the
relay itself. A headless run started with --relay-stats-interval keeps its
newest reading, and serves it on GET /v1/relay/stats/polled and the MCP tool
relay_stats_polled. Only that run's poll talks to rtpengine, however many
readers there are.
Prerequisites. Those in Before you start, with two differences:
- Reading sends nothing to the relay. It needs no
--api-allow-relay-queryor--mcp-allow-relay-query. The poll itself is the operator's, on the command line. - Serve MCP over HTTP (
--mcp --mcp-transport http) on the polling run. Over stdio, sipnab refuses--relay-stats-interval, because it prints each reading to stdout, which the stdio transport owns.
Steps. Start a headless run that polls every five seconds and serves
REST, wait for a reading, and read it. Then stop the run. This example listens
for HEP on 127.0.0.1:9061 as its live source:
# Run all of these, in order.
sipnab -N -L 127.0.0.1:9061 --rtpengine-control 127.0.0.1:22222 --relay-stats-interval 5 --api 127.0.0.1:8091 --api-key s3cret > /dev/null 2>&1 &
sleep 8
curl -s -H "Authorization: Bearer s3cret" http://127.0.0.1:8091/v1/relay/stats/polled | jq '{outcome, relay, origin, interval_secs, age_secs}'
curl -s -H "Authorization: Bearer s3cret" http://127.0.0.1:8091/v1/relay/stats/polled | jq '.statistics[] | select(.name | endswith("sessionsown"))'
kill $!Verify. The first curl prints the reading's header:
{
"outcome": "ok",
"relay": "rtpengine at 127.0.0.1:22222",
"origin": "polled",
"interval_secs": 5,
"age_secs": 2
}The second prints one of the relay's counters, with its tier:
{
"name": "statistics.currentstatistics.sessionsown",
"value": "0",
"tier": "relay_reported"
}-
outcomeisokonce the poll has obtained a reading. -
age_secsstays belowinterval_secswhile the relay answers. - An agent calls
relay_stats_polledwith no arguments and gets the same fields.
Troubleshoot.
-
"outcome": "not_polling". The run was not started with--relay-stats-interval, or it is a terminal-interface run: the TUI polls only while its relay view is open, and keeps those readings to itself. -
"outcome": "no_reading_yet"with alast_pollofunreachable. Nothing answers at--rtpengine-control. Give it rtpengine'slisten-ngaddress. The run's log saysdid not answer the polled statistics request. -
age_secskeeps growing pastinterval_secs, beside alast_poll. The poll still runs, and the relay stopped answering after the reading shown. The reading stays until a newer one replaces it. -
The run exits with
--relay-stats-interval will not poll a relay on a run that reads a file.-Icannot poll, because polling transmits. Use a live source.
The reference entries are
GET /v1/relay/stats/polled and
relay_stats_polled.
Start the TUI with the relay's control address, on a live source:
sudo sipnab -d eth0 --rtpengine-control 127.0.0.1:22222Press S to open the Relay statistics view:
- from the call list, it shows the relay's counters;
- from a call's flow view, it shows that call's counters.
The view asks in the background and says that it is asking the relay until the answer arrives. Inside it:
| Key | Shows |
|---|---|
? |
the names the relay knows |
H |
the relay sessions: each held call and whether media reaches the relay each way (see above; press again for the counters) |
K |
the relay's count beside this capture's, in a call's view only |
Esc or S
|
closes the view |
K needs the call's media in the capture. On a machine that sees the SIP
and not the media, it reads:
Relay statistics unavailable — not_configured (invocation)
the relay reports 542 RTP packet(s) for call [email protected], but this capture measured none for it; widen the capture filter to include the media
-
--relay-stats will not ask a relay on a run that reads a file(on stderr, exit 2). The run reads a capture file. Ask from a live capture with-d. sipnab refuses the run before it reads the file. -
--relay-holdings will not ask a relay on a run that reads a fileand exit 2. The same, for--relay-holdings. Its live sources are-dand-L. -
relay at 127.0.0.1:22222 did not answer the statistics request (no reply from 127.0.0.1:22222 within 2s). Nothing answers at that address. Give--rtpengine-controlthelisten-ngvalue from rtpengine's configuration, and check that sipnab can reach it. For the same cause,--relay-holdingsexits 1 with--relay-holdings: unreachable: relay (rtpengine at 127.0.0.1:22222) did not answer (no reply from 127.0.0.1:22222 within 2s); asked, nothing came back. -
Permission denied on 'eth0'and exit 1. The capture needs privileges. Run withsudo, or grant them once withsudo sipnab --setup-caps. -
not_permittedfrom every/v1/relay/route. You started the server without--api-allow-relay-query, or it reads a capture file. -
relay_stats is not available on this server. It transmits, so it needs three things(the same forquery_relayandrelay_compare), as a JSON-RPC error with"reason":"not_enabled". The run lacks one of--mcp-allow-relay-query,--rtpengine-controland a live source. A run that reads a capture file never has a live source. -
--mcp-allow-relay-query: these opt-ins act on the sipnab process or the relayand exit 2. The run opened the TUI as well as MCP. The TUI's relay view and the MCP tools share one permission to transmit, so sipnab refuses the MCP opt-in beside the TUI. Add-N. -
The comparison reads
not_configuredandthis capture measured none for it. The capture did not see the call's media. Capture where the media passes, usually on the relay's machine, and check that your capture filter admits rtpengine'sport-mintoport-maxrange. -
--relay-holdings: suspect: relay (rtpengine at 127.0.0.1:22223): a relay reply could not be trusted: rtpengine reply is not bencode: bencode: 'E' does not begin any bencode value; the reply was discarded and not readand exit 1. The address is rtpproxy's control socket, or something else that is not rtpengine. These requests are for rtpengine.
- Let sipnab name rtpengine's media: tie relay media to its call.
- Attribute media on an rtpengine relay: how sipnab decides which call a relay stream belongs to, and how far it trusts the relay.
- Add rtpengine to your voice stack: install the relay these requests ask.
-
Ask each call's rtpengine engine: with several engines
behind one proxy, ask the engine each call's
offerreached or its SDP names.