OpenTelemetry 是什么

被厂商锁定的痛点

早年做链路追踪，要么用 Zipkin 的 SDK、要么用 Jaeger 的客户端、要么用某云厂商的私有 SDK。一旦选定，埋点代码和厂商强绑定——哪天想换后端，全量重写 instrumentation。更糟的是指标、日志、追踪三家各一套 SDK、各一套格式，数据对不齐。

OTel 在可观测性体系里的位置

它只管「采集 + 导出」这一段（Instrumentation + Collector）。数据的存储与展示（Jaeger / Tempo / Prometheus / Grafana / 商业 APM）由后端负责。所以它不和你现有的监控栈冲突，而是「把数据喂给它们」的中间层。

三者的关系

Metric 看趋势 → Trace 定位问题请求 → Log 看细节。OTel 的精髓是让三者通过 trace_id / span_id / Resource 关联起来，形成闭环，而不是三张互不相干的表。

四个核心角色

traceparent（W3C 标准头）

跨服务传递 trace 上下文的标准 HTTP 头，长这样：traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01。四段分别是：版本 - traceId - parentSpanId - traceFlags（是否采样）。只要所有服务都认识这个头，不管什么语言、什么框架，链路都能串起来。

① 初始化 TracerProvider（全局做一次）

在 main.go 里装配 Exporter + Resource + TracerProvider，并设为全局。这是「初始化写在哪」那篇强调的集中装配原则。

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)

func newTracerProvider(ctx context.Context) (*sdktrace.TracerProvider, error) {
    // 1) Exporter：数据发到 OTLP 端点（如 Collector :4317）
    exp, err := otlptracegrpc.New(ctx,
        otlptracegrpc.WithEndpoint("localhost:4317"),
        otlptracegrpc.WithInsecure(), // 仅开发用，生产走 TLS
    )
    if err != nil { return nil, err }

    // 2) Resource：服务名等元信息，所有 span 都带
    r, err := resource.Merge(resource.Default(),
        resource.NewWithAttributes(semconv.SchemaURL,
            semconv.ServiceName("my-go-service"),
            semconv.ServiceVersion("1.0.0"),
        ))
    if err != nil { return nil, err }

    // 3) TracerProvider：批处理 + 资源属性
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp),   // 批量导出，降开销
        sdktrace.WithResource(r),
        sdktrace.WithSampler(sdktrace.AlwaysSample()), // 生产按需采样
    )
    return tp, nil
}

func main() {
    ctx := context.Background()
    tp, err := newTracerProvider(ctx)
    if err != nil { log.Fatalf("otel init: %v", err) }
    defer func() { _ = tp.Shutdown(ctx) }() // 优雅退出，别丢数据

    otel.SetTracerProvider(tp)            // 设为全局
    otel.SetTextMapPropagator(propagation.TraceContext{}) // W3C 传播
    // ... 启动你的 HTTP / gRPC 服务
}

② 手动创建 Span（在你关心的业务逻辑上）

用全局 Tracer 起 span，务必把返回的 ctx 往下传，否则链路断开（和 go-zero 的 ctx 铁律一致）。

import "go.opentelemetry.io/otel"
import "go.opentelemetry.io/otel/attribute"

func (s *svc) Deduct(ctx context.Context, orderID string) error {
    // 从全局 provider 拿 tracer，起一个 span
    tracer := otel.Tracer("my-go-service/billing")
    ctx, span := tracer.Start(ctx, "billing:deduct")
    defer span.End() // 结束才会被导出

    span.SetAttributes(attribute.String("order_id", orderID)) // 打业务标签

    // 调下游时继续传 ctx —— 链路自动接上
    return s.payClient.Pay(ctx, orderID)
}

③ 自动插桩：HTTP / gRPC 不用手埋

社区 contrib/instrumentation 提供现成的中间件 / 拦截器，自动给每个请求起 span、自动注入/抽取 W3C 头。这是 Gin 项目接 OTel 最省力的一招。

// HTTP（gin / net/http）接入 otelhttp
import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"

handler := otelhttp.NewHandler(yourMux, "my-service")
http.ListenAndServe(":8080", handler) // 每个请求自动带 trace

// 作为客户端调别的服务时，用 otelhttp.Transport 包裹
client := &http.Client{ Transport: otelhttp.NewTransport(http.DefaultTransport) }
// 发出去的请求会自动带 traceparent 头，对端能接上

// gRPC 服务端/客户端接入 otelgrpc
import "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
// server: grpc.NewServer(grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()))
// client: grpc.WithStatsHandler(otelgrpc.NewClientHandler())

① 配置文件开启（etc 目录 yaml）

# user-api.yaml / user-rpc.yaml
Name: user-api
Host: 0.0.0.0
Port: 8888

Trace:
  Name: user-api                # 本服务在链路中显示的名字
  Endpoint: http://jaeger:4318/v1/traces  # OTLP HTTP 地址（或 Zipkin）
  Sampler: 1.0               # 采样率 0~1，1.0=全采
  Batcher: otlp              # otlp 或 zipkin
  ServiceName: user-api    # 可选，覆盖 Name

② 你只做两件事

③ go-zero 内置 vs 手动 OTel 的关系

二者底层是同一套 OTel 数据模型与 OTLP 协议，所以你在 Jaeger / Tempo 看到的链路格式完全兼容。区别只在「谁初始化」：go-zero 自动；Gin / 标准库项目手动。如果某服务用 go-zero、某服务用 Gin，只要都导出 OTLP 到同一个 Collector，跨框架链路依然能拼成一条——这就是 OTel 标准的价值。