tokio-rs/console: a gRPC-based task debugger for async Rust, from console-subscriber to the tokio-console TUI

Three crates split the wire format, the instrumentation and the viewer

The repository is a Cargo workspace with four members: tokio-console, console-subscriber, console-api and xtask. The first three are the product. console-api holds generated code for a wire protocol defined with gRPC and protocol buffers, aimed at projects that use the tonic gRPC implementation. Projects using other gRPC code generators, including ones in other languages, can depend on the protobuf definitions directly.

console-subscriber is the instrumentation side. It implements the producer API as a tracing-subscriber Layer, for projects using Tokio and tracing. tokio-console is the client, an interactive command-line tool. The design lets other clients exist, such as graphical or web-based tools, but those are described as possible, and the only one in this repository is the terminal tool.

Without the tokio_unstable cfg the console has no task data to show

Instrumenting an application takes a dependency on console-subscriber and one line at the top of main:

console_subscriber::init();

The catch is that, to collect task data from Tokio, the tokio_unstable cfg must be enabled. You can pass it on the command line:

RUSTFLAGS="--cfg tokio_unstable" cargo build

or put it in your .cargo/config.toml file:

[build]
rustflags = ["--cfg", "tokio_unstable"]

The consequence is that the instrumented build differs from a normal build, and that cfg is a build setting for your whole crate graph, not something the init call sets for you. The README points to the console-subscriber readme for where the config file should live, especially in workspaces, so a config file in the wrong directory leaves the cfg off.

The tokio and runtime targets must stay at TRACE or the data dries up

Besides the cfg, the tokio and runtime tracing targets must be enabled at the TRACE level. If you use console_subscriber::init() or the console_subscriber::Builder API, those targets are enabled automatically, so the simple path needs no filter work.

If you configure the tracing subscriber by hand with the EnvFilter or Targets filters from tracing-subscriber, you add "tokio=trace,runtime=trace" to your filter configuration yourself. A hand-built subscriber that filters at info will therefore run without errors and send the console nothing useful. You also have to make sure none of the compile time filter features of tracing are enabled in your Cargo.toml, because those strip the events before any runtime filter can see them.

The client connects to localhost on port 6669 unless you hand it a target

Running the viewer is two commands. Install it from crates.io and start it:

cargo install --locked tokio-console

tokio-console

By default it attempts to connect to an instrumented application on localhost, port 6669. If the application runs elsewhere, or serves the console endpoint on a different port, you pass a target address as an argument, either an IP:PORT or a DNS_NAME:PORT. From a local checkout the same thing looks like this:

cargo run -- http://my.great.console.app.local:5555

The repository also supports running the tool from a checkout with cargo run. The practical limit is that the endpoint is a gRPC server inside your process, so reaching a remote service means making that port reachable first.

gen-config writes a console.toml so flags do not have to be retyped

The command-line tool accepts a number of flags, and tokio-console --help lists them. Its usage line is tokio-console [OPTIONS] [TARGET_ADDR] [COMMAND], and the commands are gen-config, gen-completion and help.

gen-config generates a console.toml config file with the default configuration values, overridden by any command-line arguments you provided. That gives you a way to freeze a target address and display choices into a file instead of repeating them on each run. gen-completion generates shell completions. The help output in the README is cut off after the Arguments heading, so the individual option names are not reproduced here, and you should read them from tokio-console --help on the version you install.

It covers Tokio programs on tracing only, and the terminal client is the one viewer

The scope is narrow by design. The instrumentation crate targets projects using Tokio and tracing, and the data it exposes is task data collected from Tokio. A program on a different async runtime, or one that cannot adopt tracing, has no instrumentation path in this repository.

On the display side, the pitch is that it is like top(1) for tasks, with a detail view for a single task. The README names its inspiration as pprof, Unix top(1) and htop(1), and XCode's Instruments, and traces the idea to a 2019 Google Summer of Code project by Matthias Prechtl that built an early prototype focused on interactive log viewing. None of that gives you historical storage, which this tool does not claim: it is a live debugger, so a stall you did not watch is not something you can replay.

The last published crates date from October 2025, while the repository saw a push in August 2026

The three recent releases are tokio-console-v0.1.14, console-subscriber-v0.5.0 and console-api-v0.9.0, all tagged on 2025-10-30. The tokio-console client is still on a 0.1 line, and console-subscriber is on 0.5.0, so expect version numbers below 1.0 and plan for changes between minor versions. The latest push to main was on 2026-08-08, later than the newest release, meaning some work on main has no tagged release yet.

The repository is not archived and carries the MIT license. Build tooling visible at the top level includes release-plz.toml, cliff.toml, dist-workspace.toml and a nix flake. The workspace sets resolver = "2" and a dist profile that inherits release with thin LTO, which is the profile used to build distributed binaries.

Editorial conclusion

Use tokio-console if your service runs on Tokio and you can build it with --cfg tokio_unstable, because it shows live task state with a one-line init call. Skip it if you cannot enable that cfg, if you are not on Tokio and tracing, or if you need a graphical or web client, since only the terminal client is implemented here.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tokio-rs/console on GitHub