console-subscriber

console-subscriber is the instrumentation half of tokio-console, a diagnostics and debugging toolkit for asynchronous Rust programs. It implements a tracing_subscriber::Layer that collects task, resource, and runtime diagnostic data from a running Tokio application and streams it over a gRPC wire protocol to the companion tokio-console command-line client — effectively giving async Rust programs a top(1)-like live view of their tasks.

Adding console_subscriber::init() to an application’s main function (with the tokio_unstable cfg flag enabled) exposes task polling, wakeups, and resource data that the separate tokio-console CLI tool then visualizes interactively, without requiring custom instrumentation code in application logic.

What You Get

• console_subscriber::init() — a one-line setup to start streaming diagnostic data from a Tokio application
• A configurable Builder API for customizing retention, bind address, and recording behavior
• An in-process aggregator that tracks task polls, wakeups, spawns, and resource lifecycles
• A gRPC server (via the console-api/tonic wire protocol) that the tokio-console CLI connects to
• Built-in lint-style warnings (self-wakes, lost wakers, never-yielded tasks, auto-boxed/large futures) surfaced through the CLI

Common Use Cases

• Diagnosing why an async Rust service is dropping frames, stalling, or spending time on unexpectedly costly tasks
• Finding tasks that never yield, hold locks too long, or wake themselves excessively (self-wake loops)
• Getting a live top(1)-style view of all running Tokio tasks in a production or development process
• Auditing runtime health of a Tokio-based application without modifying its business logic

Under The Hood

Architecture — console-subscriber is one of three crates in the tokio-rs/console workspace: console-api (generated gRPC/protobuf types for the wire protocol), console-subscriber (this package — the instrumentation-side tracing_subscriber::Layer), and tokio-console (the interactive CLI client). Inside console-subscriber/src, an aggregator module maintains in-memory task/resource state built from tracing callsite events (callsites.rs, visitors.rs, attribute.rs), which builder.rs wires into a gRPC server exposed to remote tokio-console clients over the protocol defined in console-api.

Tech Stack — Rust (82.5% of the overall repo, the remainder mostly TypeScript for the docs/website), built on tracing/tracing-subscriber for instrumentation hooks, tonic/prost for the gRPC wire format, and Tokio itself as the async runtime being instrumented. Requires the nightly-only tokio_unstable cfg flag on the instrumented application since it depends on Tokio’s unstable diagnostic APIs.

Code Quality — console-subscriber/tests contains integration tests (framework.rs, poll.rs, spawn.rs, wake.rs) exercising the aggregator against realistic task-lifecycle scenarios, backed by a support test-helper module. The workspace uses release-plz and cliff.toml for changelog/release automation and ships a SECURITY.md disclosure policy, indicating disciplined release and security practices for a project embedded in the official Tokio organization.

API Design — The single-call console_subscriber::init() entrypoint minimizes integration friction for the common case, while the Builder API exposes finer-grained configuration (retention window, bind address) for production deployments. The unavoidable requirement to recompile with RUSTFLAGS="--cfg tokio_unstable" is an explicit tradeoff the project accepts in exchange for access to Tokio’s richer, unstable instrumentation hooks rather than a slower-evolving stable API.