freeswitch-sofia-trace-parser 0.8.1

Parser for FreeSWITCH mod_sofia SIP trace dump files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# FreeSWITCH Setup

This parser reads dump files produced by libsofia-sip's `TPTAG_DUMP()` feature. Two
patches are required to enable file-based SIP trace logging with full timestamps.
Both patches are included in `patches/`.

## Patches

Apply against FreeSWITCH v1.10.x and its bundled sofia-sip:

1. **`0001-sofia-sip-add-date-to-tport-logging.patch`** (sofia-sip)
   Adds `YYYY-MM-DD` date prefix to frame timestamps. Without this patch, timestamps
   are time-only (`HH:MM:SS.usec`) and lack date context across rotated files. The
   parser supports both formats.

2. **`0002-mod_sofia-add-sip-dump-file-option.patch`** (FreeSWITCH)
   Adds the `sip-dump-file` SIP profile parameter that passes a file path to
   `TPTAG_DUMP()`, enabling persistent binary SIP trace logging to disk.

## SIP Profile Configuration

Add `sip-dump-file` to each SIP profile that should be traced. Create the target
directory before starting FreeSWITCH:

```sh
mkdir -p /var/log/freeswitch/sip_traces/esinet1-v6-tcp
```

In the SIP profile XML (e.g., `conf/sip_profiles/esinet1-v6-tcp.xml`), add after
the `sip-trace` parameter:

```xml
<param name="sip-dump-file" value="/var/log/freeswitch/sip_traces/esinet1-v6-tcp/esinet1-v6-tcp.dump"/>
```

One dump file per profile. The file grows continuously until rotated.

## Log Rotation

Dump files grow fast on busy systems. The included `patches/sip-traces.logrotate`
rotates daily with XZ compression and 10-year retention. Install it as:

```sh
cp patches/sip-traces.logrotate /etc/logrotate.d/sip-traces
```

The rotation uses `copy` + `fallocate -c` (punch-hole) instead of `copytruncate`,
which avoids the race condition where writes between the copy and truncate are lost.
The `fallocate` call deallocates the already-rotated blocks from the original file
on filesystems that support hole-punching (ext4, XFS, btrfs, bcachefs), effectively
truncating the file without losing in-flight writes.

## Reading Dump Files

```sh
# Live file
freeswitch-sofia-trace-parser /var/log/freeswitch/sip_traces/esinet1-v6-tcp/esinet1-v6-tcp.dump

# Rotated compressed files (oldest first)
xzcat esinet1-v6-tcp.dump.3.xz esinet1-v6-tcp.dump.2.xz esinet1-v6-tcp.dump.1.xz \
    | freeswitch-sofia-trace-parser -D -m INVITE

# Or pass multiple files directly (parser handles concatenation)
freeswitch-sofia-trace-parser esinet1-v6-tcp.dump.2 esinet1-v6-tcp.dump.1 esinet1-v6-tcp.dump
```