console-subscriber

tokio-console subscriber

📡️ A tracing-subscriber Layer for collecting tokio-console telemetry.

Website | Chat | API Documentation

Overview

tokio-console is a debugging and profiling tool for asynchronous Rust applications, which collects and displays in-depth diagnostic data on the asynchronous tasks, resources, and operations in an application. The console system consists of two primary components:

• instrumentation, embedded in the application, which collects data from the async runtime and exposes it over the console's wire format
• consumers, such as the tokio-console command-line application, which connect to the instrumented application, recieve telemetry data, and display it to the user

This crate implements the instrumentation-side interface using data emitted by the async runtime using the tracing. It provides a type implementing the Layer trait from tracing-subscriber, for collecting and aggregating the runtime's tracing data, and a gRPC server that exports telemetry to clients.

Getting Started

To instrument your asynchronous application, you must be using an async runtime that supports the tracing instrumentation required by the console. Currently, the only runtime that implements this instrumentation is Tokio version 1.7.0 and newer.

Enabling Tokio Instrumentation

⚠️ Currently, the tracing support in the tokio runtime is considered experimental. In order to use console-subscriber with Tokio, the following is required:

• Tokio's optional tracing dependency must be enabled. For example:

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

• The tokio_unstable cfg flag, which enables experimental APIs in Tokio, must be enabled. It can be enabled by setting the RUSTFLAGS environment variable at build-time:

  $ RUSTFLAGS="--cfg tokio_unstable" cargo build

  or, by adding the following to the .cargo/config file in a Cargo workspace:

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

Adding the Console Subscriber

If the runtime emits compatible tracing events, enabling the console is as simple as adding the following line to your main function:

console_subscriber::init();

This sets the default tracing subscriber to serve console telemetry (as well as logging to stdout based on the RUST_LOG environment variable). The console subscriber's behavior can be configured via a set of environment variables.

For programmatic configuration, a builder interface is also provided:

use std::time::Duration;

console_subscriber::ConsoleLayer::builder()
    // set how long the console will retain data from completed tasks
    .retention(Duration::from_secs(60))
    // set the address the server is bound to
    .server_addr(([127, 0, 0, 1], 5555))
    // ... other configurations ...
    .init();

The layer provided by this crate can also be combined with other Layers from other crates:

use tracing_subscriber::prelude::*;

// spawn the console server in the background,
// returning a `Layer`:
let console_layer = console_subscriber::spawn();

// build a `Subscriber` by combining layers with a
// `tracing_subscriber::Registry`:
tracing_subscriber::registry()
    // add the console layer to the subscriber
    .with(console_layer)
    // add other layers...
    .with(tracing_subscriber::fmt::layer())
 // .with(...)
    .init();

Crate Feature Flags

This crate provides the following feature flags and optional dependencies:

• parking_lot: Use the parking_lot crate's locks, rather than std::sync. Using parking_lot may result in improved performance, especially in highly concurrent applications. Disabled by default.

Getting Help

First, see if the answer to your question can be found in the API documentation. If the answer is not there, there is an active community in the Tokio Discord server. We would be happy to try to answer your question. You can also ask your question on the discussions page.

Contributing

🎈 Thanks for your help improving the project! We are so happy to have you! We have a contributing guide to help you get involved in the Tokio console project.

Supported Rust Versions

The Tokio console is built against the latest stable release. The minimum supported version is 1.56. The current Tokio console version is not guaranteed to build on Rust versions earlier than the minimum supported version.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.