trace-tools

使用 tokio 和 tracing 为异步任务提供跟踪和诊断工具。

该库包含一些组件

• Observe 特征
• 一个 tracing::Subscriber 实现，以及一些有用的 Layer。
• 诊断工具（目前只有一个，在 Flamegrapher 中）。
• #[observe] 过程式宏属性。

Observe 特征

此特征提供将未来封装在有仪器范围的跨度中的能力，类似于 tracing_futures::Instrument 特征。这个跨度有一些默认属性，使其容易在订阅者中注册和过滤

tracing::trace_span!(
    target: "trace_tools::observe",
    "observed",
    observed.name = <my_function_name>,
    loc.file = <caller_file>,
    loc.line = <caller_line>,
    loc.col = <caller_column>,
);

关键的是，这个跨度包含与 tokio 内部生成的相同的字段（当使用 --cfg tokio_unstable 编译时），这意味着订阅者可以像与 tokio 的内部跨度一样与 Observe 生成的跨度交互。

订阅者实现

trace-tools 提供了一个订阅者和两个 Layer 来处理跨度的事件

1. 火焰图 层：生成一个折叠的堆栈文件，详细说明仪器跨度堆栈（由 tokio 或 trace-tools 内部仪器）可用于生成所有 观察 代码的火焰图。
2. 日志记录 层：允许将 log 记录转换为 tracing 事件，并在订阅者内部重建完整的日志记录功能（相当于 fern-logger），因为一次无法设置两个记录器/订阅者。这意味着无论是否使用 trace-tools，日志记录都保持一致。
3. 控制台层（由 tokio-console 功能启用）：构建一个 console_subscriber::ConsoleLayer（来自 tokio 的 console 项目）来收集任务指标并广播它们。启用此层后，您可以运行 console 二进制文件并实时观察所有异步任务。注意：只有与 任务 相关的跨度将被这种方式观察，而不是所有的跨度；使用 trace_tools::observe 的跨度将不会出现。

订阅者可以通过一个构建器进行初始化，该构建器可以设置全局订阅者或返回一个可以进一步扩展更多 Layer 的 Layered 实例。

设置为默认订阅者

// `Flamegrapher` handle returned, for building a flamegraph at the end of the run.
let flamegrapher = trace_tools::subscriber::build()
    .with_flamegraph_layer(stack_filename)
    .with_log_layer(log_config)
    .init()?
    .unwrap();

返回一个 Layered 结构体

let (subscriber, flamegrapher) = trace_tools::subscriber::build()
    .with_flamegraph_layer(stack_filename)
    .with_log_layer(log_config)
    .finish()?;

// Extend the subscriber with external layers.
let subscriber = subscriber.with(console_layer);

// Set the global subscriber.
subscriber.init();

火焰图生成器

使用给定的折叠堆栈文件生成火焰图，使用 inferno 包。

let flamegrapher = trace_tools::subscriber::build()
    .with_flamegraph_layer(stack_filename)
    .init()?
    .unwrap();

// Run some instrumented code...
// ...
// ...

// Programatically create the flamegraph file.
flamegrapher
    .with_graph_file("flamegraph.svg")?
    .write_flamegraph()?;

#[observe] 属性

trace-tools 提供了一个简单的属性 proc-macro，用于使用指定 trace_tools::observe 目标的跨度来仪表化函数和 futures。跨度中的位置字段将描述标记函数或 futures 的位置，而 observed.name 字段将指定函数名称

use trace_tools::observe;

#[observe]
pub async fn say_hello() {
    println!("hello");
}

这相当于以下内容

trace_tools::Observe(say_hello(), "say_hello").await;

此宏可以与常规、非 async 函数一起使用，与 Observe 特性不同。

tokio-console 功能

tokio-console 功能启用了控制台层。请注意，这使用不稳定的 tokio 功能来工作。因此，此 crate 也必须使用 RUSTFLAGS="--cfg tokio_unstable" 来使用该功能。

示例

在 trace-tools/examples 中为每个层提供了一个示例。火焰图示例生成了这个交互式图表