Debugging Asterisk: SIP Traces and Logging

When calls fail or registrations drop, SIP traces are the first tool to reach for. Asterisk can dump full SIP message traces to the CLI, showing every REGISTER, INVITE, and response in real time.

Enable SIP Debug

CLI Commands

; Enable PJSIP debug logging at runtime
*CLI> pjsip set logger on

; Increase verbosity for more context
*CLI> core set verbose 5

; Watch logs in real time
*CLI> core set debug 5

Reading a Registration Trace

A successful PJSIP registration involves a challenge/response exchange:

Step 1: Phone sends REGISTER
<--- Received SIP request from UDP:192.168.1.100:5060 --->
REGISTER sip:192.168.1.10 SIP/2.0
From: <sip:1001@192.168.1.10>;tag=abc123
Contact: <sip:1001@192.168.1.100:5060>
Expires: 60

Step 2: Asterisk responds 401 Unauthorized with a challenge
<--- Transmitting SIP response --->
SIP/2.0 401 Unauthorized
WWW-Authenticate: Digest realm="asterisk",nonce="...",algorithm=md5,qop="auth"

Step 3: Phone re-sends REGISTER with credentials
<--- Received SIP request --->
REGISTER sip:192.168.1.10 SIP/2.0
Authorization: Digest username="1001",realm="asterisk",response="...",qop=auth

Step 4: Asterisk responds 200 OK
<--- Transmitting SIP response --->
SIP/2.0 200 OK
Contact: <sip:1001@192.168.1.100>;expires=59
  == Endpoint 1001 is now Reachable

Reading a Call (INVITE) Trace

Step 1: INVITE sent from caller
<--- Received SIP request --->
INVITE sip:1002@192.168.1.10 SIP/2.0
From: <sip:1001@192.168.1.10>;tag=xyz789
Content-Type: application/sdp
(SDP body with codec offers)

Step 2: 401 challenge (same as registration)
Step 3: Re-INVITE with Authorization header

Step 4: 100 Trying
<--- Transmitting SIP response --->
SIP/2.0 100 Trying

Step 5: 200 OK with SDP answer
<--- Transmitting SIP response --->
SIP/2.0 200 OK
Content-Type: application/sdp
(SDP body with selected codec)

Step 6: ACK from caller -- call is now established
<--- Received SIP request --->
ACK sip:192.168.1.10:5060 SIP/2.0

Step 7: BYE to end the call
<--- Transmitting SIP request --->
BYE sip:1001@192.168.1.100 SIP/2.0
Reason: Q.850;cause=16

Common Problems and What to Look For

How it works

1. Digest authentication: SIP uses HTTP Digest auth. The server sends a nonce in the 401 response. The client hashes its credentials with the nonce and sends the result. This avoids sending passwords in cleartext (though it's not as strong as TLS).
2. SDP negotiation: The INVITE carries an SDP offer listing codecs the caller supports. The 200 OK carries the SDP answer with the selected codec. Mismatched codecs = no audio.
3. Q.850 cause codes: The Reason header in BYE messages shows the ISDN cause code. cause=16 is normal clearing. cause=21 is call rejected. cause=34 is no circuit available.
4. NAT and Contact rewriting: If the phone is behind NAT, its Contact header contains a private IP that Asterisk can't route responses to. rewrite_contact = yes on the endpoint fixes this by using the source IP/port from the packet instead.

Tips

• Capture SIP traces to a file: asterisk -rx "pjsip set logger on" && tail -f /var/log/asterisk/full.
• For packet-level analysis, use tcpdump -i any -w /tmp/sip.pcap port 5060 and open in Wireshark. Wireshark's "VoIP Calls" view reconstructs entire call flows.
• To debug a single endpoint: pjsip set logger on then pjsip qualify 1001 to trigger a SIP exchange.
• Turn off debug logging when done: pjsip set logger off and core set verbose 0. Debug logging is verbose and can impact performance.
• The CLI command pjsip show endpoints shows all endpoints and their registration status at a glance.