> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/reference/logs-and-body-storage · Doc index: https://docs.gatellm.io/en/llms.txt


# Logs and body storage

The Logs page shows the complete record of every API request: client request, upstream forwarding, response, and error details. It supports real-time streaming push, persistent storage, and body viewing. For the UI-oriented log list/detail/SSE live stream, see [Logs viewer](/en/console/logs-viewer.md).

## Log body (Request/Response Body)

Each request's request body and response body are captured in the logs and viewable on the detail page:

| Variable | Default | Description |
|------|--------|------|
| `LOG_MAX_BODY_SIZE_MB` | `25` | Maximum capture size per body (MB); truncated beyond this |
| `LOG_BODY_TO_TERMINAL` | `false` | Whether to write the body to terminal output |
| `LOG_PERSIST_REQUEST_LOGS` | `false` | Whether to persist to the database |
| `LOG_RETENTION_DAYS` | `7` | Log retention days (0 = disable auto-cleanup) |
| `OMS_RETENTION_DAYS` | `30` | Responses stateful-conversation retention days (0 = disable auto-cleanup) |

**Security warning**: log bodies may contain sensitive data (PII, keys in prompts, generated content). Enable only for debugging, and turn off when done.

### Sensitive-info redaction

The request body is auto-redacted before being written to disk (28 credential categories), including:
- The value of the `Authorization` header
- API key fields
- Other known credential patterns

## SSE log-body disk spill

Streaming response bodies don't stay in memory; they spill to disk segment files:

| Variable | Default | Description |
|------|--------|------|
| `LOG_STREAM_BODY_MAX_DISK_MB` | `1024` | Streaming body disk cap (MB) |
| `LOG_STREAM_BODY_BATCH_SIZE_KB` | `64` | writer batch size |
| `LOG_STREAM_BODY_LINGER_MS` | `5` | batch max wait time (milliseconds) |
| `LOG_STREAM_BODY_CHANNEL_CAPACITY_CHUNKS` | `2048` | mpsc channel capacity (chunks) |

Once the disk cap is exceeded, new chunks are dropped and marked `body_incomplete`.

## Environment variables

For the full list of log-related environment variables (`LOG_LEVEL`, `LOG_FORMAT`, disk totals `LOG_QUEUE_*`, etc.) see [Environment variable reference](/en/reference/configuration.md#log-retention). Environment-variable changes require a container restart to take effect.

## Request-ID correlation

Each request has a unique `z-request-id` header (format `<iso8601>-<uuid4>`), which:

- Is injected into the request header before the request enters processing
- Is mirrored to the response header returned to the client
- Is forwarded to the upstream as an extra header
- Is embedded in all structured log entries

Enter the full request ID in the Logs page search box to locate a specific request. See [Export billing Excel and troubleshoot logs](/en/howto/billing-export-and-logs.md).

## Log-body detail fields

After expanding on the log detail page:

| Label | Content |
|------|------|
| Overview | Request ID, model, upstream URL, status code, latency, token usage, access key name/group |
| Client request | Request headers (sensitive values redacted) + request body |
| Upstream request | Transformed request headers + request body (the actual content sent to the upstream) |
| Upstream response | Response status code + response headers + response body |
| Error | Error detail for 4xx/5xx (truncated to 512 bytes) |

### Notification

The top of the log detail page shows special notifications for that request, e.g.:
- **script_use_model_swap**: this request's upstream model was switched by a script via `context.useModel`, not the client's originally-requested model

## FAQ

**Q: Is the log list real-time?**
With the Live switch on, it's real-time push (SSE). With Live off, it's poll refresh.

**Q: Why is the body in the log truncated?**
`LOG_MAX_BODY_SIZE_MB` limits each body's capture size. Large bodies (long conversations, large embedding requests) get truncated. Raise it to capture more, at the cost of more memory and disk.

**Q: Where do I see a streaming request's response body?**
The streaming response's body is recorded by a background task after the stream ends. If the stream broke abnormally (client disconnected), the body may be incomplete (marked `body_incomplete`).

**Q: Too many logs, disk almost full?**
Lower `LOG_RETENTION_DAYS` (e.g. 3 days) to speed cleanup; lower `LOG_STREAM_BODY_MAX_DISK_MB` to reduce streaming-body disk usage.

**Q: Who can see logs?**
The Logs page is visible to admin and monitor. `normal_user` can't log into the console, so it can't see logs (it only has API-key usage rights).

**Q: What's the difference between logs and audit logs?**
Logs (this chapter) record each API call's request/response; audit logs ([Audit and security configuration](/en/reference/audit-and-security-config.md)) record console config changes (create/delete/modify). The two complement each other.

**Next**: [Logs viewer](/en/console/logs-viewer.md) for the UI view; [Environment variable reference](/en/reference/configuration.md) for all environment variables; [Audit and security configuration](/en/reference/audit-and-security-config.md) for audit logs.