百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
C

channels-console

> 编程语言
开源

对 Rust 通道的实时监控、指标和日志。现已与 https://hotpath.rs 集成

369 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

对 Rust 通道的实时监控、指标和日志。现已与 https://hotpath.rs 集成

channels-console

The codebase has been integrated into hotpath. Further updates and enhancements will continue in the new repository.

A lightweight, easy-to-use tool for real-time visibility into your Rust channels and streams. Inspect live message contents and observe how channels interact to better understand data flow. Track queue depth, delay, throughput, and memory usage to spot channel-related issues.

Supports std::sync, Tokio, futures-rs, and crossbeam channels, plus any type implementing the futures::Stream trait.

Features

  • Zero-cost when disabled — fully gated by a feature flag
  • Minimal configuration - just one channel! or stream! macro to start collecting metrics
  • Detailed stats - per channel/stream status, sent/received messages, queue capacity, and memory usage
  • Background processing - minimal profiling impact
  • Live monitoring - view metrics in a clear, real-time TUI dashboard (built with ratatui.rs)

Getting started

Cargo.toml

toml
channels-console = { version = "0.3", optional = true, features=['tokio', 'futures', 'crossbeam'] }

[features]
channels-console = ["dep:channels-console"]

This config ensures that the lib has zero overhead unless explicitly enabled via a channels-console feature.

std::sync channels can be instrumented by default. Enable tokio, futures, or crossbeam features for Tokio, futures-rs, and crossbeam channels, respectively.

Instrumenting Channels

Use the channel! macro to monitor selected channels:

rust
let (tx1, rx1) = tokio::sync::mpsc::channel::(10);
#[cfg(feature = "channels-console")]
let (tx1, rx1) = channels_console::channel!((tx1, rx1));

let (mut txb, mut rxb) = futures_channel::mpsc::channel::(10);
#[cfg(feature = "channels-console")]
let (mut txb, mut rxb) = channels_console::channel!((txb, rxb), capacity = 10);

Futures and std::sync bounded channels don't provide an API exposing their size, so you have to provide capacity to the channel! macro.

Instrumenting Streams

Use the stream! macro to monitor any type implementing the Stream trait:

rust
use futures::stream::{self, StreamExt};

let s = stream::iter(1..=10);
#[cfg(feature = "channels-console")]
let s = channels_console::stream!(s, label = "my-stream");

let items: Vec = s.collect().await;

This is the only change you have to do in your codebase. Both macros return exactly the same types so they remain 100% compatible.

Now, install channels-console TUI:

bash
cargo install channels-console --features=tui

Execute your program with --features=channels-console:

bash
cargo run --features=channels-console

In a different terminal run channels-console CLI to start the TUI and see live usage metrics:

bash
channels-console

Quickstart demo guide

  1. Install CLI:
bash
cargo install channels-console --features=tui
  1. Clone this repo:
bash
git clone [email protected]:pawurb/channels-console.git
  1. Run console_feed example:
bash
cd channels-console
cargo run --example console_feed_tokio --features=channels-console
  1. Run TUI (in a different terminal):
bash
channels-console

How it works?

The channel! macro wraps channels with lightweight proxies that transparently forward all messages while collecting real-time statistics. Each send and recv operation passes through a monitored proxy channel that emits updates to a background metrics system.

The stream! macro wraps streams and tracks items as they are yielded, collecting statistics about throughput and completion.

In the background, an HTTP server process exposes gathered metrics in a JSON format, allowing the TUI process to display them in the interface.

A note on accuracy

channels-console instruments proxy channels that wrap your actual channel instances. It observes messages as they pass through these proxies rather than when they are finally consumed. As a result, the displayed metrics are an approximation of real channel activity - useful for debugging and diagnosing flow issues, but not a 100% accurate source of truth for production monitoring.

Because of this proxy design, each bounded channel is effectively represented by three layers - the outer proxy, the original channel, and the inner proxy. In practice, this triples the total buffering capacity. For the same reason, it's currently not possible to measure the queue size of unbounded channels. Even with a slow consumer, the intermediate proxies will immediately absorb all incoming messages, masking true backlog behavior.

That said, since the proxy layer introduces virtually no overhead compared to direct channel usage, timing and delay metrics should remain accurate. Logged messages contents and ordering is also 100% accurate.

Current design intentionally sacrifices accuracy for the ease of integration - you can instrument channels with minimal code changes and still get meaningful visibility into their behavior.

There be bugs

This library has just been released. I've tested it with several apps, big and small, and it consistently produced reliable metrics. However, please note that enabling monitoring can subtly affect channel behavior in some cases. For example, using try_send may not return an error as expected, since the proxy layers effectively increase total capacity. I'm actively improving the library, so any feedback, issues, bug reports are appreciated.

API

Supported Channel Types

std::sync Channels

  • std::sync::mpsc::channel
  • std::sync::mpsc::sync_channel

Tokio Channels

  • tokio::sync::mpsc::channel
  • tokio::sync::mpsc::unbounded_channel
  • tokio::sync::oneshot::channel

Futures Channels

  • futures_channel::mpsc::channel
  • futures_channel::mpsc::unbounded
  • futures_channel::oneshot::channel

Crossbeam Channels

  • crossbeam_channel::bounded
  • crossbeam_channel::unbounded

Streams

  • Any type implementing futures_util::Stream

I'm planning to support more channel types. PRs are welcome!

channel! Macro

The channel! macro is the primary way to monitor channels. It wraps channel creation expressions and returns instrumented versions that collect metrics.

Basic Usage:

rust
use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    // Create channels normally
    let (tx, rx) = mpsc::channel::(100);

    // Instrument them only when the feature is enabled
    #[cfg(feature = "channels-console")]
    let (tx, rx) = channels_console::channel!((tx, rx));

    // The channel works exactly the same way
    tx.send("Hello".to_string()).await.unwrap();
}

Zero-Cost Abstraction: When the channels-console feature is disabled, the #[cfg] attribute ensures the instrumentation code is completely removed at compile time - there's absolutely zero runtime overhead.

Note: The first invocation of channel! automatically starts:

  • A background thread for metrics collection
  • An HTTP server on http://127.0.0.1:6770 (default port) exposing metrics in JSON format

This initialization happens only once and is shared across all instrumented channels.

Channel Labels:

By default, channels are labeled with their file location and line number (e.g., src/worker.rs:25). You can provide custom labels for easier identification:

rust
let (tx, rx) = mpsc::channel::(10);
#[cfg(feature = "channels-console")]
let (tx, rx) = channels_console::channel!((tx, rx), label = "task-queue");

Capacity Parameter Requirement:

⚠️ Important: For std::sync::mpsc and futures::channel::mpsc bounded channels, you must specify the capacity parameter because their APIs don't expose the capacity after creation:

rust
use std::sync::mpsc;

// std::sync::mpsc::sync_channel - MUST specify capacity
let (tx, rx) = mpsc::sync_channel::(10);
#[cfg(feature = "channels-console")]
let (tx, rx) = channels_console::channel!((tx, rx), capacity = 10);
rust
use futures_channel::mpsc;

// futures bounded channel - MUST specify capacity
let (tx, rx) = mpsc::channel::(10);
#[cfg(feature = "channels-console")]
let (tx, rx) = channels_console::channel!((tx, rx), capacity = 10);

Tokio and crossbeam channels don't require the capacity parameter because their capacity is accessible from the channel handles.

Message Logging:

By default, instrumentation only tracks message timestamps. To capture the actual content of messages for debugging, enable logging with the log = true parameter (the message type must implement std::fmt::Debug):

rust
use tokio::sync::mpsc;

let (tx, rx) = mpsc::channel::(10);
#[cfg(feature = "channels-console")]
let (tx, rx) = channels_console::channel!((tx, rx), log = true);

stream! Macro

The stream! macro allows you to monitor any type implementing the futures::Stream trait:

Basic Usage:

rust
use futures_util::stream::{self, StreamExt};

#[tokio::main]
async fn main() {
    // Create a stream
    let stream = stream::iter(1..=10);

    // Instrument it
    #[cfg(feature = "channels-console")]
    let stream = channels_console::stream!(stream);

    // Use it normally
    let items: Vec = stream.collect().await;
}

Stream Labels:

Like channels, streams can be labeled for easier identification:

rust
let stream = stream::iter(1..=10);
#[cfg(feature = "channels-console")]
let stream = channels_console::stream!(stream, label = "number-stream");

Message Logging:

Capture the actual content of yielded items (requires Debug trait on the item type):

rust
let stream = stream::iter(vec!["hello", "world"]);
#[cfg(feature = "channels-console")]
let stream = channels_console::stream!(stream, log = true);

What's Tracked:

For streams, the instrumentation tracks:

  • Yielded - Total number of items produced by the stream
  • State - Whether the stream is active or completed (returned None)
  • Item Logs - Optional Debug representation of yielded items (when log = true)

Note: Unlike channels, streams don't have concepts like "queue depth" or "sent vs received" - they only yield items.

ChannelsGuard - Printing Statistics on Drop

Similar to the hotpath API the ChannelsGuard is a RAII guard that automatically prints channel statistics when dropped (typically at program end). This is useful for debugging and getting a summary of channel usage.

Basic Usage:

rust
use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    // Create guard at the start of your program (onl

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言