如何在客户端与服务端正确搭配使用OpenTelemetry Exporter和Collector？

看起来你已经搭好了基础的OTel架构，但客户端的CollectorTraceExporter连不上Collector的核心问题在于接收端配置缺失、端口映射错误，以及URL路径不正确，下面一步步帮你解决：

问题根源分析 #

你尝试的几个URL都无法工作的原因：

• http://localhost:55680/v1/trace：这个端口映射的是Collector的zpages扩展（配置里是:55679），根本不是OTLP trace接收端点，所以返回404
• http://localhost:14268/v1/trace：14268是Jaeger的Thrift HTTP接收端口，不处理OTLP协议请求，所以无响应
• http://localhost:55681/v1/trace：这个端口根本没在docker-compose里映射，自然无法访问

另外，你的Agent配置里没有启用OTLP HTTP Receiver，而CollectorTraceExporter默认使用OTLP HTTP协议发送trace数据，这是核心问题。

解决方案步骤 #

1. 修改OTel Agent配置，添加OTLP HTTP Receiver #

编辑otel-agent-config.yaml，在receivers部分新增OTLP接收端，并把它加入trace pipeline：

receivers:
  opencensus:
  zipkin:
    endpoint: :9411
  jaeger:
    protocols:
      thrift_http:
  # 新增OTLP HTTP Receiver
  otlp:
    protocols:
      http:
        endpoint: ":4318" # OTLP HTTP默认端口，可自定义

# ...

service:
  extensions: [health_check, pprof, zpages]
  pipelines:
    traces:
      # 把otlp加入receivers列表
      receivers: [opencensus, jaeger, zipkin, otlp]
      processors: [batch, queued_retry]
      exporters: [opencensus, logging]
    metrics:
      receivers: [opencensus]
      processors: [batch]
      exporters: [logging,opencensus]

2. 在docker-compose中映射Agent的OTLP HTTP端口 #

编辑docker-compose.yml，给otel-agent服务添加端口映射，把容器内的4318端口映射到主机的4318：

otel-agent:
  image: ${OTELCOL_IMG}
  command: ["--config=/etc/otel-agent-config.yaml", "${OTELCOL_ARGS}"]
  volumes:
    - ./otel-agent-config.yaml:/etc/otel-agent-config.yaml
  ports:
    - "1777:1777" # pprof extension
    - "8887:8888" # Prometheus metrics exposed by the agent
    - "14268" # Jaeger receiver
    - "55678" # OpenCensus receiver
    - "55679:55679" # zpages extension
    - "13133" # health_check
    - "4318:4318" # 新增：OTLP HTTP Receiver端口映射
  depends_on:
    - otel-collector

3. 修正客户端Exporter的URL配置 #

注意两个关键点：

• 路径是v1/traces（你之前写的v1/trace少了s，这也是404的原因之一）
• 目标地址是Agent的4318端口（推荐通过Agent转发到Collector，而非直接连Collector）

修改客户端代码：

import { CollectorTraceExporter } from '@opentelemetry/exporter-collector';
// ...
tracerProvider.addSpanProcessor(
  new SimpleSpanProcessor(
    new CollectorTraceExporter({
      serviceName: 'my-service',
      url: 'http://localhost:4318/v1/traces', // 修正路径和端口
    })
  )
);

4. 重启服务验证 #

执行以下命令重启所有服务：

docker-compose down && docker-compose up -d

然后运行你的Web/Node应用，之后：

• 访问Jaeger UI（http://localhost:16686）查看是否能收到trace
• 查看Agent日志确认是否有接收trace的记录：

  docker-compose logs otel-agent | grep "trace"
  

额外建议 #

@opentelemetry/exporter-collector已经被标记为废弃，推荐使用官方最新的OTLP HTTP exporter：

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

// ...
tracerProvider.addSpanProcessor(
  new SimpleSpanProcessor(
    new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces',
      serviceName: 'my-service',
    })
  )
);

内容的提问来源于stack exchange，提问作者Hongbo Miao