tracing

README

tracing

分布式追踪门面——OTel 接入/trace_id 真相源/HTTP·Redis·GORM 插桩装饰器

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/tracing@v0.2.0

这个仓库做什么

tracing 是分布式追踪门面：OTel 接入、trace_id 唯一真相源、HTTP/Redis/GORM 插桩装饰器。

口径：核心组件零 tracing 强制注入，装饰器显式接入——redisx/gormx 等核心构造无任何可观测性副作用，需要 span 时用本仓装饰器一行接入。

组成

包	做什么
根包	tracing.Init(Config)：OTLP 导出器 + provider（Endpoint 为空 = 仅本地 provider，零网络）
traceid	trace_id 生成/提取/桥接：Middleware()、FromContext、ContextWith。logx 的 Ctx* 方法自动读取
httpotel	net/http 插桩（Transport() / WrapTransport）
redisotel	go-redis 插桩（InstrumentTracing）
gormotel	GORM 插桩插件（NewPlugin，db.Use 显式挂载）

快速使用

import "github.com/oekit/tracing"

provider, _ := tracing.Init(tracing.Config{
    ServiceName: "my-service",
    Endpoint:    "otel-collector:4317",
    Insecure:    true,
})
defer provider.Shutdown(context.Background())

装饰器接入（均为显式、无 SDK 时 noop）：

import (
    gormotel "github.com/oekit/tracing/gormotel"
    redisotel "github.com/oekit/tracing/redisotel"
)

// GORM：显式挂插件
_ = db.Use(gormotel.NewPlugin(gormotel.WithDBName("mydb")))

// Redis：装饰已创建的 client
_ = redisotel.InstrumentTracing(rdb.Client())

边界

• Hertz/Kitex 框架侧 instrumentation 分属 hertz（hertzotel/hertztracer） 与 kitex（kitexotel）——同一服务 OTel 与 OpenTracing 二选一，叠加会双 span

矩阵总览

矩阵总览（23 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 16 合 1（errors/validator/stringx/…）	—
concurrency	并发与流控原语	—
logx	日志门面 + shutdown	—
core	应用基建件	—
istio	Istio XDS	—
metrics	Prometheus 门面	core
tracing	OTel + traceid	logx
registry	注册发现 + Nacos + 配置	core、logx
data	缓存检查器	concurrency、logx
gorm	SQL/CRUD	logx、pkg
redis	Redis 全家	concurrency、data、logx
httpx	HTTP 客户端	concurrency、core、logx、metrics、registry、tracing
network	轻量网络件	concurrency、logx、tracing
timertask	定时任务	concurrency、logx
middleware	Hertz 中间件栈	concurrency、core、logx、metrics、pkg、registry、tracing
nns	服务治理门面	concurrency、core、logx、registry
nns-endpoint	端点熔断重试	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用引导	concurrency、logx
handler	CRUD handler	concurrency、core、gorm、logx、metrics、middleware、pkg、registry、tracing
hertz	Hertz 运行时	bootstrap、concurrency、core、logx、metrics、nns、registry、tracing
kitex	Kitex 生态	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	流程编排	concurrency、logx
kitex-examples	Kitex 示例	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE

Documentation

Overview

Package tracing 提供 OpenTelemetry 分布式追踪初始化。

直接基于 go.opentelemetry.io/otel + OTLP gRPC 导出器实现（不依赖任何 HTTP/RPC 框架，纯 Kitex 服务引用本包不会引入 Hertz），一行代码完成：

• OTLP gRPC Trace Exporter + BatchSpanProcessor
• OTLP gRPC Metrics Exporter（15s 周期读取）+ Go Runtime 指标采集
• B3 + OpenTracing + W3C TraceContext + Baggage 传播器
• service.name 资源属性

快速接入

provider, err := tracing.Init(tracing.Config{
    ServiceName: "wechat",
    Endpoint:    "otel-collector:4317",
    Insecure:    true,
})
if err != nil {
    log.Fatal(err)
}
defer provider.Shutdown(context.Background())

// Hertz server tracing（hertzotel 住在 github.com/oekit/hertz 仓）
tracing := hertzotel.NewServerTracing()
h := server.New(server.WithHostPorts(":8080"), tracing.Option)
h.Use(tracing.Middleware)

// ehttp client tracing
client := ehttp.NewClient("moyu", ehttp.WithTracing())

配置说明

• ServiceName: 服务名称，写入 resource 的 service.name 属性
• Endpoint: OTLP gRPC 地址，如 "otel-collector:4317"；为空时不创建 导出器、不发起网络连接（仅安装本地 provider）
• Insecure: 是否跳过 TLS（本地开发用 true，生产用 false）
• SampleRate: 采样率，0.0~1.0；0 < SampleRate < 1.0 时启用 ParentBased(TraceIDRatioBased)，其余（含 <= 0）为全量采样

重复调用

Init 会安装全局 provider；重复调用会自动关闭上一个被替换的 provider 后再安装新实例。常规服务应只 Init 一次（bootstrap 已保证）。

与 bootstrap 集成

bootstrap.Run 会自动初始化 tracing：

b, _ := bootstrap.New(bootstrap.WithServiceName("my-service"),
    bootstrapobs.WithTracing(tracing.Config{Endpoint: "otel-collector:4317"})) // bootstrap/obs
b.Run(func(app *bootstrap.App) error {
    // ...
})

子包（装饰器显式接入——核心组件不做 tracing 强制注入）

• httpotel: 标准库 net/http 客户端追踪（otelhttp Transport 封装）
• redisotel: go-redis 追踪（redisotel.InstrumentTracing(client.Client())）
• gormotel: GORM 追踪插件（db.Use(gormotel.NewPlugin())）
• traceid: trace_id 生成/提取/桥接

Hertz/Kitex 框架侧 instrumentation 分属 github.com/oekit/hertz（hertzotel/ hertztracer）与 github.com/oekit/kitex（kitexotel）。

Index

• type Config
• type Provider
  • func Init(cfg Config) (Provider, error)

Types

type Config

type Config struct {
	// ServiceName 服务名称，如 "wechat"、"fuxi_engine"。
	ServiceName string

	// Endpoint OTLP gRPC 地址，如 "otel-collector:4317"。
	// 为空时不创建 OTLP 导出器、不发起任何网络连接，仅安装本地 provider。
	Endpoint string

	// Insecure 是否跳过 TLS（本地开发用 true，生产用 false）。
	Insecure bool

	// SampleRate 采样率，0.0~1.0。
	// 0 < SampleRate < 1.0 时启用 ParentBased(TraceIDRatioBased) 采样；
	// SampleRate >= 1.0 或 <= 0 均为全量采样（默认 1.0）——<=0 沿用旧版
	// "静默全量" 语义，不视为错误。
	SampleRate float64
}

Config 是 OpenTelemetry Provider 的配置。

type Provider

type Provider interface {
	Shutdown(ctx context.Context) error
}

Provider 是 tracing provider 的最小接口，仅暴露 Shutdown 能力。 用于解耦调用方对具体 OTel SDK 实现的直接依赖。

func Init

func Init(cfg Config) (Provider, error)

Init 初始化 OpenTelemetry 全局 TracerProvider、Propagator（Endpoint 非空时 还包含 MeterProvider 与 Go runtime 指标采集），返回 Provider 接口用于 关闭时 flush。进程退出前调用 provider.Shutdown(ctx) 确保数据 flush。

行为说明：

• Propagator: B3 + OpenTracing + W3C TraceContext + Baggage（与旧 hertz-contrib/obs-opentelemetry/provider 的默认组合一致）
• 采样: 0 < SampleRate < 1.0 → ParentBased(TraceIDRatioBased(rate))； SampleRate >= 1.0 或 <= 0 → 全量采样
• Endpoint 非空时同时初始化 OTLP gRPC Metrics（15s 周期读取 + runtime 指标）； Endpoint 为空时跳过导出器初始化，不产生网络连接
• 重复调用 Init 会自动关闭上一个 provider 后再安装新 provider； 被替换 provider 的原持有方再调用 Shutdown 会得到 already-shutdown 类错误，可安全忽略。常规服务应只 Init 一次