30 分钟接入 OpenTelemetry：从 Collector 到炬鲸 OBSERVE

OpenTelemetry 已经是一套事实标准，但很多团队卡在"怎么把三类信号统一送进后端"。这篇教程用最小配置，让你在半小时内把 trace、metric、log 都接入炬鲸 OBSERVE。

第一步：部署 Collector

建议用官方 Docker 镜像跑一个本地 Collector，避免在业务进程里堆配置：

docker run -d --name otel-col \
  -v $(pwd)/otel-collector.yaml:/etc/otel/config.yaml \
  otel/opentelemetry-collector-contrib:0.110.0 \
  --config=/etc/otel/config.yaml

选择 contrib 版本，它内置了更多 receiver 和 exporter。确保业务进程能访问 4317（gRPC）和 4318（HTTP）两个端口。

第二步：编写配置文件

下面这份 otel-collector.yaml 同时接收 OTLP 数据并转发到炬鲸 OBSERVE：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch:
    timeout: 5s
    send_batch_size: 512
  memory_limiter:
    check_interval: 5s
    limit_mib: 512
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otel/v1
    headers:
      Authorization: Bearer <你的 token>
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]

三个 pipeline 分别对应三类信号，batch 处理器把零散数据攒批再发，能显著降低后端压力；memory_limiter 则防止 Collector 自身内存被打爆。token 在炬鲸 OBSERVE 控制台的「接入配置」页生成。

第三步：在业务代码里埋点

以 Java 为例，引入 opentelemetry-javaagent 即可自动采集：

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
  -Dotel.service.name=order-api \
  -jar order-api.jar

不改业务代码就能拿到 HTTP 请求的 trace 和基础 metric。需要业务语义（比如下单、扣库存）时，再手动加 Span，把业务动作挂在现有 trace 上。

第四步：验证数据已到达

启动后等一分钟，在炬鲸 OBSERVE 的「链路追踪」页搜索 order-api，能看到一条条 trace；「指标」页能查到 JVM 和 HTTP 相关指标；日志页也能看到 Collector 转发的日志。三处都能看到数据，接入就算完成。

常见坑

• 401 报错：检查 Authorization header 的 token 是否有效、是否有多余空格。
• 数据时有时无：确认 batch 的 timeout 和到后端的网络连通性。
• 指标对不上：确认各服务的 service.name 一致，否则同一服务的 trace 和 metric 对不上。