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.2

这个仓库做什么

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

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

模块	内容	矩阵内依赖
pkg	微工具集 19 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap；v0.10.0 起 uidgen/validator 拆至 kitx）；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约 + Checker；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试	pkg
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入	—
core	应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version）	—
kitx	标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail），自 pkg v0.10.0 拆出	pkg
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge	core、logx
data	数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；all/ 聚合模块已废弃 retract	concurrency、gormx、logx、pkg、redisx、timertask
gormx	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名）	logx、pkg
redisx	Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）	concurrency、logx、pkg
etcdx	etcd 全家——客户端封装（根包：生产默认值/Health 探活/Close(ctx) 幂等）、registry 注册发现实现（SPI 对接 registry/nacos 链路：Lease KeepAlive 注册 + 丢约指数退避自动重注册、prefix Watch 订阅推送、ConfigStore KV 配置监听）、distlock 分布式锁（Session+concurrency.Mutex 公平排队，接口与 redisx/distlock.Locker 同形可互换，可选无 etcd 降级放行）	concurrency、core、logx、registry
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传/一致性哈希（权重感知虚拟副本）	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）	concurrency、core、logx、metrics、pkg、registry、tracing
k8s	Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限）	logx
nns	NNS 服务治理客户端——provider 无关发现/配置/实例缓存	concurrency、core、logx、registry
nns-endpoint	NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——bootstrap.Run 骨架 + healthz	concurrency、logx
hertz	Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）	bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	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 一次