接入 OpenTelemetry：15 分钟跑通全链路追踪

很多团队对链路追踪「想上又不敢上」，卡点在接入成本。其实用 OpenTelemetry（OTel）标准协议接入炬鲸 OBSERVE，一条完整链路从部署到出图，熟练的话 15 分钟足够。下面按顺序走一遍。

第一步：部署 Collector

OTel Collector 负责接收、处理、转发遥测数据。生产环境建议单独部署，用 Docker 最快：

docker run -d --name otel-collector   -p 4317:4317 -p 4318:4318   -v $PWD/otel-collector-config.yaml:/etc/otelcol/config.yaml   otel/opentelemetry-collector-contrib:latest

关键在配置文件，核心是 receivers 和 exporters 两段：

receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
      http: { endpoint: 0.0.0.0:4318 }
exporters:
  otlphttp:
    endpoint: https://ob.jjhub.cn/otel
    headers:
      Authorization: "Bearer <你的接入令牌>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp]

4317 走 gRPC，4318 走 HTTP，应用按语言习惯任选其一。炬鲸侧用 OTLP over HTTP 接收，鉴权靠令牌头。

第二步：应用侧埋点

Java 最省事的方式是 Java Agent，一行 JVM 参数搞定，不用改代码：

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

Go/Python/Node 则用对应 SDK 手工埋点。以 Go 为例，初始化一个 TracerProvider 并把 exporter 指到 Collector：

ctx := context.Background()
exp, _ := otlptracehttp.New(ctx,
    otlptracehttp.WithEndpoint("localhost:4318"),
    otlptracehttp.WithInsecure())
tp := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exp),
    sdktrace.WithResource(resource.NewWithAttributes(
        semconv.ServiceName("order-svc"))))
otel.SetTracerProvider(tp)

HTTP 框架（gin、echo、chi）建议挂上官方 instrumentation 中间件，自动给每个请求生成 span，不用手写埋点。

第三步：验证链路

先确认 Collector 没报错：docker logs -f otel-collector 里应看到 exporter 持续刷新。然后在应用里制造几次请求，到炬鲸 OBSERVE 的「链路追踪」页面，按 service 名过滤，应该能看到一条条 trace。点开任意一条，检查三件事：

1. span 是否完整覆盖（入口请求 → 下游调用 → 数据库/缓存）。
2. 每个 span 的耗时、状态码、属性是否正常。
3. 点 span 能否下钻到对应日志（需要日志里带 traceId）。

常见问题

• 数据进不来：先查 Collector 日志，再确认 endpoint 和令牌。多数是 exporter 的 header 没写对。
• span 断链：确认跨服务传递用了 W3C Trace Context，不要用各家私有 header。
• 采样率：默认全量采样对高 QPS 系统成本高，生产建议配 parentbased_traceidratio 采样器，保留错误全采。
• 时间对不上：检查主机和容器时区/时钟是否用 NTP 同步，否则 span 时序会错乱。

链路追踪的价值，只有真的接进去、看到完整链路之后才会显现。按上面三步走，先跑通一条，再逐步覆盖更多服务。