Reading a SIP trace to debug a carrier issue

A SIP trace is a log of the actual SIP messages a call exchanged with your Carrier. Read it top to bottom and you can see exactly where the call broke: which message went out, what came back, and where the conversation stopped. It is the single most useful tool for a stubborn trunk problem.

Capturing the trace

You have three easy options on an Asterisk box, depending on the channel driver:

• Chan_sip: run sip set debug on at the Asterisk CLI (and sip set debug off when done). Every SIP packet to and from the carrier prints live.
• PJSIP: run pjsip set logger on for the same effect on the newer stack.
• sngrep: a terminal tool that captures SIP off the wire and draws the call flow as a ladder diagram. The easiest way to read a trace if you are new to it.

What a healthy call looks like

A normal outbound call has a predictable shape. Your box sends an INVITE. The carrier acknowledges receipt with a 100 Trying, then 180 Ringing while the far end rings, then 200 OK when it answers. Your box replies with an ACK and audio starts flowing. If you see all of those in order, the signaling is healthy and any remaining problem (like One-way audio) is in the media path, not the SIP.

sequenceDiagram
  participant V as VICIdial
  participant C as Carrier
  V->>C: INVITE
  C-->>V: 100 Trying
  C-->>V: 180 Ringing
  C-->>V: 200 OK
  V->>C: ACK
  Note over V,C: Healthy: audio flows
  V->>C: INVITE (failure variant)
  C-->>V: 100 Trying
  C-->>V: 503 Service Unavailable
  V->>C: ACK
  Note over V,C: Call rejected, read the code

Reading where it breaks

Walk the trace down and find the first message that is not part of the healthy sequence above. Where it stops tells you the fault:

• INVITE goes out, nothing comes back: the carrier never received it. Suspect a firewall, a wrong host/port, or an unregistered trunk.
• INVITE then 401/407: the carrier wants authentication. Your box should answer with a second INVITE carrying credentials. If it does not, your registration or secret is wrong.
• INVITE then 4xx/5xx/6xx with no 200 OK: the carrier rejected it. The exact code (a SIP 503 Service Unavailable, a 603, a 404) is your next clue.
• 200 OK and ACK but no audio: signaling is fine. Stop reading the SIP trace and look at the media — the SDP body inside the INVITE and 200 OK shows the IP and port each side will send RTP to.

Look inside the messages too, not just the codes. The SDP carried in the INVITE and 200 OK lists the Codec each side offers and the address it expects audio on. A codec with no overlap, or a private IP in the SDP from a NAT box, is visible right there in the trace before you ever pick up a phone.

Once you can read a trace, most carrier mysteries become obvious. For how the trunk is defined in the first place, see our carrier integration guide, and for the conf-file side of the peer definition, see the carrier account entry.

If you would rather spend your time reading traces than building the box they run on, see our plans — a working VICIdial server with CLI access is up in under 40 seconds.