How to capture a SIP trace with FreeSWITCH
FreeSWITCH exposes SIP via the Sofia stack, and `sofia loglevel` / `sofia global siptrace` give you message-level traces without restarting. Combine with `fs_cli` and tcpdump for a complete capture suitable for SIP Flow.
When to reach for this
- You operate a FreeSWITCH box (PBX, SBC, or class-4 switch)
- You want per-profile SIP message tracing without changing config files
- You need to correlate ESL events with raw SIP
Before you start
- FreeSWITCH 1.10+ with `mod_sofia` loaded
- Access to `fs_cli` (local socket auth or ESL password)
- Read access to `/usr/local/freeswitch/log/freeswitch.log` (or distro equivalent)
Steps
- 1
Enable Sofia SIP trace globally
From `fs_cli`, turn on the SIP wire trace. This prints every send/recv to the FreeSWITCH console and the main log file.
fs_cli -x 'sofia global siptrace on' - 2
Or scope it to one profile
On busy boxes, scope the trace to just the profile (e.g. `internal`, `external`, or your custom one) so you don't drown in unrelated traffic.
fs_cli -x 'sofia profile external siptrace on' - 3
Crank loglevel for full SDP / headers
By default Sofia loglevel is 0. Bump it for the duration of your test so headers and SDP show in `freeswitch.log`.
fs_cli -x 'sofia loglevel all 9' - 4
Reproduce and harvest the log
Place the failing call, then grab the slice of the log that matches. SIP Flow accepts the raw FreeSWITCH log as text input.
tail -n 10000 /usr/local/freeswitch/log/freeswitch.log \ > /tmp/freeswitch-sip.txt - 5
Optional — capture a real pcap in parallel
For ladder + RTP, run tcpdump on the SIP-facing interface while you reproduce the call. SIP Flow renders this directly.
sudo tcpdump -i any -n -s 0 -w /tmp/freeswitch.pcap \ 'udp port 5060 or tcp port 5060 or tcp port 5080 or tcp port 5081' - 6
Turn the trace back off
Don't leave Sofia trace on in production — it noticeably affects log volume on busy gateways.
fs_cli -x 'sofia global siptrace off' && \ fs_cli -x 'sofia loglevel all 0'
Tips from people who've done this 1,000 times
- Use `sofia status profile <name>` to confirm which port a profile binds to before you tcpdump
- `uuid_chat <uuid>` and `show channels` correlate FreeSWITCH UUIDs back to SIP Call-IDs
- For TLS profiles, FreeSWITCH must terminate TLS itself; capture decrypted traffic via `sofia siptrace`, not tcpdump
Pitfalls
- Sofia trace is per-profile when scoped — leaving `internal` on but tracing an `external` call shows nothing
- On systemd-managed installs the log path may be `/var/log/freeswitch/freeswitch.log`; check `freeswitch.xml` for the actual `log_dir`
- High `loglevel` plus high call volume can fill disk fast — set a duration limit
Got the trace? Render the ladder.
Drop your FreeSWITCH export into SIP Flow and we'll render the call flow, surface RFC issues, and (optionally) ask Gemini to explain what went wrong — all client-side by default.
Open analyzer