# 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. _(since v3.1.0)_ The audit log, slow-query log and cluster 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 Edition Purpose
SURREAL_METRICS_ENABLED true _(Community)_ Mount the /metrics endpoint. When false the route returns 404.
SURREAL_TELEMETRY_PROVIDER unset _(Community)_ Set to otlp to enable the OTLP push pipeline (metrics, logs and traces). Any other value leaves OTLP off.
SURREAL_TELEMETRY_DISABLE_METRICS false _(Community)_ Skip the OTLP metrics reader specifically, leaving logs and traces unaffected.
SURREAL_TELEMETRY_DISABLE_TRACING false _(Community)_ Skip the OTLP trace exporter specifically, leaving metrics and logs unaffected.
SURREAL_SLOW_QUERY_METRIC_THRESHOLD_MS 1000 _(Community)_ 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 _(Community)_ 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 _(Community)_ OTLP gRPC endpoint. Standard OpenTelemetry variable.
OTEL_METRIC_EXPORT_INTERVAL 60000 (ms) _(Community)_ OTLP push cadence. Standard OpenTelemetry variable.
## Audit log knobs _(Enterprise)_ Controls the [Enterprise audit log pipeline](/docs/manage/observability/audit-logging.md). 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](/docs/manage/observability/slow-query-logging.md). 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.
## Cluster networking, consensus and storage _(Enterprise)_ > [!NOTE] > The `SURREAL_DS_*` variables below apply to multi-node clusters, which use distributed storage with replication and consensus - on [SurrealDB Cloud Scale](https://surrealdb.com/pricing/scale) or in self-hosted Enterprise installations. A short list of the cluster networking, consensus and storage-memory knobs that operators routinely tune in response to a metric signal. 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.
SURREAL_DS_ROCKSDB_BLOCK_CACHE_SIZE_(since v3.1.1)_ max(memory/2 - 1 GiB, 16 MiB) Steady-state RSS pressure. The largest single consumer in a node using the RocksDB durable backend. Full-text index reads are served through it entirely; vector index reads hit it on load and on cache misses. The default is derived from detected memory, so set it explicitly on memory-constrained pods.
SURREAL_DS_ROCKSDB_MAX_WRITE_BUFFER_NUMBER_(since v3.1.1)_ Derived from detected memory (2-32) RSS pressure during sustained write phases. The memtable ceiling is this value multiplied by SURREAL_DS_ROCKSDB_WRITE_BUFFER_SIZE and by the four heavy column families, so it is the knob to cap first when headroom is tight.
> [!NOTE] > `SURREAL_DS_ROCKSDB_*` applies only when a node's store path selects the RocksDB durable backend. Memtable and block-cache memory are accounted together, and an undersized write budget presents as write latency rather than errors - but the operative limits are the per-column-family memtable count and the L0 compaction trigger, not the combined ceiling. `SURREAL_DS_ROCKSDB_WRITE_BUFFER_SIZE` sets the per-column-family memtable size; the complete reference is in the Enterprise Kubernetes deployment guide. ## Recommended configurations **Local development** The minimum needed to scrape metrics from a local server during development: ```bash 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): ```bash 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): ```bash SURREAL_METRICS_ENABLED=false surreal start ... # /metrics → 404 ``` **Self-hosted production** 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: ```bash # 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](/docs/manage/observability/metrics.md#alert-hints) and the alerting rules on `surrealdb_audit_dropped`, `surrealdb_audit_append_errors` and `surrealdb_audit_queue_depth` listed in the [Compliance checklist](#compliance-checklist) below. **Multi-tenant / cloud-facing** 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. ```bash # 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](/docs/manage/observability/metrics.md#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: ```bash 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](/docs/manage/observability/audit-logging.md) 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. |