OpenTelemetry 接入炬鲸 OBSERVE 全流程：Collector、SDK 与日志关联

为什么用 OpenTelemetry

OpenTelemetry（OTel）是主流的可观测性数据采集标准，一套 SDK 同时产出 Trace、Metrics、Logs，避免在代码里分别集成多个厂商的埋点库。炬鲸 OBSERVE 完全兼容 OTLP 协议，接入只需「加依赖 + 改配置」，不改业务逻辑。

第一步：部署 Collector

生产环境建议在每台主机或每个 K8s 节点部署 OTel Collector，由它统一接收、处理后转发到 OBSERVE。核心配置如下：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otlp
    headers:
      X-Tenant: platform
      Authorization: Bearer <token>
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

batch 处理器把零散的 span 合并成批再发送，能显著降低网络开销和出口压力。

第二步：在应用里加 SDK

Java 应用通常用 opentelemetry-javaagent，启动参数加一行即可，零代码改动：

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

Agent 会自动给 HTTP、数据库、消息队列等常见组件埋点。Python、Go、Node.js 用对应 SDK，导出器同样指向 Collector 的 4317 端口，注意 service.name 要和后台登记一致。

第三步：打通 Trace 与 Log

光有 trace 不够，排查时还要把日志和 span 关联起来。让日志携带 trace_id 和 span_id，在 OBSERVE 里就能从一条日志直接跳到对应链路。以 Logback 为例：

<pattern>%d{yyyy-MM-dd HH:mm:ss} [%X{trace_id}/%X{span_id}] %-5level %logger{36} - %msg%n</pattern>

配合 OTel 的 MDC 自动注入，%X{trace_id} 会被自动填充，无需手写。

实践建议

先接 Trace 再接 Metrics，最后统一日志格式，避免一次性铺开导致排查困难。采样率按流量分级：核心链路 100%，一般接口 10%，健康检查直接关闭。上线前用 Collector 的 debug 导出器在本地验证数据格式，确认无误再切到 OBSERVE 生产地址。