Skip to main content
pgw’s normal log says what happened to a call. The SIP message log shows the messages themselves, which you need when the question is what exactly the app or the PBX sent. Use it to debug one call or one registration.
While the SIP message log is on, pgw’s log holds phone numbers and media addresses, and grows with each message. Turn it off when you finish.

Turn on the SIP message log

1

Turn on the log and debug logging

Set sip_log: true and log_level: debug in the configuration file, or set PGW_SIP_LOG=true and PGW_LOG_LEVEL=debug. At any other log level, pgw logs no SIP messages and warns at startup.
2

Restart pgw

3

Read the messages of one call

Replace CALL_ID with the call’s Call-ID.
The command prints the messages with that Call-ID and skips the other log lines.
To turn the log off, set sip_log: false and restart pgw.

How a message looks

pgw writes each message as a header line, then the message as it went over the network, with its secrets masked. The following REGISTER carries an app’s credentials.
The header line has the following fields, in order. Messages that pgw can’t parse don’t appear in the SIP message log.

What pgw masks

pgw replaces the following values with [redacted]:
  • pn-* parameters
  • The values of the Authorization, Proxy-Authorization, Authentication-Info, Proxy-Authentication-Info, Cookie, and Set-Cookie headers, and of any other header whose name marks it as a secret
  • Passwords in SIP URIs
  • The values of the SDP lines a=crypto, a=ice-pwd, and k=
pgw replaces every message body other than SDP with [body redacted].

Send the SIP message log to a log collector

A log collector that reads one JSON object per line can’t read the text blocks. Set log_format: json and sip_log_format: json, or PGW_LOG_FORMAT=json and PGW_SIP_LOG_FORMAT=json, and restart pgw. pgw then writes each message as one log line with the message sip message. The message text is in the sip field, and the header line’s fields are in dir, transport, remote, and call_id. The masking is the same. To read the messages of one call, replace CALL_ID with its Call-ID.
If writing the log falls behind, pgw leaves messages out instead of slowing SIP, and counts them in pgw_sip_log_dropped_total.

Next steps

Troubleshooting

Match what the messages show to a known failure and its fix.

SIP responses

Look up why pgw answered a request with a given status.