DOCSEARCHbyAlgolia
Submit Docs

tokio-console

repository·main·Indexed 26 days ago

https://github.com/tokio-rs/console

A diagnostics and debugging toolkit for asynchronous Rust programs. It provides an interactive CLI (similar to top) to explore tasks and runtime behavior. The system consists of the tokio-console CLI tool, the console-subscriber crate for application instrumentation, and the console-api crate providing protobuf bindings for the wire format.

Tokens
9.3K
Snippets
17
Records
48
Agent score
88%

What's inside tokio-console

  1. Overview of tokio-console

    main

    tokio-console is a debugging and profiling tool for asynchronous Rust applications. It provides an interactive command-line interface to monitor and diagnose asynchronous tasks, resources (like synchronization primitives and I/O), and operations.

    The system consists of two parts:

    1. Instrumentation: Embedded in your application (typically via console-subscriber) to collect data from the async runtime.
    2. Consumers: The tokio-console CLI application that connects to the instrumented app to display telemetry data.

  2. Overview of tokio-console components

    main

    tokio-console is a diagnostic and debugging toolkit for asynchronous Rust programs. It consists of three main components:

    • Wire Protocol: A gRPC and Protocol Buffers-based format for streaming diagnostic data. The console-api crate provides the generated code for tonic users.
    • Instrumentation: The console-subscriber crate provides a tracing-subscriber Layer to collect diagnostic data from processes using Tokio and tracing.
    • Display Tools: The tokio-console crate is an interactive command-line tool (similar to top(1)) that consumes the diagnostic data via gRPC.

  3. Understand the tokio-console wire format and console-api crate

    main

    The console-api crate provides generated [protobuf] bindings for the tokio-console wire format. This format is used to export diagnostic data from instrumented applications to consumers (like the tokio-console CLI) that aggregate and display telemetry.

    Note for most users: Most developers will not need to depend on console-api directly. Instead:

    1. Use console-subscriber to instrument your application.
    2. Use the tokio-console CLI tool to consume and view the data.

    console-api is primarily intended for developers implementing new software that needs to consume tokio-console diagnostic data.

  5. Run the tokio-console CLI

    main

    Once installed, you can connect to your instrumented application using the following commands:

    • Connect to localhost (default port 6669):
      tokio-console
    • Connect to a specific address/port:
      tokio-console http://192.168.0.42:9090
    • Connect via DNS name:
      tokio-console http://my.instrumented.application.local:6669

    Windows Users: To support the UTF-8 rich terminal UI, use a UTF-8-enabled terminal (like Windows Terminal) and explicitly set the language flag:

    tokio-console --lang en_US.UTF-8

  6. Install and run the tokio-console CLI

    main

    To use the tokio-console debugger, install the CLI tool from crates.io and run it locally.

    Installation:

    cargo install --locked tokio-console

    Running locally:

    tokio-console

    By default, the tool attempts to connect to an instrumented application on localhost:6669.

    Connecting to a remote or custom address: If your application is running on a different host or port, pass the address as an argument:

    tokio-console <IP>:<PORT>
# OR
tokio-console <DNS_NAME>:<PORT>
# OR (for local checkout)
cargo run -- http://my.great.console.app.local:5555

    Windows Users: To display the rich terminal UI correctly, use a UTF-8-enabled terminal (like Windows Terminal) and explicitly set the language flag:

    tokio-console --lang en_US.UTF-8
    cargo install --locked tokio-console
tokio-console

  7. Use tokio-console with non-Tokio runtimes

    main
    If you are using a custom runtime that supports tokio-console telemetry but does not require the experimental tokio_unstable flag, you must enable the console_without_tokio_unstable cfg flag. This tells console-subscriber to skip its internal check for the tokio_unstable configuration.

  8. Instrument an application with tokio-console

    main

    To enable tokio-console debugging for your Tokio application, follow these steps:

    1. Add the console-subscriber crate as a dependency to your project.
    2. Add console_subscriber::init(); to the very top of your main function.
    3. Enable tokio_unstable: You must compile your project with the tokio_unstable configuration enabled to collect task data.

    Ways to enable tokio_unstable:

    • Via RUSTFLAGS:

      RUSTFLAGS="--cfg tokio_unstable" cargo build

    • Via .cargo/config.toml:

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

    Tracing Configuration:

    • The tokio and runtime tracing targets must be enabled at the TRACE level.
    • If using console_subscriber::init() or console_subscriber::Builder, these are enabled automatically.
    • If manually configuring tracing-subscriber (e.g., using EnvFilter or Targets), add "tokio=trace,runtime=trace" to your filter.
    • Ensure you have not enabled any compile-time filter features in your Cargo.toml that might suppress these levels.
    console_subscriber::init();

  9. Instrument an application with console-subscriber

    main

    To use the console, your application must be instrumented to emit telemetry. The recommended way is using the console-subscriber crate.

    Requirements for Tokio users:

    • You must enable Tokio's unstable features.
    • You must use a compatible Tokio version (v1.0 or greater is required; specific features may require later versions).
    • The application's runtime must emit tracing data in a format compatible with the console.

  10. Add the Console Subscriber to your application

    main

    You can integrate console-subscriber into your application using several methods depending on your needs for configuration and layer composition.

    Simple Initialization

    For a quick setup that sets the default tracing subscriber and serves telemetry (while also logging to stdout via RUST_LOG), call init() in your main function.

    Programmatic Configuration with Builder

    Use the ConsoleLayer::builder() to customize settings such as data retention duration and the gRPC server address.

    Combining with other Tracing Layers

    If you are using a tracing-subscriber::Registry, you can use console_subscriber::spawn() to create a Layer that runs the console server in the background, allowing you to compose it with other layers like fmt::layer().

    // Simple initialization
console_subscriber::init();
    // Programmatic configuration
use std::time::Duration;

console_subscriber::ConsoleLayer::builder()
    .retention(Duration::from_secs(60))
    .server_addr(([127, 0, 0, 1], 5555))
    .init();
    // Combining with other layers
use tracing_subscriber::prelude::*;

let console_layer = console_subscriber::spawn();

tracing_subscriber::registry()
    .with(console_layer)
    .with(tracing_subscriber::fmt::layer())
    .init();

  11. Navigate the tokio-console UI

    main

    The console provides several interactive views and navigation shortcuts:

    • Tasks List: The default view showing all asynchronous tasks.
    • Task Details: Detailed view of a specific task (accessed by highlighting a task and pressing <enter>).
    • Resources List: View synchronization primitives and I/O resources (press <r> from the task list).
    • Resource Details: View tasks waiting on a specific resource (accessed by highlighting a resource and pressing <enter>).

    Navigation Keys:

    • <up> / <down>: Navigate through lists.
    • <enter>: Open details for the highlighted item.
    • <escape>: Return to the previous list view.
    • <t>: Switch from the Resource List back to the Task List.

  12. Enable Tokio Instrumentation for tokio-console

    main

    To use console-subscriber with the Tokio runtime, you must enable experimental features. This requires three specific steps:

    1. Enable Tokio's tracing feature: In your Cargo.toml, ensure the tracing feature is enabled for tokio.
    2. Enable tokio_unstable: You must pass the --cfg tokio_unstable flag during compilation. You can do this via the RUSTFLAGS environment variable or by adding it to your .cargo/config.toml.
    3. Set tracing levels: The tokio and runtime targets must be enabled at the TRACE level. If you use console_subscriber::init() or the Builder API, this is handled automatically. If you use manual filters like EnvFilter or Targets, you must explicitly add "tokio=trace,runtime=trace" to your configuration.

    Warning: Missing the tokio_unstable configuration will cause tokio-console to fail to work.

    [dependencies]
tokio = { version = "1.15", features = ["full", "tracing"] }

    Via RUSTFLAGS

    $ RUSTFLAGS="--cfg tokio_unstable" cargo build

    Or in .cargo/config.toml

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