Chat | API Documentation (main
branch)
this repository contains an implementation of TurboWish/tokio-console, a diagnostics and debugging tool for asynchronous Rust programs. the diagnostic toolkit consists of multiple components:
-
a wire protocol for streaming diagnostic data from instrumented applications to diagnostic tools. the wire format is defined using gRPC and protocol buffers, for efficient transport on the wire and interoperability between different implementations of data producers and consumers.
the
console-api
crate contains generated code for this wire format for projects using thetonic
gRPC implementation. additionally, projects using other gRPC code generators (including those in other languages!) can depend on the protobuf definitions themselves. -
instrumentation for collecting diagnostic data from a process and exposing it over the wire format. the
console-subscriber
crate in this repository contains an implementation of the instrumentation-side API as atracing-subscriber
Layer
, for projects using Tokio andtracing
. -
tools for displaying and exploring diagnostic data, implemented as gRPC clients using the console wire protocol. the
tokio-console
crate implements an an interactive command-line tool that consumes this data, but other implementations, such as graphical or web-based tools, are also possible.
wow! whoa! it's like top(1)
for tasks!
viewing details for a single task:
the console is part of a much larger effort to improve debugging tooling for async Rust. a 2019 Google Summer of Code project by Matthias Prechtl (@matprec) implemented an initial prototype, with a focus on interactive log viewing. more recently, both the Tokio team and the async foundations working group have made diagnostics and debugging tools a priority for async Rust in 2021 and beyond. in particular, a series of blog posts by @pnkfelix lay out much of the vision that this project seeks to eventually implement.
furthermore, we're indebted to our antecedents in other programming languages
and environments for inspiration. this includes tools and systems such as
pprof
, Unix top(1)
and htop(1)
, XCode's Instruments, and many
others.
to instrument an application using Tokio, add a dependency on the
console-subscriber
crate, and add this one-liner to the top of your
main
function:
console_subscriber::init();
notes:
-
in order to collect task data from Tokio, the
tokio_unstable
cfg must be enabled. for example, you could build your project withRUSTFLAGS="--cfg tokio_unstable" cargo build
or add the following to your
.cargo/config.toml
file:[build] rustflags = ["--cfg", "tokio_unstable"]
For more information on the appropriate location of your
.cargo/config.toml
file, especially when using workspaces, see the console-subscriber readme. -
the
tokio
andruntime
tracing
targets must be enabled at theTRACE
level.-
if you're using the
console_subscriber::init()
orconsole_subscriber::Builder
APIs, these targets are enabled automatically. -
if you are manually configuring the
tracing
subscriber using theEnvFilter
orTargets
filters fromtracing-subscriber
, add"tokio=trace,runtime=trace"
to your filter configuration. -
also, ensure you have not enabled any of the compile time filter features in your
Cargo.toml
.
-
to run the console command-line tool, install tokio-console
from crates.io
cargo install --locked tokio-console
and run locally
tokio-console
alternative method: run the tool from a local checkout of this repository
$ cargo run
by default, this will attempt to connect to an instrumented application running
on localhost on port 6669. if the application is running somewhere else, or is
serving the console endpoint on a different port, a target address can be passed
as an argument to the console (either as an <IP>:<PORT>
or
<DNS_NAME>:<PORT>
). for example:
cargo run -- http://my.great.console.app.local:5555
The console command-line tool supports a number of additional flags to configure
its behavior. The help
command will print a list of supported command-line
flags and arguments:
USAGE:
tokio-console [OPTIONS] [TARGET_ADDR] [SUBCOMMAND]
ARGS:
<TARGET_ADDR>
The address of a console-enabled process to connect to.
This may be an IP address and port, or a DNS name.
On Unix platforms, this may also be a URI with the `file` scheme that specifies the path
to a Unix domain socket, as in `file://localhost/path/to/socket`.
[default: http://127.0.0.1:6669]
OPTIONS:
--ascii-only <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=]
--log <ENV_FILTER>
Log level filter for the console's internal diagnostics.
Logs are written to a new file at the path given by the `--log-dir` argument (or its
default value), or to the system journal if `systemd-journald` support is enabled.
If this is set to 'off' or is not set, no logs will be written.
[default: off]
[env: RUST_LOG=]
--log-dir <LOG_DIRECTORY>
Path to a directory to write the console's internal logs to.
[default: /tmp/tokio-console/logs]
--no-colors
Disable ANSI colors entirely
--no-duration-colors <COLOR_DURATIONS>
Disable color-coding for duration units
--no-terminated-colors <COLOR_TERMINATED>
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
SUBCOMMANDS:
gen-completion
Generate shell completions
gen-config
Generate a `console.toml` config file with the default configuration values, overridden
by any provided command-line arguments
help
Print this message or the help of the given subcommand(s)
the console-subscriber/examples
directory contains some potentially useful
tools:
app.rs
: a very simple example program that spawns a bunch of tasks in a loop foreverdump.rs
: a simple CLI program that dumps the data stream from aTasks
server
Examples can be executed with:
cargo run --example $name