Configuration reference | SurrealDB Docs

Every observability, audit log and slow-query log environment variable, plus recommended configurations for local, production and multi-tenant deployments.

Every environment variable that controls the observability surface. Variables marked

Enterprise

exist only when the Enterprise binary is running; everything else is available in all editions.

Available since: v3.1.0

The audit log, slow-query log and SurrealDS configuration surfaces are new in SurrealDB 3.1.

How to read this page

Default is the value used when the variable is unset. Cells marked — are required when the surrounding feature is enabled.
Edition identifies which builds register the variable. Variables marked
Enterprise
are no-ops on a Community binary.
All variables can be set via environment, a .env file loaded by the deployment, or the orchestrator's secret store.

Core knobs

These knobs control the two access paths (Prometheus pull and OTLP push) and the global telemetry switches. They are available in every edition.

Variable	Default	Purpose
`SURREAL_METRICS_ENABLED`	`true`	Mount the `/metrics` endpoint. When `false` the route returns `404`.
`SURREAL_TELEMETRY_PROVIDER`	unset	Set to `otlp` to enable the OTLP push pipeline (metrics, logs and traces). Any other value leaves OTLP off.
`SURREAL_TELEMETRY_DISABLE_METRICS`	`false`	Skip the OTLP metrics reader specifically, leaving logs and traces unaffected.
`SURREAL_TELEMETRY_DISABLE_TRACING`	`false`	Skip the OTLP trace exporter specifically, leaving metrics and logs unaffected.
`SURREAL_SLOW_QUERY_METRIC_THRESHOLD_MS`	`1000`	Threshold above which a completed statement is counted on `surrealdb_slow_query_total`. Set to `0` to disable the counter.
`SURREAL_PROCESS_METRICS_REFRESH_INTERVAL`	`5`	Cadence in seconds for refreshing the cached process snapshot that backs `surrealdb_process_memory_bytes` and `surrealdb_process_cpu_percent`. Floored at 1.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317`	OTLP gRPC endpoint. Standard OpenTelemetry variable.
`OTEL_METRIC_EXPORT_INTERVAL`	`60000` (ms)	OTLP push cadence. Standard OpenTelemetry variable.

Audit log knobs

Enterprise

Controls the Enterprise audit log pipeline. Setting SURREAL_AUDIT_SINK=none (the default) leaves the pipeline disabled entirely; no observer is registered and the cost is zero.

Variable	Default	Purpose
`SURREAL_AUDIT_SINK`	`none`	One of `none`, `file`. `syslog` and `table` are reserved but rejected at startup.
`SURREAL_AUDIT_FILE_PATH`	—	Required when `SURREAL_AUDIT_SINK=file`. Parent directory must exist; startup fails loudly if it doesn't. File is opened with mode `0600` on Unix.
`SURREAL_AUDIT_FILE_ROTATE_BYTES`	`268435456` (256 MiB)	Size threshold that triggers rotation.
`SURREAL_AUDIT_FILE_ROTATE_KEEP`	`8`	Number of rotated files to retain.
`SURREAL_AUDIT_FSYNC_EVERY`	`0`	Mid-stream fsync cadence. `0` never fsyncs mid-stream; `1` fsyncs every record; `N>1` fsyncs every Nth record. Rotation and graceful shutdown always fsync regardless.
`SURREAL_AUDIT_HASH_CHAIN`	`false`	Adds `prev_hash` / `hash` SHA-256 fields to every record for tamper-evidence. Requires `SURREAL_AUDIT_FSYNC_EVERY=1` — startup fails otherwise.
`SURREAL_AUDIT_INCLUDE_SQL`	`false`	Include the full SQL text on `statement` records. Off by default; the identity and action context is still emitted.
`SURREAL_AUDIT_QUEUE_CAPACITY`	`4096`	Records the bounded observer-to-worker queue can hold.
`SURREAL_AUDIT_OVERFLOW`	`block`	`drop` (single non-blocking `try_send`) or `block` (bounded busy-yield retry). See overflow semantics. Neither offers a lossless guarantee.
`SURREAL_AUDIT_REDACT_TABLES`	—	Comma-separated identifier tokens replaced with `***` in captured SQL.
`SURREAL_AUDIT_REDACT_REGEX`	—	Semicolon-separated regex patterns applied to captured SQL. Each pattern is compiled at startup; an invalid pattern fails startup.
`SURREAL_AUDIT_REDACT_LITERALS`	`false`	Replace every quoted literal with `***`. Off by default.
`SURREAL_AUDIT_OTEL_EXPORT`	`false`	Also emit each audit record as an OTel `LogRecord`. Off by default so compliance-sensitive records stay on the local file sink.

Slow-query log knobs

Enterprise

Controls the Enterprise slow-query log pipeline. Setting SURREAL_SLOW_QUERY_SINK=none (the default) leaves the pipeline disabled entirely.

Variable	Default	Purpose
`SURREAL_SLOW_QUERY_SINK`	`none`	Same selector set as `SURREAL_AUDIT_SINK`.
`SURREAL_SLOW_QUERY_FILE_PATH`	—	Required when the sink is `file`.
`SURREAL_SLOW_QUERY_FILE_ROTATE_BYTES`	`268435456` (256 MiB)	Rotation threshold.
`SURREAL_SLOW_QUERY_FILE_ROTATE_KEEP`	`8`	Retained rotation generations.
`SURREAL_SLOW_QUERY_FSYNC_EVERY`	`0`	Same semantics as the audit equivalent.
`SURREAL_SLOW_QUERY_HASH_CHAIN`	`false`	Tamper-evident chain. Requires `SURREAL_SLOW_QUERY_FSYNC_EVERY=1`.
`SURREAL_SLOW_QUERY_THRESHOLD_MS`	—	Duration threshold above which a statement is captured. Required when the sink is enabled.
`SURREAL_SLOW_QUERY_INCLUDE_SQL`	`true`	Capture SQL text in slow-query records. Setting to `false` lets throughput-sensitive deployments skip per-statement `to_sql()` rendering at the cost of losing SQL context on captures.
`SURREAL_SLOW_QUERY_QUEUE_CAPACITY`	`4096`	Records the queue can hold.
`SURREAL_SLOW_QUERY_OVERFLOW`	`drop`	Default differs from audit — slow-query records are triage data, so dropping is preferred over busy-yielding the executor.
`SURREAL_SLOW_QUERY_REDACT_TABLES`	—	Same syntax as the audit equivalent.
`SURREAL_SLOW_QUERY_REDACT_REGEX`	—	Same syntax as the audit equivalent.
`SURREAL_SLOW_QUERY_REDACT_LITERALS`	`false`	Same semantics as the audit equivalent.
`SURREAL_SLOW_QUERY_OTEL_EXPORT`	`false`	Emit each slow-query record as an OTel `LogRecord` at `WARN` severity.

SurrealDS networking

Enterprise

A short list of the SurrealDS networking and consensus knobs that operators routinely tune in response to a metric signal. The complete SURREAL_DS_* reference is part of the SurrealDS Kubernetes deployment guide.

Variable	Default	Tune in response to
`SURREAL_DS_NTW_INBOUND_BYTES`	`3 * MAX_MSG_BYTES` (768 MiB) per `MessageClass`	`QUIC inbound bytes ... saturation warning` log.
`SURREAL_DS_NTW_INFLIGHT_PROCESSING_CAP`	`max(384, num_cpus*32)`	`QUIC inbound handlers ... saturation warning` log.
`SURREAL_DS_MAX_READ_OPERATIONS`	`192`	Steady-state RSS pressure or scan-heavy workloads.
`SURREAL_DS_MAX_WRITE_OPERATIONS`	`96`	`Write operations limit saturation warning` log.
`SURREAL_DS_CONSENSUS_FAST_QUORUM_TIMEOUT_MS`	implementation default	Rising `surrealdb_ds_consensus_fast_quorum_timeouts_total`.
`SURREAL_DS_RETRY_BASE_MS` / `SURREAL_DS_RETRY_MAX_MS`	`500` / `5000`	Rising `surrealdb_ds_finalize_prepare_retries_total`.

Recommended configurations

The minimum needed to scrape metrics from a local server during development:

surreal start --user root --pass root memory
# Anonymous: only the public allowlist
curl http://127.0.0.1:8000/metrics
# Authenticated: the full surface
curl -u root:root http://127.0.0.1:8000/metrics

To push to a local OpenTelemetry collector (for example a Grafana / Tempo / Loki / Prometheus docker-compose stack):

SURREAL_TELEMETRY_PROVIDER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
surreal start --user root --pass root memory

To disable the endpoint entirely (useful when running with a third-party agent that scrapes via OTLP only):

SURREAL_METRICS_ENABLED=false surreal start ...
# /metrics → 404

For a self-hosted production deployment that ships metrics over OTLP and writes audit and slow-query records to a local sink for SIEM ingestion:

# Telemetry
SURREAL_METRICS_ENABLED=true
SURREAL_TELEMETRY_PROVIDER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.internal:4317
OTEL_METRIC_EXPORT_INTERVAL=30000

# Audit log (Enterprise) — durable, hash-chained
SURREAL_AUDIT_SINK=file
SURREAL_AUDIT_FILE_PATH=/var/log/surrealdb/audit.log
SURREAL_AUDIT_FSYNC_EVERY=1
SURREAL_AUDIT_HASH_CHAIN=true
SURREAL_AUDIT_INCLUDE_SQL=true
SURREAL_AUDIT_REDACT_LITERALS=true
SURREAL_AUDIT_OVERFLOW=block

# Slow-query log (Enterprise) — best-effort triage data
SURREAL_SLOW_QUERY_SINK=file
SURREAL_SLOW_QUERY_FILE_PATH=/var/log/surrealdb/slow-query.log
SURREAL_SLOW_QUERY_THRESHOLD_MS=250

Pair this with the alert hints in the metrics reference and the alerting rules on surrealdb_audit_dropped, surrealdb_audit_append_errors and surrealdb_audit_queue_depth listed in the Compliance checklist below.

For pods that serve customer traffic directly, the default posture is deny scraping at the pod boundary and serve metrics from an internal sidecar instead. Customer-visible metrics should be filtered at a proxy.

# Customer-facing pod
SURREAL_METRICS_ENABLED=false

# Internal sidecar pod (same workload, internal-only interface)
SURREAL_METRICS_ENABLED=true
SURREAL_TELEMETRY_PROVIDER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.internal:4317

Filter on namespace and database at the proxy and strip the user label before exposing to a customer. See the Recommended cloud whitelist for the suggested customer-visible subset.

Compliance checklist

Enterprise

For deployments that require tamper-evident, durable audit trails the recommended configuration is:

SURREAL_AUDIT_SINK=file
SURREAL_AUDIT_FILE_PATH=/var/log/surrealdb/audit.log
SURREAL_AUDIT_FSYNC_EVERY=1            # required for hash chain
SURREAL_AUDIT_HASH_CHAIN=true
SURREAL_AUDIT_INCLUDE_SQL=true         # if a regulator requires statement text
SURREAL_AUDIT_REDACT_LITERALS=true     # scrub embedded PII from quoted values
SURREAL_AUDIT_OVERFLOW=block           # already the default; explicit for clarity

Plus alerts on:

surrealdb_audit_dropped — any non-zero rate is a lost record.
surrealdb_audit_append_errors — any non-zero rate is a lost record.
surrealdb_audit_queue_depth sustained above ~50% of SURREAL_AUDIT_QUEUE_CAPACITY — the sink is falling behind.

For the full pipeline details (record shape, rotation, hash chain, redaction) see the Audit logging reference.

Troubleshooting

Symptom	Likely cause	Investigation
`/metrics` returns `404`	`SURREAL_METRICS_ENABLED=false`	Re-enable, or scrape over OTLP instead.
`/metrics` returns only six metrics	Anonymous scrape against the public allowlist	Configure basic-auth with root credentials.
No `surrealdb_ds_*` metrics on a single-node setup	Enterprise composer did not start a metrics reader	Confirm the Enterprise binary is running and at least one of `SURREAL_METRICS_ENABLED=true` / `SURREAL_TELEMETRY_PROVIDER=otlp` is set.
`surrealdb_audit_records` missing entirely	Audit sink set to `none` (the default)	Set `SURREAL_AUDIT_SINK=file` and `SURREAL_AUDIT_FILE_PATH`.
Sustained `surrealdb_audit_dropped` rate	Worker can't keep up	Raise `SURREAL_AUDIT_QUEUE_CAPACITY`; check sink disk I/O; consider switching from `block` to `drop` if drops are acceptable.
`QUIC inbound bytes ... saturation warning` log	Per-class inbound budget saturated	Raise `SURREAL_DS_NTW_INBOUND_BYTES`.
OTLP collector not receiving metrics	`SURREAL_TELEMETRY_PROVIDER` unset, or `SURREAL_TELEMETRY_DISABLE_METRICS=true`	Confirm both, plus that `OTEL_EXPORTER_OTLP_ENDPOINT` is reachable.
Hash chain rejected at startup	`SURREAL_AUDIT_HASH_CHAIN=true` without `SURREAL_AUDIT_FSYNC_EVERY=1`	Set both, or disable hash chaining.