Configuration reference

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

Note

SurrealDS is SurrealDB's distributed storage engine for highly available, horizontally scalable clusters. The SURREAL_DS_* variables below apply when that runtime is deployed — on SurrealDB Cloud Scale or in self-hosted Enterprise installations.

A short list of the SurrealDS networking and consensus knobs that operators routinely tune in response to a metric signal. For a product overview, see SurrealDS. The complete SURREAL_DS_* reference is part of the Enterprise 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 secret
# Anonymous: only the public allowlist
curl http://127.0.0.1:8000/metrics
# Authenticated: the full surface
curl -u root:secret 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 secret

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

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.