2. OpenTelemetry 核心概念回顾：Signal、Context Propagation 与 Collector 架构
在构建平台工程的自助目录之前，必须统一团队对 OpenTelemetry (OTel) 核心概念的认知。本章聚焦三大支柱：Signal（遥测信号）、Context Propagation（上下文传播）以及Collector 架构。这三者构成了可观测性管线的数据基础与路由中枢。
2.1 三大 Signal：Trace / Metric / Log
OpenTelemetry 将可观测性数据抽象为三种标准信号（Signal），每种信号解决不同维度的观测问题：
| Signal | 核心作用 | 数据模型要点 | 典型用例 |
|---|---|---|---|
| Trace（链路） | 追踪请求在分布式系统中的完整路径 | Span（跨度）构成 Trace；Span 包含 TraceId、SpanId、ParentSpanId、时间戳、属性 | 定位慢调用、错误传播分析、依赖拓扑 |
| Metric（指标） | 聚合统计系统或服务的数值特征 | Counter、Histogram、Gauge、UpDownCounter；支持 Attributes 维度 | CPU 使用率、请求延迟 P99、错误率 |
| Log（日志） | 记录离散的事件文本 | LogRecord 包含时间戳、Body、Severity、Attributes；支持与 Trace 关联 | 异常堆栈、审计事件、业务操作记录 |
平台工程视角： 自助目录必须让开发者能够按需选择 Signal 类型。例如，高流量服务可能只需要 Metric 聚合，而核心交易链路必须开启 Trace 采样。目录应提供 Signal 级别的开关与采样率配置。
2.2 Context Propagation：跨服务关联的粘合剂
Context Propagation（上下文传播）是分布式追踪的核心机制。它确保一个请求经过多个微服务时，所有 Span 能够被关联到同一个 Trace 中。
- Context 对象： 包含 TraceId、SpanId、Baggage（自定义键值对）等关键信息。
- 传播协议： W3C TraceContext（traceparent/tracestate 头）是标准推荐；也支持 Jaeger、Zipkin 等旧格式。
- 自动注入与提取： OTel SDK 通过 Instrumentation 库自动在 HTTP/gRPC 请求中注入 Context，并在接收端提取。
关键设计原则： 在平台管线中，Context Propagation 必须端到端无损。任何中间件（如消息队列、网关、异步任务）如果丢失 Context，将导致链路断裂。自助目录应提供“上下文传播检查清单”，帮助开发者验证各组件是否正确传递 TraceContext。
2.3 Collector 架构：管线的智能中枢
OpenTelemetry Collector 是一个与厂商无关的代理/网关，负责接收、处理、导出遥测数据。它是平台工程中构建自助管线的核心组件。
Collector 的架构分为三个主要阶段：
- Receivers（接收器）： 接收来自 SDK 或其他系统的数据。常见 Receiver 包括 OTLP、Jaeger、Prometheus、Kafka。
- Processors（处理器）： 对数据进行过滤、采样、修改、批处理。例如：
batch（批处理）、filter（过滤）、attributes（属性修改）、tailsampling（尾部采样）。 - Exporters（导出器）： 将处理后的数据发送到后端存储或分析系统。例如：OTLP、Prometheus、Jaeger、Splunk、Datadog。
2.4 Collector 部署模式：Agent vs. Gateway
在平台工程中，Collector 通常以两种模式部署，自助目录需要根据场景提供选择：
| 模式 | 部署位置 | 优势 | 适用场景 |
|---|---|---|---|
| Agent（代理） | 与应用程序同节点（Sidecar 或 DaemonSet） | 低延迟、数据本地处理、减少网络传输 | Kubernetes 集群内、边缘节点、高吞吐服务 |
| Gateway（网关） | 独立部署为集群服务 | 集中策略管理、数据路由、多租户隔离、负载均衡 | 跨集群聚合、企业级管控、数据脱敏与合规 |
架构避坑： 不要将所有 Collector 功能堆叠在 Agent 中。Agent 应保持轻量，只做必要的预处理（如批处理、基础过滤）；复杂的采样策略、多后端路由、数据脱敏应放在 Gateway 层。自助目录应提供“Agent + Gateway”双层架构模板，让开发者按需组合。
2.5 核心概念与平台工程的关系
理解上述概念后，平台工程团队可以构建以下能力：
- Signal 标准化： 统一 Trace/Metric/Log 的数据模型，避免各团队自行定义属性命名规范。
- Context 强制传播： 在服务网格、API 网关、消息中间件中强制注入 TraceContext，保证链路完整性。
- Collector 管线模板化： 将 Receiver → Processor → Exporter 组合封装为可复用的 Pipeline 模板，纳入自助目录。
平台工程行动项： 在自助目录中提供“OTel 概念速查表”与“Collector Pipeline 生成器”。开发者只需选择 Signal 类型、采样率、后端目标，系统自动生成对应的 Collector 配置与 SDK 初始化代码。