tokio-console

tokio-console CLI

🎛️ The Tokio console: a debugger for asynchronous Rust programs.

Website | Chat | API Documentation

Overview

tokio-console is a debugging and profiling tool for asynchronous Rust applications, which collects and displays in-depth diagnostic data on the asynchronous tasks, resources, and operations in an application. The console system consists of two primary components:

• 📡️ instrumentation, embedded in the application, which collects data from the async runtime and exposes it over the console's wire format
• 🛰️ consumers, which connect to the instrumented application, recieve telemetry data, and display it to the user

This crate is the primary consumer of tokio-console telemetry, a command-line application that provides an interactive debugging interface.

Getting Started

To use the console to monitor and debug a program, it must be instrumented to emit the data the console consumes. Then, the tokio-console CLI application can be used to connect to the application and monitor its operation.

Instrumenting the Application

Before the console can connect to an application, it must first be instrumented to record tokio-console telemetry. The easiest way to do this is using the console-subscriber crate.

console-subscriber requires that the application's async runtime (or runtimes) emit tracing data in a format that the console can record. For programs that use the Tokio runtime, this means that:

• Tokio's unstable features must be enabled. See the console-subscriber documentation for details.
• A compatible Tokio version must be used. Tokio v1.0 or greater is required to use the console, and some features are only available in later versions. See the console-subscriber documentation for details.

Using the Console

Once the application is instrumented, install the console CLI using

cargo install --locked tokio-console

Running tokio-console without any arguments will connect to an application on localhost listening on the default port, port 6669:

tokio-console

If the application is not running locally, or was configured to listen on a different port, the console will also accept a target address as a command-like argument:

tokio-console http://192.168.0.42:9090

A DNS name can also be provided as the target address:

tokio-console http://my.instrumented.application.local:6669

See here for a complete list of all command-line arguments.

When the console CLI is launched, it displays a list of all asynchronous tasks in the program:

Using the ↑ and ↓ arrow keys, an individual task can be highlighted. Pressingenter while a task is highlighted displays details about that task:

Pressing the escape key returns to the task list.

The r key switches from the list of tasks to a list of resources, such as synchronization primitives, I/O resources, et cetera:

Pressing the t key switches the view back to the task list.

Like the task list view, the resource list view can be navigated using the ↑ and ↓ arrow keys. Pressing enter while a resource is highlighted displays details about that resource:

The resource details view lists the tasks currently waiting on that resource. This may be a single task, as in the [tokio::time::Sleep] above, or a large number of tasks, such as this private tokio::sync::batch_semaphore::Semaphore:

Like the task details view, pressing the escape key while viewing a resource's details returns to the resource list.

A configuration file (console.toml) can be used to configure the console's behavior. See the documentation for details.

Getting Help

First, see if the answer to your question can be found in the API documentation. If the answer is not there, there is an active community in the Tokio Discord server. We would be happy to try to answer your question. You can also ask your question on the discussions page.

Contributing

🎈 Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the Tokio console project.

Supported Rust Versions

The Tokio console is built against the latest stable release. The minimum supported version is 1.58. The current Tokio console version is not guaranteed to build on Rust versions earlier than the minimum supported version.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.