Getting Started with Tokio Console

Step 1: Download the console

The tokio-console isn't available via crates.io (yet). So you will need to download its source code. You can find it on github, here: https://github.com/tokio-rs/console

% git clone [e-mail]:tokio-rs/console.git console
% cd console
console%

We will be tracking a specific "preview" branch of the console where we can make changes and adapt to your needs as we discover them. So after you download the console repository, make sure to check out the preview branch:

console% git checkout preview

Step 2: Tokio instrumentation

The console works by monitoring tracing events that are emitted from the tokio runtime that describe operational steps the runtime takes.

Tokio version

For this to work, you need to be using a version of tokio that has the necessary instrumentation.

Console Features	Tokio Version Required
tasks, polls	1.7 (?)
resource monitoring	(not in tokio release yet)

Tokio build customization

You will also need to build this version of tokio with the --cfg tokio_unstable flag to opt into the tracing instrumentation. You can do this by adding this to a .cargo/config.toml file:

[build]
rustflags = ["--cfg", "tokio_unstable"]

Alternatively, you can get the same effect via the RUST_FLAGS environment variable when you build:

myapp% RUSTFLAGS="--cfg tokio_unstable" cargo build

Step 3: Update your code with a console subscriber

In your code, you'll need to register a "subscriber" that captures the tokio-emitted events and uses them to build an internal model of the runtime state.

In the Cargo.toml for your crate, add the console_subscriber as a dependency:

[dependencies]
...
console-subscriber = { path = "path/to/console/console-subscriber" }

Then in your code, after making that change to your Cargo.toml, somewhere before service's task is spawned (or early on in the execution of your [tokio::main] function), add this line:

console_subscriber::init();

If you want to customize the configuration, you can use a more complex builder invocation such as the one documented on the console repository.

Step 4: Build and run the console

Go to your checkout of the console repository and build it!

console% cargo build

Step 5: Run your code and the console

Since you are going to be running your code and monitoring it with the console, you may want to use two separate terminal sessions for this. We we be labelling the first session for your service with myapp%, and the second session for the console itself with console%

Go to your application code and run it.

myapp% cargo run 

After it has started, you can run the console to start monitoring your server:

console% cargo run

Customizations

If you want to customize how the console-subscriber and console interact, you can use environment variables when you run your code to adjust the console's preset-defaults.

For example, if you are running multiple programs each with their own console-subscriber, then you'll want to customize which port they use to communicate with the console; you can do that with TOKIO_CONSOLE_BIND, like so:

myapp% TOKIO_CONSOLE_BIND=localhost:6667 cargo run 

And then just pass that customized description when you start the console itself:

console% cargo run -- localhost:6667

---

The full set of environment variables is copied here from the console documentation:

Environment Variable	Purpose	Default Value
TOKIO_CONSOLE_RETENTION_SECS	The number of seconds to accumulate completed tracing data	3600s (1h)
TOKIO_CONSOLE_BIND	A HOST:PORT description, such as localhost:1234	127.0.0.1:6669
TOKIO_CONSOLE_PUBLISH_INTERVAL_MS	The number of milliseconds to wait between sending updates to the console	1000ms (1s)
TOKIO_CONSOLE_RECORD_PATH	The file path to save a recording	None
RUST_LOG	Configure the tracing filter. See EnvFilter for further information	tokio=trace