1. 课程导论：什么是 Collector 管道、什么是上下文传播、自助目录配置同步的痛点与目标
1.1 什么是 Collector 管道
在可观测性领域，Collector 管道（Pipeline）是一套数据流处理架构，它将数据采集、处理与导出拆解为三个可组合的阶段。以 OpenTelemetry Collector 为例，其管道由以下核心组件构成：
| 阶段 | 组件 | 职责 |
|---|---|---|
| 接收器 | Receiver | 从应用、基础设施或第三方系统接收遥测数据（Trace、Metric、Log） |
| 处理器 | Processor | 对数据进行过滤、采样、聚合、属性修改等中间处理 |
| 导出器 | Exporter | 将处理后的数据发送至后端存储或分析平台（如 Prometheus、Jaeger、Datadog） |
管道内的数据以 Batch 或 Record 粒度流动，每个阶段均可通过配置进行插拔式替换。这种设计使得数据流具备高度可编排性，但也带来了一个关键挑战：如何让管道内不同阶段共享同一个请求的上下文信息？
关键概念： Collector 管道本质是一个有向无环图（DAG），数据从 Receiver 流入，经 Processor 链处理，最终由 Exporter 流出。每个阶段独立运行，但共享的上下文信息需要显式传递。
1.2 什么是上下文传播
上下文传播（Context Propagation）是指在分布式系统中，将请求的元数据（如 Trace ID、Span ID、租户标识、用户身份、配置版本号）从一个处理单元传递到下一个处理单元的过程。在 Collector 管道中，上下文传播发生在两个层面：
- 进程内传播： 同一 Collector 实例内，数据从 Receiver 流经 Processor 再到 Exporter 时，通过
context.Context对象携带元数据。 - 进程间传播： 当数据跨 Collector 实例或跨服务发送时，通过 W3C Trace Context 或 Baggage 等协议将上下文序列化到请求头中。
上下文传播的核心载体包括：
| 载体 | 作用范围 | 典型字段 |
|---|---|---|
context.Context |
进程内 | TraceID, SpanID, Baggage |
| W3C Trace Context | 进程间 | traceparent, tracestate |
| OpenTelemetry Baggage | 进程间 | 自定义键值对（如 tenant_id, config_version） |
实践要点： 在自助目录配置同步场景中，上下文传播需要携带
catalog_id、sync_batch_id 和 config_hash，以确保每个配置变更都能被准确追踪到源头。
1.3 自助目录配置同步的痛点与目标
自助目录（Self-Service Catalog）是企业内部用于管理服务、资源与配置的中央注册中心。当用户通过自助目录提交配置变更后，系统需要将变更同步到多个 Collector 实例。这一过程面临以下核心痛点：
- 上下文断裂： 配置变更从目录出发，经过 API 网关、消息队列、配置中心，最终到达 Collector 管道。每个跳转点都可能丢失原始请求的 Trace ID 和租户信息，导致问题排查时无法串联全链路。
- 配置版本冲突： 多个用户同时修改同一目录条目时，Collector 管道可能收到乱序的配置更新，缺乏版本号上下文导致覆盖错误。
- 同步延迟不可观测： 无法判断配置变更是否已到达所有目标 Collector，以及每个 Collector 应用新配置的耗时。
- 回滚困难： 当新配置引发故障时，缺少上下文信息来快速定位受影响的 Collector 实例和配置版本。
本课程的目标是构建一套基于 Collector 管道上下文传播的配置同步方案，实现：
| 目标 | 描述 | 衡量指标 |
|---|---|---|
| 全链路可追踪 | 配置变更从提交到生效的每个环节都携带统一 Trace ID | 链路完整率 > 99.9% |
| 配置版本一致性 | 所有 Collector 实例最终应用同一版本的配置 | 版本偏差为 0 |
| 同步延迟可观测 | 实时展示每个 Collector 的配置同步状态与耗时 | 延迟 P99 < 5s |
| 快速回滚 | 通过上下文中的配置版本号，支持按版本批量回滚 | 回滚操作 < 30s |
常见误区： 很多团队只在 Collector 管道内部实现了上下文传播，却忽略了从自助目录到消息队列之间的上下文传递。这会导致配置变更的“第一公里”成为可观测性盲区。本课程将覆盖从提交到生效的完整链路。