tokio-rstracing：Rust 可观测性的标准答案

tokio-rs/tracing：Rust 可观测性的标准答案

tracing 在 GitHub 上已经拿到 6.7K Star。它是 Tokio 团队维护的 Rust 诊断框架，crates.io 累计下载量过亿。

一句话概括它做的事：给 Rust 程序装上结构化、事件驱动的诊断能力。不依赖 tokio 运行时，同步代码一样用。

1、核心概念：span 和 event

tracing 的模型分两层。span 代表一段操作的时间范围，比如"处理一次 HTTP 请求"或者"执行一个数据库查询"。event 代表某个时刻发生的事，比如"连接超时"或者"yak 剃完了"。

span 可以嵌套，形成一棵调用树。event 在 span 内部产生，自动继承 span 的上下文字段。这套模型跟 OpenTelemetry 的 span/event 概念完全对齐，导出到分布式追踪系统不需要额外转换。

2、和 log crate 的本质区别

Rust 生态里 log crate 是日志的事实标准，但它输出的是扁平字符串。要加结构化信息，只能在字符串里拼 key=value。tracing 的 event 原生支持字段，每条 event 都是键值对的集合。下游 collector 拿到的，是结构化数据而非需要正则解析的文本行。

另一个关键差异是异步支持。在 async fn 里用传统的 span guard，span 会和 future 同生共死，而不只是在 poll 期间存活，导致调用链完全错乱。tracing 的 #[instrument] 宏和 Future::instrument 方法从设计上解决了这个问题，span 的生命周期精确对应 future 的执行区间。

3、怎么用

应用端三步走：加依赖、装 collector、写宏。collector 可以设全局（tracing_subscriber::fmt::init()），也可以按代码块局部生效（with_default），灵活度很高。

[dependencies]
tracing = "0.1"
tracing-subscriber = "0.3"

use tracing::info;

fn main() {
    tracing_subscriber::fmt::init();
    info!(yaks = 3, "preparing to shave yaks");
}

库代码里原则很直白：只依赖 tracing crate，用 #[tracing::instrument] 给函数自动生成 span，用 info! / debug! / error! 宏发 event。不装 collector，留给下游应用决定数据去哪。

异步函数加一行属性宏即可，参数自动记录为 span 字段：

use tracing::instrument;

#[instrument]
async fn write(stream: &mut TcpStream) -> io::Result<usize> {
    let result = stream.write(b"hello world\n").await;
    info!("wrote to stream; success={:?}", result.is_ok());
    result
}

4、生态

tracing 本身的定位是插桩层，真正的输出和对接靠生态。Tokio 自己维护了十来个子 crate：tracing-subscriber 做收集、tracing-appender 做文件滚动输出、tracing-log 兼容 log crate、tracing-flame 出火焰图、tracing-journald 对接 Linux journald。

第三方生态铺得也很开：tracing-opentelemetry 打通 OTel 标准，tracing-honeycomb 对接 Honeycomb，tracing-elastic-apm 输出到 Elastic APM，tracing-loki 送到 Grafana Loki，tracing-chrome 导出的数据能在 chrome://tracing 里直接看。actix-web、axum、reqwest 这些库都有对应的集成。社区还在持续加新后端和中间件。

5、适合哪些人

• 写 Rust 后端服务、需要结构化日志和分布式追踪的开发者
• 用 tokio/axum/actix-web 想看清异步调用链的人
• 有现成可观测性平台（OpenTelemetry、Elastic、Grafana 等），需要把 Rust 服务的 trace 接进去的团队

现成可观测性平台（OpenTelemetry、Elastic、Grafana 等），需要把 Rust 服务的 trace 接进去的团队