2. OpenTelemetry 核心概念：Trace、Span、Metrics、Logs、Context Propagation

在构建值班机器人故障诊断体系之前，必须理解 OpenTelemetry 的五大核心概念。它们构成了可观测性的数据基础，也是事件触发与根因分析的原始素材来源。本节将逐一拆解这些概念，并展示它们如何在故障诊断链路中协同工作。

2.1 核心概念全景图

OpenTelemetry 将可观测性数据归纳为三大信号（Traces、Metrics、Logs），并通过 Context Propagation 将它们关联到同一个请求上下文中。下图展示了这四类数据与传播机制的关系：

2.2 Trace（追踪）

Trace 记录一个请求从入口到出口的完整路径，跨越多个服务、进程和网络边界。在故障诊断中，Trace 是还原请求全貌的核心工具。

2.3 Span（跨度）

Span 是 Trace 中的最小工作单元，代表一个操作或一个步骤。每个 Span 包含操作名称、开始时间、结束时间、状态和属性。

Span 的关键属性：

• Span ID：当前 Span 的唯一标识
• Parent Span ID：父 Span 的 ID，用于构建调用链
• Span Kind：Client、Server、Internal、Producer、Consumer
• Status：Unset、Ok、Error（含错误描述）
• Attributes：键值对，记录业务或技术上下文
• Events：Span 生命周期内的关键事件

// Span 创建示例（伪代码）
span = tracer.startSpan("process_order")
span.setAttribute("order.id", "ORD-12345")
span.setAttribute("payment.amount", 299.99)
// ... 执行业务逻辑 ...
span.setStatus(StatusCode.ERROR, "支付超时")
span.end()

2.4 Metrics（指标）

Metrics 是聚合后的数值数据，用于衡量系统在时间维度上的行为。与 Trace 的请求级粒度不同，Metrics 关注的是整体趋势和阈值。

2.5 Logs（日志）

Logs 是带有时间戳的结构化或非结构化文本记录。OpenTelemetry 的 Logs 信号与 Trace 深度集成，每条日志可以关联到特定的 Trace ID 和 Span ID。

结构化日志推荐格式：

{
  "timestamp": "2025-03-21T14:30:00.123Z",
  "severity": "ERROR",
  "body": "数据库连接超时",
  "trace_id": "abc123def456",
  "span_id": "span789",
  "attributes": {
    "db.system": "postgresql",
    "db.operation": "SELECT",
    "error.type": "timeout"
  }
}

2.6 Context Propagation（上下文传播）

Context Propagation 是 OpenTelemetry 的粘合剂，负责在服务之间传递上下文信息（Trace ID、Span ID、Baggage 等）。没有它，Trace 会在服务边界断裂，Metrics 和 Logs 也无法关联到同一个请求。

传播机制分为两部分：

• W3C Trace Context：标准 HTTP 头 traceparent 和 tracestate
• Baggage：携带业务上下文（如用户 ID、租户 ID）

// HTTP 请求中的上下文传播示例
// 客户端发送请求时自动注入
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate: vendor_id=abc123
baggage: user_id=u_98765,tenant=prod-east

2.7 四类数据在故障诊断中的协同

下表总结了 Trace、Span、Metrics、Logs 在值班机器人故障诊断流程中的角色：

2.8 实战：从 Metrics 告警到 Trace 关联

以下是一个典型的值班机器人故障诊断数据流：

2.9 关键概念速查表