Rust / 系统课时
使用 Tokio Console 排查任务
使用 Tokio Console 排查任务
异步服务“卡住”时,日志通常只能说明业务停在某一步,无法回答任务为什么没有继续执行。本篇接入 console-subscriber 与 Tokio Console,并用三个可复现任务辨认忙轮询、未被唤醒和资源等待三类现象,最后把界面指标落到具体排查动作。
学习目标
- 正确启用 Tokio 运行时的 Console instrumentation,并连接 Tokio Console
- 根据
Busy、Sched、Idle、Polls与资源等待关系区分不同卡顿模式 - 从异常任务追到具体同步资源或缺失唤醒点,而不是只凭“任务一直存在”下结论
接入 Console instrumentation
Tokio Console 依赖运行时的 tracing instrumentation。项目需要启用 Tokio 的 tracing feature,并在编译时打开 tokio_unstable;后者是编译配置,不是 Cargo.toml 里的普通 Cargo feature。下面给出一个最小项目。
[package]
name = "tokio-console-demo"
version = "0.1.0"
edition = "2021"
[dependencies]
tokio = { version = "1", features = ["full", "tracing"] }
console-subscriber = "0.5"在项目根目录创建 .cargo/config.toml:
[build]
rustflags = ["--cfg", "tokio_unstable"]配置的验证方法是直接让 Cargo 检查项目:
cargo check预期输出
Finished `dev` profile [unoptimized + debuginfo] target(s) in <TIME>实际耗时会不同;如果编译器提示找不到 tokio::task::Builder,优先检查 tracing feature 与 .cargo/config.toml 是否同时生效。
再安装并确认 Console CLI:
cargo install --locked tokio-console
tokio-console --version预期输出
tokio-console <VERSION>制造三类可观察任务
下面的程序固定把 Console 服务绑定到 127.0.0.1:6669。busy-poll 持续主动让出并再次被调度,unwoken 永久返回等待且不注册新的唤醒来源,resource-wait 则等待一个被主任务长期占有的 Semaphore 许可。
use std::{future::pending, sync::Arc, time::Duration};
use tokio::sync::Semaphore;
#[tokio::main(flavor = "multi_thread", worker_threads = 2)]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
console_subscriber::ConsoleLayer::builder()
.server_addr(([127, 0, 0, 1], 6669))
.init();
let semaphore = Arc::new(Semaphore::new(1));
// 主任务占住唯一许可,让 resource-wait 稳定停在资源等待状态。
let held_permit = semaphore.clone().acquire_owned().await?;
let busy = tokio::task::Builder::new()
.name("busy-poll")
.spawn(async {
loop {
tokio::task::yield_now().await;
}
})?;
let unwoken = tokio::task::Builder::new()
.name("unwoken")
.spawn(async {
// pending() 不会自行注册可再次唤醒本任务的事件。
pending::<()>().await;
})?;
let resource_wait = tokio::task::Builder::new()
.name("resource-wait")
.spawn(async move {
let _permit = semaphore
.acquire()
.await
.expect("semaphore must stay open");
})?;
println!("demo listening on 127.0.0.1:6669 for 30 seconds");
tokio::time::sleep(Duration::from_secs(30)).await;
busy.abort();
unwoken.abort();
resource_wait.abort();
drop(held_permit);
Ok(())
}预期结果
程序可编译运行,并在 30 秒观察窗口内持续提供 Console telemetry。运行程序:
cargo run预期输出
demo listening on 127.0.0.1:6669 for 30 seconds程序保留 30 秒观察窗口,实际 Cargo 编译日志可能额外出现。
在 Console 中读任务状态
保持程序运行,在第二个终端连接:
tokio-console http://127.0.0.1:6669预期结果
busy-poll: Polls 持续快速增长
unwoken: 长时间 IDLE,Polls 基本不再增长
resource-wait: 长时间 IDLE,可继续追到同步资源等待Console 的任务列表里,Busy 表示任务正在被 poll 的累计时间,Sched 表示已经可运行但仍等着被 poll 的时间,Idle 表示等待再次唤醒的时间,Polls 则记录 poll 次数。单看某一列不能定性:高 Busy 可能是单次 poll 太长;Polls 极快增长更像自唤醒或忙轮询;长 Idle 既可能是正常等待,也可能是丢失唤醒。

追到资源等待根因
对 resource-wait,按 r 切到 Resources,再找到 Semaphore 相关同步资源并进入详情。资源详情会列出等待它的任务;如果能看到 resource-wait,就有了“任务停滞是因为许可未释放”的直接证据。随后回到代码检查谁持有许可、持有范围是否跨越了不必要的 .await,以及是否存在泄漏或永不结束的持有者。
对 unwoken,关键证据正好相反:它长期 Idle,却没有一个合理的计时器、I/O 或同步资源解释等待,而且 poll 次数不再变化。此时应检查自定义 Future::poll 是否在返回 Poll::Pending 前正确登记 Waker,以及外部事件发生后是否真的调用了唤醒路径。
用证据缩小排查范围
看到任务异常后,先判断它属于“持续被 poll”“已唤醒但迟迟得不到运行”还是“等待唤醒”,再决定看 CPU/阻塞、运行时调度,还是资源与 Waker。这样可以把“服务卡住”转换成可验证的任务状态,并把下一步检查限定到少数几个代码位置。