GORM Jaeger 链路追踪插件

Jaeger 插件为 GORM 提供分布式链路追踪能力，可记录每次 SQL 执行的完整调用链。

插件功能

追踪信息

插件自动记录以下信息到 Jaeger Span：

• SQL 语句与参数
• 执行耗时
• 影响行数
• 错误堆栈

集成步骤

安装依赖

go get gorm.io/plugin/opentelemetry/tracing

初始化 Jaeger

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/jaeger"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func initJaeger() (*sdktrace.TracerProvider, error) {
    exporter, err := jaeger.New(jaeger.WithCollectorEndpoint(
        jaeger.WithEndpoint("http://localhost:14268/api/traces"),
    ))
    if err != nil {
        return nil, err
    }

    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithResource(resource.NewWithAttributes(
            semconv.SchemaURL,
            semconv.ServiceNameKey.String("gorm-service"),
        )),
    )
    otel.SetTracerProvider(tp)
    return tp, nil
}

注册插件

import "gorm.io/plugin/opentelemetry"

db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
if err != nil {
    panic(err)
}

// 注册 OpenTelemetry/Jaeger 插件
db.Use(opentelemetry.New(opentelemetry.Config{
    ExcludeTables: []string{"logs"}, // 排除不需要追踪的表
}))

追踪上下文传递

在业务代码中使用

func GetUser(ctx context.Context, id uint) (*User, error) {
    var user User
    // GORM 会自动从 ctx 中提取 trace context
    err := db.WithContext(ctx).First(&user, id).Error
    return &user, err
}

HTTP 中间件集成

func tracingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx, span := tracer.Start(r.Context(), r.URL.Path)
        defer span.End()

        r = r.WithContext(ctx)
        next.ServeHTTP(w, r)
    })
}

Jaeger UI 查看

访问界面

打开 http://localhost:16686，选择服务 gorm-service 即可查看追踪记录。

查询示例

在 Jaeger UI 中可看到：

• 每个 SQL 语句作为独立 Span
• SQL 参数以 Tag 形式记录
• 执行耗时以 Duration 展示
• 错误信息以 Logs 形式附加

注意事项

生产环境建议采样率不超过 10%，避免追踪数据量过大影响性能。

敏感参数（如密码）不会自动脱敏，需确认脱敏规则。

Jaeger Collector 地址需根据实际部署配置调整。

要点总结

• Jaeger 插件基于 OpenTelemetry 标准实现链路追踪
• 自动记录 SQL 语句、参数、耗时与错误
• 通过 WithContext 传递 trace context 实现调用链串联
• 配合 Jaeger UI 可可视化查询完整调用链
• 生产环境需控制采样率，避免性能损耗

存放路径：D:\git2\jwdev\articles\GORM\进阶\插件系统\Jaeger 链路追踪.md