网站 | 聊天 | 文档 (master分支)

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

概述

tracing是一个框架，用于收集结构化、基于事件的诊断信息，以对Rust程序进行检测。虽然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()，因此此收集器将作为默认值在所有线程中使用，直到程序结束，类似于log包中的日志记录器。

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

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");
}

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

这种方法允许在不同上下文中由多个收集器收集跟踪数据。注意，重写仅适用于当前正在执行的线程；其他线程将看不到from_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();
    // ...
}

范围保护_s将不会退出，直到由async块生成的未来完成。由于未来和范围可以多次进入和退出而不完成，范围将保持进入状态，直到未来存在，而不是仅在它被轮询时进入，从而导致非常混乱和错误的结果。有关更多详细信息，请参阅关于关闭范围的文档。

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

use tracing::Instrument;

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

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

Future::instrument将范围附加到未来，确保范围的生存期与未来的生存期相同。

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

支持的Rust版本

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

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

寻求帮助

首先，查看您的答案是否可以在API文档中找到。如果答案不在那里，在跟踪Discord频道中有一个活跃的社区。我们很乐意尝试回答您的问题。最后，如果那样也不行，尝试打开一个问题。

贡献

🎈 感谢您为改进项目做出的贡献！我们非常高兴有您的参与！我们有一个贡献指南，以帮助您参与到追踪项目中。

项目布局

tracing 包含主要的 仪表化 API，用于对库和应用程序进行仪表化以发出跟踪数据。 tracing-core 包含 核心 API 原语，其余的 tracing 都基于此进行仪表化。跟踪订阅者的作者可以依赖于 tracing-core，这保证了更高的稳定性。

此外，这个存储库还包含了一些基于 tracing 的兼容性和实用库。其中一些包处于预发布状态，比 tracing 和 tracing-core 包的稳定性要低。

包含在追踪中的包有

• tracing-futures：用于仪表化 futures 的实用工具。（crates.io|文档）

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

• tracing-attributes：用于自动仪表化函数的进程宏属性。（crates.io|文档）

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

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

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

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

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

• 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 实例框架提供 tracing 集成。
• axum-insights 为 axum 网络框架提供 tracing 集成和应用洞察导出。
• tracing-gelf 实现了一个用于导出跟踪信息的 Greylog GELF 格式订阅者。
• tracing-coz 为仅在 Linux 上可用的 coz 因果分析器提供集成。
• 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 提供了一个层实现，将事件以级别感知的方式记录到浏览器 console.* 以及跨度事件记录到 用户计时 API (window.performance)。
• test-log 根据环境变量使用与 env_logger 兼容的语法初始化测试中的 tracing。
• tracing-unwrap 为在 Result 或 Option 类型上报告失败的 unwraps 提供便利方法到 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。

外部资源

这是一份关于 Tracing 的博客文章、会议演讲和教程链接列表。

博客文章

• Tokio 博客上的诊断与跟踪，2019 年 8 月
• Rust 应用程序的生产级日志记录，2020 年 11 月
• 使用 tracing 和 tracing-subscriber 在 Rust 中进行自定义日志记录，第 1 部分 和 第 2 部分，2021 年 10 月
• 为 Axum 项目进行仪器化，2023 年 8 月

演讲

• 湾区 Rust Meetup 演讲和问答，2019 年 3 月
• RustConf 2019 演讲 和 幻灯片，2019 年 8 月
• 我们是否已被观察到？@ RustyDays 讲座 和 幻灯片，2020年8月
• 带仪器的蟹！，2021年9月

帮助我们扩展这个列表！如果你已经撰写或谈论过追踪，或者知道未列出的资源，请发起一个pull request添加它们。

许可证

本项目采用MIT许可证。

贡献

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