10 分钟接入 OpenTelemetry 链路追踪到炬鲸 OBSERVE

前置条件

开始前确认三件事：服务能访问炬鲸 OBSERVE 的 Collector 端点（默认 otel-collector.jjhub.cn:4317 走 gRPC，4318 走 HTTP）；拿到了租户的接入 Token（在控制台「接入管理 → 数据接入」里生成）；SDK 版本尽量用最新的稳定版。下面以 Java（Spring Boot）和 Go 两个最常用的场景为例，其他语言的步骤完全一致，只有包名和初始化写法不同。

第一步：引入 OpenTelemetry SDK

Java 项目在 pom.xml 里加依赖，用 OpenTelemetry Java Agent 的方式最省事，改启动命令即可，不侵入代码：

java -javaagent:opentelemetry-javaagent.jar   -Dotel.service.name=order-api   -Dotel.exporter.otlp.endpoint=http://otel-collector.jjhub.cn:4318   -Dotel.metrics.exporter=none   -jar order-api.jar

Go 项目则用官方 SDK 初始化一个 TracerProvider：

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/sdk/trace"
)

exp, _ := otlptracehttp.New(context.Background(),
    otlptracehttp.WithEndpoint("otel-collector.jjhub.cn:4318"),
    otlptracehttp.WithInsecure())
tp := trace.NewTracerProvider(trace.WithBatcher(exp))
otel.SetTracerProvider(tp)

第二步：配置导出端点和鉴权

导出端点是关键配置，写错这一行整条链路都看不到数据。要点有三个：一是协议要和端口对应，4317 是 gRPC、4318 是 HTTP，别混用；二是鉴权，炬鲸要求在请求头里带上接入 Token，Java Agent 用 -Dotel.exporter.otlp.headers=Authorization=Bearer <token>，Go 用 otlptracehttp.WithHeaders(map[string]string{"Authorization": "Bearer <token>"})；三是 service.name 一定要设，它是控制台里区分服务的唯一标识，多个实例共用一个名字即可，靠 host.name 或实例 ID 区分副本。

第三步：采样策略与验证

全量采集在生产环境既不必要也费钱，建议头部采样 + 尾部采样结合：默认用 traceidratio 按 10%~20% 比例采样，同时把错误请求和慢请求强制保留。Java Agent 通过 -Dotel.traces.sampler=traceidratio -Dotel.traces.sampler.arg=0.1 配置，Go 则用 trace.ParentBased(trace.TraceIDRatioBased(0.1)) 包一层。接入完成后，在代码里打一个测试请求，等 30 秒左右，到控制台「链路追踪」页按 service.name 过滤，能看到完整的 span 瀑布图、每段耗时和错误标记，即说明接入成功。常见的坑：Token 没带导致静默丢弃、端点上多了 /v1/traces 路径、容器网络隔离访问不到 4318 端口，排查时优先看 Collector 端是否有接收日志。