OpenTelemetry Collector怎么部署？采集管道配置清单

适用场景：面向首次在 Kubernetes 中接入 OpenTelemetry Collector 的开发、运维和平台团队，示例以最小可用采集链路为目标，具体版本和字段应以对应版本说明为准。

OpenTelemetry Collector怎么部署，第一步不是选 Helm 还是 YAML，而是先确认要采集什么信号、从哪里接收、处理后发到哪里。Collector 的配置由 receivers、processors、exporters、extensions 和 service pipelines 组成，部署只是把这条管道稳定运行起来。

图1：OpenTelemetry Collector 在微服务

先确定 OpenTelemetry Collector 部署形态

OpenTelemetry Collector 常见部署形态包括 Agent、Gateway 或两者组合。Agent 更靠近应用和节点，适合接收本地遥测数据；Gateway 更适合作为集中处理和转发层。OpenTelemetry 官方文档也按部署模式说明了不同拓扑的适用方向^[2]。

如果是第一次接入，建议先回答四个问题：

应用是否已经通过 OTLP 上报 traces、metrics 或 logs？
Collector 是每个节点部署，还是集中部署一组副本？
数据最终发往哪个后端，例如 Jaeger、Prometheus、Tempo、Loki 或厂商平台？
是否需要在 Collector 内做批处理、资源属性补全、采样或过滤？

对微服务系统来说，链路追踪往往是服务治理的基础能力。部署规划阶段应先梳理服务调用、网关、注册发现和可观测性的上下游关系。

采集管道配置要从 receiver 到 exporter 串起来

Collector 配置最容易混淆的地方，是写了 receiver 和 exporter，却忘了在 `service.pipelines` 中把它们串起来。官方配置模型中，pipeline 会声明某类信号使用哪些 receivers、processors 和 exporters^[1]。

图2：OTel Collector 采集管道中 receive

下面是一个用于理解结构的简化示例，实际字段和镜像版本需按当前官方文档核对^[1]：

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
  resource:
    attributes:
      - key: deployment.environment
        value: prod
        action: upsert

exporters:
  logging:
    verbosity: basic

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

这段配置只用于说明管道结构：receiver 接收 OTLP 数据，processor 补充资源属性并批处理，exporter 输出到日志。生产环境通常会替换为真实后端 exporter，并补充认证、TLS、队列和重试策略。

配置清单要覆盖三类信号

如果团队准备同时采集 traces、metrics 和 logs，不要假设一条 pipeline 自动覆盖所有信号。建议分别定义三类管道，再逐步启用。这样出现数据缺口时，可以判断是某个 receiver 未开放、某个 processor 改写属性，还是某个 exporter 无法连接后端。

Kubernetes部署时先保证最小可验证链路

在 Kubernetes 中部署 Collector 时，可以使用 Helm chart、Operator 或普通 YAML。对首次验证，建议先做最小链路：应用通过 OTLP 发数据，Collector 接收并输出到可观察的 exporter，再逐步接入生产后端。OpenTelemetry Kubernetes 文档提供了面向集群部署的说明和示例入口^[3]。

最小验证顺序可以这样做：

创建命名空间和 Collector 配置。
暴露 OTLP gRPC / HTTP 入口，确保应用能访问。
让一个测试服务上报 traces 或 metrics。
查看 Collector 日志，确认 receiver 收到数据。
替换 logging exporter 为目标后端 exporter。
观察后端是否出现服务名、span、指标或日志字段。

kubectl get pods -n observability
kubectl logs deploy/otel-collector -n observability
kubectl describe configmap otel-collector-config -n observability

这些命令只能确认部署和配置是否被加载，不能替代端到端链路验证^[3]。端到端验证应从应用侧发出一条可识别请求，再到后端查询同一条 trace 或同一组指标。

常见错误通常出在端口、属性和后端连通性

Collector 本身启动成功，不代表采集链路已经成功。常见问题包括：应用端 OTLP 协议和 Collector 暴露端口不一致、pipeline 未引用 receiver、resource 属性缺失、exporter 地址写错、后端认证失败、网络策略阻断出站流量等。

现象	优先检查	处理建议
Collector 有 Pod 但无数据	`service.pipelines` 是否引用 receiver	先用 logging exporter 验证输入
应用报连接失败	OTLP gRPC / HTTP 端口和 Service	核对协议、端口、DNS 和 NetworkPolicy
后端看不到服务名	resource processor 和 SDK 配置	补充 service.name、namespace、environment
数据量突然变大	batch、采样、过滤策略	先观察再调整，不直接丢弃关键信号

回滚目标是恢复采集路径

如果新配置导致数据中断，回滚不一定要删除 Collector。更稳妥的做法是回退 ConfigMap、保留旧 Service、恢复前一个 exporter 地址，并让应用侧配置保持不变。回滚目标不是“组件恢复 Running”，而是关键链路重新能被查询到。

接入后要把验证写进发布流程

OpenTelemetry Collector 部署完成后，建议把验证动作纳入应用发布和平台巡检。否则后续改 exporter、采样策略或资源属性时，很难判断是应用没有上报，还是 Collector 管道中断。

图3：OpenTelemetry Collector 从部署、

上线前至少检查：

Collector 配置能被加载，Pod 日志无明显解析错误。
应用侧 OTLP endpoint、协议和端口与 Service 一致。
目标后端能查询到测试 trace、指标或日志。
关键资源属性可用于筛选服务、环境、命名空间和版本。
回滚路径明确，包括配置回退、后端地址恢复和采样策略恢复。

部署验证完成后，可以在微服务架构分类中继续串联服务通信、治理和可观测性相关内容，也可以通过微服务架构专题回到架构治理入口，避免 Collector 只成为孤立采集组件。

小结

OpenTelemetry Collector 部署的重点是“先管道，后形态”。先定义接收、处理、输出和验证目标，再选择 Agent、Gateway、Helm、Operator 或 YAML。对首次接入，建议从最小可验证链路开始，让应用数据能被 Collector 接收并在后端查询到。

配置上要特别关注 `service.pipelines`、OTLP 端口、resource 属性、batch 处理、后端 exporter 和回滚路径。只有端到端数据可查，Collector 部署才算真正完成。

参考资料

常见问题

1. OpenTelemetry Collector怎么部署更适合小团队？

如果只是验证链路，优先使用最小可用的 Gateway 或单副本 Deployment，先打通 OTLP 到后端的路径。等服务数量增多、节点本地采集需求明确后，再考虑 Agent + Gateway 组合。不要一开始就把所有 processor 和 exporter 都启用。

2. Collector 和应用 SDK 是什么关系？

应用 SDK 负责在进程内生成遥测数据，Collector 负责接收、处理和转发数据。两者不是替代关系。应用侧需要正确设置 service.name、endpoint 和协议；Collector 侧需要保证 receiver、processor、exporter 和 pipeline 配置一致。

3. OpenTelemetry Collector配置是否可以一套模板全站复用？

可以复用基础模板，但不建议所有服务共享完全相同的处理策略。不同业务对采样、属性、日志字段和后端路由的要求不同。平台可以统一 receiver、通用 resource 属性和默认 batch 策略，再允许业务按命名空间或环境扩展。

4. Collector 启动成功但后端没有 trace，应该先查哪里？

先看 Collector 日志是否收到 OTLP 数据，再检查 `service.pipelines.traces` 是否引用了正确 receiver 和 exporter。随后检查后端地址、认证、网络策略和应用侧 endpoint。不要只看 Pod Running 状态，因为配置链路断开时 Pod 仍可能正常运行。

原创声明：本文为 CNBPA 云原生社区原创技术内容，非商业转载须注明出处：https://www.cloudnative-tech.com/p/9595/。文中原创图示、架构图和文章内容未经许可不得用于商业转载、培训课件、营销材料或二次分发。