SurrealDB writes server logs to stderr by default. You can set flags on surreal db start or the matching environment variables 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 and in Environment variables.
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:
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:
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-levelorSURREAL_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), Enterprise observability, and in the Metrics reference. In-tree detail lives in doc/OBSERVABILITY.md on GitHub.