3. OpenTelemetry 核心概念：Trace、Span、SpanContext、Attributes、Events、Links

在构建 BFF 层的可观测性体系时，OpenTelemetry 提供了一套标准化的数据模型。理解这些核心概念是进行链路数据采集与聚合优化的前提。本章将逐一拆解 Trace、Span、SpanContext、Attributes、Events 和 Links，并结合 BFF 场景说明其实际含义。

3.1 Trace：一次请求的完整旅程

Trace（追踪）代表一个端到端的请求在分布式系统中的完整执行路径。在 BFF 架构中，一次用户请求（例如“获取首页推荐”）会依次经过 BFF 层、多个下游微服务（用户服务、推荐服务、内容服务），最终返回结果。这个请求从入口到出口的完整生命周期，就是一个 Trace。

• 唯一标识：每个 Trace 由一个全局唯一的 TraceId 标识。
• 树状结构：Trace 由多个 Span 组成，这些 Span 按照调用关系形成一棵有向无环图（DAG）。
• BFF 视角：BFF 层通常是 Trace 的起点（Root Span），负责生成 TraceId 并向下游传播。

3.2 Span：追踪的最小工作单元

Span 是 Trace 中的基本组成单元，代表一个具有开始时间和结束时间的操作。每个 Span 封装了以下信息：

在 BFF 层，一个典型的 Span 分解示例如下：

Trace: 用户请求 /api/home
├── Span: BFF 入口处理 (Root Span)
│   ├── Span: 调用用户服务 (Client Span)
│   ├── Span: 调用推荐服务 (Client Span)
│   └── Span: 调用内容服务 (Client Span)
└── Span: 响应组装与返回

3.3 SpanContext：跨进程传播的载体

SpanContext 是 Span 的上下文信息，负责在服务之间传递追踪状态。它包含三个核心字段：

• TraceId：全局追踪 ID。
• SpanId：当前 Span 的 ID。
• TraceFlags：追踪选项，如是否采样。
• TraceState：供应商特定的追踪元数据（可选）。

在 BFF 层，SpanContext 通常通过 HTTP 头（如 traceparent）或 gRPC 元数据传播。BFF 作为聚合层，必须正确提取和注入 SpanContext，才能保证下游服务的链路连续。

3.4 Attributes：Span 的元数据注解

Attributes（属性）是键值对形式的元数据，用于描述 Span 的上下文细节。OpenTelemetry 定义了语义约定（Semantic Conventions），推荐使用标准属性名。

在 BFF 聚合优化中，合理添加 Attributes 可以大幅提升链路分析效率。例如，添加 user.id 属性后，可以快速过滤特定用户的请求链路。

3.5 Events：Span 内的时序事件

Events（事件）是附加在 Span 时间线上的结构化日志记录。与 Attributes 不同，Events 带有独立的时间戳，用于标记 Span 生命周期内的关键瞬间。

• 典型用途：记录异常、缓存命中/未命中、重试次数、关键业务决策点。
• 结构：事件名称 + 时间戳 + 可选的 Attributes。

BFF 层使用 Events 的示例：

Span: 调用推荐服务
├── Event: "cache.miss" @ t1
│   └── attributes: { "cache.key": "rec:user_12345" }
├── Event: "retry.attempt" @ t2
│   └── attributes: { "attempt": 1, "reason": "timeout" }
└── Event: "response.received" @ t3
    └── attributes: { "size_bytes": 2048 }

3.6 Links：跨 Trace 的关联

Links（链接）允许一个 Span 关联到另一个 Trace 中的 Span，形成跨 Trace 的因果关系。这在 BFF 层处理异步消息、批量任务或事件驱动架构时尤为重要。

• 使用场景：
  • BFF 层消费消息队列中的事件，需要关联到原始请求的 Trace。
  • BFF 发起异步批处理任务，任务结果需要回溯到触发请求。
  • 跨 Trace 的扇出调用（如批量查询多个用户）。
• 结构：每个 Link 包含一个 SpanContext 和可选的 Attributes。

例如，BFF 层从 Kafka 消费一个用户注册事件，并创建一个新的 Span 来处理该事件。通过 Links，可以将这个处理 Span 关联到原始用户注册请求的 Trace，即使它们属于不同的 Trace。

3.7 核心概念关系图

下图展示了 Trace、Span、SpanContext、Attributes、Events 和 Links 之间的整体关系：

3.8 BFF 层概念映射总结

下表将 OpenTelemetry 核心概念直接映射到 BFF 层的具体实现，帮助你在实际开发中快速定位：