网站 | 聊天 | 文档（master分支）

master分支是tracing的预发布、开发版本。请查看v0.1.x分支以获取发布到crates.io的tracing版本。

概述

tracing是一个用于收集结构化、基于事件的诊断信息的框架。 tracing由Tokio项目维护，但不需要使用tokio运行时。

用法

在应用程序中

为了记录跟踪事件，可执行文件必须使用与tracing兼容的收集器实现。收集器实现了一种收集跟踪数据的方式，例如通过将日志记录到标准输出。 tracing-subscriber的fmt模块提供了一个具有合理默认值的收集器，用于记录跟踪。此外，tracing-subscriber能够消费由log工具库和模块发出的消息。

要使用tracing-subscriber，将以下内容添加到您的Cargo.toml

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

然后创建并安装一个收集器，例如使用init()

use tracing::info;
use tracing_subscriber;

fn main() {
    // install global collector configured based on RUST_LOG env var.
    tracing_subscriber::fmt::init();

    let number_of_yaks = 3;
    // this creates a new event, outside of any spans.
    info!(number_of_yaks, "preparing to shave yaks");

    let number_shaved = yak_shave::shave_all(number_of_yaks);
    info!(
        all_yaks_shaved = number_shaved == number_of_yaks,
        "yak shaving completed."
    );
}

使用init()调用set_global_default()，因此此收集器将作为默认值在所有线程中使用，直到程序结束，类似于logcrate中的日志记录器。

为了获得更多控制，收集器可以分阶段构建，而不是全局设置，而是用于局部覆盖默认收集器。例如：

use tracing::{info, Level};
use tracing_subscriber;

fn main() {
    let collector = tracing_subscriber::fmt()
        // filter spans/events with level TRACE or higher.
        .with_max_level(Level::TRACE)
        // build but do not install the subscriber.
        .finish();

    tracing::collect::with_default(collector, || {
        info!("This will be logged to stdout");
    });
    info!("This will _not_ be logged to stdout");
}

在收集器上下文之外生成的任何跟踪事件都不会被收集。

这种方法允许在程序的多个不同上下文中通过多个收集器收集跟踪数据。请注意，覆盖仅适用于当前正在执行的线程；其他线程将不会看到从with_default中发生的变化。

一旦设置了一个收集器，就可以使用tracing crate的宏向可执行文件添加仪表点。

在库中

库应仅依赖于tracing crate，并使用提供的宏和类型收集可能对下游消费者有用的任何信息。

use std::{error::Error, io};
use tracing::{debug, error, info, span, warn, Level};

// the `#[tracing::instrument]` attribute creates and enters a span
// every time the instrumented function is called. The span is named after
// the function or method. Parameters passed to the function are recorded as fields.
#[tracing::instrument]
pub fn shave(yak: usize) -> Result<(), Box<dyn Error + 'static>> {
    // this creates an event at the DEBUG level with two fields:
    // - `excitement`, with the key "excitement" and the value "yay!"
    // - `message`, with the key "message" and the value "hello! I'm gonna shave a yak."
    //
    // unlike other fields, `message`'s shorthand initialization is just the string itself.
    debug!(excitement = "yay!", "hello! I'm gonna shave a yak.");
    if yak == 3 {
        warn!("could not locate yak!");
        // note that this is intended to demonstrate `tracing`'s features, not idiomatic
        // error handling! in a library or application, you should consider returning
        // a dedicated `YakError`. libraries like snafu or thiserror make this easy.
        return Err(io::Error::new(io::ErrorKind::Other, "shaving yak failed!").into());
    } else {
        debug!("yak shaved successfully");
    }
    Ok(())
}

pub fn shave_all(yaks: usize) -> usize {
    // Constructs a new span named "shaving_yaks" at the TRACE level,
    // and a field whose key is "yaks". This is equivalent to writing:
    //
    // let span = span!(Level::TRACE, "shaving_yaks", yaks = yaks);
    //
    // local variables (`yaks`) can be used as field values
    // without an assignment, similar to struct initializers.
    let span = span!(Level::TRACE, "shaving_yaks", yaks);
    let _enter = span.enter();

    info!("shaving yaks");

    let mut yaks_shaved = 0;
    for yak in 1..=yaks {
        let res = shave(yak);
        debug!(yak, shaved = res.is_ok());

        if let Err(ref error) = res {
            // Like spans, events can also use the field initialization shorthand.
            // In this instance, `yak` is the field being initialized.
            error!(yak, error = error.as_ref(), "failed to shave yak!");
        } else {
            yaks_shaved += 1;
        }
        debug!(yaks_shaved);
    }

    yaks_shaved
}

[dependencies]
tracing = "0.1"

注意：库不应通过调用set_global_default()方法安装收集器，因为这会在可执行文件稍后尝试设置默认值时导致冲突。

在异步代码中

要跟踪async fn，首选方法是使用#[instrument]属性

use tracing::{info, instrument};
use tokio::{io::AsyncWriteExt, net::TcpStream};
use std::io;

#[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
}

对于使用std::future::Future或带有async/await的代码块的一般情况，需要特殊处理，因为以下示例将不会工作

async {
    let _s = span.enter();
    // ...
}

span guard _s将不会退出，直到由async块生成的future完成。由于future和span可以在它们完成之前多次进入和退出，因此span将保持进入状态，直到future存在，而不是只在它被轮询时进入，从而导致非常混乱和不正确的输出。有关更多详细信息，请参阅关闭span的文档。

可以使用Future::instrument组合器解决这个问题

use tracing::Instrument;

let my_future = async {
    // ...
};

my_future
    .instrument(tracing::info_span!("my_future"))
    .await

Future::instrument将一个span附加到future上，确保span的寿命与future的寿命相同。

在底层，#[instrument]宏执行与Future::instrument相同的显式span附加操作。

支持的Rust版本

跟踪是针对最新稳定版本构建的。最低支持的版本是1.63。当前跟踪版本不保证在低于最低支持版本的Rust版本上构建。

跟踪遵循Tokio项目的其余部分的相同编译器支持策略。当前稳定Rust编译器和它之前的三个最近的次要版本将始终得到支持。例如，如果当前稳定编译器版本是1.69，则最低支持版本不会超过1.66，即之前的三个次要版本。只要这样做符合此策略，增加最低支持的编译器版本不被视为semver破坏性更改。

获取帮助

首先，查看您的答案是否可以在API文档中找到。如果答案不在那里，Tracing Discord频道（点击访问）有一个活跃的社区。我们很乐意尝试回答您的问题。最后，如果还不行，尝试打开一个包含问题的问题。

贡献

🎈 感谢您的帮助，使项目得到改进！我们非常高兴有您！我们有一个贡献指南，帮助您参与Tracing项目。

项目布局

tracing存储库包含主要的 instrumentation API，用于为库和应用程序添加跟踪数据。 tracing-core存储库包含 core API原语，其余的tracing都是基于这些原语进行instrumentation的。跟踪订阅者的作者可能依赖于tracing-core，这保证了更高的稳定性。

此外，此存储库包含基于tracing构建的几个兼容性和实用库。其中一些存储库处于预发布状态，稳定性不如tracing和tracing-core存储库。

Tracing包括以下存储库

• tracing-futures：用于instrumenting futures的实用工具。（crates.io|docs）

• tracing-macros：用于发出跟踪事件的实验性宏（不稳定）。

• tracing-attributes：用于自动instrumenting函数的过程宏属性。（crates.io|docs）

• tracing-log：与log存储库的兼容性（不稳定）。

• tracing-serde：与serde序列化跟踪数据的兼容层（不稳定）。

• tracing-subscriber：收集器实现，以及实现和组合Collector的实用工具。（crates.io|docs）

• tracing-tower：与tower生态系统的兼容性（不稳定）。

• tracing-appender：输出跟踪数据的实用工具，包括文件附加程序和非阻塞写入器。（crates.io|docs）

• tracing-error：提供SpanTrace，一种用于跟踪跟踪跨度中错误的类型

• tracing-flame；提供基于跟踪跨度入口/退出事件的火焰图生成层。

• tracing-journald：为将事件记录到Linux journald 服务提供一个层次结构，保留结构化数据。

相关包

除了这个存储库，还有一些由 tokio 项目不维护的第三方包。包括以下内容

• tracing-timing 在 tracing 上实现了事件间的计时度量。它提供了一个订阅者，记录 tracing 事件之间的时间差并生成直方图。
• tracing-honeycomb 提供了一个层次结构，将跨多台机器的跟踪信息报告给 honeycomb.io。由 tracing-distributed 支持。
• tracing-distributed 提供了一个通用的层，将跨越多台机器的跟踪信息报告到某个后端。
• tracing-actix-web 为 actix-web 网络框架提供 tracing 集成。
• tracing-actix 为 actix actor 框架提供 tracing 集成。
• axum-insights 为 axum 网络框架提供 tracing 集成和应用洞察导出。
• tracing-gelf 实现了一个订阅者，用于以 Greylog GELF 格式导出跟踪。
• tracing-coz 为 coz 因果分析器（仅限 Linux）提供集成。
• tracing-bunyan-formatter 提供了一个层实现，以 bunyan 格式报告事件和跨度，并增加了计时信息。
• tide-tracing 为 tide 中间件提供，用于跟踪所有传入请求和响应。
• color-spantrace 为以 color-backtrace 风格渲染跨度跟踪提供格式化程序。
• color-eyre 为 eyre::Report 提供自定义的恐慌和 eyre 报告处理器，用于捕获带有新错误和美观打印的跨度跟踪和回溯。
• spandoc 为在函数内部的文档注释中从文档注释构建跨度提供 proc 宏。
• tracing-wasm 提供了一个 Collector/Subscriber 实现来通过浏览器 console.log 和 用户计时 API (window.performance) 报告事件和跨度。
• tracing-web 提供了一种面向层的实现，用于将事件以级别感知的方式记录到 Web 浏览器的 console.* 和跨度事件到 用户计时 API (window.performance)。
• test-log 根据环境变量以及与 env_logger 兼容的语法来初始化 tracing 以供测试使用。
• tracing-unwrap 提供了便利的方法来报告在 Result 或 Option 类型上失败的展开到 Collector。
• diesel-tracing 提供了与 diesel 数据库连接的集成。
• tracing-tracy 为在受监控的应用程序中收集 Tracy 配置文件提供了一种方式。
• tracing-elastic-apm 提供了一个用于向 Elastic APM 报告跟踪的层。
• tracing-etw 提供了一个用于发出 Windows ETW 事件的层。
• sentry-tracing 提供了一个用于向 Sentry 报告事件和跟踪的层。
• tracing-forest 提供了一个订阅者，通过在写入时将来自同一跨度的日志分组在一起来保持上下文一致性。
• tracing-loki 提供了一个将日志发送到 Grafana Loki 的层。
• tracing-logfmt 提供了一个将事件和跨度格式化为 logfmt 格式的层。
• tracing-chrome 提供了一个可以将跟踪数据导出到 chrome://tracing 进行查看的层。
• reqwest-tracing 提供了一个中间件，用于跟踪 reqwest HTTP 请求。
• tracing-cloudwatch 提供了一个将事件发送到 AWS CloudWatch Logs 的层。
• clippy-tracing 提供了一个工具，用于添加、删除和检查 tracing::instrument。

(如果你是这个列表中没有的 tracing 生态系统 crate 的维护者，请告诉我们！)

注意： 目前，某些生态系统 crate 尚未发布，正在积极开发中。它们可能比 tracing 和 tracing-core 不太稳定。

外部资源

这是一个链接列表，包括关于跟踪的博客文章、会议演讲和教程。

博客文章

• 在 Tokio 博客上关于跟踪的诊断，2019 年 8 月
• Rust 应用程序中的生产级日志记录，2020 年 11 月
• 在Rust中使用tracing和tracing-subscriber进行自定义日志记录，第一部分 和 第二部分，2021年10月
• Axum项目的监控，2023年8月

演讲

• 湾区Rust Meetup演讲和问答，2019年3月
• RustConf 2019演讲 和 幻灯片，2019年8月
• 我们是否已经可观察？@ RustyDays演讲 和 幻灯片，2020年8月
• Crabs with instruments!，2021年9月

帮助我们扩展这个列表！如果你已经撰写或讲述了关于Tracing的内容，或者知道未列出的资源，请提交一个pull request添加它们。

许可证

本项目根据MIT许可证授权。

贡献

除非你明确说明，否则你提交给Tracing的任何有意贡献都应按照MIT许可证授权，不附加任何额外条款或条件。