OpenTelemetry 零改造接入炬鲸 OBSERVE：从采集器到面板的完整链路

为什么用 Collector 而不是直连

接入可观测平台最常见的坑，是把 SDK 直接指向后端。这样做一旦要切换后端、加过滤、做脱敏，就得改应用代码。正确做法是在中间放一个 OpenTelemetry Collector，应用只把数据发给本地的 Collector，剩下的路由、采样、脱敏、上报全部由它完成。下面按"部署 Collector → 自动埋点 → 验证数据"三步走，全程不改业务代码。

第一步：部署 Collector

下载对应平台的二进制或容器镜像后，核心是配置文件 otelcol-config.yaml。以炬鲸 OBSERVE 的 OTLP 端点为例：

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

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

exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otel/v1/traces
    headers:
      Authorization: "Bearer <你的 Token>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlphttp]

memory_limiter 防止突发流量把 Collector 打爆，batch 把数据攒批再发，减少网络开销。Token 在炬鲸 OBSERVE 控制台的"接入管理"里生成，按团队隔离。

第二步：自动埋点，不动业务代码

Java 应用在启动命令加一行 agent 参数即可：

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

Python 用 SDK 包，Go 用编译期注入或 runtime 自动埋点，Node.js 用 --require 加载。它们的共同点是把 exporter 指向本地 Collector（localhost:4317），而不是直连平台。日志和指标同理：指标可以用 OTLP exporter 从 Prometheus 采集器转发，日志用 Filelog receiver 或直接走 OTLP。

第三步：验证数据有没有进

接入完成后，先看 Collector 自身的日志有没有报错，再到炬鲸 OBSERVE 的"链路追踪"页面，按 service 名筛选最近 5 分钟，确认有 Trace 落盘。更进一步，随便触发一次请求，记下 traceId，在日志检索里按 traceId = 'xxx' 过滤，能看到整条请求的上下文日志，说明日志和链路已经关联上。

常见问题

• Trace 有，但日志对不上：检查日志里是否带 trace_id 字段，以及解析规则有没有把这个字段结构化。
• 数据延迟高：多半是 batch 参数配得太大，把 timeout 调小到 1s 以内。
• Collector 内存暴涨：把 memory_limiter 的 limit_mib 按机器内存的一半设置，并确认没有多个 exporter 重复缓存。

按这个流程走完，日志、指标、链路三类数据就全部进了平台，后续告警和拓扑分析可以直接开用。