tracing-serde-structured

一个用于使用serde序列化tracing类型的替代、结构化适配器。

概述

tracing是一个用于为Rust程序添加仪器的框架，用于收集范围、结构和异步感知的诊断信息。tracing-serde-structured允许使用serde序列化tracing类型。

传统的日志基于人类可读的文本消息。tracing提供了机器可读的结构化诊断信息。这使得我们可以以编程方式与诊断数据交互。使用tracing-serde-structured，您可以实现一个Subscriber来序列化您的tracing类型，并利用现有的serde序列化器生态系统与分布式跟踪系统进行通信。

序列化诊断信息使我们能够对日志值做更多操作。例如，当在开发中使用JSON处理日志数据时，可以在调试时进行美化打印，并将JSON和跟踪数据输出到生产环境中以监控服务。

tracing crate提供了用于向库和应用程序添加仪器以输出跟踪数据的API。

与tracing-serde crate的区别

与上游的 tracing-serde crate 不同，tracing-serde-structured 以结构化的方式执行序列化，使数据与二进制格式（如 postcard）兼容，同时允许数据的反序列化。

tracing-serde-structured 仍然与 JSON 的序列化和反序列化兼容，尽管它会改变 JSON 数据的格式，这意味着它并不是一个100%的即插即用替代品。

以下是一个 tracing-serde 和 tracing-serde-structured 数据差异的示例

pub fn main() {
    // 1 - new span
    let span = tracing::span!(Level::TRACE, "outer_span");
    // 2 - enter span
    let _span = span.enter();
    do_thing::doit();
    // 7 - exit span
}

mod do_thing {
    pub fn doit() {
        // 3 - new span
        let span = tracing::span!(Level::TRACE, "my span");
        // 4- enter span
        span.in_scope(|| {
            // 5 - event
            event!(Level::INFO, "something has happened!");
            // 6 - exit span
        });
    }
}

# 1 - new span
- '{"name":"outer_span","target":"tracing_playground","level":"TRACE","module_path":"tracing_playground","file":"src/main.rs","line":34,"fields":[],"is_span":true,"is_event":false}'
+ '{"name":"outer_span","target":"tracing_playground","level":"TRACE","module_path":"tracing_playground","file":"src/main.rs","line":34,"fields":[],"is_span":true,"is_event":false}'
# 2 - enter span
- '{"metadata":{"name":"outer_span","target":"tracing_playground","level":"TRACE","module_path":"tracing_playground","file":"src/main.rs","line":34,"fields":[],"is_span":true,"is_event":false},"parent":null,"is_root":false}'
+ '{"metadata":{"name":"outer_span","target":"tracing_playground","level":"TRACE","module_path":"tracing_playground","file":"src/main.rs","line":34,"fields":[],"is_span":true,"is_event":false},"parent":null,"is_root":false}'
- '[1]'
+ '{"id":1}'
# 3 - new span
- '{"name":"my span","target":"tracing_playground::do_thing","level":"TRACE","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":74,"fields":[],"is_span":true,"is_event":false}'
+ '{"name":"my span","target":"tracing_playground::do_thing","level":"TRACE","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":74,"fields":[],"is_span":true,"is_event":false}'
# 4 - enter span
- '{"metadata":{"name":"my span","target":"tracing_playground::do_thing","level":"TRACE","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":74,"fields":[],"is_span":true,"is_event":false},"parent":null,"is_root":false}'
+ '{"metadata":{"name":"my span","target":"tracing_playground::do_thing","level":"TRACE","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":74,"fields":[],"is_span":true,"is_event":false},"parent":null,"is_root":false}'
- '[2]'
+ '{"id":2}'
# 5 - event
- '{"name":"event src/main.rs:76","target":"tracing_playground::do_thing","level":"INFO","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":76,"fields":["message"],"is_span":false,"is_event":true}'
+ '{"name":"event src/main.rs:76","target":"tracing_playground::do_thing","level":"INFO","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":76,"fields":["message"],"is_span":false,"is_event":true}'
- '{"metadata":{"name":"event src/main.rs:76","target":"tracing_playground::do_thing","level":"INFO","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":76,"fields":["message"],"is_span":false,"is_event":true},"message":"something has happened!"}'
+ '{"fields":{"message":{"Debug":"something has happened!"}},"metadata":{"name":"event src/main.rs:76","target":"tracing_playground::do_thing","level":"INFO","module_path":"tracing_playground::do_thing","file":"src/main.rs","line":76,"fields":["message"],"is_span":false,"is_event":true},"parent":null}'
# 6 - exit span
- '[2]'
+ '{"id":2}'
# 7 - exit span
- '[1]'
+ '{"id":1}'

用法

首先，将以下内容添加到您的 Cargo.toml

[dependencies]
tracing = "0.1"
tracing-serde-structured = "0.1"

然后，将以下内容添加到您的 crate 中

use tracing_serde::AsSerde;

请阅读 tracing 文档 了解如何创建跟踪数据的相关信息。

此 crate 通过 AsSerde trait 提供了 as_serde 函数，它使 Attributes、Event、Id、Metadata 和 Record 等跟踪值可以序列化。

实现一个 Subscriber 来格式化 tracing 类型的序列化，按照您的需求。

pub struct JsonSubscriber {
    next_id: AtomicUsize, // you need to assign span IDs, so you need a counter
}

impl Subscriber for JsonSubscriber {

    fn new_span(&self, attrs: &Attributes) -> Id {
        let id = self.next_id.fetch_add(1, Ordering::Relaxed);
        let id = Id::from_u64(id as u64);
        let json = json!({
        "new_span": {
            "attributes": attrs.as_serde(),
            "id": id.as_serde(),
        }});
        println!("{}", json);
        id
    }
    // ...
}

在实现您的 Subscriber 之后，您可以使用您的 tracing 订阅者（如上例中的 JsonSubscriber）来记录序列化的跟踪数据。

Crate 功能标志

以下 crate 功能标志可用

• std：依赖于 Rust 标准库（默认启用）。

  no_std 用户可以使用 default_features = false 禁用此功能

  [dependencies]
  tracing-serde-structured = { version = "0.1", default-features = false }
  

不稳定功能

以下功能标志启用了 不稳定 功能。公共 API 可能会在 0.1.x 版本中中断。要启用这些功能，必须在编译时将 --cfg tracing_unstable 传递给 rustc。

以下目前可用的不稳定功能标志

• valuable：启用 Visit::record_value 实现，用于使用 valuable crate 记录的值进行序列化。

启用不稳定功能

设置 tracing_unstable cfg 的最简单方法是使用 RUSTFLAGS 环境变量在运行 cargo 命令时进行设置

RUSTFLAGS="--cfg tracing_unstable" cargo build

或者，以下内容可以添加到项目中的 .cargo/config 文件中，以自动为该项目启用 cfg 标志

[build]
rustflags = ["--cfg", "tracing_unstable"]