> ## 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.

# Read pgw logs

> Read and filter pgw's logs, follow one device or call, and send the logs to a log collector.

pgw writes one line for each event. Every line about a device or a call carries the same identifying fields, so one search returns every line about that device or call.

pgw writes to standard output, which `journalctl` shows under systemd:

```bash theme={null}
journalctl -u pgw
```

Set `log_level` to `debug`, `info`, `warn`, or `error`. The default is `info`.

By default, each line is a list of `key=value` fields. pgw quotes a value that holds a space, a quote, or a line break, so an event never takes two lines.

```text theme={null}
time=2026-11-16T02:58:10.772+03:00 level=INFO msg=registered call_id=d0fe8e65-f5e8-4969-b7b7-b5225c1e38cd source=127.0.0.1:59992 aor=sip:1003@localhost upstream=managed-pbx binding=7sim12gDyqfOttYB12GutA platform="" device="Linphone/5.2.5 (iPhone)" changes=new granted=3600 mode=managed
```

pgw never logs push tokens, `pn-*` parameters, or credentials.

## Filter by level

`journalctl` shows errors in red and warnings in yellow. To list only warnings and errors, filter by priority.

```bash theme={null}
journalctl -u pgw -p warning
```

Under systemd, pgw starts each line with a syslog priority, which `journalctl` uses to color and filter. This needs the systemd default, `SyslogLevelPrefix=yes`, in the pgw service. With `SyslogLevelPrefix=no`, each line in the journal starts with `<3>`, `<4>`, `<6>`, or `<7>` instead.

In a terminal on Linux or macOS, pgw colors errors red, warnings yellow, and debug lines dim. To change how lines show their level, set `log_color`, which [Settings](https://docs.pgw.sipmicro.services/reference/settings.md) describes.

## Fields that name a device

Lines about a device or a call carry the following fields. A line leaves out a field that pgw doesn't know, such as `device` when the app sends no User-Agent.

| Field | Meaning |
| - | - |
| `call_id` | The Call-ID of the SIP request. The PBX's call record shows the same Call-ID. |
| `source` | The address and port that the SIP request came from. |
| `binding` | pgw's key for one registered device. `pgw binding list` shows it as `key`. |
| `aor` | The SIP account that the device registers, such as `sip:1001@pbx.example.com`. |
| `platform` | `ios`, `android`, or `web`. Empty for a device that registers without push parameters. |
| `device` | The User-Agent of the device's last REGISTER, which names the app and often the phone model. |
| `upstream` | The name of the upstream that the device registers through. |
| `upstream_id` | The upstream's ID, for the `pgw upstream` commands. |
| `app` | The app's name, or its bundle ID when the app has no name. To set the name, run `pgw app set-name`. |

To follow one device, search for its AOR.

```bash theme={null}
journalctl -u pgw | grep 'aor=sip:1001@pbx.example.com'
```

## Registration lines

| Message | Level | When |
| - | - | - |
| `registered` | `INFO` | A device registers for the first time, or its REGISTER changes the registration. `changes` says what changed, and `granted` is the registration time in seconds that pgw gave the app. In managed mode, the line also has `mode=managed`. |
| `registered` | `DEBUG` | A device refreshes its registration and nothing changes. A device that keeps its connection does this every few minutes, so these lines appear only with `log_level: debug`. They have `changes=""`. |
| `unregistered` | `INFO` | The app removes its registration with `Expires: 0`, or removes all of the account's registrations with `Contact: *`, which writes one line for each device. |
| `binding expired` | `INFO` | In passthrough mode, the app didn't register again before its registration expired, for example because a refresh push didn't reach it. |

`changes` holds one or more of the following values, separated by commas, such as `changes=contact,remote_addr`.

| Value | What changed |
| - | - |
| `new` | pgw had no registration for this device. |
| `contact` | The Contact URI of the REGISTER. |
| `remote_addr` | The device's IP address or port. The device registered over a new connection, for example after a push woke it or after it moved from Wi-Fi to mobile data. |
| `transport` | The connection type, TLS or WSS. |
| `user_agent` | The User-Agent, for example because the app was updated. |
| `push` | The push token or another push parameter. pgw logs only that it changed, never the value. |

## Call lines

pgw writes one `call ended` line for each device that a call rings, when that device's part of the call ends. A call to a user with three devices writes three lines with the same `call_id`.

```text theme={null}
time=2026-11-16T02:58:16.301+03:00 level=INFO msg="call ended" call_id=5ac8dc803eb34ba4a5f5bf0563bc5cf9@127.0.0.1 source=127.0.0.1:23998 binding=7sim12gDyqfOttYB12GutA aor=sip:1003@localhost platform="" device="Linphone/5.2.5 (iPhone)" upstream=managed-pbx outcome=delivered status=486 ring_ms=3016 pushed=false
```

The line also has the following fields.

| Field | Meaning |
| - | - |
| `outcome` | How the call ended for this device, with the `result` values of `pgw_invite_outcomes_total`. `delivered` means the app sent a final response, which can be a decline. |
| `status` | The final response for this device. It is the app's, such as `200` for an answer or `486` or `603` for a decline, or pgw's own, such as `480` when the app didn't wake in time or `487` when the call was cancelled. |
| `ring_ms` | Milliseconds from the INVITE's arrival to the end of the device's part of the call. |
| `pushed` | `true` when pgw sent the device a call push for this call. |
| `wake_ms` | Milliseconds from the call push to the app's first response. Present only when pgw pushed and the app responded. |

An INVITE that pgw refuses with `403` or `404` before it rings a device writes no `call ended` line. pgw logs `invite refused` with the reason instead, at most once a minute for each source address.

```text theme={null}
time=2026-11-16T02:55:35.876+03:00 level=WARN msg="invite refused" call_id=b1070e36362b49e899b0b79818ee27f5@127.0.0.1 source=127.0.0.1:23998 reason="no binding for the request"
```

## Push lines

pgw writes one `push` line for each push that it sends or skips. The line has the fields that name the device, plus `call_id`, `type`, `status`, `push_type`, and `err`. `type` is `call`, `missed`, `refresh`, or `test`, and `status` is the push service's HTTP status. A failed push writes a `WARN` line. A skipped push, a push that pgw held back, and a call push whose call ended while the push waited in the queue each write an `INFO` line.

## Messages to watch for

| Message | Level | Meaning |
| - | - | - |
| `upstream unreachable` | `WARN` | The PBX missed 3 OPTIONS in a row. pgw logs `upstream reachable` when it answers again. |
| `upstream refused the stored credentials` | `WARN` | The PBX refused a managed registration with the stored password. Logged at most once every 10 minutes for each account. |
| `upstream did not keep pgw's Path` | `WARN` | The PBX's answer to a registration dropped pgw's Path. Logged at most once every 10 minutes for each upstream. |
| `kamailio domains not loaded; pgw keeps the last ones` | `WARN` | A read of Kamailio's domain table failed. Logged at most once every 10 minutes for each upstream. |
| `missed-call push skipped` | `INFO` | pgw sent no missed-call push. The `reason` is `answered elsewhere` when another device took the call. Otherwise it names the call push limit. |
| `call ended before the app responded` | `INFO` | A woken app never answered the INVITE, and the caller hung up or 32 seconds passed. |
| `cancel failed` | `WARN` | pgw couldn't cancel a call toward the app or the PBX. `by` is `caller` when the caller hung up, or `pgw` when pgw ended the call. |
| `refresh lead cut to half the granted lifetime` | `WARN` | The PBX granted a registration too short for the usual refresh push timing, so pgw pushes halfway through it. |
| `register source banned` | `WARN` | pgw banned a source address for too many refused credentials. |
| `register ban table full` | `WARN` | pgw tracks 65,536 source addresses and can't count more toward a ban. |
| `register credentials refused` | `DEBUG` | pgw counted refused credentials toward a ban. The line has the `reason` of `pgw_register_auth_failures_total`. |
| `register challenged` | `DEBUG` | pgw answered a REGISTER with `401` that counted nothing, such as a REGISTER without credentials. |
| `bearer token refused` | `DEBUG` | A Bearer token failed its checks. The line names the check, never the token. |
| `handler panic`, `router goroutine panic`, `push worker panic`, `refresh push panic`, `refresh scan panic`, `lease panic`, `stray response panic` | `ERROR` | pgw recovered from an internal error. Each one adds 1 to `pgw_panics_total`. |

The following line reports an unreachable PBX.

```text theme={null}
time=2026-11-16T02:53:25.923+03:00 level=WARN msg="upstream unreachable" upstream=office-pbx upstream_id=15w6y1ZKQtnFlUhCefAqJA host=127.0.0.1 port=23999 missed=3 err="upstream: options: context deadline exceeded"
```

## Send logs to a log collector

**1. Turn on JSON logs**

Set `log_format: json` in the configuration file, or set `PGW_LOG_FORMAT=json`.

**2. Restart pgw**

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

Each line is now one JSON object with the same fields.

```json theme={null}
{"time":"2026-11-16T02:58:37.429074+03:00","level":"INFO","msg":"registered","call_id":"09aab7dc-a404-4949-9078-392f26fbaa4e","source":"127.0.0.1:60060","aor":"sip:1004@localhost","upstream":"managed-pbx","binding":"WUkZKZ8jRQBrlKJJgcgSKA","platform":"","device":"Linphone/5.2.5 (iPhone)","changes":"new","granted":3600,"mode":"managed"}
```

If you also turn on the SIP message log, set `sip_log_format: json`, so the collector gets SIP messages as JSON lines.

## Next steps

> [card] [Log SIP messages](https://docs.pgw.sipmicro.services/sip-message-log.md)
>
> See every SIP message of one call or registration.

> [card] [Read the push log](https://docs.pgw.sipmicro.services/push-log.md)
>
> Check what the push service answered for each push.


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