Application and call-flow logging
Use this page to understand what is logged during a call’s application and media path, what each log level means, and how to correlate those logs with SIP signaling. It covers TelSys (voice PBX), TelPro (SIP edge), and RTPEngine (media).
For JSON field names, SigNoz queries, and per-service *_LOG_LEVEL variables, see Monitoring in SigNoz. For SIP ladder captures and response codes, see SIP signaling reference.
Purpose
Structured logs let operators reconstruct:
- Call lifecycle on the voice PBX (answer, AI session, hangup, transfer)
- Edge routing and call-control outcomes (trunk/number selection, outbound transfer, BYE handling, failover)
- Media quality and media-layer failures (MOS, ICE/DTLS/SRTP, DTMF)
Together with the Debug SIP ladder, these logs support end-to-end investigation of a single conversation.
Log levels
All structured logs use lowercase Pino-style labels:
| Level | Meaning |
|---|---|
error | Failed call path or hard failure (auth reject, media/control failure). |
warn | Degraded but recoverable (failover, sticky miss, non-SUCCESS transfer, poor MOS). |
info | Normal lifecycle milestones (call start/end, successful route, hangup). |
debug | Troubleshooting detail (session teardown chatter, temporary verbosity). |
trace | Rare deep diagnostics. |
fatal | Process- or edge-level unrecoverable failure. |
Control verbosity with the global LOG_LEVEL or service overrides such as TELSYS_LOG_LEVEL, TELPRO_LOG_LEVEL, RTPENGINE_LOG_LEVEL, and TELPHI_LOG_LEVEL. See Per-service log levels and the environment variable index.
SIP ladder capture is independent of general log verbosity: lowering info/warn filtering does not remove sip_message captures used by the Debug SIP ladder.
Correlation
Use the same identifiers across TelPro, TelSys, media, and application logs:
| Identifier | Use |
|---|---|
trace_id | Distributed trace across edge, voice, and app logs. |
sipCallId | SIP Call-ID (also shown as call id in TelWeb / Debug). |
| Conversation | TelWeb conversation id when investigating from a call detail page. |
Start from TelWeb Conversations → call detail → Debug (Logs / Spans / SIP ladder), then search SigNoz with the same trace_id or Call-ID.
What is logged
TelSys (voice PBX)
Call and AI-session lifecycle events (typically info):
| Area | Examples | Typical level |
|---|---|---|
| Call entry | Call start, channel created, channel answer | info |
| AI session | Session enter / exit with the voice AI app | info |
| Hangup | Hangup with cause / optional hangup reason | info |
| Transfer | Transfer initiated; transfer result | info / warn if not SUCCESS |
| Dialplan errors | Error-handling paths | error |
Operational bootstrap and config notes use operational log records (see Structured logging schema).
TelPro (SIP edge)
Routing and call-control outcomes (not the raw SIP frames — those are in the SIP ladder):
| Area | Examples | Typical level |
|---|---|---|
| Ingress / routing | Trunk identified, number/customer route, server selected | info |
| Rejects | Unknown trunk, TLS/auth failure, unverified internal source | warn / error |
| Outbound / transfer | Outbound or direct-URI transfer detected or rejected | info / warn |
| BYE / disconnect | Carrier-bound BYE routing; loop prevention when edge misroutes | info / warn / error |
| Failover | TelSys server failure, failover attempt or abort | warn / error |
| Media control (via TelPro) | RTPEngine offer / answer success or failure | info / error |
RTPEngine (media)
Data-plane media outcomes. Control-plane offer/answer commands are logged from TelPro (see SigNoz monitoring).
| Area | Examples | Typical level |
|---|---|---|
| Call quality | End-of-call stats (rtpengine_call_stats: MOS, jitter, loss) | info; warn / error when MOS is poor |
| Media errors | ICE / DTLS / SRTP failures | error |
| Resource errors | Port / socket exhaustion | error |
| Control errors | Unknown call, offer/answer rejected at the media engine | error |
| DTMF | RFC4733 media DTMF events | info |
| Session end | Media session teardown notices | debug |
Payload and detail policy
| Policy | Behavior |
|---|---|
| Metadata always | Targets, status codes, event names, and handling labels (for example bot / STT / TTS) are logged when available. |
| Bodies on failure | Request/response payloads are included when a response indicates failure. |
| Optional fuller payloads | Broader payload logging can be enabled for short support windows; expect higher volume and cost. |
| PII | Redaction before SigNoz export is controlled separately — see PII redaction. |
Security-relevant events
These appear as structured warn or error logs and are searchable in SigNoz (filter by service and event text):
- Unknown or unauthorized trunk / source
- Inbound authentication or TLS peer verification failures
- Outbound or transfer attempts from an unverified internal source
- BYE self-relay blocked (misrouted disconnect toward the platform instead of the carrier)
Where to look
| Surface | Best for |
|---|---|
| TelWeb → conversation → Debug | Per-call logs, spans, and SIP ladder for one conversation. |
| SigNoz Logs | Cross-call search by trace_id, Call-ID, level, or event. |
| SIP signaling reference | Which SIP messages were captured and what response codes mean. |
| Monitoring in SigNoz | Schema keys, log-level env vars, dashboards, and PII. |