console

tokio-console is a debugging tool for asynchronous Rust programs. Asynchronous programs run many tasks at once, and when something goes wrong, such as a task getting stuck or running too slow, traditional debuggers do not surface the problem well. This tool gives you a live, interactive view of what those tasks are doing as your program runs.

The project has three parts that work together. First, there is a wire protocol: a defined format for streaming diagnostic data from a running program to an external viewer. Second, there is a library called console-subscriber that you add to your Rust project, which collects task data and sends it out over that wire format. Third, there is the tokio-console command-line tool itself, which connects to that data stream and shows a real-time task list, similar to how the top command shows OS processes.

Getting started takes two steps. You add console-subscriber as a dependency and call one function at the top of your main function. You also need to build your program with a specific compiler flag called tokio_unstable, because the underlying task data comes from an experimental part of the Tokio async runtime. After that, you run the console tool separately, and it connects to your program on localhost port 6669 by default. A different address can be passed as an argument if your program runs elsewhere.

The interactive terminal display shows tasks currently running in your program, with information like how long each task has been alive, how many times it has been polled by the runtime, and whether it is idle or active. Selecting a task shows additional detail. This kind of visibility into async behavior is otherwise difficult to get from standard tools.

The project builds on Tokio, the most widely used async runtime for Rust, and uses the tracing library for instrumentation. The wire protocol uses gRPC and protocol buffers. The README notes this work builds on a 2019 prototype and on broader community efforts to improve async debugging in Rust.