### Running Tokio Console Example and Application Source: https://github.com/tokio-rs/console/blob/main/CONTRIBUTING.md Commands to launch the example application in the background and then start the Tokio console. Useful for testing UI changes. ```shell :; cargo run --example app & :; cargo run ``` -------------------------------- ### Start gRPC-web Server Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/app/README.md Starts the gRPC server example using Cargo. This command should be run from the root `console-subscriber` directory and requires the `grpc-web` feature flag to be enabled. ```sh cargo run --example grpc_web --features grpc-web ``` -------------------------------- ### Install Node.js Dependencies Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/app/README.md Installs all necessary dependencies for the web application using npm. This command should be run from the `console-subscriber/examples/grpc_web/app` directory. ```sh npm install ``` -------------------------------- ### Start Web Application Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/README.md Starts the web application development server using npm. This command should be run from the `console-subscriber/examples/grpc_web/app` directory. ```sh npm run dev ``` -------------------------------- ### Start gRPC-web Server Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/README.md Starts the gRPC server example using Cargo. This command should be run from the root `console-subscriber` directory and requires the `grpc-web` feature flag to be enabled. ```sh cargo run --example grpc_web --features grpc-web ``` -------------------------------- ### Start Web Application Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/app/README.md Starts the web application development server using npm. This command should be run from the `console-subscriber/examples/grpc_web/app` directory. ```sh npm run dev ``` -------------------------------- ### Install Node.js Dependencies Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/README.md Installs all necessary dependencies for the web application using npm. This command should be run from the `console-subscriber/examples/grpc_web/app` directory. ```sh npm install ``` -------------------------------- ### Developing with Tokio Console Examples Source: https://github.com/tokio-rs/console/blob/main/README.md Information on how to execute example programs provided within the console-subscriber/examples directory for development purposes. ```shell cargo run --example $name ``` -------------------------------- ### Rust: Tokio Timeout::new Example Source: https://github.com/tokio-rs/console/blob/main/CONTRIBUTING.md Presents a documentation test for Tokio's `Timeout::new` constructor. This example explicitly uses the `Timeout::new` function to wrap a future, showcasing a different approach to applying timeouts and highlighting the use of hidden lines for test setup. ```rust /// use tokio::timer::Timeout; /// use futures::Future; /// use futures::sync::oneshot; /// use std::time::Duration; /// /// # fn main() { /// let (tx, rx) = oneshot::channel(); /// # tx.send(()).unwrap(); /// /// # tokio::runtime::current_thread::block_on_all( /// // Wrap the future with a `Timeout` set to expire in 10 milliseconds. /// Timeout::new(rx, Duration::from_millis(10)) /// # ).unwrap(); /// # } /// ``` -------------------------------- ### Install tokio-console CLI Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Installs the tokio-console command-line interface using Cargo. The `--locked` flag ensures that the exact versions specified in the Cargo.lock file are used. ```shell cargo install --locked tokio-console ``` -------------------------------- ### Generate gRPC Code Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/app/README.md Generates gRPC code using the `buf` tool, as specified in the project's scripts. This command is used to create the necessary client code for gRPC communication from the protobuf definitions. ```sh npm run gen ``` -------------------------------- ### Generate gRPC Code Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/examples/grpc_web/README.md Generates gRPC code using the `buf` tool, as specified in the project's scripts. This command is used to create the necessary client code for gRPC communication from the protobuf definitions. ```sh npm run gen ``` -------------------------------- ### Run tokio-console (default connection) Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Starts the tokio-console CLI, connecting to an instrumented application on localhost listening on the default port (6669). ```shell tokio-console ``` -------------------------------- ### Install Tokio Console Source: https://github.com/tokio-rs/console/blob/main/README.md Installs the tokio-console command-line tool from crates.io using Cargo. The `--locked` flag ensures that the exact versions specified in the lock file are used. ```shell cargo install --locked tokio-console ``` -------------------------------- ### Run tokio-console (custom target address) Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Starts the tokio-console CLI, connecting to an instrumented application at a specified target address, which can be an IP address or a DNS name with a port. ```shell tokio-console http://192.168.0.42:9090 ``` ```shell tokio-console http://my.instrumented.application.local:6669 ``` -------------------------------- ### Run Tokio Console Locally Source: https://github.com/tokio-rs/console/blob/main/README.md Executes the tokio-console tool from a local checkout of the repository. This is an alternative to installing it from crates.io. ```shell cargo run ``` -------------------------------- ### Rust: Tokio Timeout Example with FutureExt::timeout Source: https://github.com/tokio-rs/console/blob/main/CONTRIBUTING.md Demonstrates a documentation test for Tokio's `FutureExt::timeout` trait. It shows how to wrap a future with a timeout and includes hidden lines (`/// #`) necessary for the test to compile and run, illustrating common patterns for testing asynchronous operations. ```rust /// // import the `timeout` function, usually this is done /// // with `use tokio::prelude::*` /// use tokio::prelude::FutureExt; /// use futures::Stream; /// use futures::sync::mpsc; /// use std::time::Duration; /// /// # fn main() { /// let (tx, rx) = mpsc::unbounded(); /// # tx.unbounded_send(()).unwrap(); /// # drop(tx); /// /// let process = rx.for_each(|item| { /// // do something with `item` /// # drop(item); /// # Ok(()) /// }); /// /// # tokio::runtime::current_thread::block_on_all( /// // Wrap the future with a `Timeout` set to expire in 10 milliseconds. /// process.timeout(Duration::from_millis(10)) /// # ).unwrap(); /// # } /// ``` -------------------------------- ### Initialize Tokio Console Subscriber (Rust) Source: https://github.com/tokio-rs/console/blob/main/README.md Adds the `console-subscriber` crate and initializes it with a single line of code in the `main` function. This is the primary step to start collecting telemetry data from your Tokio application. ```rust console_subscriber::init(); ``` -------------------------------- ### Running Tokio Console on Windows Source: https://github.com/tokio-rs/console/blob/main/README.md Instructions for running the Tokio Console on Windows, emphasizing the need for a UTF-8 enabled terminal and the correct command-line flag. ```shell # Ensure you are using a UTF-8 enabled terminal like Windows Terminal tokio-console --lang en_US.UTF-8 ``` -------------------------------- ### Tokio Console CLI Help Source: https://github.com/tokio-rs/console/blob/main/README.md Displays the help message for the Tokio console command-line interface, outlining its usage, available commands, arguments, and options. ```APIDOC Tokio Console CLI: Usage: tokio-console[EXE] [OPTIONS] [TARGET_ADDR] [COMMAND] The Tokio console: a debugger for async Rust. Commands: gen-config Generate a `console.toml` config file with the default configuration values, overridden by any provided command-line arguments gen-completion Generate shell completions help Print this message or the help of the given subcommand(s) Arguments: [TARGET_ADDR] The address of a console-enabled process to connect to. This may be an IP address and port, or a DNS name. On Unix platforms, this may also be a URI with the `file` scheme that specifies the path to a Unix domain socket, as in `file://localhost/path/to/socket`. When the `vsock` feature is enabled, this may also be a URI with the `vsock` scheme that specifies a vsock connection, as in `vsock://2:6669` to connect to CID 2 port 6669. [default: http://127.0.0.1:6669] Options: --log Log level filter for the console's internal diagnostics. Logs are written to a new file at the path given by the `--log-dir` argument (or its default value), or to the system journal if `systemd-journald` support is enabled. If this is set to 'off' or is not set, no logs will be written. [default: off] [env: RUST_LOG=] -W, --warn ... Enable lint warnings. This is a comma-separated list of warnings to enable. Each warning is specified by its name, which is one of: * `self-wakes` -- Warns when a task wakes itself more than a certain percentage of its total wakeups. Default percentage is 50%. * `lost-waker` -- Warns when a task is dropped without being woken. * `never-yielded` -- Warns when a task has never yielded. * `auto-boxed-future` -- Warnings when the future driving a task was automatically boxed by the runtime because it was large. * `large-future` -- Warnings when the future driving a task occupies a large amount of stack space. [default: self-wakes lost-waker never-yielded auto-boxed-future large-future] [possible values: self-wakes, lost-waker, never-yielded, auto-boxed-future, large-future] -A, --allow ... Allow lint warnings. This is a comma-separated list of warnings to allow. Each warning is specified by its name, which is one of: * `self-wakes` -- Warns when a task wakes itself more than a certain percentage of its total wakeups. Default percentage is 50%. * `lost-waker` -- Warns when a task is dropped without being woken. * `never-yielded` -- Warns when a task has never yielded. * `auto-boxed-future` -- Warnings when the future driving a task was automatically boxed by the runtime because it was large. * `large-future` -- Warnings when the future driving a task occupies a large amount of stack space. If this is set to `all`, all warnings are allowed. [possible values: all, self-wakes, lost-waker, never-yielded, large-future, auto-boxed-future] --log-dir Path to a directory to write the console's internal logs to. [default: /tmp/tokio-console/logs] --lang Overrides the terminal's default language [env: LANG=en_US.UTF-8] --ascii-only ``` -------------------------------- ### Tokio Resource Monitoring APIs Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Information on Rust APIs related to synchronization primitives and timers that are instrumented and displayed as resources by Tokio Console. ```APIDOC tokio::sync: Module containing synchronization primitives like Mutex, Semaphore, etc. Instances of these types are displayed as 'Sync' resources. tokio::sync::Mutex: A mutual exclusion primitive. Instrumented resources will show 'Sync' kind and 'Mutex' type. tokio::time: Module for time-related utilities, including timers and sleeps. Instances like `tokio::time::Sleep` are displayed as 'Timer' resources. tokio::time::Sleep: A timer that elapses after a specified duration. Instrumented resources will show 'Timer' kind and 'Sleep' type, potentially with a 'duration' attribute. ``` -------------------------------- ### Pull Request Process Source: https://github.com/tokio-rs/console/blob/main/CONTRIBUTING.md Details the steps and considerations for opening, discussing, and updating pull requests within the tokio-rs/console project. ```APIDOC Pull Request Process: 1. **Opening a Pull Request**: - Use the GitHub web UI. - Follow commit message guidelines for title and description. 2. **Discuss and Update**: - Expect feedback and requests for changes. - Community members can review PRs; conflicting feedback is possible. - Look for comments from code owners for guidance. - **Do not rebase commits once the PR is open**. 3. **Commit Squashing**: - Generally, do not squash commits added during review. - Commits may be squashed into one per logical change upon landing. - Metadata (PR links, issue links, reviewer names) will be added. ``` -------------------------------- ### Tokio Console CLI Navigation Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Key bindings and actions for navigating and interacting with the Tokio Console CLI interface. ```cli ↑ / ↓: Navigate up/down through the list of tasks or resources. enter: When a task is highlighted, displays detailed information about that task. When a resource is highlighted, displays detailed information about that resource. r: Switch the view from the task list to the resource list. t: Switch the view from the resource list back to the task list. escape: When viewing task details, returns to the task list. ``` -------------------------------- ### Console Wire Protocol API Documentation Source: https://github.com/tokio-rs/console/blob/main/README.md Documentation for the console wire protocol, defining the gRPC and Protocol Buffer specifications used for streaming diagnostic data from instrumented applications to diagnostic tools. ```APIDOC Console Wire Protocol: - Defines a wire protocol for streaming diagnostic data. - Uses gRPC and Protocol Buffers for efficient transport and interoperability. - The `console-api` crate contains generated code for the wire format using `tonic`. - Projects can depend on the protobuf definitions directly for other gRPC implementations. Key Components: - Wire Protocol Definition: Specifies the data format and communication methods. - Instrumentation: Crates like `console-subscriber` implement `tracing-subscriber` Layers to collect data. - Diagnostic Tools: Clients (e.g., `tokio-console` CLI) consume data over the wire protocol. Related Crate: - `console-api`: Contains generated code for the wire format. - `console-subscriber`: Implements instrumentation as a `tracing-subscriber` Layer. - `tokio-console`: Implements an interactive command-line tool. ``` -------------------------------- ### Tokio Task Monitoring APIs Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Details on Rust APIs used for instrumenting and identifying asynchronous tasks within the Tokio runtime, as displayed by Tokio Console. ```APIDOC tokio::task::Id: Represents the unique identifier for an asynchronous task. Used to reference tasks within the Tokio runtime and the console. tokio::task::Builder::name(name: &str): Sets a human-readable name for a spawned task. This name is displayed in the 'Name' column of the task list. tokio::task::spawn_blocking(future: F) -> JoinHandle where F: FnOnce() -> T + Send + 'static, T: Send + 'static: Spawns a blocking task onto the Tokio runtime. These tasks are distinguished in the console's 'Target' column as 'tokio::task::blocking'. ``` -------------------------------- ### Rust Instrumentation with tracing-subscriber Source: https://github.com/tokio-rs/console/blob/main/README.md Details on how to instrument asynchronous Rust programs using the `console-subscriber` crate, which acts as a `tracing-subscriber` Layer to collect diagnostic data. ```Rust use console_subscriber::ConsoleSubscriber; use tracing_subscriber::layer::Layer; // Example of setting up the console subscriber as a tracing Layer // This requires a Tokio runtime and the `tracing` crate. // fn main() { // let subscriber = tracing_subscriber::registry() // .with(tracing_subscriber::fmt::layer()) // .with(ConsoleSubscriber::default()); // // tracing::subscriber::set_global_default(subscriber).unwrap(); // // // Your async application logic here... // } ``` -------------------------------- ### tokio-console API Overview and console-api Crate Source: https://github.com/tokio-rs/console/blob/main/console-api/README.md Provides an overview of the tokio-console system, which is a debugging and profiling tool for asynchronous Rust applications. It details the role of the console-api crate, which contains generated protobuf bindings for the wire format used by both instrumentation (console-subscriber) and consumers of telemetry data. It also covers API stability and the project's relationship with Tonic. ```APIDOC tokio-console API This crate contains generated [protobuf] bindings for the [`tokio-console`] wire format. The wire format is used to export diagnostic data from instrumented applications to consumers that aggregate and display that data. [`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, receive telemetry data, and display it to the user The wire format [protobuf] bindings in this crate are used by both the instrumentation in the [`console-subscriber`] crate, which emits telemetry in this format, and by the clients that consume that telemetry. In general, most [`tokio-console`] users will *not* depend on this crate directly. Applications are typically instrumented using the [`console-subscriber`] crate, which collects data and exports it using this wire format; this data can be consumed using the [`tokio-console`] command-line application. However, the wire format API definition in this crate may be useful for anyone implementing other software that also consumes the [`tokio-console`] diagnostic data. Stability: ⚠️ The protobuf wire format is not currently considered totally stable. While we will try to avoid unnecessary protobuf-incompatible changes, protobuf compatibility is only guaranteed within SemVer-compatible releases of this crate. For example, the protobuf as of `console-api` v0.2.5 may not be backwards-compatible with `console-api` v0.1.12. ``` -------------------------------- ### Tokio Console CLI Arguments Source: https://github.com/tokio-rs/console/blob/main/README.md This section details the various command-line arguments available for the tokio-console CLI tool. It covers options for controlling color output, terminal features, and data retention periods. ```APIDOC Tokio Console CLI Options: --no-colors Disable ANSI colors entirely. --colorterm Overrides the value of the `COLORTERM` environment variable. If this is set to `24bit` or `truecolor`, 24-bit RGB color support will be enabled. [env: COLORTERM=truecolor] [possible values: 24bit, truecolor] --palette Explicitly set which color palette to use. [possible values: 8, 16, 256, all, off] --no-duration-colors Disable color-coding for duration units. [possible values: true, false] --no-terminated-colors Disable color-coding for terminated tasks. [possible values: true, false] --retain-for How long to continue displaying completed tasks and dropped resources after they have been closed. This accepts either a duration, parsed as a combination of time spans (such as `5days 2min 2s`), or `none` to disable removing completed tasks and dropped resources. Each time span is an integer number followed by a suffix. Supported suffixes are: * `nsec`, `ns` -- nanoseconds * `usec`, `us` -- microseconds * `msec`, `ms` -- milliseconds * `seconds`, `second`, `sec`, `s` * `minutes`, `minute`, `min`, `m` * `hours`, `hour`, `hr`, `h` * `days`, `day`, `d` * `weeks`, `week`, `w` * `months`, `month`, `M` -- defined as 30.44 days * `years`, `year`, `y` -- defined as 365.25 days [default: 6s] -h, --help Print help (see a summary with '-h'). -V, --version Print version. ``` -------------------------------- ### Pull Request Review Guidelines Source: https://github.com/tokio-rs/console/blob/main/CONTRIBUTING.md Establishes principles for reviewers to provide helpful, insightful feedback that aims to improve contributions and support contributors' success. ```APIDOC Reviewer Responsibilities: - **Welcome All Reviewers**: - Any Tokio community member can review. - **Reviewer Goals**: - Provide helpful, insightful feedback. - Improve the contribution. - Support the contributor's success. - Explain reasons for rejection; do not block without explanation. - Be open to changing your mind and collaborating. - **Code of Conduct**: - Reviews must be respectful and not dismissive. - **Outcome**: - Even if a PR does not land, contributors should feel their effort was valued. ``` -------------------------------- ### Enable Tokio Tracing Dependency Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/README.md Specifies how to enable Tokio's optional `tracing` dependency in `Cargo.toml` to ensure compatibility with `tokio-console`. This is a prerequisite for instrumenting your application. ```toml [dependencies] # ... tokio = { version = "1.15", features = ["full", "tracing"] } ``` -------------------------------- ### Supported Rust Versions Source: https://github.com/tokio-rs/console/blob/main/console-api/README.md Specifies the minimum supported Rust version for the Tokio console project. ```APIDOC Supported Rust Versions: The Tokio console is built against the latest stable release. The minimum supported version is 1.64. The current Tokio console version is not guaranteed to build on Rust versions earlier than the minimum supported version. ``` -------------------------------- ### Initialize Tokio Console Subscriber Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/README.md Adds the console subscriber as the default tracing subscriber, enabling console telemetry and logging to stdout based on the RUST_LOG environment variable. ```rust console_subscriber::init(); ``` -------------------------------- ### Combine Console Subscriber with Other Tracing Layers Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/README.md Demonstrates how to combine the console subscriber layer with other tracing layers, such as the formatting layer, to build a custom tracing subscriber. ```rust 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(); ``` -------------------------------- ### Run tokio-console on Windows with UTF-8 Source: https://github.com/tokio-rs/console/blob/main/tokio-console/README.md Executes the tokio-console CLI on Windows, explicitly setting the language flag to ensure proper UTF-8 character display for terminal UI elements. ```shell tokio-console --lang en_US.UTF-8 ``` -------------------------------- ### Configure Tokio Console Subscriber with Builder Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/README.md Programmatically configures the console subscriber using a builder interface. Allows setting retention duration for completed tasks and the server address for the console. ```rust 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(); ``` -------------------------------- ### Run Tokio Console with Custom Target Source: https://github.com/tokio-rs/console/blob/main/README.md Runs the tokio-console tool, specifying a custom target address for the instrumented application. This allows connecting to applications running on different hosts or ports. ```shell cargo run -- http://my.great.console.app.local:5555 ``` -------------------------------- ### Configure Tracing Targets for Tokio Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/README.md Ensures that the `tokio` and `runtime` tracing targets are enabled at the `TRACE` level. This is crucial for `console-subscriber` to collect necessary telemetry data. If using manual subscriber configuration, add `"tokio=trace,runtime=trace"` to your filter. ```rust // If using console_subscriber::init() or Builder, these are enabled automatically. // If manually configuring tracing-subscriber with EnvFilter or Targets: // Add "tokio=trace,runtime=trace" to your filter configuration. ``` -------------------------------- ### Enable tokio_unstable cfg Flag Source: https://github.com/tokio-rs/console/blob/main/console-subscriber/README.md Enables the `tokio_unstable` configuration flag, which is required for experimental APIs in Tokio, including those used by `console-subscriber`. This can be set via the `RUSTFLAGS` environment variable or a `.cargo/config.toml` file. ```shell $ RUSTFLAGS="--cfg tokio_unstable" cargo build ``` ```toml [build] rustflags = ["--cfg", "tokio_unstable"] ``` -------------------------------- ### Enable Tokio Unstable Feature (TOML) Source: https://github.com/tokio-rs/console/blob/main/README.md Configures the `tokio_unstable` feature globally for Cargo builds by adding the `rustflags` setting to the `.cargo/config.toml` file. This provides an alternative to setting the `RUSTFLAGS` environment variable for every build. ```toml [build] rustflags = ["--cfg", "tokio_unstable"] ``` -------------------------------- ### console-api Crate Feature Flags Source: https://github.com/tokio-rs/console/blob/main/console-api/README.md Lists and describes the available feature flags for the console-api crate, which can be used to customize code generation and compatibility. ```APIDOC Crate Feature Flags: * `transport`: Generate code that is compatible with [Tonic]'s [`transport` module] (disabled by default) ``` -------------------------------- ### Enable Tokio Unstable Feature (Shell) Source: https://github.com/tokio-rs/console/blob/main/README.md Builds the Rust project with the `tokio_unstable` configuration flag enabled using the `RUSTFLAGS` environment variable. This flag is necessary for Tokio to collect task data, which is then used by the console subscriber. ```shell RUSTFLAGS="--cfg tokio_unstable" cargo build ``` -------------------------------- ### Git Commit Message Format Source: https://github.com/tokio-rs/console/blob/main/CONTRIBUTING.md Defines the standard format for Git commit messages used in this project. It specifies a header (type, scope, subject), an optional body, and an optional footer, with a strict 72-character limit per line to ensure readability and facilitate automated changelog generation. ```sh git commit message format: ```sh ():