README
¶
ekit-tracing
OpenTelemetry 分布式追踪 + trace_id 唯一真相源。
本仓库是 ekit（git.enjoye.top/enjoydream/ekit v0.34.0）
拆分出的独立 Go module，属于 oekit ekit 子项目矩阵（Round-2 深拆粒度）。
安装
go get github.com/oekit/tracing@v0.1.0
包清单
- 根包 `tracing`（import `github.com/oekit/tracing`）— Init(Config) OTel 接入
- `traceid/` — trace_id 生成/提取/桥接（FromContext/ContextWith/Middleware）
- `httpotel/` — net/http OTel 插桩
- `redisotel/` — go-redis OTel 插桩
矩阵总览（20 活跃仓 + 19 微库，自动生成）
ekit-observability已在 Round-2 解散归档；本表由源码 import 自动生成。 依赖严格单向：工具微库/L0 → 可观测门面 → registry → data/httpx/middleware → nns/bootstrap → hertz/kitex。
当前仓库依赖
详见上方矩阵表中本仓库行。
与 ekit 单体仓库的关系
- 代码与 ekit v0.34.0 等价，module 路径
git.enjoye.top/enjoydream/ekit/...→github.com/oekit/tracing/... - 各子仓库独立发版（SemVer）；开发规范沿用 ekit AGENTS.md 约定
License
见 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（通过 instrumentation/hertzotel 接入）
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：
bootstrap.Run(bootstrap.Config{
Tracing: &tracing.Config{
Endpoint: "otel-collector:4317",
},
}, func(app *bootstrap.App) error {
// ...
})
子包 ¶
- instrumentation/hertzotel: Hertz server/client 追踪（含 NewServerTracing 成对 API）
- instrumentation/kitexotel: Kitex server/client 追踪
- instrumentation/httpotel: HTTP 客户端追踪（标准库 http.Client）
- instrumentation/redis: Redis 追踪
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
Provider 是 tracing provider 的最小接口，仅暴露 Shutdown 能力。 用于解耦调用方对具体 OTel SDK 实现的直接依赖。
func Init ¶
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 一次
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package httpxotel 为标准库 net/http 提供 OpenTelemetry 追踪的 Transport 封装。
|
Package httpxotel 为标准库 net/http 提供 OpenTelemetry 追踪的 Transport 封装。 |
|
instrumentation
|
|
|
httpotel
Package httpxotel 为标准库 net/http 提供 OpenTelemetry 追踪的 Transport 封装。
|
Package httpxotel 为标准库 net/http 提供 OpenTelemetry 追踪的 Transport 封装。 |
|
redis
Package redisotel 为 go-redis 客户端提供 OpenTelemetry 追踪插桩。
|
Package redisotel 为 go-redis 客户端提供 OpenTelemetry 追踪插桩。 |
|
Package redisotel 为 go-redis 客户端提供 OpenTelemetry 追踪插桩。
|
Package redisotel 为 go-redis 客户端提供 OpenTelemetry 追踪插桩。 |
|
Package traceid 负责 HTTP 请求链路追踪 ID（trace_id）的生成、透传与提取。
|
Package traceid 负责 HTTP 请求链路追踪 ID（trace_id）的生成、透传与提取。 |