🎛️ The [Tokio console][tokio-console]: a debugger for
asynchronous Rust programs.
Website | Chat | API Documentation
[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:
This crate is the primary consumer of tokio-console telemetry, a command-line
application that provides an interactive debugging interface.
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.
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:
console-subscriber
documentation for details.console-subscriber documentation for details.Once the application is instrumented, install the console CLI using
shell
cargo install tokio-console
Running tokio-console without any arguments will connect to an application on
localhost listening on the default port, port 6669:
shell
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:
shell
tokio-console http://192.168.0.42:9090
A DNS name can also be provided as the target address:
shell
tokio-console http://my.instrumented.application.local:6669
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::sync::oneshot] channel above, or
a large number of tasks, such as this [tokio::sync::Semaphore]:
Like the task details view, pressing the escape key while viewing a resource's details returns to the resource list.
Running tokio-console --help displays a list of all available command-line
arguments:
```shell
$ tokio-console --help
tokio-console 0.1.3
USAGE: tokio-console [OPTIONS] [TARGET_ADDR]
ARGS:
This may be an IP address and port, or a DNS name.
[default: http://127.0.0.1:6669]
OPTIONS: --ascii-only Explicitly use only ASCII characters
--colorterm <truecolor>
Overrides the value of the `COLORTERM` environment variable.
If this is set to `24bit` or `truecolor`, 24-bit RGB color support will be enabled.
[env: COLORTERM=truecolor]
[possible values: 24bit, truecolor]
-h, --help
Print help information
--lang <LANG>
Overrides the terminal's default language
[env: LANG=en_US.UTF-8]
[default: en_us.UTF-8]
--log <ENV_FILTER>
Log level filter for the console's internal diagnostics.
The console will log to stderr if a log level filter is provided. Since the console
application runs interactively, stderr should generally be redirected to a file to avoid
interfering with the console's text output.
[env: RUST_LOG=]
[default: off]
--no-colors
Disable ANSI colors entirely
--no-duration-colors
Disable color-coding for duration units
--no-terminated-colors
Disable color-coding for terminated tasks
--palette <PALETTE>
Explicitly set which color palette to use
[possible values: 8, 16, 256, all, off]
--retain-for <RETAIN_FOR>
How long to continue displaying completed tasks and dropped resources after they have
been closed.
This accepts either a duration, parsed as a combination of time spans (such as `5days
2min 2s`), or `none` to disable removing completed tasks and dropped resources.
Each time span is an integer number followed by a suffix. Supported suffixes are:
* `nsec`, `ns` -- nanoseconds
* `usec`, `us` -- microseconds
* `msec`, `ms` -- milliseconds
* `seconds`, `second`, `sec`, `s`
* `minutes`, `minute`, `min`, `m`
* `hours`, `hour`, `hr`, `h`
* `days`, `day`, `d`
* `weeks`, `week`, `w`
* `months`, `month`, `M` -- defined as 30.44 days
* `years`, `year`, `y` -- defined as 365.25 days
[default: 6s]
-V, --version
Print version information
```
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.
🎈 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.
The Tokio console is built against the latest stable release. The minimum supported version is 1.56. The current Tokio console version is not guaranteed to build on Rust versions earlier than the minimum supported version.
This project is licensed under the [MIT license].
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.