Pomerium provides verbose logging to help users audit, manage, and troubleshoot their configurations. The amount of logs output can be overwhelming, so on this page we'll cover how to sort for and understand logs from the authorization service. These logs often provide the most helpful information when first configuring Pomerium.

## Find Logs

The command to display Pomerium's logs will depend on your installation method:

**System Daemon:**

```bash
sudo journalctl -u pomerium.service
```

The `-f` flag can also be provided to show new logs as they are generated.

**Docker:**

```bash
docker logs pomerium
```

The container name will depend on your configuration. The `-f` flag can also be provided to show new logs as they are generated.

**Kubernetes:**

```bash
kubectl logs -f deploy/pomerium-authorize
```

The deployment name will depend on your configuration. The `-f` flag can also be provided to show new logs as they are generated.

### Filter Logs

To filter log output to just the Authorize service logs, we can pipe (`|`) the output through `grep`:

**System Daemon:**

```bash
sudo journalctl -u pomerium.service | grep '"service":"authorize"'
```

**Docker:**

```bash
docker logs pomerium | grep '"service":"authorize"'
```

**Kubernetes:**

```bash
kubectl logs -f deploy/pomerium-authorize | grep '"service":"authorize"'
```

### Formatted Logs

To better parse the logs, you can install [jq](https://stedolan.github.io/jq/) and use another pipe to pass the content through it:

```bash
kubectl logs -f deploy/pomerium-authorize | grep '"service":"authorize"' | jq
{
  "level": "info",
  "service": "authorize",
  "request-id": "46747f58-...",
  "check-request-id": "7700fe70-a166-406c-a326-48f433029f98",
  "method": "GET",
  "path": "/",
  "host": "grafana.example.com",
  "query": "",
  "session-id": "46b36e11...",
  "allow": false,
  "allow-why-false": ["claim-unauthorized", "non-pomerium-route"],
  "deny": false,
  "deny-why-false": [],
  "user": "941b0719-...",
  "email": "alex@example.com",
  "databroker_server_version": ...,
  "databroker_record_version": ...,
  "time": "2022-05-16T18:18:55Z",
  "message": "authorize check"
}
```

## Authorization Log Keys

The keys described below usually contain the relevant information when debugging an authorization issue:

| Key | Description |
| --- | --- |
| <a className="entRef-anchor" id="allow">#</a><a href="#allow">`allow`</a> | If true, at least one allow rule passed. As long as `deny` is false, the request will be allowed. |
| <a className="entRef-anchor" id="allow-why-false">#</a><a href="#allow-why-false">`allow-why-false` & `allow-why-true`</a> | The short reason strings why access was allowed (or not allowed). <br /> <br /> In the example output above, `claim-unauthorized` means that there was a policy rule on a claim that didn't pass.<br /><br />`non-pomerium-route` means that it was not a request to `/.pomerium/`, which is allowed for any authenticated user. |
| <a className="entRef-anchor" id="deny">#</a><a href="#deny">`deny`</a> | If true it means that at least one deny rule passed, and the request will be denied. |
| <a className="entRef-anchor" id="deny-why-false">#</a><a href="#deny-why-false">`deny-why-false` & `deny-why-true`</a> | The short reason strings why access was denied (or not denied). |
| <a className="entRef-anchor" id="databroker">#</a><a href="#databroker">`databroker_server_version` & `databroker_record_version`</a> | These values are used for auditing. With these version numbers and a complete history of all changes in the databroker, you can determine what data was used for policy evaluation. |

## Understanding Authorization Logs

The most confusing keys for new users to understand are likely `allow-why-false` and `deny-why-false`. To better understand them, we should first discuss how [Pomerium Policy Language](https://www.pomerium.com/docs/internals/ppl.md) (**PPL**) works.

PPL allows a request to a route if the claim matches at least one **allow** policy rule, and matches zero **deny** policy rules. With that in mind, `allow-why-false` and `allow-why-true` will describe a situation where the request either does or not not meet the requirements of an **allow** block a policy applied to that route. Conversely, `deny-why-true` and `deny-why-false` will describe why a request did or did not match a **deny** block for a policy assigned to the route.

## Common Uses for Audit Logs

### Zero Usage Tracking

To determine which users are considered active for the purposes of billing, user details can be seen in the authorization logs under the `user` and `email` keys.

This information is also available in the postgres database used by the Pomerium Databroker:

```sql
SELECT id AS session_id,
       data#>>'{userId}' AS user_id,
       data#>>'{claims,name,0}' AS user_display_name,
       data#>>'{claims,email,0}' AS user_email
FROM pomerium.records
WHERE "type" = 'type.googleapis.com/session.Session'
```