---
title: "Logging"
description: "Log levels, text and JSON formats, and file, socket and OTel output."
canonical_url: "https://surrealdb.com/docs/operate/observability/logging"
section: "Observability"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Logging

Log levels, text and JSON formats, and file, socket and OTel output.

SurrealDB writes server logs to stderr by default. You can set flags on [`surreal db start`](/docs/reference/cli/db/commands/start.md) or the matching [environment variables](/docs/reference/cli/db/environment-variables.md) and ship lines to your collector or log store.

## Core options

| Concern | CLI flag (examples) | Environment variable (examples) |
| --- | --- | --- |
| Level | `--log` | `SURREAL_LOG` |
| Format | `--log-format` (`text` or `json`) | `SURREAL_LOG_FORMAT` |
| Remote socket | `--log-socket` | `SURREAL_LOG_SOCKET` |
| File logging | `--log-file-enabled`, `--log-file-path`, `--log-file-rotation`, … | `SURREAL_LOG_FILE_ENABLED`, `SURREAL_LOG_FILE_PATH`, `SURREAL_LOG_FILE_ROTATION`, … |
| File level | `--log-file-level` | `SURREAL_LOG_FILE_LEVEL` |
| Slow queries | `--slow-log-threshold`, `--slow-log-param-allow`, `--slow-log-param-deny` | `SURREAL_SLOW_QUERY_LOG_THRESHOLD`, `SURREAL_SLOW_QUERY_LOG_PARAM_ALLOW`, `SURREAL_SLOW_QUERY_LOG_PARAM_DENY` |

Further socket and file options (`--log-socket-level`, `--log-file-name`, `--log-file-format`, and others) are documented on [`surreal db start`](/docs/reference/cli/db/commands/start.md) and in [Environment variables](/docs/reference/cli/db/environment-variables.md).

Slow-query logging records statements that exceed your threshold, as a warning that gives the time taken, the statement and the values of its bound parameters:

```text title="Example output"
Slow query detected - time: 1.204193667s - query: SELECT * FROM person WHERE name = $public AND token = $secret - params: [ $public='foo' ]
```

The statement is written with its parameter names, and the values appear only in the `params` list. A parameter value is listed only when `--slow-log-param-allow` names the parameter and `--slow-log-param-deny` does not, so without `--slow-log-param-allow` the list is always empty. The deny list wins when a name is on both lists, which keeps a parameter such as `secret` out of the log even when a broad allow list is set. The entry above comes from a server started with `--slow-log-param-allow=public,secret --slow-log-param-deny=secret`.

The threshold is checked for each statement. When the query timeout or a cancellation stops a request whose statements each finished under the threshold, but which as a whole ran for at least the threshold, the request is logged once, with the time since it started and the reason it stopped. The statement named is the one that the timeout or cancellation interrupted:

```text title="Example output"
Slow query detected - time: 1.001s - batch did not complete (timed out after 1s) - query: SLEEP 20ms - params: [  ]
```

## OpenTelemetry trace and log verbosity

OpenTelemetry trace output can be tuned separately from ordinary server logs:

* `--log-otel-level` or `SURREAL_LOG_OTEL_LEVEL` - verbosity of OTel-related tracing output.

When OTLP is enabled, **SurrealDB Enterprise** can also emit audit and slow-query records as OpenTelemetry logs when you set `SURREAL_AUDIT_OTEL_EXPORT` / `SURREAL_SLOW_QUERY_OTEL_EXPORT`. Severity mapping and dual paths (file sink versus OTLP) are summarised on [Observability (metrics and Prometheus)](/docs/operate/observability/observability.md), [Enterprise observability](/docs/operate/observability/enterprise-observability.md), and in the [Metrics reference](/docs/operate/observability/metrics.md). In-tree detail lives in [`doc/OBSERVABILITY.md`](https://github.com/surrealdb/surrealdb/blob/main/doc/OBSERVABILITY.md) on GitHub.
