tokio-console

Chat | API Documentation (main branch)

what's all this, then? Copy Chapter

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

extremely cool and amazing screenshots Copy Chapter

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

viewing details for a single task:

on the shoulders of giants Copy Chapter

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 Copy Chapter

instrumenting your program Copy Section

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

  shell Copy

  RUSTFLAGS="--cfg tokio_unstable" cargo build

  or add the following to your .cargo/config.toml file:

  toml Copy

  [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 and runtime tracing targets must be enabled at the TRACE
  level.

  • if you're using the console_subscriber::init() or
    console_subscriber::Builder 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.

  • also, ensure you have not enabled any of the compile time filter
    features in your Cargo.toml.

running the console Copy Section

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

shell Copy

$ 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 : or
<DNS_NAME>:). 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:

/* Detailed source-code truncated for AI context efficiency. */

running the console on windows

The console uses the UTF-8 character set to display graphs and other visual
features in the terminal. In order to display this rich terminal UI on Windows,
it's necessary to use a UTF-8-enabled terminal emulator, such as the new
Windows Terminal.

If you're using a terminal that supports UTF-8, make sure to explicitly call
tokio-console with the UTF-8 language flag set:

tokio-console --lang en_US.UTF-8

for development Copy Chapter

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