Observability

SurrealDB exposes logging, metrics, traces, and (with SurrealDB Enterprise) durable audit and slow-query record pipelines through one OpenTelemetry-oriented surface. Signals can leave the process in two complementary ways:

• Pull — scrapers call GET /metrics (Prometheus text exposition).

• Push — the server exports metrics, logs, and traces over OTLP to a collector when SURREAL_TELEMETRY_PROVIDER=otlp.

Both paths can run together or independently; each is controlled with environment variables documented on the configuration reference.

Suggested reading order

1. Logging — stderr, JSON, files, sockets, and line-based slow-query logging (no metrics stack required).

2. Observability (metrics and Prometheus) — GET /metrics, naming, migration from pre-3.1 series, the public allowlist, and behaviour common to Community and Enterprise.

3. Telemetry (OTLP) — push export, intervals, and backward-compatible instruments on the wire.

4. Enterprise observability — SurrealDS cluster metrics, audit and slow-query file pipelines, pipeline self-metrics, and OTLP log export opt-ins.

5. Metrics reference — full catalogue, labels, alert hints, and the 3.0 → 3.1 migration table.

6. Configuration — every telemetry, audit, and slow-query environment variable.

7. Audit logging and Slow-query logging — Enterprise pipeline references.

8. Tokio console — optional async-runtime debugging alongside metrics and traces.

Pull means scrapers call your server. Push means the server opens an export connection to a collector. From SurrealDB 3.1 onward, both paths share the same instruments. Canonical prose also ships in-tree: doc/OBSERVABILITY.md and doc/TELEMETRY.md; the Enterprise distribution extends doc/OBSERVABILITY.md with [C] / [E] catalogue markers.

The surrealdb.* metric namespace, the PUBLIC_METRICS allowlist, the audit-log pipeline, and the slow-query log pipeline are new in SurrealDB 3.1. Operators upgrading from 3.0 should read the Migration from 3.0 section in the metrics reference.

Editions at a glance

The Community server publishes the full set of primary signal families. The Enterprise composer adds the SurrealDS cluster metrics, the audit and slow-query log pipelines (with their own self-metrics), and the reserved per-tenant rollup scope.

Edition is also carried on the OTel Resource via the service.edition attribute (community or enterprise), so dashboards can group or filter on it without hard-coding metric scopes.

Quickstart

# Start the server (Community example)
surreal start --user root --pass root memory

# Anonymous scrape — public allowlist only
curl http://127.0.0.1:8000/metrics

# Operator scrape — full surface, including labelled families
curl -u root:root http://127.0.0.1:8000/metrics

SURREAL_METRICS_ENABLED=false surreal start ...
# /metrics now returns 404

SURREAL_TELEMETRY_PROVIDER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT="http://my-collector.monitoring.svc.cluster.local:4317" \
surreal start ...

SURREAL_TELEMETRY_DISABLE_METRICS=true   # OTLP metrics off; logs + traces still push
SURREAL_TELEMETRY_DISABLE_TRACING=true   # OTLP traces off; metrics + logs still push

What is new in 3.1

• A reworked metric namespace — every instrument is now surrealdb.*, grouped by signal family (statement, query, transaction, RPC, …). Names from 3.0 are mapped in the migration table.

• Dual access paths. Prometheus pull on /metrics and OTLP push run side-by-side. Both pipelines can be toggled independently.

• Public metrics allowlist (PUBLIC_METRICS). Six low-sensitivity gauges are safe to expose anonymously; the rest require root credentials.

• Audit log pipeline.

  Enterprise

  Durable NDJSON file sink with size-based rotation, tunable fsync cadence, optional hash chaining for tamper-evidence, and three-pass redaction.

• Slow-query log pipeline.

  Enterprise

  Mirrors the audit pipeline, with a configurable duration threshold and the slow-query counter metric.

• SurrealDS cluster metrics.

  Enterprise

  Around thirty instruments covering network, consensus, view changes, recovery and garbage collection.

• OpenTelemetry alignment. Standard semantic-convention attribute keys (http.request.method, http.route, http.response.status_code, db.namespace, db.user) replace ad-hoc keys.

Where to go next

Structured logs versus audit and slow-query records

Server structured logs (levels, format, files, sockets, and the --slow-log-* line-based slow-query helpers) are configured on surreal start and in the environment variables catalogue — see Logging. That stream is separate from the Enterprise audit and slow-query NDJSON pipelines, which have their own sinks and optional OTel log export — see Audit logging and Slow-query logging.

For async runtime introspection (tasks, poll histograms), use the Tokio console on trusted hosts only; it complements OTLP and /metrics, it does not replace them.