Jaeger Span标签复盘规范 - 第1节

1.1 Span 的定义与核心属性

在分布式追踪体系中，Span（跨度）是追踪链路的最小工作单元，代表系统中一个具名、定时的操作片段。每个 Span 记录了一次特定操作（如 HTTP 请求、数据库查询、消息发送）的开始时间、结束时间、状态以及附加上下文。

1.2 Span 在分布式追踪中的角色

Span 是分布式追踪系统的数据骨架，承担以下核心角色：

• 追踪单元：每个 Span 记录一个服务或组件内的单一操作，是链路追踪的最小可观测数据单元。
• 调用关系载体：通过 ParentSpanID 与 ChildSpanID 的引用，Span 构建出请求在多个服务间的完整调用拓扑。
• 时序锚点：Span 的开始/结束时间戳提供了精确的延迟测量能力，用于定位性能瓶颈。
• 上下文传播媒介：Span 携带的 TraceID 和 Baggage（随 Span 传播的键值对）在服务间传递，保证跨进程追踪的连续性。
• 故障定位入口：当请求出错时，Span 的状态（如 error=true）和关联的 Tags/Logs 是排查根因的第一手证据。

1.3 Tag（标签）的作用与分类

Tag 是附加在 Span 上的键值对元数据，用于描述 Span 的特征、状态和上下文。Tag 是 Span 的“属性标签”，帮助开发者在海量 Span 中快速过滤、聚合和分析。

Tag 的核心作用

• 过滤与检索：通过 Tag 键值对快速筛选特定类型的 Span（如 http.method=POST）。
• 性能分析：记录关键指标（如 db.statement、http.url），辅助定位慢操作。
• 错误诊断：标记错误类型、异常堆栈或状态码（如 error.object、http.status_code=500）。
• 业务上下文：注入业务标识（如 order.id、user.role），实现业务维度的追踪分析。

Tag 的标准分类

1.4 Span 与 Tag 的关系结构

下图展示了 Span 与 Tag 在分布式追踪中的层次关系：一个 Trace 包含多个 Span，每个 Span 携带一组 Tags，Tags 按语义约定和自定义分类组织。

1.5 典型 Tag 注入示例

以下代码展示了在 Jaeger 客户端中为 Span 注入标准 Tag 和自定义 Tag 的典型方式：

// 创建 Span 并注入 Tags
span.setTag("http.method", "POST");
span.setTag("http.url", "/api/payment");
span.setTag("http.status_code", 200);
span.setTag("peer.service", "payment-service");

// 自定义业务 Tag
span.setTag("order.id", "ORD-20240301-001");
span.setTag("payment.amount", 99.80);
span.setTag("user.id", "user-abc");

// 错误标记
if (err != nil) {
    span.setTag("error", true);
    span.setTag("error.kind", "timeout");
    span.setTag("error.message", "connection refused");
}