SIP Trace Analyser

1What it is

SIP Trace Analyser is the QVCCS voice-diagnostics tool for Genesys Cloud CX. It joins two Genesys data sources into one investigation workflow:

• Analytics conversation details — finds voice conversations in a date range and classifies their disconnect reasons (error, system, transportFailure, …), participant by participant, segment by segment.
• Telephony SIP traces — the actual SIP signalling Genesys kept for those calls: one record per SIP message, carrying its Call-ID, method or response, From/To users and domains, source and destination addresses, timing, the request-URI domain (ruriDomain) and the raw message text. The app can turn those records into a downloadable text trace file, and can ask Genesys to prepare a PCAP of the call.

Typical investigations:

• Find every call that failed with a SIP/transport error in a time window.
• Hunt one response code — e.g. every 503 Service Unavailable yesterday — by having the app parse the raw SIP messages returned with each call’s trace records.
• Attribute failures to a specific carrier trunk: the app identifies the trunk from the INVITE’s ruriDomain, from trunk SIP-host configuration and from SIP access-control IP ranges — because the Analytics API itself never records which trunk carried a call.
• Export a text trace file of the SIP messages, or a PCAP for a packet-level deep-dive in Wireshark.

What it deliberately does not do: there is no ladder-diagram view of the SIP exchange. Each message can be read on its own with View trace, the whole call is in the text trace file, and Wireshark’s flow graph on the PCAP does the ladder job properly.

2Quick start

1. Sign in — pick the region (the canonical 14-region list), paste an OAuth client-credentials Client ID/Secret with the permissions from §5, and press Sign in. Your Client ID and region are remembered in the browser for next time; the secret never is.
2. Set the window — the query panel defaults to the last 24 hours. Keep SIP errors only ticked and press Run Analysis.
3. Read the results — a stats strip (total matches, this page, SIP errors, error rate) over a 25-per-page table. Error rows are tinted red; the Trunk column fills in asynchronously as each row’s INVITE trace is inspected.
4. Open a call — View SIP shows the error segments, the participants and segment breakdown, and every SIP message record with View trace / Download trace file / Download PCAP actions.
5. First sign-in only — a one-time trunk setup panel may ask you to confirm which trunk each observed SIP domain belongs to. Confirmations persist in your browser (§4).

3UI walkthrough

The app is three screens — the sign-in page, the dashboard, and a per-call detail view — plus a conversation-detail modal. The dashboard top bar shows the org name and region badge, the Guide button, and Sign out.

Query panel

• Start / End date-time — the analytics interval, local-time pickers sent as ISO-8601. Defaults to the last 24 hours.
• Conversation ID filter — optional exact match on one conversation.
• Trunk filter — a dropdown of trunk base names: Genesys often auto-names trunk instances <Label> Trunk <uuid>, so the UUID suffix is stripped and instances grouped (the option shows the type and an instance count; inactive trunks are greyed). Filtering is applied client-side after per-row trunk identification — see §4 for why.
• SIP errors only (default on) — restricts the analytics query to conversations with a disconnectType of error, system or transportFailure. How those are then judged per row is purpose-aware — §4.
• Filter by SIP response code — enables the deep scan (§4): checkbox presets 400 401 403 404 407 408 480 481 486 487 488 500 502 503 504 (each labelled, e.g. 486 Busy Here), plus custom three-digit codes via + Add and a Clear all.

Results table

• Stats strip — Total matches (the analytics totalHits across all pages), This page (rows currently shown, after any code filter / trunk hiding), SIP errors and Error rate. The error count and rate are computed over the visible page, not the whole result set.
• Columns — truncated conversation ID, direction, start, duration, worst-disconnect badge, ANI, Trunk, an optional SIP Codes column (only when the code scan ran), and View SIP. Rows containing a genuine SIP error are tinted red.
• Trunk column — starts as “…” and resolves in the background: a confirmed trunk name badge, or the raw SIP domain in italics when the domain is seen but not yet mapped, or “—” when no INVITE trace exists. 25 rows per page with Prev/Next paging.
• Advisory panels — a blue one-time trunk setup panel when unmapped SIP identifiers are seen; a shared-edge note when the selected trunk shares edge infrastructure with others; a cancellable progress bar while a code scan runs.

Detail view (one conversation)

• Stat row — direction, start, duration, SIP error count, and a full-width Trunk tile that refines itself as evidence arrives (analytics identification → scan result → INVITE ruriDomain ground truth, shown raw if unmapped).
• ANI / DNIS — caller and dialled numbers from the customer participant’s sessions.
• Error segments — a red panel listing each failing segment: participant purpose, disconnect type, segment type, time, and any errorCode.
• SIP response codes in segment data — codes Genesys already recorded in the analytics record (sipResponseCodes per segment), shown as class-coloured badges with the reporting participant purposes on hover — no trace download needed.
• Participants & segment breakdown — every participant with its purpose, and each session segment with its type, disconnect badge and timing.
• SIP Traces — one card per SIP message, in time order: Call-ID, a method/response badge (e.g. INVITE or 503 Service Unavailable), From/To (user@domain, each with a live reverse-DNS resolution of the host part), date, source → destination address, request-URI and User-Agent when present, any extra metadata fields the API returned, and three actions:
  • View trace — expands the raw SIP message text of that record in place.
  • Download trace file — a .txt file of every SIP message with the same Call-ID in the conversation’s time window, in time order, each preceded by a header line (time, source → destination, method/response, Call-ID). Generated by the app from the trace records.
  • Download PCAP — asks Genesys to prepare a PCAP for that Call-ID, waits while it is built (“Preparing PCAP…”), then shows a PCAP ready — download link. The link is a short-lived signed URL, so use it promptly; press the button again for a fresh one.
  A collapsible raw-JSON view shows the record exactly as Genesys returned it.

Conversation Detail Record modal

Clicking the conversation ID in the detail header opens the full analytics detail record as a styled, collapsible tree — ISO timestamps rendered as local times, UUIDs dimmed, URLs clickable — with a Copy JSON button. Records are cached per conversation for the session, and Esc closes the modal.

4SIP concepts as implemented

Call legs & error classification

An analytics conversation is a tree: participants (with a purpose such as customer, external, outbound, agent, ivr, acd) → sessions (the media legs) → segments (routing states, each with a disconnectType). “Is this a SIP error?” is judged per segment, purpose-aware:

• error and transportFailure are always counted as SIP errors.
• system counts only on external-party legs (purpose customer, external or outbound). On internal legs — an IVR→agent transfer, an ACD segment ending — system just means “the platform ended this routing segment” and is normal.
• Segments whose errorCode matches webrtc|ice|dtls are excluded: those are agent-side media failures, not SIP-trunk failures — the SIP call itself completed.

Badge colouring follows the same taxonomy: red for error/system/transportFailure, amber for timeout/uncallable/noAnswer, green for client/endpoint (normal hang-ups), blue for peer. A row’s worst badge prefers a genuine SIP error, then a warning type, then whatever disconnect appeared first.

Trace records = SIP messages

Each record (HomerRecord) returned by the Genesys SIP-trace search is one SIP message. Messages belonging to the same dialog share a Call-ID (field callid, lower case); a single conversation commonly has several Call-IDs — the carrier leg, internal legs, transfers. The viewer maps the documented fields to labelled rows: callid, method + replyReason, fromUser@fromDomain, toUser@toDomain, date, sourceIp:sourcePort → destinationIp:destinationPort, ruri and userAgent, and lists any other fields dynamically. The raw message text is msg, used by View trace, the trace file and the code scan. Host parts of SIP URIs (sip:user@host) are reverse-DNS-resolved live by the app — cosmetic enrichment that many carrier IPs won’t have (no PTR record).

Download trace file goes through the app, which runs the same metadata search for the Call-ID and writes the messages out as text, so the download is covered by your signed-in session. Download PCAP uses Genesys’ two-step capture download (§5): the app requests the file, polls until Genesys reports it ready, and hands the browser the signed URL.

Response-code scan (deep filter)

Enabling Filter by SIP response code adds a second pass after the analytics query: the current page’s conversations are scanned in small batches, with a cancellable progress bar. Per conversation:

1. Fetch the conversation’s trace metadata for its own time window.
2. Parse every SIP/2.0 NNN Reason status line in each record’s msg text, de-duplicated by code (a record without message text falls back to its numeric method and replyReason). No separate file download is needed.

Rows are then filtered to conversations whose parsed codes intersect your selection, and a SIP Codes column appears (4xx amber, 5xx red, reason on hover; “none found” otherwise). Cancelling keeps partial results.

Trunk identification — three signals, never a guess

The Genesys Analytics API records provider="Edge" and a shared edgeId for edge-routed calls — it does not say which trunk carried a call, and one edge hosts many trunks. The app therefore refuses to guess: a trunk name is shown only when positively identified, in this priority order:

1. Analytics signals (immediate, per row): the session’s provider string matching a known trunk name; an edgeId whose edge hosts exactly one trunk; or explicit trunkName/trunk.name session fields. External-party legs are scanned — plus agent legs on outbound calls, where the trunk association can sit on the dialling leg.
2. INVITE ruriDomain (the ground truth, resolved in the background): for each visible row the app fetches trace metadata (a few rows at a time) and takes the INVITE’s request-URI domain — the trunk’s BYOC FQDN or the carrier IP. FQDNs match a learned domain→trunk map (exact, then prefix); IPs match the trunks’ SIP access-control lists (exact IP, then CIDR range). ACK records are ignored — their ruriDomain is the media server.
3. Trunk configuration harvest (feeds the map): on sign-in the app loads all trunks, the external trunk bases’ ACL IP ranges and BYOC termination FQDNs (<termId>.byoc.<region>), and each trunk’s outbound-proxy / SIP-server hostnames — auto-matching discovered domains to trunk names by shared name tokens.

Discovery & the setup panel: after sign-in the app samples the last 24 hours of traces for INVITE ruriDomain values. Anything it cannot auto-match appears in a one-time trunk setup panel — pick the owning trunk and press Confirm. Confirmed mappings are remembered in your browser — another browser or profile must confirm them again.

Trunk filtering is a client-side consequence: selecting a trunk does not change the analytics query. Once rows are identified, rows whose resolved domain differs from the selected trunk’s confirmed domain are hidden (unidentified rows stay visible, and the page count notes how many other-trunk calls were hidden). A note also warns when the selected trunk shares edges with named others — the reason edge-level filtering alone would mis-attribute calls.

5Data sources & permissions

Everything comes from the Genesys Cloud public API, live, at query time — there is no file upload, no capture agent and no local trace store. The browser talks only to this app; the app holds the OAuth session on the server and makes every Genesys call on your behalf (§6).

OAuth client: a Client Credentials grant whose role has Analytics conversation details (analytics:conversationDetail:view), Telephony SIP traces (telephony:pcap:view — metadata search and collecting a prepared PCAP), trunks and external trunk bases (commonly granted via telephony:plugin:all or the equivalent telephony read permissions), and Organization read for the name badge. Download PCAP additionally needs telephony:pcap:add, because it asks Genesys to prepare the file; leave it out and only that button fails (HTTP 403). No configuration-changing permission is needed or used.

6Storage, privacy & security

• No database. Nothing about your org is stored. Trace files are generated on request and never stored; PCAP files are downloaded by your browser straight from Genesys’ signed URL and never pass through the app.
• Credentials stay on the server. Sign-in exchanges your client credentials with Genesys; credentials and token are held on the server for your session only and never sent to the browser.
• Sessions — end when you sign out or after a period of inactivity. If the service is busy, signing in again with the same Client ID + region reuses your own earlier session.
• Browser-side state — your browser remembers only the last Client ID + region (never the secret) and your confirmed domain→trunk mappings.
• Request protection — every data request requires your signed-in session, and the session is protected against cross-site use.
• Trace content is sensitive — traces contain phone numbers and SIP URIs: treat downloads like call metadata exports.

7Technology

• Web application — an authenticated service between your browser and the Genesys Cloud API: the browser talks only to the app, and the app holds the OAuth session and calls Genesys on your behalf. It also performs the reverse-DNS enrichment.
• Browser interface — a single-page dashboard plus a separate sign-in page; visitors who are not signed in are sent to the sign-in page.
• State — no database and nothing written to storage (§6). Trunk-domain mappings are remembered in your browser (§4).

8Troubleshooting

Sign-in fails with an OAuth error (“authentication failure”, “invalid_client”, …).

The message on the sign-in page is Genesys’ own error_description. Check the region matches the org, the ID/secret are exact, the client is a Client Credentials grant and active, and its role carries the permissions from §5. The upstream HTTP status (usually 401) is passed through.

“The service is busy – try again shortly.”

The service is handling as many sign-ins as it can. If your own earlier tab is the culprit, sign in again with the same Client ID + region — that reuses your session. Otherwise try again shortly.

Bounced to the login page mid-investigation.

Your session ended after a period of inactivity, or the service was restarted. Sign in again — nothing else is lost.

Query failed: HTTP 400 / “interval” errors.

The analytics API rejected the interval. Ensure Start < End and the range is sane. Very old ranges return nothing anyway — SIP traces are assumed retained for 21 days.

“No SIP traces found” on a call that clearly happened.

Seen when the call never traversed an external trunk (station-to-station / WebRTC only), the conversation is outside trace retention, or Genesys didn’t record signalling for it (e.g. high edge concurrency). The analytics record still shows the disconnect data.

The code scan is slow.

By design: each conversation needs its own metadata query, and only a few run at once to protect the org’s API rate limits. Narrow the range, filter by conversation ID, or run without the code filter and drill into candidates.

The code scan matches calls without my codes.

You left every checkbox unticked — that matches any parsed status line (see §4), which is nearly every call with a trace. Tick the specific codes you are hunting.

Trunk column shows a raw domain in italics, or “—”.

Italic domain: the INVITE’s ruriDomain is known but unmapped — confirm it in the trunk setup panel (mappings are remembered per browser; a different profile must confirm again). “—”: no INVITE trace was found for that row. Cloud trunks without edge IDs can only be identified via the domain mapping.

Trunk filter shows rows from other trunks, or too few rows.

Filtering hides only rows positively identified as a different trunk; unidentified rows stay visible by design (never guess). The shared-edge note lists trunks sharing infrastructure — open a row and check the INVITE ruriDomain to confirm attribution.

Download PCAP shows “PCAP failed” or “still being prepared”.

“PCAP failed: …” shows Genesys’ own message — HTTP 403 usually means the role lacks telephony:pcap:add (to request the file) or telephony:pcap:view (to collect it). “Still being prepared” means Genesys had not finished within about 90 s; press the button again shortly. If the PCAP ready link stops working, the signed URL has expired — press Download PCAP again for a fresh one.

Download trace file shows an error instead of a file.

No SIP messages matched means the metadata search for that Call-ID in the conversation’s window returned nothing (e.g. it has aged out of retention since the page loaded). Any other status is Genesys’ own answer, passed through.

Reverse-DNS shows the bare IP or an error code.

Many carrier IPs have no reverse-DNS (PTR) record. Cosmetic only — trunk identification does not depend on it.

Does anything get written to my org? Where do credentials live?

No configuration changes. The only request that creates anything is Download PCAP, which asks Genesys to prepare a capture file for download. Credentials and tokens are held on the server only for the session’s lifetime (sign-out, inactivity or a restart ends it); they are never written to storage and never sent to the browser.