OpenTelemetry 接入炬鲸 OBSERVE：日志、指标、链路一步到位

为什么要用 OpenTelemetry

接入可观测系统最怕被厂商绑定：今天用 A 家的 SDK，明天想换 B 家就得重写埋点。OpenTelemetry（OTel）是一套厂商中立的标准，定义了日志（Logs）、指标（Metrics）、链路（Traces）三类信号，以及统一的采集和传输格式。炬鲸 OBSERVE 原生支持 OTLP 协议，接 OTel 就等于一次把三类数据都接进来，以后换后端也只改一个导出地址，埋点代码一行不用动。

第一步：部署 Collector

推荐用 OTel Collector 做统一网关，应用把数据推给本机或就近的 Collector，Collector 再转发到 OBSERVE。这样应用侧配置极简，收集中间件日志也方便。

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  filelog:
    include: [/var/log/app/*.log]
    operators:
      - type: json_parser
processors:
  batch:
    timeout: 5s
    send_batch_size: 1024
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otlp
    headers:
      Authorization: Bearer <your-token>
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp, filelog]
      processors: [batch]
      exporters: [otlphttp]

第二步：SDK 自动埋点

以 Java 为例，挂上 agent 即可自动采集 HTTP、数据库、消息队列的链路，不改业务代码：

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

Python、Go、Node.js 同理，官方都有对应的 agent 或 SDK。手动埋点只在需要业务自定义 span 时再做，比如给下单、扣款这类关键操作包一层 span，附上订单号等属性。

第三步：关联日志与链路

链路追踪最实用的技巧是把 trace_id 注入日志。Java 用 logback 的 MDC 自动注入：

<encoder>
  <pattern>%d %-5level [%X{trace_id}] %logger{36} - %msg%n</pattern>
</encoder>

这样 OBSERVE 里点开任意一条日志，就能一键跳转到整条链路，反之亦然，排障时不用在两个页面之间来回切。

验证与常见坑

接入完成后先确认三类数据都到了：日志能搜到、指标能查到、链路能打开火焰图。常见的坑有三个：

• 时间不同步：容器和宿主机时钟漂移会导致链路时序错乱，务必用 NTP 或 chrony 同步。
• 采样率：高 QPS 服务建议按比例采样（otel.traces.sampler=traceidratio，0.1 起步），全量采集存储成本很高。
• 鉴权头：Collector 到 OBSERVE 的 exporter 要带上 token，漏了会报 401。