要在go项目中集成opentelemetry实现分布式追踪，1. 安装必要依赖包如otel sdk和导出器；2. 初始化tracerprovider并设置全局tracer，配置采样策略、span处理器和资源信息；3. 使用中间件自动注入trace上下文到http请求；4. 配置导出方式通过otlp或jaeger导出器将数据发送至collector或后端存储。整个流程通过代码初始化和环境变量配置完成，关键在于正确构建tracerprovider并配合中间件实现自动追踪与传播。
在分布式系统中，追踪请求的流转路径是调试和性能优化的关键。Golang项目集成OpenTelemetry SDK，可以实现跨服务的分布式追踪，帮助我们清晰地看到每个请求在各个微服务之间的调用链路。下面从配置入手，讲讲如何在Go项目中落地OpenTelemetry。
安装必要的依赖包
要使用OpenTelemetry，首先得引入相关的SDK和导出器。目前最常用的是官方维护的go.opentelemetry.io/otel以及配套的Exporter（如OTLP、Jaeger等）。
常用的几个依赖：
立即学习“go语言免费学习笔记（深入）”；
go get go.opentelemetry.io/otel go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc go get go.opentelemetry.io/otel/sdk
如果你使用像Jaeger或Zipkin这样的后端，还需要对应的导出器。例如：
go get go.opentelemetry.io/otel/exporters/jaeger
这些包构成了基础的SDK能力，包括TracerProvider、Sampler、SpanProcessor等核心组件。
初始化TracerProvider并设置全局Tracer
OpenTelemetry的核心是构建一个TracerProvider，它是生成Trace的源头。初始化时需要指定采样策略、Span处理器和资源信息。
基本结构如下：
import (
"context"
"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.21.0"
)
func initTracer() func(context.Context) error {
// 创建OTLP gRPC导出器，发送到Collector
exporter, err := otlptracegrpc.New(context.Background())
if err != nil {
panic(err)
}
// 设置采样策略：这里为全采样，生产环境建议使用ParentBasedSampler
sampler := sdktrace.ParentBasedSampler{
Sampler: sdktrace.TraceIDRatioBased(1.0), // 100%采样率
}
// 构建TracerProvider
tp := sdktrace.NewTracerProvider(
sdktrace.WithSampler(sampler),
sdktrace.WithBatcher(exporter),
sdktrace.WithResource(resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceNameKey.String("my-go-service"),
)),
)
// 设置为全局TracerProvider
otel.SetTracerProvider(tp)
return tp.Shutdown
}-
WithSampler控制是否记录某个请求的完整Trace。 -
WithBatcher负责将Span异步批量发送出去。 -
WithResource是元数据信息，用于标识服务名、实例等。
这个初始化过程一般在程序启动阶段执行一次即可。
在HTTP服务中自动注入Trace上下文
如果你使用标准库的http.Handler或者类似Gin、Echo这样的框架，可以通过中间件来自动处理Trace的传播与注入。
以标准库为例：
import (
"net/http"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
func main() {
shutdown := initTracer()
defer shutdown(context.Background())
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
_, span := otel.Tracer("my-tracer").Start(r.Context(), "handleRequest")
defer span.End()
w.Write([]byte("Hello"))
})
http.ListenAndServe(":8080", otelhttp.NewHandler(handler, "root-handler"))
}关键点：
- 使用
otelhttp.NewHandler包装原始Handler，自动处理HTTP头中的Trace-ID和Span-ID传播。 - 每个请求都会自动生成Root Span，并携带正确的Trace上下文。
对于Gin或其他框架，也有类似的中间件支持，比如gin-gonic的otelgin。
配置导出方式与连接Collector
实际部署中，推荐通过OTLP协议将Trace数据发送给OpenTelemetry Collector，再由Collector统一转发到后端存储（如Jaeger、Prometheus + Tempo等）。
你可以通过环境变量控制导出行为，而无需硬编码配置：
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" export OTEL_SERVICE_NAME="my-go-service"
这样做的好处是：
- 不需要修改代码就能切换导出目标
- 可配合Kubernetes ConfigMap或环境变量进行灵活配置
如果想直接导出到Jaeger而不是走Collector，也可以改用Jaeger Exporter：
import (
"go.opentelemetry.io/otel/exporters/jaeger"
)
exp, err := jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint("http://jaeger-collector:14268/api/traces")))但更推荐使用Collector作为中间层，便于统一管理和扩展。
基本上就这些。整个流程不算复杂，但容易忽略的地方在于环境变量配置和导出器的选择。只要TracerProvider正确初始化，加上中间件对HTTP请求的自动追踪，就可以轻松实现完整的分布式追踪能力了。
