tokio-rs/console

This system is the Tokio Console, a diagnostic tool for observing and instrumenting the Tokio async runtime in Rust applications. It consists of a subscriber library that captures runtime events like task lifecycles and resource states, and a CLI interface that visualizes this data in real-time via a terminal UI. The system supports remote inspection over various transports and provides detailed metrics on polling, scheduling, and synchronization primitives to help developers identify performance issues and misbehaving tasks.

10 changes.

This period established the project's foundational structure, including documentation, licensing, and a Nix-based build environment. It introduced the core Tokio Console API protocol definitions and the console-subscriber instrumentation layer, enabling real-time observation of async runtime events. The work also involved upgrading dependencies to Tonic 0.14 and refactoring the codebase to support the new gRPC-based architecture.

11 changes.

The Tokio Console underwent a major architectural and interface overhaul, migrating its terminal UI to ratatui and introducing comprehensive tracking for asynchronous operations and poll-time histograms. This period also focused on strengthening developer tooling and reliability through new protobuf generation utilities, integration tests for the subscriber, and expanded connection support including vsock and gRPC-web.

This change introduces the complete set of Protocol Buffers (proto3) definitions for the Tokio Console API, establishing the contract for observing and instrumenting the Tokio async runtime. The new files define the core data models for tasks, resources, and async operations, including their lifecycle states, performance statistics (such as poll counts, busy time, and scheduled durations), and source code locations. It also specifies the gRPC services used by the console observer to stream real-time updates (WatchUpdates, WatchTaskDetails, WatchState) and trace events, along with support for pausing/resuming streams and handling dropped events when the instrumentation buffer is full.

console-api/proto · high confidence

This change establishes the foundational structure of the repository by adding essential project documentation and configuration files. It introduces a Code of Conduct, a detailed Contributing guide, a Security policy, and the MIT License. The README is added to describe the Tokio Console as a diagnostic tool for async Rust, including usage instructions for instrumentation and the CLI. Additionally, the build and development environment is configured with a new Nix flake (replacing the legacy shell.nix/default.nix), a cargo-dist workspace configuration for releases, a git-cliff changelog configuration, and a Netlify setup for automatic API documentation publishing.

(repo-wide) · high confidence

Adds the \console-subscriber\ crate, providing a \ConsoleLayer\ that captures Tokio runtime events (spawns, polls, wakers, resources) and exports them via a gRPC server. This enables users to connect the \tokio-console\ CLI to inspect task lifecycles, poll durations, and resource states in real-time. The implementation includes a configurable \Builder\ for tuning buffer capacities and retention, a \Recorder\ for saving event streams to JSON files, and support for various transport addresses including TCP, Unix domain sockets, and vsock.

console-subscriber/src · high confidence

The project now includes a Nix-based build system for the tokio-console component. This introduces a package definition (nix/tokio-console.nix) that builds the Rust application using the standard rustPlatform, respecting Cargo.lock for reproducible builds and filtering out non-source files via gitignore. Additionally, a development shell (nix/shell.nix) is provided, which configures the environment with necessary build inputs, sets RUST\_SRC\_PATH for IDE support, and enables consistent terminal coloring and backtraces.

nix · high confidence

The \console-subscriber\ now includes a new \aggregator\ module (located in \src/aggregator\) that manages the collection and transmission of instrumentation data. This module introduces \ShrinkMap\ and \ShrinkVec\ collections that automatically shrink their underlying capacity when entries are removed, preventing memory bloat from retained historical data. It implements an \IdData\ structure to track tasks, resources, and async operations, applying configurable retention periods to drop closed entities while respecting client watchers. The aggregator also handles timestamp anchoring for monotonic time conversion and manages the flow of updates to connected clients via gRPC streams.

console-subscriber/src/aggregator · high confidence

The examples directory now includes a comprehensive suite of demonstration applications to help users understand and debug Tokio runtime behavior via the console. The new \app\ example serves as a versatile diagnostic tool, allowing users to spawn misbehaving tasks (such as blocking, burning CPU, or failing to yield) via CLI flags to observe their impact. Additional examples cover specific synchronization primitives (\mutex\, \rwlock\, \semaphore\, \barrier\) and local tasks, while \uds\ demonstrates serving the console API over Unix domain sockets. Finally, \long\_scheduled\ and \long\_sleep\ illustrate how to identify tasks with excessive scheduled times or long sleep durations, and \dump\ provides a standalone client to stream instrumentation data.

console-subscriber/examples · high confidence

Added a new gRPC-web example application under \console-subscriber/examples/grpc\_web\ that demonstrates how to connect a web browser to the Tokio console server. The example includes a React-based frontend using the \connect-es\ library to subscribe to runtime updates via the \WatchUpdates\ RPC, along with the necessary build configuration (buf, ESLint, Prettier) and generated TypeScript protocol buffer code to facilitate this communication.

_console-subscriber/examples/grpc\web · high confidence

A new \xtask\ tool has been added to the project, providing two developer-focused commands: \gen-proto\ to generate \console-api\ protobuf bindings from source \.proto\ files, and \check-docs-images\ to verify that image assets referenced in the tokio-console README actually exist on disk. This change introduces a new entry point for build-time tasks but does not alter the runtime behavior of the console itself.

xtask · high confidence

The \proto/trace.proto\ file, which defined the \rs.tokio.console.trace\ package and the \Trace\ service for watching trace events (including thread registration, span metadata, and span lifecycle events), has been deleted. This change removes the protocol buffer definitions for the previous in-process tracing model, indicating a shift away from this specific API surface.

proto · high confidence

The internal state architecture for tokio-console has been refactored to use a new generic \Store\ type that manages sequential IDs and visibility, replacing the previous implementation. This change introduces a new \AsyncOpsState\ module to track and display asynchronous operations (including dropped event counts) alongside the existing tasks and resources views. Additionally, a new \DurationHistogram\ component has been added to parse and display poll-time histograms, enabling users to visualize task scheduling and polling distributions.

tokio-console/src/state · high confidence

The console-api library has been restructured to replace inline protocol buffer definitions with generated modules (async\_ops, common, instrument, resources, tasks, trace), improving code organization. A key behavioral change is that tracing metadata now includes field names when sent over the wire, allowing clients to see structured field data rather than just values. Additionally, the conversion from tracing\_core metadata to the API's internal representation now uses non-exhaustive matching for metadata kinds to ensure compatibility across different versions of the tracing\_core library, preventing potential panics or warnings on newer compiler versions.

console-api/src · high confidence

The generated Rust code in \console-api/src/generated\ has been updated to reflect the upgrade of the \tonic\ dependency to version 0.13. This regeneration ensures that the gRPC client and server stubs, along with the message definitions for tasks, resources, async operations, and tracing, remain compatible with the new Tonic version.

console-api/src/generated · high confidence

The Tokio Console CLI now supports connecting to remote processes via Unix domain sockets (using \file://\ URIs) and vsock connections (using \vsock://\ URIs), in addition to standard HTTP/HTTPS. Users can configure the console via a TOML config file or command-line arguments, with a new \gen-config\ subcommand to generate a default configuration. The UI, migrated to \ratatui\ and \crossterm\, now displays dropped event counts for tasks, resources, and async ops, and includes a help view modal. Several lint warnings are now available, including \self-wakes\, \lost-waker\, \never-yielded\, \auto-boxed-future\, and \large-future\, which can be enabled or disabled via \--warn\ and \--allow\ flags. The \retain\_for\ setting for keeping completed tasks in the view now defaults to 6 seconds if not specified. Key release and repeat events are now ignored to prevent duplicate input on Windows.

tokio-console/src · high confidence

The Tokio Console terminal interface has been rebuilt using the ratatui library, replacing the previous TUI backend. This change introduces new views for inspecting async operations and resources, including a dedicated table for async ops that displays parent, task, source, and duration metrics. A new help modal provides on-screen keyboard shortcuts, and a unified controls widget displays available actions across all views. Duration data is now visualized using a new mini-histogram widget alongside percentile statistics, and the resource view allows drilling down into specific resource details and their associated async operations.

tokio-console/src/view · high confidence

The Windows installer (main.wxs) has been updated to include a component that adds the installation's bin directory to the system PATH environment variable. This allows users to run the tokio-console executable from any location in the command line without needing to manually configure their environment variables.

tokio-console/wix · high confidence

The console-api crate has been updated to version 0.9.0, which includes a breaking upgrade of the public \tonic\ dependency to version 0.14 (breaking compatibility with 0.13.x) and introduces a new WatchState API. Additionally, the crate's build process has been simplified by removing the custom \build.rs\ script, likely relying on standard procedural macro or generated code mechanisms instead.

console-api · high confidence

Added CLI UI tests for tokio-console; Added integration test support for console-subscriber; Added integration tests for console-subscriber task polling and waking behavior; Added test to verify protobuf generation consistency.

The Tokio Console toolchain has been upgraded to use Tonic 0.14.2 and Prost 0.14.1, replacing the previous 0.4/0.7 versions, and the minimum supported Rust version (MSRV) for all components (console-api, console-subscriber, tokio-console, and xtask) has been raised to Rust 1.88.0. This update also includes a comprehensive dependency refresh across the workspace, such as updating clap to 4.5.4, ratatui to 0.30.2, and crossterm to 0.29.0, while adding a new xtask crate for build automation and configuring the workspace for cargo-dist releases.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 66 → 67 (+0.7)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 89 → 89 (+0.0)
• Architecture 100 → 97 (-3.0)
• Maturity 58 → 58 (+0.1)
• Readiness 64 → 64 (-0.4)
• Security 70 → 76 (+6.1)
• Performance 100 (new)

• Dependency hygiene PARTLY measured — npm pinning read, dependency currency not (no pnpm-resolved versions to grade)
• Documentation: no architecture or design documentation
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (console-subscriber/examples/grpc_web/README.md)
• Hotspot: tokio-console/src/view/mini_histogram.rs (tokio-console/src/view/mini_histogram.rs)

• Inconsistent and confusing method naming/signatures. serve_with and serve_with_grpc_web take a builder: Server as an argument, which is semantically incorrect (a server does not take another server as a builder). It is likely these methods are meant to configure the server before serving, but the signature suggests passing a server instance. Additionally, having serve, serve_with, and serve_with_grpc_web on the same type creates ambiguity about which one to use and what the 'with' variants actually do differently if not via the confusingly named parameter.
• Inverted test pyramid
• Outdated: cfg-if
• Outdated: clap
• Outdated: clap_complete
• Outdated: crossbeam-channel
• Outdated: crossbeam-utils
• Outdated: futures
• Outdated: futures-core
• Outdated: futures-task
• Outdated: h2
• Outdated: hdrhistogram
• Outdated: humantime
• Outdated: hyper-util
• Outdated: once_cell
• Outdated: parking_lot
• Outdated: prost
• Outdated: prost-types
• Outdated: regex
• Outdated: serde
• …and 13 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

tokio-rs/console was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.