3. OpenTelemetry 标准：数据模型、API 与 SDK 架构概览

OpenTelemetry（简称 OTel）是 CNCF 孵化的可观测性标准，统一了分布式追踪、指标和日志的采集规范。在微服务并发瓶颈与慢查询关联分析中，理解 OTel 的数据模型与架构是构建有效链路追踪的基础。本节聚焦其核心数据模型、API 与 SDK 的分层设计。

3.1 核心数据模型：Span、Trace 与 Resource

OTel 的追踪数据模型围绕三个核心概念构建，它们共同描述了请求在分布式系统中的完整路径。

以下 SVG 展示了 Trace 中 Span 的层级关系与数据模型结构：

3.2 API 与 SDK 分层架构

OTel 采用清晰的分层架构，将 API（接口定义）与 SDK（具体实现）分离，确保可移植性与可扩展性。

• API 层： 定义 Tracer、Span、Meter、Logger 等接口，不包含任何实现逻辑。应用代码仅依赖 API，避免与特定厂商绑定。
• SDK 层： 实现 API 接口，提供采样、导出、上下文传播等核心功能。SDK 是可插拔的，用户可自定义 Processor 和 Exporter。
• Instrumentation 层： 针对常见框架（如 Spring Boot、Express、gRPC）提供自动埋点库，减少手动埋点工作量。
• Exporter 层： 将采集到的 Span 数据发送到后端存储（如 Jaeger、Zipkin、Prometheus、Datadog）。

以下 SVG 展示了 OTel 的分层架构与数据流：

3.3 上下文传播机制

在微服务调用链中，上下文传播（Context Propagation）确保 Span 之间的父子关系正确建立。OTel 通过 Propagator 组件实现跨进程的 TraceId 传递。

• W3C TraceContext： 标准 HTTP 头 traceparent 和 tracestate，用于传递 TraceId、SpanId 和采样标志。
• Baggage： 通过 baggage 头传递业务上下文（如用户 ID、请求来源），但需注意性能开销，避免传递大量数据。

3.4 采样策略与性能权衡

全量采集所有请求的追踪数据在高并发系统中会产生巨大的存储和网络开销。OTel SDK 内置多种采样策略，帮助调优者在数据完整性与系统开销之间做出选择。

3.5 代码示例：手动创建 Span 并注入属性

以下 Java 示例展示了如何使用 OTel API 手动创建 Span，并注入慢查询相关的关键属性：

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;

public class OrderService {
    private final Tracer tracer;

    public OrderService(Tracer tracer) {
        this.tracer = tracer;
    }

    public void createOrder(String orderId, String sql) {
        // 创建 Span，设置 SpanKind 为 INTERNAL
        Span span = tracer.spanBuilder("db.order.insert")
                .setSpanKind(SpanKind.INTERNAL)
                .startSpan();

        // 将 Span 放入当前上下文
        try (Scope scope = span.makeCurrent()) {
            // 注入慢查询关键属性
            span.setAttribute("db.system", "mysql");
            span.setAttribute("db.statement", sql);
            span.setAttribute("db.instance", "orders_db_prod");
            span.setAttribute("net.peer.name", "mysql-01.internal");

            // 模拟数据库操作
            long startTime = System.currentTimeMillis();
            // ... 执行 SQL ...
            long duration = System.currentTimeMillis() - startTime;

            // 记录执行耗时
            span.setAttribute("db.duration_ms", duration);

            // 如果超过阈值，标记为慢查询
            if (duration > 200) {
                span.setAttribute("slow_query", true);
                span.setStatus(StatusCode.ERROR, "Query took " + duration + "ms");
            }
        } catch (Exception e) {
            span.recordException(e);
            span.setStatus(StatusCode.ERROR, "Query failed");
        } finally {
            span.end(); // 结束 Span
        }
    }
}