Lib.rs

minitrace是一个跟踪库，比其他库快10~100倍

特性

• 易于使用
• 极快
• 库级跟踪
• 与日志crate及其宏兼容
• 与 Jaeger，Datadog 和 OpenTelemetry 兼容

资源

• 文档
• 示例
• 常见问题解答

入门

在库中

库应该将 minitrace 作为依赖项添加，而不启用任何额外功能。

[dependencies]
minitrace = "0.6"

将 trace 属性添加到您想要跟踪的函数。在此示例中，如果调用者设置了跟踪上下文，则每次调用函数时都会收集一个 SpanRecord。

#[minitrace::trace]
pub fn send_request(req: HttpRequest) -> Result<(), Error> {
    // ...
}

无论调用者是否设置了跟踪上下文，库都能够设置独立的跟踪上下文。这可以通过使用 Span::root() 启动新的跟踪和 Span::set_local_parent() 为当前线程设置本地上下文来实现。

full_name!() 宏可以检测函数的全名，该全名用作根span的名称。

use minitrace::prelude::*;

pub fn send_request(req: HttpRequest) -> Result<(), Error> {
    let root = Span::root(full_name!(), SpanContext::random());
    let _guard = root.set_local_parent();

    // ...
}

在应用程序中

应用应将 minitrace 作为依赖项，并启用 enable 功能集。要静态禁用 minitrace，只需移除 enable 功能。

[dependencies]
minitrace = { version = "0.6", features = ["enable"] }

应用应在程序运行早期初始化一个 Reporter 实现。在报告初始化之前生成的跨度记录将被忽略。在终止之前，应调用 flush() 以确保所有收集到的跨度记录都被报告。

当根跨度被丢弃时，其所有子跨度及其自身将同时被报告。因此，建议为短任务（如处理请求）创建根跨度，如下面的示例所示。否则，无止境的跟踪将不会被报告。

use minitrace::collector::Config;
use minitrace::collector::ConsoleReporter;
use minitrace::prelude::*;

fn main() {
    minitrace::set_reporter(ConsoleReporter, Config::default());

    loop {
        let root = Span::root("worker-loop", SpanContext::random());
        let _guard = root.set_local_parent();

        handle_request();
    }

    minitrace::flush();
}

基准测试

按不同架构

通过创建不同数量的跨度

详细信息可在 etc/benchmark-result 中找到。

使用 minitrace 的项目

欢迎在此处添加您的项目

• TiKV：分布式事务型键值数据库
• Conductor：开源 GraphQL 网关
• Apache OpenDAL：多种存储的数据访问层
• Databend：Snowflake 的低成本替代品

常见问题解答

为什么 minitrace 那么快？

minitrace 维护者发布了一些文章

• Rust 中高性能跟踪库的设计（中文）
• 如何以低于 5% 的性能影响跟踪 KV 数据库

什么是库级跟踪？

库级跟踪是指将跟踪能力直接集成到库中的功能，而不是将其限制在应用级或系统级跟踪中。

跟踪可能会给程序执行引入开销。虽然在应用级通常可以接受这种开销，因为与整体执行时间相比，增加的开销通常微不足道，但在库级可能会遇到更多问题。在这里，函数可能被频繁调用或性能可能至关重要，跟踪的开销可能会变得很大。因此，没有考虑速度和效率的跟踪库可能不适合库级跟踪。

在 minitrace 库的领域内，库级跟踪被设计为快速和轻量级，在没有激活时几乎无开销。这使得 minitrace 成为了性能敏感型应用的绝佳选择，并且它可以像日志 crate 一样无缝集成到库中，这是其他跟踪库可能无法提供的。

minitrace 与其他跟踪库有何不同？

虽然许多跟踪库追求丰富的功能，但 minitrace 优先考虑性能和简洁性。

例如，minitrace不引入新的日志宏，例如info!()或error!()，而是无缝集成了log库。这允许您使用现有的日志宏和依赖项，日志会自动附加到当前的追踪范围。

minitrace会包含“级别”范围吗？

“级别”的概念可能不是追踪系统的最佳特性。虽然tokio-tracing包含了这一特性，但在范围中包含级别的根本动机主要与性能相关。更具体地说，它关系到追踪非关注元素的性能影响。然而，追踪与日志记录在两个关键方面有所不同

1. 忽略低级别的范围可能会意外地丢弃高级别的子范围。
2. 在追踪系统中，过滤过程或通常称为“级别”，应应用于整个追踪，而不是追踪中的单个范围。

在这种情况下，minitrace通过其独特的尾部采样设计，通过过滤掉整个不感兴趣的追踪范围，提供了更有效的解决方案。因此，直接从日志系统借用的“级别”概念可能不适合minitrace。

minitrace会支持OpenTelemetry功能的'X'吗？

minitrace专注于高性能追踪。您可以提出缺少的追踪特性问题。

请注意，我们始终将性能放在功能之上，因此并非所有追踪功能请求都可能被接受。

这个库的状态是什么？

API 不稳定：API尚未稳定，未来可能会更改。

代码库已测试：minitrace已进行高覆盖率测试。然而，使用minitrace的应用程序尚未广泛部署，因此minitrace目前尚未被视为经过实战测试的。