tokio-console

⚠️ extremely serious warning: this is pre-alpha software undergoing active development! currently, the wire format has no stability guarantees — the crates in this repository are not guaranteed to be interoperable except within the same Git revision. when these crates are published to crates.io, the wire format will follow semver, but currently, anything could happen!

Chat | API Documentation (main branch)

what's all this, then?

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 the tonic 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 a tracing-subscriber Layer, for projects using Tokio and tracing.
tools for displaying and exploring diagnostic data, implemented as gRPC clients using the console wire protocol. the 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.

extremely cool and amazing screenshots

wow! whoa! it's like top(1) for tasks!

viewing details for a single task:

on the shoulders of giants...

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.

using it

instrumenting your program

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 with
```
$ RUSTFLAGS="--cfg tokio_unstable" cargo build
```
or add the following to your .cargo/config file:
```
[build]
rustflags = ["--cfg", "tokio_unstable"]
```
the tokio and runtime [tracing targets] must be enabled at the TRACE level.

if you're using the using console_subscriber::init() or console_subscriber::build() APIs, these targets are enabled automatically.

if you are manually configuring the tracing subscriber using the EnvFilter or Targets filters from tracing-subscriber, add "tokio=trace,runtime=trace" to your filter configuration.

running the console

to run the console command-line tool, simply

$ cargo run

in this repository.

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 -h or --help flag will print a list of supported command-line flags and arguments:

USAGE:
    tokio-console [FLAGS] [OPTIONS] [TARGET_ADDR]

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. [default: http://127.0.0.1:6669]

FLAGS:
        --ascii-only
            Explicitly use only ASCII characters

    -h, --help
            Print help information

        --no-colors
            Disable ANSI colors entirely

        --no-duration-colors
            Disable color-coding for duration units

        --no-terminated-colors
            Disable color-coding for terminated tasks

    -V, --version
            Print version information

OPTIONS:
        --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]

        --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]

        --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]

for development:

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 forever
dump.rs: a simple CLI program that dumps the data stream from a Tasks server

Examples can be executed with:

cargo run --example $name

asonix / console