Getting Started with Tokio Console

# 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 ```shell % git clone git@github.com: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: ```shell console% git checkout preview ``` ## Step 2: Tokio instrumentation The console works by monitoring [`tracing`](https://github.com/tokio-rs/tracing#readme) 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](https://doc.rust-lang.org/cargo/reference/config.html): ```toml [build] rustflags = ["--cfg", "tokio_unstable"] ``` Alternatively, you can get the same effect via the `RUST_FLAGS` environment variable when you build: ```shell 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: ```toml [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: ```rust 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](https://github.com/tokio-rs/console#using-it). ## Step 4: Build and run the console Go to your checkout of the `console` repository and build it! ```shell 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. ```shell myapp% cargo run ``` After it has started, you can run the console to start monitoring your server: ```shell 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: ```shell myapp% TOKIO_CONSOLE_BIND=localhost:6667 cargo run ``` And then just pass that customized description when you start the console itself: ```shell 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` | [`EnvFilter`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html