# Tokio console

Inspect SurrealDB’s async runtime with the Tokio console - tasks, polls, and bottlenecks separate from OpenTelemetry metrics and traces.

_(since v3.0.0)_

[Telemetry (OTLP)](/docs/manage/observability/telemetry.md) and [`GET /metrics`](/docs/manage/observability/observability.md) (Prometheus pull) tell you what the database is doing from the outside (requests, statements, resources). The [Tokio console](https://github.com/tokio-rs/console) shows what the Tokio runtime is doing on the inside: which async tasks exist, how long they spend polled versus waiting, and where scheduling stalls appear. It is aimed at contributors and advanced operators debugging performance or deadlocks, not at replacing production metrics.

SurrealDB embeds Tokio console support behind environment variables. It is disabled by default; enable it only on trusted hosts (for example local development or a dedicated staging instance).

## Install the console CLI

The server exposes data to the console subscriber; you still need the Tokio console client on your machine.

1. [Install Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) if you do not already have them.
2. Install the CLI: `cargo install --locked tokio-console`
3. Start SurrealDB with console support enabled (see below), then run `tokio-console` in another terminal. By default it connects to `127.0.0.1:6669`.

## Enable console support on the server

Set the following before starting `surreal`:

* `SURREAL_TOKIO_CONSOLE_ENABLED` - set to `true` to turn on the subscriber.
* `SURREAL_TOKIO_CONSOLE_SOCKET_ADDR` - optional; overrides the default listen address `127.0.0.1:6669`.
* `SURREAL_TOKIO_CONSOLE_RETENTION` - optional; overrides the default `6s` (six seconds) for how long to [retain data for completed events](https://docs.rs/console-subscriber/0.4.1/console_subscriber/struct.Builder.html#method.retention).

The socket listens only on the address you configure; keep it on loopback unless you fully understand the exposure (the stream describes internal task behaviour).

## What you will see

![A screenshot of the Tokio console showing active SurrealDB tasks.](~/assets/img/surrealdb/reference-guide/tokio_console_1.png)

![A screenshot of the Tokio console showing poll times by percentile.](~/assets/img/surrealdb/reference-guide/tokio_console_2.png)

Typical uses for the tokio console are: spotting tasks that rarely get polled, comparing poll percentiles after a change, and correlating spikes in load with specific async workloads.