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

# Query logs

> See which names clients ask for, who answered them, and how long the logs and traffic counts are kept.

DNZ logs every DNS query it answers: the name and type, the status, who answered it (a local zone,
an upstream, the cache, a blocklist), the client's address and how long it took. Use the log to
check that a record is being used, to find a client that keeps asking for a missing name, or to see
why a site is blocked.

## Open the query log

Open **DNS → Query Logs**. Viewing it needs the `logs.read` permission.

| Column | Shows |
| - | - |
| **Time** | When the query came in, in the server's time zone (see [Settings](/admin/settings)) |
| **Name** | The queried name |
| **Type** | The record type asked for |
| **Status** | The answer's result code, such as NOERROR, NXDOMAIN or SERVFAIL |
| **Answered by** | `local`, `forwarded`, `conditional` (a [forwarding rule](/dns/forwarding#conditional-forwarding)), `cache`, `blocked`, `rpz` (a [response policy zone](/dns/rpz)), `safe_search` ([safe search](/dns/filtering#safe-search)) or `error` |
| **Client** | The client's IP address |
| **Latency** | Time to answer, in milliseconds |

* Type in **Filter by name or client** to search.
* Turn on **Live** to refresh the list every 5 seconds, or click **Refresh**.

### This division and All queries

By default the page shows queries for names in **this division's zones**. Forwarded and cached
queries belong to no division, so they don't appear there.

**Superadmins** also get a **Scope** switch. **All queries** shows every query the server
answered, including names forwarded to upstreams, and adds a source filter:

* **All sources**
* **Local zones**
* **Forwarded & cache**
* **Blocked**: every blocked query (blocklists and RPZ), with the client's IP (see [Filtering](/dns/filtering))
* **Errors**

## From the command line

**Recent queries**

```bash theme={null}
dnz logs -n 100
dnz logs --query example.com --source forwarded
dnz logs --client 192.168.1.20
dnz logs --division it
```

| Option | Meaning |
| - | - |
| `-n`, `--limit` | How many queries, newest first (default 50) |
| `-q`, `--query` | The name or client contains this text |
| `--client` | Only this client address |
| `--source` | `local`, `forwarded` or `error` |
| `-d`, `--division` | Only this division's zones. Superadmins see every query without it. |

**Traffic summary**

`dnz stats` sums up a division's traffic like the dashboard does: the number of queries, the
NXDOMAIN ratio, SERVFAILs, the average answer time, counts per time bucket, then the top five
names and clients with each client's NXDOMAIN share.

```bash theme={null}
dnz stats --division it
dnz stats --range 30d
dnz stats --json
```

| `--range` | Buckets |
| - | - |
| `24h` (default) | One per hour |
| `7d` | One per 6 hours |
| `30d`, `90d` | One per day |

See [CLI: monitoring](/cli/monitoring) for every option. Scripts can also read a division's log
over the API with a token that has `logs.read`: `GET /api/divisions/{id}/logs?q=&limit=` (see
[API overview](/api/overview)).

## How long data is kept

DNZ keeps two kinds of data:

| Data | Kept for | Used by |
| - | - | - |
| The query log (one row per query) | `DNZ_LOG_RETENTION_DAYS`, **7 days** by default | The Query Logs page, `dnz logs`, top names and clients |
| Hourly query counts | **400 days** | Dashboard charts (back to 90 days) and the counts in `dnz stats` |

Queries are written to the log in batches, and rows older than the retention period are deleted.
Change the period in the config file or the environment:

```toml /etc/dnz/dnz.toml theme={null}
[dns]
log_retention_days = 30
```

```ini /etc/dnz/dnz.env theme={null}
DNZ_LOG_RETENTION_DAYS=30
```

> [!NOTE]
>
> The top names and clients in `dnz stats` come from the query log, so they cover at most
> `log_retention_days`, even when you ask for `--range 90d`. The counts come from the hourly totals
> and cover the whole range.

> **[Monitoring](/dashboard/monitoring)**
>
> Usage charts, upstream health and alerts on the Overview.

> **[Notifications](/integrations/notifications)**
>
> NXDOMAIN spikes, rate limiting and a daily summary.


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