📚 课程目录第4章 OpenTelemetry入门

4. OpenTelemetry 入门：OTel 架构、SDK/API、Collector、Exporter 配置

OpenTelemetry（简称 OTel）是 CNCF 孵化的可观测性标准框架，统一了 Trace、Metric、Log 三大信号的采集、处理与导出规范。本章聚焦 OTel 的核心架构、SDK/API 使用方式、Collector 管道配置以及 Exporter 对接后端系统的方法，为后续 TraceID 触发 Runbook 排障流程打下数据采集基础。

4.1 OTel 整体架构

OTel 采用“生产-处理-导出”三层架构，各组件职责清晰，便于灵活部署与扩展。

  架构核心原则： 应用通过 SDK/API 生成遥测数据，Collector 负责接收、处理、路由，Exporter 将数据发送到后端存储或分析平台。

4.2 OTel SDK / API 核心概念

OTel SDK 提供语言原生接口，开发者通过 API 创建 Span、设置属性、记录事件。SDK 负责采样、上下文传播、导出等底层逻辑。

组件	职责	常用方法 / 接口
TracerProvider	管理 Tracer 实例，配置采样策略	`getTracer(name, version)`
Tracer	创建 Span，控制追踪生命周期	`startSpan(name)`, `startActiveSpan(name)`
Span	记录操作名称、开始/结束时间、属性、事件	`setAttribute(key, value)`, `addEvent(name)`
Context	隐式传递 TraceID / SpanID，支持跨进程传播	`Context.current()`, `with(context)`
Sampler	决定哪些 Trace 被采样并导出	`AlwaysOnSampler`, `TraceIdRatioBasedSampler`

最佳实践： 生产环境推荐使用 TraceIdRatioBasedSampler 按比例采样（如 10%），避免全量采集导致存储成本过高。关键业务 Span 可通过 Sampler.ALWAYS_ON 强制保留。

4.3 OTel Collector 管道配置

Collector 是 OTel 的数据中枢，通过 Receiver → Processor → Exporter 管道处理遥测数据。配置文件采用 YAML 格式，核心结构如下：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 1s
    limit_mib: 512

exporters:
  otlp:
    endpoint: "jaeger:4317"
    tls:
      insecure: true
  prometheus:
    endpoint: "0.0.0.0:8889"
  logging:
    loglevel: debug

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

4.4 Exporter 配置与后端对接

Exporter 负责将处理后的数据发送到指定后端。常见 Exporter 类型及配置要点如下：

Exporter 类型	目标后端	配置关键参数
OTLP Exporter	Jaeger / Tempo / 其他 OTLP 兼容后端	`endpoint`, `tls.insecure`, `headers`
Prometheus Exporter	Prometheus / VictoriaMetrics	`endpoint`, `namespace`, `const_labels`
Loki Exporter	Grafana Loki	`endpoint`, `tenant_id`, `labels`
Logging Exporter	标准输出（调试用）	`loglevel` (debug/info/warn/error)

注意： 生产环境务必配置 batch 和 memory_limiter Processor，防止 Collector 内存溢出。Exporter 应启用重试与持久化队列，避免数据丢失。

4.5 数据流与 TraceID 传递

TraceID 是贯穿整个排障流程的核心标识。OTel 通过 W3C Trace Context 标准（traceparent 头）在服务间传递 TraceID，确保端到端链路可追踪。

traceparent 头传递 TraceID 和父 SpanID • 消息队列通过 tracestate 扩展传递上下文 • Collector 自动解析并关联所有 Span，形成完整 Trace

4.6 实战要点总结

SDK 初始化： 在应用启动时配置 TracerProvider 和 Exporter，推荐使用环境变量或配置文件驱动。
Collector 部署： 建议使用 Docker Compose 或 Kubernetes DaemonSet 部署，确保高可用。
Exporter 冗余： 同时配置至少两个后端（如 Jaeger + Logging），便于调试和故障切换。
采样策略： 根据业务重要性设置不同采样率，关键链路强制全采。
安全传输： 生产环境启用 TLS 加密，避免遥测数据泄露。