tokio-trace

一个范围化的、结构化日志和诊断系统。

文档

概述

tokio-trace 是一个用于收集结构化、事件驱动的诊断信息的 Rust 程序框架。

在像 Tokio 这样的异步系统中，解析传统的日志消息通常相当具有挑战性。由于单个任务在相同的线程上复用，相关的事件和日志行会混合在一起，使得难以跟踪逻辑流程。《code>tokio-trace 通过允许库和应用程序记录关于 时间 和 因果关系 的额外信息的结构化事件，扩展了日志风格的诊断。与日志消息不同，tokio-trace 中的 span 有一个开始和结束时间，可以由执行流程进入和退出，并且可以存在于类似 span 的嵌套树中。此外，tokio-trace 中的 span 是 结构化 的，能够记录类型化数据以及文本消息。

tokio-trace 软件包提供了用于将库和应用程序仪器化的 API，以发出跟踪数据。

用法

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

[dependencies]
tokio-trace = "0.1"

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

#[macro_use]
extern crate tokio_trace;

此 crate 提供了创建 Span 和 Event 宏，分别代表程序执行中的时间段和瞬时事件。

一般来说，span 应用于表示离散的工作单元（例如，服务器中特定请求的生命周期）或花费在特定上下文中的时间段（例如，与外部系统实例（如数据库）交互的时间）。相比之下，event 应用于表示 span 内的时间点——例如，带有特定状态码的请求返回，队列中提取了 n 个新项目等。

Span 是通过使用 span! 宏来构建的，然后通过 进入 来表示一些代码发生在该 Span 的上下文中。

// Construct a new span named "my span".
let mut span = span!("my span");
span.enter(|| {
    // Any trace events in this closure or code called by it will occur within
    // the span.
});
// Dropping the span will close it, indicating that it has ended.

Event 类型代表一个瞬时发生的事件，本质上是一个无法进入的 Span。它们是通过使用 event! 宏来创建的。

use tokio_trace::Level;
event!(Level::INFO, "something has happened!");

使用 log 库的用户应该注意，tokio-trace 提供了一系列用于创建 Event 的宏（trace!、debug!、info!、warn! 和 error!），其语法与 log 库中同名宏的语法相同。通常，将项目转换为使用 tokio-trace 的过程可以从简单的替换开始。

让我们考虑 log 库的剃羊毛示例。

#[macro_use]
extern crate tokio_trace;
use tokio_trace::field;

pub fn shave_the_yak(yak: &mut Yak) {
    // Create a new span for this invocation of `shave_the_yak`, annotated
    // with  the yak being shaved as a *field* on the span.
    span!("shave_the_yak", yak = field::debug(&yak)).enter(|| {
        // Since the span is annotated with the yak, it is part of the context
        // for everything happening inside the span. Therefore, we don't need
        // to add it to the message for this event, as the `log` crate does.
        info!(target: "yak_events", "Commencing yak shaving");

        loop {
            match find_a_razor() {
                Ok(razor) => {
                    // We can add the razor as a field rather than formatting it
                    // as part of the message, allowing subscribers to consume it
                    // in a more structured manner:
                    info!({ razor = field::display(razor) }, "Razor located");
                    yak.shave(razor);
                    break;
                }
                Err(err) => {
                    // However, we can also create events with formatted messages,
                    // just as we would for log records.
                    warn!("Unable to locate a razor: {}, retrying", err);
                }
            }
        }
    })
}

您可以在示例目录中找到如何使用此库的示例。

在库中

库应仅链接到 tokio-trace 库，并使用提供的宏来记录对下游消费者有用的任何信息。

在可执行文件中

为了记录跟踪事件，可执行文件必须使用与 tokio-trace 兼容的 Subscriber 实现。一个 Subscriber 实现了一种收集跟踪数据的方式，例如将其记录到标准输出。

与 log 库不同，tokio-trace 不会使用一个全局的 Subscriber，该全局 Subscriber 只初始化一次。相反，它遵循 tokio 在上下文中执行代码的模式。例如

#[macro_use]
extern crate tokio_trace;

let my_subscriber = FooSubscriber::new();

tokio_trace::subscriber::with_default(subscriber, || {
    // Any trace events generated in this closure or by functions it calls
    // will be collected by `my_subscriber`.
})

这种方法允许跟踪数据由程序中不同上下文中的多个订阅者收集。或者，可以由 main 函数构建单个订阅者，所有后续代码都使用该订阅者作为默认执行。任何在订阅者上下文之外生成的跟踪事件都不会被收集。

可执行文件本身也可以使用 tokio-trace 库来自我监控。

tokio-trace-nursery 存储库包含一些不太稳定的库，这些库旨在与 tokio-trace 生态系统一起使用。它包括一系列 Subscriber 实现以及实用和适配器库。

许可证

本项目采用 MIT 许可证。

贡献

除非您明确声明，否则您提交给 Tokio 的任何有意包含的贡献，都将按照 MIT 许可证授权，不附加任何额外条款或条件。