> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Log SIP messages

> Turn on the SIP message log to see every SIP message that pgw sends and receives, with its secrets masked.

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.

> [!WARNING]
>
> 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**

```bash theme={null}
sudo systemctl restart pgw
```

**3. Read the messages of one call**

Replace `CALL_ID` with the call's Call-ID.

```bash theme={null}
journalctl -u pgw -o cat | awk -v id=CALL_ID '/^--- sip /{p = ($NF == "call-id=" id)} /^([{]|time=)/{p = 0} p'
```

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.

```text theme={null}
--- sip in tls 127.0.0.1:60083 2026-11-15T23:58:59.278176Z call-id=062490ab-b3ba-464b-b6c7-d9292a785f01
REGISTER sip:localhost SIP/2.0
Via: SIP/2.0/TLS 127.0.0.1:60083;branch=z9hG4bK9837d2c107;rport
Max-Forwards: 70
From: <sip:1005@localhost>;tag=abc2
To: <sip:1005@localhost>
Call-ID: 062490ab-b3ba-464b-b6c7-d9292a785f01
CSeq: 2 REGISTER
Contact: <sip:1005@127.0.0.1:60083;transport=tls>
Expires: 600
User-Agent: Linphone/5.2.5 (iPhone)
Authorization: [redacted]
Content-Length: 0
```

The header line has the following fields, in order.

| Field | Description |
| - | - |
| `in` or `out` | `in` for a message that pgw received, `out` for one that it sent. A retransmission appears each time pgw sends it. |
| Transport | `udp`, `tcp`, `tls`, or `wss`. |
| Remote address | The address of the peer. |
| Time | The time in UTC, in RFC 3339 format. |
| `call-id=` | The message's Call-ID. |

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.

```bash theme={null}
journalctl -u pgw -o cat | jq -rR 'fromjson? | select(.msg == "sip message" and .call_id == "CALL_ID") | .sip'
```

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

> [card] [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md)
>
> Match what the messages show to a known failure and its fix.

> [card] [SIP responses](https://docs.pgw.sipmicro.services/reference/sip-responses.md)
>
> Look up why pgw answered a request with a given status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.