tracing-modality

tracing-modality 为使用Rust编写的跟踪系统提供了tracing.rs Layer，以便将数据输出到Auxon Modality。

开始使用最简单的方法是让TracingModality将自己注册为全局默认跟踪器，这可以通过使用TracingModality::init()实现。

use tracing_modality::TracingModality;
use tracing::info;

#[tokio::main]
async fn main() {
    // first thing in main
    let mut modality = TracingModality::init().await.expect("init");

    info!("my application has started");

    // last thing in main
    modality.finish().await
}

还可以使用TracingModality::init_with_options设置一些基本配置选项，在初始化时进行设置。

如示例所示，您必须在主线程结束时调用TracingModality::finish，以确保处理所有跟踪事件的数据收集线程有足够的时间将所有排队的事件刷新完毕，然后再退出程序。

使用方法

完成初始设置后，如上图所示，该库不会直接使用，而是通过在 tracing.rs 中定义的宏来使用。这些宏的功能与 log crate 的日志宏 error、warn、info、debug 和 trace 类似，但它们还允许你以字段的形式传递结构化值，这些值作为独立值记录在跟踪数据中，而不是将它们字符串化为日志消息。

此外，tracing 还提供了一套类似的宏来发射跨度：error_span、warn_span、info_span、debug_span 和 trace_span。跨度用于标记执行区域。

还有许多其他方式可以使用 tracing，例如 #[instrument] 属性和 Value 特性。请参阅 tracing 的文档 了解完整的 API。

到模态概念的映射

尽管 tracing 和模态都处理跟踪数据，但它们使用的确切数据模型有一些差异。本节描述了如何将 tracing 的概念映射到模态的概念中。

模态时间线

在模态中，时间线是一系列事件的线性序列。该库将每个操作系统线程表示为单独的时间线。

要记录线程之间的交互，必须知道远程线程的时间线 ID。每个线程都可以使用 [timeline_id()] 函数访问其自己的时间线 ID，并且应该将该 ID 与交互一起发送，以便远程线程能够在其自己的时间线上记录交互。

tracing 元数据

tracing 隐式地为每个事件和跨度生成一些元数据，而 tracing-modality 将根据其对每个事件或跨度的看法添加更多元数据。

以下是每个元数据如何映射到模态中的

• name -> event.name[^1]
• level -> event.severity
• module_path -> event.source.module
• file -> event.source.file
• line -> event.source.line
• 事件类型 -> event.internal.rs.kind ["span:defined", "span:enter", "span:exit" ]
• id -> event.internal.rs.span_id (跨度仅限)

[^1]: event.name 字段几乎总是被覆盖，请参阅下一节以获取详细信息。

tracing 字段

字段是在使用事件或跨度宏时定义的结构化数据。它由一个键和一个 tracing 支持的类型之一的值组成。

所有字段直接映射到event.*，除了以modality.为前缀的字段，这些字段映射到特定数据源命名空间event.internal.rs.*。手动设置的字段将覆盖任何由元数据设置的默认值（如果存在）。

对于event.name存在特殊情况，它将被字段name覆盖，但如果该字段不存在，则将被字段message覆盖。如果字段message提升为name，则仅记录为name，而不会同时记录为message。

许可协议

版权所有 2022 Auxon Corporation

根据Apache License，版本2.0（“许可协议”）；除非您遵守许可协议，否则不得使用此文件。您可以在以下位置获得许可协议的副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可协议下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可协议的具体语言，请参阅许可协议。