OpenTelemetry 三件套接入炬鲸：从埋点到看到调用链

整体架构

三步走：应用用 OpenTelemetry SDK 埋点 → 集群内跑 OTel Collector 统一接收、批处理、转发 → 炬鲸后端按 OTLP 协议接收落库。推荐中间加一层 Collector，而不是让应用直连炬鲸：它可以本地缓冲、脱敏、采样，应用重启也不丢数据，还避免了每个服务都维护一份推送配置。

Collector 配置

下面这份 otelcol-config.yaml 可以直接用：三个 receiver（otlp 收 SDK 数据、hostmetrics 收机器指标、filelog 收日志文件），统一用 OTLP HTTP exporter 推到炬鲸：

receivers:
  otlp:
    protocols: { grpc: { endpoint: 0.0.0.0:4317 }, http: { endpoint: 0.0.0.0:4318 } }
  hostmetrics:
    scrapers: { cpu: {}, memory: {}, disk: {}, network: {} }
    collection_interval: 30s
  filelog:
    include: [ /var/log/app/*.log ]
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<level>\S+) (?P<message>.*)$'

processors:
  batch: { timeout: 5s, send_batch_size: 512 }
  memory_limiter: { limit_mib: 512 }

exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otel
    headers: { "x-api-key": "${JJHUB_TOKEN}" }

service:
  pipelines:
    traces:  { receivers: [otlp], processors: [batch], exporters: [otlphttp] }
    metrics: { receivers: [otlp, hostmetrics], processors: [batch], exporters: [otlphttp] }
    logs:    { receivers: [otlp, filelog], processors: [batch], exporters: [otlphttp] }

关键在 headers 里的 x-api-key，去控制台"接入管理"页面生成。别硬编码进仓库，用环境变量注入，token 轮换时只改环境即可。

应用侧埋点

Java 用 javaagent 自动埋点，零代码改动：

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

HTTP、数据库、消息队列的调用会自动生成 span，不用改业务代码。Go 侧手动埋点更常见，给关键函数包一层：

ctx, span := tracer.Start(ctx, "query_order")
defer span.End()

埋点时顺手把业务 ID（订单号、用户 ID）写进 span attribute，排查时能直接按订单号反查整条链路，这是自动埋点给不了的业务上下文。

日志与 Trace 关联

要让日志能点进链路，日志里必须带 trace_id。Java 用 Logback 的 MDC 注入，配置一句：

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

Go 侧把 span.SpanContext().TraceID() 写进日志字段即可。两侧的 trace_id 落进炬鲸后，在任意一条日志上都能一键跳转到对应调用链。

常见问题

常见坑有三个：一是时钟不同步，容器和宿主机漂移会导致 trace 断层，统一配 NTP；二是采样率太高，生产环境把 traces 采样调到 5%-10%，日志保留全量、指标全量；三是 exporter 漏配 headers 报 401，先用 curl 带 token 验证一遍再查应用侧配置，省得两头猜。