SIP Trace Analyser: from “why did this call fail?” to the trunk and the response code

Monday morning, and a business manager forwards a complaint: customers calling the sales line on Saturday got a fast busy, then nothing. The carrier’s ticket response says no faults were found. The IT Systems, Telecoms & SIP Engineer now needs to find every affected call, prove what the signalling said, and show which trunk carried it – ideally before the next escalation call, and certainly before the evidence ages out.

SIP Trace Analyser is the QVCCS tool for exactly that investigation. It joins two Genesys data sources into one workflow. Analytics conversation details find voice conversations in a date range and classify their disconnects, participant by participant and segment by segment. Telephony SIP traces provide the signalling records Genesys kept for those calls – one record per SIP Call-ID, with From and To URIs, direction, timing, the INVITE’s request-URI domain, a downloadable trace file of the raw messages and a pre-signed PCAP link.

Speed matters as much as accuracy. Genesys keeps signalling evidence for a limited window, carriers ask for Call-IDs and timestamps before they will investigate, and a failure that affects one call in fifty is invisible in queue statistics. So the brief we set ourselves was a single investigation workflow: query a window, see which calls failed and why, prove it from the signalling, name the trunk, and hand over the raw evidence in a form the carrier’s engineers can open.

Genesys Cloud has built-in SIP diagnostics, and we use them constantly. The Details tab of an interaction includes a SIP Diagnostics section from which you can download that interaction’s SIP traces file and its PCAP. A PCAP is a packet capture that can be opened in freely available network protocol analysers to see the signalling history of a specific call between Genesys Cloud and the carrier or PBX at the other end.

The documentation is clear about the boundaries. PCAPs are generated for calls that traverse an external trunk – BYOC Cloud carrier, PBX trunks or premises Edge external trunks – and are available for 21 days. Station-to-station calls do not generate them. For BYOC Premises, the Conversation Headers setting must be enabled on the trunk or the capture cannot be queried by conversation ID, and in a hybrid BYOC Cloud and Premises environment a PCAP shows only part of the path. Generation is best-effort under load. These are diagnostics per interaction, and they need the Telephony > Plugin > All and Telephony > Pcap permissions.

The insight that shaped the tool is that “did this call fail?” is not one question. An analytics conversation is a tree: participants, each with a purpose such as customer, external, outbound, agent, ivr or acd; sessions under them, which are the media legs; and segments under those, each with a disconnectType. SIP Trace Analyser queries /api/v2/analytics/conversations/details/query for voice conversations whose segments ended with error, system or transportFailure, then judges each segment with the participant’s purpose in mind.

Error and transportFailure always count as SIP errors. System counts only on external-party legs – customer, external or outbound – because on an internal leg, such as an IVR-to-agent transfer, it simply means the platform ended a routing segment, which is normal. Segments whose errorCode points to WebRTC, ICE or DTLS are excluded: those are agent-side media failures, and the SIP call itself completed. Without these rules, an error-rate figure would be dominated by noise.

Badges follow the same taxonomy: red for error, system and transportFailure, amber for timeout, uncallable and noAnswer, green for normal client or endpoint hang-ups and blue for peer. Each row shows its worst badge, preferring a real SIP error. Opening a call shows the failing segments with purpose, disconnect type, time and errorCode, plus any sipResponseCodes Genesys already recorded on the segment – no trace download required.

Sometimes the question is narrower: show me every 503 Service Unavailable from yesterday, or every 480 Temporarily Unavailable on the sales line. Ticking response codes – presets from 400 to 504 with their reason phrases, plus any custom three-digit code – adds a deep scan. For each conversation on the current page, the server fetches its SIP trace metadata from /api/v2/telephony/siptraces for its own time window, reads the raw SIP text that each trace record carries, parses each “SIP/2.0 NNN Reason” status line and de-duplicates by code.

Rows are then filtered to calls whose codes intersect your selection, and a SIP Codes column appears with 4xx in amber and 5xx in red. The scan runs five conversations at a time to protect the organisation’s API rate limits, shows a cancellable progress bar and keeps partial results if you stop it. We documented one subtlety openly in the guide: with no codes ticked, a call matches if its traces contain any status line at all, including 1xx and 2xx – so tick the codes you are actually hunting.

Attributing a failure to a carrier trunk is where most of the engineering went. For Edge-routed calls the analytics record gives you the Edge, and one Edge hosts many trunks, so the app refuses to guess. A trunk name appears only when it is positively identified, in priority order. First come analytics signals: a session provider string matching a known trunk name, an edgeId whose Edge hosts exactly one trunk, or an explicit trunk name field on the session.

The ground truth is the INVITE’s request-URI domain, resolved in the background for each visible row. That domain is the trunk’s BYOC FQDN or the carrier’s IP address. FQDNs are matched against a learned domain-to-trunk map; IP addresses are matched against the trunks’ SIP access-control lists, exact address first and then CIDR range. ACK records are ignored, because their request-URI points at the media server rather than the carrier.

To build that map, the app harvests trunk configuration at sign-in: all trunks, the external trunk bases’ access-control IP ranges and BYOC termination FQDNs, and each trunk’s outbound-proxy and SIP-server hostnames, auto-matching domains to trunks by shared name tokens. It then samples the last 24 hours of traces for INVITE domains, and anything it cannot match appears once in a trunk setup panel for an engineer to confirm. Filtering by trunk hides only rows positively identified as another trunk – unidentified rows stay visible.

The per-call detail view renders each SIP trace record as a card: Call-ID, direction, From and To URIs with a live reverse-DNS lookup of the host part, start and end times, any trunk field and any extra metadata the API returned. Well-known field aliases map to labelled rows and unrecognised fields are listed dynamically, so new API fields appear without a code change. A collapsible raw-JSON view and the full analytics detail record, rendered as a navigable tree with a Copy JSON button, sit one click away.

What the tool deliberately does not do is draw a SIP message ladder. It renders trace metadata, not the message exchange, and hands the raw evidence to the right tool: the downloadable trace file and the PCAP, which open in a network protocol analyser whose flow graph does that job properly. Because Genesys keeps traces for a limited window, the app assumes 21 days – older conversations still show their analytics detail, but signalling-level work should focus on recent history.

SIP Trace Analyser signs in with an OAuth client-credentials grant whose role reads analytics conversation details and telephony data – SIP trace metadata, PCAP download, trunks and external trunk bases – plus the organisation name. Nothing in the organisation is ever changed. Every Genesys call is a read except the PCAP request, which the API models as creating a download and so needs the Telephony > Pcap > Add permission; the analytics query is a POST only because of the API’s shape. There is no database and no local trace store: trace records are parsed in memory, the trace file is generated on request from them, PCAPs are fetched from a pre-signed link, and nothing is written to disk. Tokens are refreshed proactively and on any 401, so long investigations do not die mid-hunt.

The trunk-attribution rules came straight from our telephony practice, where a single Edge carrying several carriers is an everyday design. A Senior Business Consultant captured the investigation as user stories with acceptance criteria, an IT Systems, Telecoms & SIP Engineer and a Solution Architect designed the classification and attribution rules, and a Systems Integration Tester proved them against WebRTC-only calls, expired traces, unmapped domains and shared Edges – backed, as always, by the whole practice.