Calls dropping randomly. One-way audio that nobody can reproduce on demand. Choppy voice that only happens during peak hours. VoIP problems are infuriating because they span two separate protocols — SIP handles signaling while RTP carries the actual audio — and diagnosing them usually means sifting through thousands of log lines hoping you caught the right moment.
The classic response is to run tcpdump -i eth0 -w voip.pcap port 5060 and then stare at Wireshark. That works for one-off debugging, but it doesn’t scale and it’s completely useless when a customer calls at 3 AM complaining about dropped calls from two hours ago.
Homer SIPCapture fixes this. It gives you a centralized, searchable database of every SIP transaction — call flow ladder diagrams, correlated RTP quality statistics, the whole picture — without touching your call paths or adding measurable latency.
Approach Comparison: Three Ways to Debug VoIP
Before committing to Homer, it’s worth knowing what the alternatives actually give you.
Passive Packet Capture (tcpdump / Wireshark)
You capture raw packets on the interface and analyze them offline. Wireshark has excellent SIP and RTP dissectors, and for a quick one-time investigation this is often enough. The limitation is that it’s purely reactive — you have to be capturing when the problem happens, and correlating SIP signaling with RTP streams by hand across multiple hops gets tedious fast.
PBX Verbose Logging (Asterisk / FreeSWITCH)
Both Asterisk and FreeSWITCH can log full SIP messages. sip set debug on in Asterisk or sofia global siptrace on in FreeSWITCH dumps every SIP packet to the console or log file. The problem: these logs are unstructured text with no RTP quality data, no visual call flow, and no good way to search across 100,000 lines when you’re looking for a specific call from last Thursday.
Centralized SIP Capture with Homer (HEP Protocol)
HEP (Homer Encapsulation Protocol) is a lightweight UDP encapsulation that wraps SIP messages and ships them to a central collector in real time. Asterisk, FreeSWITCH, Kamailio, and OpenSIPS all support HEP natively. Homer receives those packets and stores them with full-text indexing. The web UI lets you search by caller, callee, call ID, SIP response code, or time range — then pull up a visual ladder diagram for any call in seconds.
Pros and Cons of Each Approach
| Approach | Pros | Cons |
|---|---|---|
| tcpdump / Wireshark | Zero setup, works on any host | Must be running at time of failure; manual RTP correlation; no history |
| PBX verbose logging | Built into every major PBX; no extra tools | Text-only; no RTP stats; hard to search; no call flow visualization |
| Homer SIPCapture | Real-time; full-text searchable; call flow diagrams; RTP MOS/jitter stats; historical data | Requires HEP agent config on each PBX; needs a dedicated server |
Once you’re handling more than a few dozen calls a day, Homer pays for itself in time. Running it across several FreeSWITCH clusters in production, the pattern holds: what used to be a two-hour log-grepping session becomes a five-minute search.
Recommended Setup
Homer’s modern stack has four components:
- heplify-server — the HEP collector (Go binary); receives SIP captures and writes to database
- Homer App — React web UI for search and visualization
- PostgreSQL — storage backend (fine up to ~50k calls/day); switch to ClickHouse for higher volume
- HEP Agent — built into Asterisk/FreeSWITCH/Kamailio, or use the standalone
heplifyagent for passive capture
For a small-to-medium VoIP environment (under 200 concurrent calls), a single VM with 4 vCPUs, 8 GB RAM, and a fast SSD running Ubuntu 22.04 is plenty. PostgreSQL handles that load without tuning, and Homer’s partition rotation prunes data older than 30 days by default — disk usage stays flat.
Implementation Guide
Step 1: Install heplify-server
# Download heplify-server
wget https://github.com/sipcapture/heplify-server/releases/latest/download/heplify-server_linux_amd64.tar.gz
tar -xzf heplify-server_linux_amd64.tar.gz
sudo mv heplify-server /usr/local/bin/
sudo chmod +x /usr/local/bin/heplify-serverStep 2: Create the PostgreSQL Database
sudo -u postgres psql <<EOF
CREATE DATABASE homer_data;
CREATE DATABASE homer_config;
CREATE USER homer WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE homer_data TO homer;
GRANT ALL PRIVILEGES ON DATABASE homer_config TO homer;
EOFStep 3: Configure heplify-server
Create /etc/heplify-server.toml:
HEPAddr = "0.0.0.0:9060"
DBDriver = "postgres"
DBAddr = "localhost:5432"
DBUser = "homer"
DBPass = "your_secure_password"
DBDataTable = "homer_data"
DBConfTable = "homer_config"
DBBulk = 200
DBWorker = 8
DBRotate = true
DBPartSip = "2h"
DBPartLog = "24h"
DBPartRaw = "2h"
DBDropDays = 30
LogLvl = "info"
LogStdout = true# Create systemd service
sudo tee /etc/systemd/system/heplify-server.service <<EOF
[Unit]
Description=HEPlify Server
After=network.target postgresql.service
[Service]
ExecStart=/usr/local/bin/heplify-server -config /etc/heplify-server.toml
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now heplify-serverStep 4: Deploy Homer App via Docker
docker run -d \
--name homer-app \
--restart unless-stopped \
-p 9080:80 \
-e "DB_HOST=your-postgres-host" \
-e "DB_USER=homer" \
-e "DB_PASS=your_secure_password" \
-e "DB_NAME=homer_config" \
sipcapture/homer-app:latestAccess the UI at http://your-server:9080. Default credentials: admin / sipcapture — change these immediately.
Step 5: Enable HEP on FreeSWITCH
Edit your SIP profile (e.g. /etc/freeswitch/sip_profiles/internal.xml):
<param name="capture-server" value="udp:YOUR_HOMER_IP:9060"/>
<param name="capture-enabled" value="true"/>Reload the profile without dropping calls:
fs_cli -x "sofia profile internal rescan"Step 6: Enable HEP on Asterisk
Create /etc/asterisk/hep.conf:
[general]
enabled = yes
capture_address = YOUR_HOMER_IP
capture_port = 9060
capture_type = HEP3
uuid_type = call-idIn sip.conf or pjsip.conf:
[general]
hep_enabled = yes
hep_capture_id = 1Then reload: asterisk -rx "module reload res_hep.so"
Step 7: Add Passive RTP Capture with heplify
The built-in HEP agent sends SIP signaling — not RTP quality statistics. To get MOS, jitter, and packet loss data, deploy heplify as a passive sniffer on your media server:
wget https://github.com/sipcapture/heplify/releases/latest/download/heplify_linux_amd64.tar.gz
tar -xzf heplify_linux_amd64.tar.gz
sudo mv heplify /usr/local/bin/
# Capture SIP on port 5060 and derive RTP stats from RTCP
sudo heplify \
-hs YOUR_HOMER_IP:9060 \
-i eth0 \
-m SIPRTCP \
-pr 5060-5061 \
--rtp_stats \
-sl 7Reading the Results
Once calls flow through Homer, open the Search screen and filter by time range, caller number, or SIP response code. Click any call to open the analysis view:
- Call flow ladder — INVITE → 100 Trying → 180 Ringing → 200 OK → ACK → BYE, with timestamps and hop-by-hop routing visible
- RTP stats tab — MOS score, jitter (ms), packet loss (%), and late packets per RTP stream
- Raw SIP messages — full headers including SDP offer/answer, essential for codec and NAT debugging
When reviewing RTP quality, use these thresholds:
Jitter: < 20ms — transparent
20–50ms — noticeable
> 50ms — causes audible artifacts
Packet Loss: < 1% — acceptable
1–5% — degraded quality
> 5% — choppy, unusable
MOS Score: > 4.0 — excellent (toll quality)
3.5–4.0 — good
< 3.5 — complaints expectedDiagnosing the Most Common Problems
One-Way Audio
The call completes (200 OK received, ACK sent) but audio flows only one direction. Open the raw SIP messages and look at the c= line in the SDP. If you see a private RFC1918 address when both endpoints are on the public internet, the PBX is behind NAT without a correctly configured external IP. Fix the ext-rtp-ip setting in FreeSWITCH or externaddr in Asterisk.
Calls Drop at Exactly 30 Seconds
Almost always caused by a failed SIP re-INVITE at the 30-second refresh timer. Homer’s call flow will show the re-INVITE and the error response — typically 403 Forbidden or 488 Not Acceptable Here. Either the remote end doesn’t support re-INVITEs, or there’s a codec mismatch in the refresh SDP.
Choppy Audio During Business Hours
High jitter that correlates with peak traffic is network congestion. Export the RTP stats from Homer, graph jitter over time, and confirm the correlation. Then review your QoS configuration — VoIP RTP traffic should be in a priority queue (DSCP EF / CS5) separate from bulk data traffic.
Registration Failures
Search Homer by from_user or auth username and look at the REGISTER sequence. A correct flow is REGISTER → 401 Unauthorized (server sends challenge) → REGISTER with credentials → 200 OK. If you see repeated 401 responses with no 200 OK, the SIP password or realm in the client config is wrong.
Homer’s overhead in production is genuinely low — less than 1% additional CPU on a FreeSWITCH instance handling 50 concurrent calls. HEP packets only carry SIP text, not RTP audio, so the network cost is minimal. On a busy cluster I’ve measured roughly 2–3 MB/hour of HEP traffic. That’s a fair price for being able to pull up any call from the past 30 days in under a minute.
