Rust / 系统课时
接入 tracing 观测任务
接入 tracing 观测任务
普通日志在并发异步任务中很容易混在一起:同一时刻可能有多个连接、请求和后台任务同时输出。本节用 tracing 的 span、字段和事件建立上下文,让每条关键日志都能回答“属于哪个连接、哪个请求、哪个任务”。
学习目标
- 为连接、请求和后台任务设计可关联的 tracing span 与字段
- 使用
#[instrument]和Instrument正确传播异步任务上下文 - 根据输出中的 span 层级与字段定位并发请求的执行路径
用 span 表达上下文
tracing 把观测信息分成两类:span 表示一段有上下文的执行范围,event 表示某个时间点发生的事件。请求 ID、连接 ID、任务类型这类需要被多条事件复用的信息适合放在 span 字段中。
对异步代码而言,关键不是多打几行日志,而是让 Future 每次被轮询时进入正确 span。这样任务在 .await 处让出执行权、之后再次恢复时,事件仍能关联到正确上下文。

配置最小观测环境
示例需要 Tokio、tracing 和负责格式化输出的 tracing-subscriber。
[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 保持上下文。
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();
}预期输出
<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 上下文的价值越明显。