OpenTelemetry Collector Docker 部署排查：OTLP、4317/4318 和 Pipeline

本文记录一个 OpenTelemetry Collector Docker 部署排查流程。场景是 AI 应用已经接入 OpenTelemetry SDK，但 Trace 没有稳定进入后端。为了避免把 Collector、后端、网络、SDK 配置混在一起，先用 debug exporter 做最小闭环。

1. 排查目标

目标链路：

text 复制代码

AI App / API Gateway / Model Proxy
  -> OTLP gRPC 4317 或 OTLP HTTP 4318
  -> OpenTelemetry Collector
  -> debug exporter

先不接 Tempo、Jaeger、Prometheus、Loki。最小链路通了，再接正式后端。

2. 固定 Collector 镜像

先拉取固定版本：

bash 复制代码

docker pull docker.1ms.run/otel/opentelemetry-collector:0.154.0
docker pull docker.1ms.run/otel/opentelemetry-collector-contrib:0.154.0

排查原则：

镜像都没拉下来，不要排 OTLP。
版本不固定，不要排偶发行为。
需要更多 receiver/exporter 时，再考虑 contrib 镜像。

毫秒镜像在这里是镜像供应链层的预检入口，解决的是 Collector、示例服务和观测组件镜像拉取不稳定的问题，不替代 Collector 配置本身。

3. 最小配置文件

保存为 otel-collector-config.yaml：

yaml 复制代码

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

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

关键点：receivers、processors、exporters 只是定义组件，真正启用要看 service.pipelines。

4. 启动命令

bash 复制代码

docker run --rm --name otelcol \
  -p 4317:4317 \
  -p 4318:4318 \
  -v "$PWD/otel-collector-config.yaml:/etc/otelcol/config.yaml" \
  docker.1ms.run/otel/opentelemetry-collector:0.154.0

如果挂载路径不对，Collector 可能加载不到你写的配置。优先看容器日志里的配置加载信息。

5. 常见故障分叉

5.1 Collector 容器直接退出

优先检查：

YAML 缩进。
配置项名称。
文件挂载路径。
镜像版本和配置语法是否匹配。

5.2 4317 连不上

4317 是 OTLP gRPC 常用端口。检查：

bash 复制代码

docker ps --filter name=otelcol
lsof -i :4317

应用侧如果使用 gRPC endpoint，不要写成 HTTP 路径。

5.3 4318 连不上

4318 是 OTLP HTTP 常用端口。检查：

bash 复制代码

curl -v http://127.0.0.1:4318/

能访问端口不代表数据正确，但至少说明网络和端口映射不是第一断点。

5.4 有配置但没有输出

重点看 service.pipelines：

yaml 复制代码

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

只在 receivers 里写了 otlp，没有放进 traces pipeline，不会产生 Trace 输出。

5.5 只有入口 span，没有下游 span

这通常不是 Collector 问题，而是上下文没有继续传递。检查：

网关是否保留 trace header。
下游 HTTP/gRPC 客户端是否注入 context。
异步任务、队列、worker 是否手动传递 trace context。

6. AI 应用字段建议

AI 应用只看 HTTP 状态码不够。建议至少保留：

字段	说明
`trace_id`	串起一次完整请求
`service.name`	区分 gateway、agent-api、retriever、model-proxy
`model.name`	区分模型版本或模型供应方
`operation`	chat、embedding、rerank、tool-call
token 输入输出	观察成本和上下文膨胀
first token latency	观察用户感知延迟
retry / fallback	观察是否有隐藏故障

7. 生产前注意

debug exporter 只适合联调。生产环境至少要考虑：

batch 处理。
memory_limiter。
exporter 超时。
采样策略。
4317/4318 网络边界。
敏感字段脱敏。

8. 小结

OpenTelemetry Collector 排查不要从"后端为什么没图"开始。先按镜像、配置、端口、pipeline、应用 endpoint、trace context 的顺序排。最小 debug 链路跑通后，再接正式后端，问题边界会清楚很多。