📚 课程目录第3章 OpenTelemetry架构

3. OpenTelemetry 架构：核心组件与数据流水线

OpenTelemetry 的架构设计围绕“采集-处理-导出”这一核心思想展开，通过四个基础组件（Receiver、Processor、Exporter、Collector）和一条逻辑数据流水线（Pipeline）实现遥测数据的全生命周期管理。理解这些组件及其协作方式是构建可观测性基础设施的基石。

3.1 核心组件详解

下表从职责、输入/输出、典型场景三个维度对比四个核心组件：

组件	职责	输入 → 输出	典型场景
Receiver	接收遥测数据（Traces / Metrics / Logs）	网络协议（gRPC/HTTP）→ 内部 pdata 模型	OTLP Receiver 接收 SDK 上报；Prometheus Receiver 拉取指标
Processor	对数据进行过滤、增强、聚合、采样	pdata 模型 → pdata 模型（可修改/丢弃）	批处理、属性修改、尾部采样、Span 过滤
Exporter	将处理后的数据发送到后端存储或分析平台	pdata 模型 → 外部系统（Jaeger/Prometheus/云厂商）	OTLP Exporter 推送至 Collector；Prometheus Exporter 暴露指标端点
Collector	组件容器，管理 Pipeline 生命周期与配置	配置驱动，编排 Receiver → Processor → Exporter	独立部署的 Collector 实例；Agent 模式与 Gateway 模式

关键概念： pdata（Pipeline Data）是 OpenTelemetry Collector 内部使用的统一数据模型，所有组件通过 pdata 接口交互，保证组件可插拔、可替换。

3.2 数据流水线（Pipeline）概念

Pipeline 是 OpenTelemetry Collector 的核心编排单元，它将 Receiver、Processor、Exporter 按顺序串联成一条数据处理链路。每条 Pipeline 必须包含至少一个 Receiver 和一个 Exporter，Processor 为可选但强烈推荐。

Pipeline 的典型生命周期：

接收阶段： Receiver 监听端口或拉取数据，将外部协议转换为内部 pdata。
处理阶段： Processor 按配置顺序执行过滤、采样、批处理、属性修改等操作。
导出阶段： Exporter 将最终数据序列化并发送至后端系统。

以下 SVG 图展示了一条包含 Traces 和 Metrics 两条独立 Pipeline 的 Collector 内部架构：

3.3 组件间数据流与配置示例

在 Collector 配置文件中，Pipeline 通过 service.pipelines 段定义，组件通过 receivers、processors、exporters 顶级段声明。以下是一个同时处理 Traces 和 Metrics 的配置片段：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  prometheus:
    config:
      scrape_configs:
        - job_name: 'node-exporter'
          static_configs:
            - targets: ['localhost:9100']

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  attributes:
    actions:
      - key: environment
        value: production
        action: upsert
  filter:
    metrics:
      include:
        match_type: regexp
        metric_names:
          - "node_cpu_.*"

exporters:
  otlp:
    endpoint: tempo.example.com:4317
    tls:
      insecure: false
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, attributes]
      exporters: [otlp]
    metrics:
      receivers: [prometheus]
      processors: [filter, batch]
      exporters: [prometheus]

  配置要点：
  每个 Pipeline 的 receivers、processors、exporters 都是数组，顺序决定处理链路。
Processor 可以跨 Pipeline 复用，但每个 Pipeline 内的 Processor 实例独立。
如果不需要 Processor，可以省略该字段，但至少需要一个 Receiver 和一个 Exporter。

3.4 组件部署模式对比

模式	部署位置	典型组件	优势	劣势
Agent 模式	每个节点（K8s DaemonSet / 主机进程）	Receiver（OTLP）+ Processor（batch）+ Exporter（OTLP）	低延迟、本地预处理、减少网络传输	资源占用随节点数线性增长
Gateway 模式	独立集群（Deployment / StatefulSet）	Receiver（OTLP）+ Processor（采样/过滤）+ Exporter（多后端）	集中策略控制、全局采样、后端解耦	单点瓶颈、增加一跳延迟
混合模式	Agent + Gateway 分层	Agent 做轻量预处理，Gateway 做聚合与策略	兼顾性能与灵活性	运维复杂度增加

以下 SVG 图展示了 Agent + Gateway 混合部署的典型拓扑：

常见误区：

不要将 Processor 用于数据持久化或状态存储——Processor 是无状态的，重启后丢失中间数据。
不要在单个 Pipeline 中混用不同信号类型（Traces / Metrics / Logs），必须为每种信号类型定义独立的 Pipeline。
避免在 Agent 层做复杂采样，会增加节点 CPU 开销；复杂采样策略应放在 Gateway 层。

3.5 组件扩展机制

OpenTelemetry Collector 通过 Go 接口实现组件扩展，开发者可以自定义 Receiver、Processor、Exporter。核心接口定义如下：

// Receiver 接口
type Receiver interface {
    Start(ctx context.Context, host component.Host) error
    Shutdown(ctx context.Context) error
}

// Processor 接口
type Processor interface {
    ProcessTraces(ctx context.Context, td ptrace.Traces) (ptrace.Traces, error)
    ProcessMetrics(ctx context.Context, md pmetric.Metrics) (pmetric.Metrics, error)
    ProcessLogs(ctx context.Context, ld plog.Logs) (plog.Logs, error)
}

// Exporter 接口
type Exporter interface {
    Start(ctx context.Context, host component.Host) error
    Shutdown(ctx context.Context) error
}

自定义组件只需实现对应接口，并通过 component.MustNewType 注册到 Collector 的组件工厂中。这种设计使得 OpenTelemetry 生态拥有超过 100 个官方和社区组件，覆盖主流协议和后端。