📚 课程目录第3章 OpenTelemetry协议

3. OpenTelemetry 协议：OTel 数据模型与采集架构

分布式追踪值班台的数据源头是 OpenTelemetry（OTel）。作为 CNCF 的观测性标准，OTel 统一了指标、日志、链路（Traces）的采集与传输协议。本章聚焦 OTel 的 数据模型 与 采集架构，这是构建值班台看板的数据基础。

3.1 OTel 数据模型核心概念

OTel 将观测数据抽象为三种信号（Signal）：Traces、Metrics、Logs。值班台最关注 Traces，但 Metrics 和 Logs 的关联分析同样关键。

信号类型	核心数据结构	值班台用途
Traces	Span（跨度）	请求链路追踪、延迟分析、错误定位
Metrics	DataPoint（数据点）	服务吞吐、延迟分布、错误率聚合
Logs	LogRecord（日志记录）	异常上下文、事件关联、审计

3.2 Span 数据模型详解

Span 是 Traces 的最小单元，每个 Span 代表一个操作片段。一个完整的 Trace 由多个 Span 通过 TraceId 和 ParentSpanId 构成有向无环图（DAG）。

字段	说明	值班台看板字段映射
`TraceId`	全局唯一追踪 ID，16 字节	看板过滤、链路关联
`SpanId`	当前 Span 唯一 ID，8 字节	看板节点标识
`ParentSpanId`	父 Span ID，根 Span 为空	构建调用树
`Name`	操作名称，如 `HTTP GET /api/order`	看板服务/端点标签
`Kind`	Span 角色：`CLIENT`、`SERVER`、`INTERNAL`、`PRODUCER`、`CONSUMER`	区分调用方向
`StartTime` / `EndTime`	开始与结束时间戳	延迟计算、火焰图
`Status`	`OK` / `ERROR` / `UNSET`	错误率、错误链路高亮
`Attributes`	键值对元数据（K/V）	自定义维度过滤
`Events`	带时间戳的注解事件	异常堆栈、关键日志

  值班台关键字段： 在 Grafana 看板中，TraceId 用于跳转到 Tempo 链路详情页；Status 用于着色（红/绿）；Duration（EndTime - StartTime）用于延迟分布直方图。

3.3 OTel 采集架构：从 SDK 到后端

OTel 的采集架构分为三层：应用内 SDK → OTel Collector → 后端存储/分析。值班台的数据流必须经过 Collector 进行采样、过滤和路由。

架构要点： Collector 是值班台数据管道的核心枢纽。建议在生产环境部署 Collector 集群（Deployment 模式），并配置 Tail-Based Sampling 以保留高价值错误链路，同时降低存储成本。

3.4 OTLP 协议：gRPC 与 HTTP 传输

OTel 使用 OTLP（OpenTelemetry Protocol） 作为默认传输协议，支持 gRPC 和 HTTP/JSON 两种方式。值班台场景下，gRPC 是首选，因为其二进制编码效率高、流式传输延迟低。

传输方式	端口	编码	适用场景
gRPC	4317	Protobuf（二进制）	生产环境、高吞吐、低延迟
HTTP/JSON	4318	JSON（文本）	调试、浏览器端、受限网络

# OTLP gRPC 配置示例（Collector 端）
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlp:
    endpoint: tempo.example.com:4317
    tls:
      insecure: false
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, memory_limiter]
      exporters: [otlp]

3.5 资源与属性：看板维度注入

OTel 通过 Resource 和 Attributes 携带上下文信息。Resource 描述产生数据的实体（如 Pod、Node、Cluster），Attributes 描述 Span 的细节（如 HTTP 方法、状态码）。

维度类型	示例	值班台看板用途
Resource	`service.name`, `k8s.pod.name`, `host.name`	服务级过滤、Pod 级下钻
Span Attributes	`http.method`, `http.status_code`, `db.system`	端点延迟、错误码分布
Semantic Conventions	OTel 定义的标准化属性名	跨语言统一查询

避坑提示： 不要在 Attributes 中注入高基数（High Cardinality）字段，如 user_id、request_id。这会导致 Tempo 索引膨胀、查询性能下降。高基数信息应放在 Span Events 或关联日志中。

3.6 采样策略：值班台数据质量控制

全量采集所有 Trace 在规模化场景下不可行。OTel Collector 支持多种采样策略，值班台看板的数据质量取决于采样策略的合理性。

  值班台最佳实践： 在 Collector 中配置 tail_sampling 策略，对 status.code = ERROR 的 Span 设置 sampling_percentage = 100，对正常 Span 设置 sampling_percentage = 5。这样看板中的错误链路始终完整，而正常链路仅保留代表性样本。

3.7 数据模型与看板字段映射

理解 OTel 数据模型后，需要将其映射到 Grafana 看板的查询字段。以下为 Tempo 数据源中的典型映射关系：

OTel 字段	Tempo 查询语法	看板面板示例
`service.name`	`{resource.service.name="order-service"}`	服务下拉过滤器
`http.method`	`{span.http.method="POST"}`	端点延迟表格
`status.code`	`{span.status.code="ERROR"}`	错误率时间序列
`duration`	`{span.duration > 1000000}`（单位：μs）	慢链路告警

// Grafana Tempo 查询示例：过去 1 小时错误链路 Top 10
{
  "query": "{resource.service.name=\"payment-service\" && span.status.code=\"ERROR\"}",
  "limit": 10,
  "start": "now-1h",
  "end": "now"
}