Enterprise observability

SurrealDB Community and Enterprise share one unified observability implementation in the server: the same labelled metric families, the same GET /metrics path, and the same OTLP push pipeline when enabled. Enterprise adds optional durability and cluster depth on top:

• SurrealDS cluster instruments (surrealdb.ds.*) — consensus, networking, recovery, and garbage collection when you run the distributed datastore path.

• Audit and slow-query pipelines — bounded queues, file sinks with rotation and optional hash chaining, and pipeline self-metrics (surrealdb.audit.*, surrealdb.slow_query.*) when those sinks are configured.

• OpenTelemetry logs for audit and slow-query — the same redacted records can be emitted as OTel log records, but only when you opt in with SURREAL_AUDIT_OTEL_EXPORT=true and/or SURREAL_SLOW_QUERY_OTEL_EXPORT=true (default false so sensitive payloads stay on the file sink unless you choose otherwise).

Throughout this page, markers mean:

• [C] — Registered in every build that exposes metrics (Community and Enterprise).

• [E] — Registered only when running a SurrealDB Enterprise binary with the relevant feature enabled.

For Prometheus pull behaviour, naming rules, the public PUBLIC_METRICS allowlist, and multi-tenant guidance common to both editions, see Observability (metrics and Prometheus). For OTLP push, intervals, and legacy HTTP/RPC instruments, see Telemetry (OTLP).

Pipeline overview

HTTP / WS / Executor → ExecutionObserver → FanOutObserver
                                            ├── MetricsObserver         (labelled surrealdb.*)         [C]
                                            ├── DsMetrics               (surrealdb.ds.*)               [E]
                                            ├── AuditObserver           (audit → file + optional OTel)  [E]
                                            └── SlowQueryObserver       (slow-query → file + optional OTel) [E]
                                                       │
                                            SdkMeterProvider + SdkLoggerProvider
                                                       │
                                       ┌───────────────┼────────────────┐
                                       ▼               ▼                ▼
                          Prometheus text       OTLP metrics push   OTLP logs / traces push
                          exporter (/metrics)

ExecutionObserver short-circuits when no observer in the chain has work, so a process with neither /metrics nor OTLP configured avoids hot-path cost. Build flavour is carried on the OpenTelemetry resource as service.edition (community or enterprise), for example on target_info in Prometheus — filter dashboards on that attribute rather than on meter scope names.

/metrics versus OTLP

Disabling pieces:

Community versus Enterprise (at a glance)

Configuration highlights (Enterprise)

Core switches ([C])

These apply to every build:

Audit log ([E])

Slow-query log ([E])

Redaction (SURREAL_AUDIT_REDACT_* / SURREAL_SLOW_QUERY_REDACT_*) runs on the executor thread before the queue so the file sink and OTel path see the same scrubbed text. Full knob lists live with the rest of the server environment variables.

SurrealDS tuning ([E])

Large clusters expose saturation through surrealdb.ds.* and logs. Typical operator levers include inbound byte budgets, handler caps, read/write operation caps, and consensus timeouts. If you deploy on Kubernetes, pair metrics with the environment-variable reference in your platform runbook.

Audit and slow-query records ([E])

Records flow in parallel:

1. File sink — optional NDJSON with rotation; optional hash chain for tamper evidence.

2. OpenTelemetry logs — only when the matching SURREAL_*_OTEL_EXPORT flag is true.

Severity rules differ slightly between audit event kinds and slow-query (slow-query is always treated as a degraded path — typically WARN). Monitor surrealdb_audit_dropped, surrealdb_slow_query_dropped, surrealdb_audit_append_errors, and surrealdb_slow_query_append_errors: any sustained non-zero rate means lost or failed records.

Recommended exposure tiers (operators)

When you front /metrics with a proxy or expose metrics to customers:

1. Always safe without authentication — matches the built-in public allowlist (surrealdb_build_info, process gauges, target_info, otel_scope_info).

2. Customer-visible — only after the proxy filters dimensional series to that customer’s namespace / database. Strip user before showing outside trusted operator contexts.

3. Operator-only — surrealdb.ds.*, pipeline self-metrics, surrealdb_auth_*, storage backend detail, RPC method detail, and similar. Scrape these on a private interface with root credentials.

Migration from older Prometheus names

Legacy series names were collapsed into labelled families in SurrealDB 3.1. The same migration table applies to Community and Enterprise; see Observability (metrics and Prometheus) for the summary, Telemetry (OTLP) for wire-format and deprecation notes, and the Metrics reference for the full migration table.

Local checks

curl http://127.0.0.1:8000/metrics
curl -u root:root http://127.0.0.1:8000/metrics

Enterprise-only metrics (surrealdb_ds_*, audit/slow-query pipeline gauges) appear only in the authenticated view when those subsystems are active.

Pipeline and configuration references

• Audit logging — record shape, rotation, overflow semantics, hash chaining, redaction.

• Slow-query logging — triage pipeline mirroring the audit observer.

• Configuration — all SURREAL_AUDIT_* and SURREAL_SLOW_QUERY_* variables and the compliance checklist.