Rust / 系统课时

接入 tracing 观测任务

接入 tracing 观测任务

普通日志在并发异步任务中很容易混在一起:同一时刻可能有多个连接、请求和后台任务同时输出。本节用 tracing 的 span、字段和事件建立上下文,让每条关键日志都能回答“属于哪个连接、哪个请求、哪个任务”。

学习目标

  • 为连接、请求和后台任务设计可关联的 tracing span 与字段
  • 使用 #[instrument] 和 Instrument 正确传播异步任务上下文
  • 根据输出中的 span 层级与字段定位并发请求的执行路径

用 span 表达上下文

tracing 把观测信息分成两类:span 表示一段有上下文的执行范围,event 表示某个时间点发生的事件。请求 ID、连接 ID、任务类型这类需要被多条事件复用的信息适合放在 span 字段中。

对异步代码而言,关键不是多打几行日志,而是让 Future 每次被轮询时进入正确 span。这样任务在 .await 处让出执行权、之后再次恢复时,事件仍能关联到正确上下文。

连接请求与后台任务的 tracing 上下文关系

配置最小观测环境

示例需要 Tokio、tracing 和负责格式化输出的 tracing-subscriber。

toml
[dependencies]
tokio = { version = "1", features = ["macros", "rt", "time"] }
tracing = "0.1"
tracing-subscriber = "0.3"

这是配置片段。运行程序时初始化 subscriber 后,tracing 产生的 span 和 event 才会被实际收集并输出;真实服务还可以换成 JSON、OpenTelemetry 或其他订阅层。

给异步任务绑定 span

下面的程序建立连接 span,在请求函数上使用 #[instrument],再为派生出的后台任务创建子 span。Instrument 会在 Future 被轮询时进入对应 span,适合跨 .await 和 tokio::spawn 保持上下文。

rust
use std::time::Duration;
use tracing::{info, info_span, Instrument};

#[tokio::main(flavor = "current_thread")]
async fn main() {
    tracing_subscriber::fmt()
        .with_target(false)
        .compact()
        .init();

    serve_connection("conn-7").await;
}

async fn serve_connection(connection_id: &'static str) {
    let span = info_span!("connection", connection_id);

    async move {
        info!("connection accepted");
        handle_request(42, connection_id).await;
    }
    .instrument(span)
    .await;
}

#[tracing::instrument(
    name = "request",
    skip_all,
    fields(request_id = request_id, connection_id = connection_id)
)]
async fn handle_request(request_id: u64, connection_id: &'static str) {
    info!("request accepted");

    let task_span = info_span!(
        "background_task",
        request_id,
        job = "cache_refresh"
    );

    tokio::spawn(
        async move {
            tokio::time::sleep(Duration::from_millis(10)).await;
            info!(result = "ok", "background task finished");
        }
        .instrument(task_span),
    )
    .await
    .unwrap();
}

预期输出

text
<TIME> INFO connection{connection_id="conn-7"}: connection accepted
<TIME> INFO connection{connection_id="conn-7"}:request{request_id=42 connection_id="conn-7"}: request accepted
<TIME> INFO connection{connection_id="conn-7"}:request{request_id=42 connection_id="conn-7"}:background_task{request_id=42 job="cache_refresh"}: background task finished result="ok"

<TIME> 代表实际时间戳;空格、字段引号和 span 展示格式可能随 subscriber 配置略有不同。真正要验证的是三类事件都携带可关联的上下文,并且后台任务还能看到自己的 job 和请求 request_id。

避免跨 await 持有 enter guard

不要在异步函数里创建 let _guard = span.enter(); 后让这个 guard 跨越 .await。Future 挂起时局部变量不会立刻销毁,运行时却可能转去轮询另一个任务,这会让另一个任务错误地处在前一个 span 中。

异步场景优先使用 #[instrument]、future.instrument(span) 或 in_current_span();只有完全同步且不会跨 .await 的小段代码,才适合用 span.in_scope(...) 或短生命周期的 enter() guard。

按关联键排查并发问题

线上出现“某个请求完成很慢”时,先用 request_id 聚合该请求的事件,再查看它所属的连接 span 和派生任务 span。如果后台任务缺失,说明任务可能没有创建或没有被观测;如果任务存在但事件停在某个操作前后,则可以继续围绕该 span 增加耗时或错误字段。

这种结构把日志从“按打印时间排列的文本”变成“带父子关系和字段的执行记录”。连接、请求和后台任务并发得越多,显式传播 span 上下文的价值越明显。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入 tracing 观测任务

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

登录哪都通