tracing-opentelemetry-instrumentation-sdk

提供一组基于 OpenTelemetry 的 tracing 包构建仪表化的辅助工具，并遵循 OpenTelemetry 跟踪语义约定。

PS：欢迎贡献（错误报告、改进、功能等）

调用者侧的调用仪表化由以下步骤组成

• 使用所有属性（一些设置为 Empty）开始一个跨度
• 将传播数据（如果支持）注入调用（通过头部）
• 执行调用
• 使用响应（状态等）更新跨度的属性

调用者侧的调用仪表化由以下步骤组成

• 提取传播信息（从头部）（如果支持）并创建一个OpenTelemetry上下文
• 使用所有属性（一些设置为 Empty）开始一个跨度
• 将上下文作为父项附加到跨度上
• 执行处理
• 使用响应（状态等）更新跨度的属性

这些包提供提取/注入上下文信息、开始和更新跨度以及处理期间检索上下文或trace_id的辅助工具（例如，将trace_id注入日志、错误消息等）。

  let trace_id = tracing_opentelemetry_instrumentation_sdk::find_current_trace_id();
  //json!({ "error" :  "xxxxxx", "trace_id": trace_id})

辅助工具可以直接使用，也可以用于构建基于它的中间件（例如：axum-tracing-opentelemetry，tonic-tracing-opentelemetry是构建在为http提供的辅助工具之上的中间件（功能 & crate））

注意事项

• tracing-opentelemetry扩展了tracing以与OpenTelemetry交互。但有一些限制
  • 在关闭跟踪跨度时创建OpenTelemetry的跨度。因此，不要尝试从跟踪跨度内部与OpenTelemetry Span（或SpanBuilder）交互。
  • OpenTelemetry父上下文（以及trace_id）在NEW跨度上创建，或从父跨度继承。创建后可以覆盖父上下文，但在那时之前，trace_id是NEW的，因此跟踪的日志可能在NEW事件上报告为空或尚未设置的trace_id，直到更新为止。
  • 要从跟踪的跨度定义OpenTelemetry的跨度类型、名称等，使用特殊的记录名称：otel.name，otel.kind，...
  • 在tracing的跨度中记录应在创建时定义。因此，某些字段以值tracing::field::Empty创建，然后进行更新。
• 使用目标otel::tracing（以及级别trace）创建跟踪，以有一个启用/禁用的通用方式

仪器提示

直到每个crate都被仪器化

使用tracing::instrumented（无传播 & 无更新在响应上）

// basic handmade span far to be compliant with
//[opentelemetry-specification/.../database.md](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/trace/semantic_conventions/database.md)
fn make_otel_span(db_operation: &str) -> tracing::Span {
    // NO parsing of statement to extract information, not recommended by Specification and time-consuming
    // warning: providing the statement could leek information
    tracing_opentelemetry_instrumentation_sdk::otel_trace_span!(
        "DB request",
        db.system = "postgresql",
        // db.statement = stmt,
        db.operation = db_operation,
        otel.name = db_operation, // should be <db.operation> <db.name>.<db.sql.table>,
        otel.kind = "CLIENT",
        otel.status_code = tracing::field::Empty,
    )
}


      // Insert or update
        sqlx::query!(
                "INSERT INTO ...",
                id,
                sub_key,
                result,
            )
            .execute(&*self.pool)
            .instrument(make_otel_span("INSERT"))
            .await
            .map_err(...)?;

相关crate

• init-tracing-opentelemetry用于初始化tracing & OpenTelemetry
• axum-tracing-opentelemetry中间件，基于tracing-opentelemetry-instrumentation-sdk
• tonic-tracing-opentelemetry中间件，基于tracing-opentelemetry-instrumentation-sdk