5 分钟接入：用 OpenTelemetry 把 Go 服务送进炬鲸 OBSERVE

前置准备

假设你有一个跑在 Kubernetes 里的 Go 服务，已经用结构化日志打点。目标是把 Trace、Metrics、Logs 三路信号都送进炬鲸 OBSERVE，并且能和日志检索、告警联动。

先拿到接入地址和 token：控制台 → 接入向导 → OpenTelemetry，会生成一个带 token 的 OTLP endpoint，形如 https://ob.jjhub.cn/otlp，token 放在 HTTP 头 Authorization 里。

初始化 SDK

用官方 SDK，在 main 里初始化 trace 和 metric provider：

res := resource.NewWithAttributes(
    semconv.SchemaURL,
    semconv.ServiceName("order-service"),
    semconv.ServiceVersion("v1.2.3"),
    attribute.String("deployment.environment", "prod"),
)

ctx := context.Background()
exp, _ := otlptracehttp.New(ctx,
    otlptracehttp.WithEndpoint("ob.jjhub.cn"),
    otlptracehttp.WithHeaders(map[string]string{"Authorization": token}),
)
tp := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exp),
    sdktrace.WithResource(res),
    sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.1))),
)
otel.SetTracerProvider(tp)

三个点值得注意：ServiceName 一定要设，它是 OBSERVE 里按服务维度聚合的 key；环境名用 deployment.environment，别用自定义 key，否则和 Trace 面板的环境过滤对不上；采样率生产环境建议从 0.1 起步，全量采样会吃掉大量存储和网络。

埋点：HTTP 与数据库

RPC/HTTP 用 otelhttp 包一层 middleware 就能自动埋点，数据库用 otelsql 或对应驱动的 instrumentation。业务里需要手动建 span 的地方用 tracer.Start：

tr := otel.Tracer("order-service")
ctx, span := tr.Start(ctx, "create_order")
defer span.End()
span.SetAttributes(attribute.Int("order.id", id))

重点是把业务 ID（订单号、用户 ID）用 SetAttributes 挂到 span 上，之后在 OBSERVE 里能按这些属性检索链路、定位到具体业务对象。

日志关联

让日志能跳转到 Trace，核心是往日志里注入 traceId / spanId。用 zap 或 logrus 的话，接一个 OTel 的 hook，自动把当前 span 的 traceId 写进每条日志。这样在 OBSERVE 里点一条日志就能看到它属于哪条链路，反过来从链路也能点进日志。

常见坑

• 忘设 resource 的 ServiceName，导致所有服务混在一个叫 unknown_service 的节点下。
• 导出器用 http、而服务在集群内时 DNS 走不通 OTLP endpoint，先用 curl 验证网络连通性。
• Trace 采样太低，排查时没有链路可看；建议对错误请求做固定保留，SDK 的 Sampler 支持 always-on 的错误分支。
• Metrics 的 histogram 没配 buckets，默认桶对延迟分布不友好，QPS 和耗时要分别设置合适的桶边界。