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。下面给出一个最小项目。

toml
[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:

toml
[build]
rustflags = ["--cfg", "tokio_unstable"]

配置的验证方法是直接让 Cargo 检查项目:

bash
cargo check

预期输出

text
Finished `dev` profile [unoptimized + debuginfo] target(s) in <TIME>

实际耗时会不同;如果编译器提示找不到 tokio::task::Builder,优先检查 tracing feature 与 .cargo/config.toml 是否同时生效。

再安装并确认 Console CLI:

bash
cargo install --locked tokio-console
tokio-console --version

预期输出

text
tokio-console <VERSION>

制造三类可观察任务

下面的程序固定把 Console 服务绑定到 127.0.0.1:6669。busy-poll 持续主动让出并再次被调度,unwoken 永久返回等待且不注册新的唤醒来源,resource-wait 则等待一个被主任务长期占有的 Semaphore 许可。

rust
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(())
}

预期结果

text
程序可编译运行,并在 30 秒观察窗口内持续提供 Console telemetry。

运行程序:

bash
cargo run

预期输出

text
demo listening on 127.0.0.1:6669 for 30 seconds

程序保留 30 秒观察窗口,实际 Cargo 编译日志可能额外出现。

在 Console 中读任务状态

保持程序运行,在第二个终端连接:

bash
tokio-console http://127.0.0.1:6669

预期结果

text
busy-poll: Polls 持续快速增长
unwoken: 长时间 IDLE,Polls 基本不再增长
resource-wait: 长时间 IDLE,可继续追到同步资源等待

Console 的任务列表里,Busy 表示任务正在被 poll 的累计时间,Sched 表示已经可运行但仍等着被 poll 的时间,Idle 表示等待再次唤醒的时间,Polls 则记录 poll 次数。单看某一列不能定性:高 Busy 可能是单次 poll 太长;Polls 极快增长更像自唤醒或忙轮询;长 Idle 既可能是正常等待,也可能是丢失唤醒。

Tokio Console 中三类任务的任务列表

追到资源等待根因

对 resource-wait,按 r 切到 Resources,再找到 Semaphore 相关同步资源并进入详情。资源详情会列出等待它的任务;如果能看到 resource-wait,就有了“任务停滞是因为许可未释放”的直接证据。随后回到代码检查谁持有许可、持有范围是否跨越了不必要的 .await,以及是否存在泄漏或永不结束的持有者。

对 unwoken,关键证据正好相反:它长期 Idle,却没有一个合理的计时器、I/O 或同步资源解释等待,而且 poll 次数不再变化。此时应检查自定义 Future::poll 是否在返回 Poll::Pending 前正确登记 Waker,以及外部事件发生后是否真的调用了唤醒路径。

用证据缩小排查范围

看到任务异常后,先判断它属于“持续被 poll”“已唤醒但迟迟得不到运行”还是“等待唤醒”,再决定看 CPU/阻塞、运行时调度,还是资源与 Waker。这样可以把“服务卡住”转换成可验证的任务状态,并把下一步检查限定到少数几个代码位置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Tokio Console 排查任务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通