This page covers push export using the OpenTelemetry Protocol (OTLP): your server sends signals to a collector. For pull scraping of GET /metrics (Prometheus), see Observability (metrics and Prometheus).
SurrealDB can be monitored by enabling built-in observability.
Enable observability
To enable observability, the SURREAL_TELEMETRY_PROVIDER environment variable has to be set to otlp. If set to anything else, no observability will be available.
If enabled, SurrealDB sends metrics and/or traces to an OpenTelemetry Collector. Configuration of the collector follows the OpenTelemetry environment variable conventions. The most important variable is OTEL_EXPORTER_OTLP_ENDPOINT. By default this points at localhost. Set it to the gRPC endpoint of your collector. For example, if your collector named my-collector runs in Kubernetes in the monitoring namespace:
Metrics can be disabled (even if SURREAL_TELEMETRY_PROVIDER is set to otlp) by setting SURREAL_TELEMETRY_DISABLE_METRICS to true. Similarly, traces can be disabled with SURREAL_TELEMETRY_DISABLE_TRACING=true.
Metrics
Metrics are gathered every minute and sent to the collector. The following metrics are present:
| Name | Instrument | Explanation |
|---|---|---|
| rpc.server.duration | histogram | Measures duration of inbound RPC requests in milliseconds |
| rpc.server.active_connections | counter | The number of active WebSocket connections |
| rpc.server.response.size | histogram | Measures the size of HTTP response messages |
| http.server.duration | histogram | The HTTP server duration in milliseconds |
| http.server.active_requests | counter | The number of active HTTP requests |
| http.server.request.size | histogram | Measures the size of HTTP request messages |
| http.server.response.size | histogram | Measures the size of HTTP response messages |
The metrics are shown here in the form required by the OpenTelemetry Metrics Semantic Conventions with a . separator. When ingested into Prometheus the . separator is replaced with _. For example rpc.server.active_connections becomes rpc_server_active_connections.
For async runtime introspection (tasks, polls, scheduling), you can use the Tokio console which is separate from OTLP.
For server logging (levels, JSON, files, sockets, slow-query logging), see Logging.
For async runtime debugging with the Tokio console (tasks, poll histograms), see Tokio console. That workflow sits beside OTLP and is not version-split in the tabs above.
For diagrams, histogram bucket rules, deprecated variables, and the full OTLP signal matrix in prose form, see doc/TELEMETRY.md in the open-source repository alongside doc/OBSERVABILITY.md for /metrics, allowlists, and metric catalogues. The Enterprise distribution ships an extended doc/OBSERVABILITY.md with [C] / [E] markers — summarised on Enterprise observability.