tracing

README

ekit-tracing

OpenTelemetry 分布式追踪 + trace_id 唯一真相源。

本仓库是 ekit（git.enjoye.top/enjoydream/ekit v0.34.0） 拆分出的独立 Go module，属于 yi-nology ekit 子项目矩阵（Round-2 深拆粒度）。

安装

go get github.com/yi-nology/ekit-tracing@v0.1.0

包清单

• 根包 `tracing`（import `github.com/yi-nology/ekit-tracing`）— Init(Config) OTel 接入
• `traceid/` — trace_id 生成/提取/桥接（FromContext/ContextWith/Middleware）
• `httpotel/` — net/http OTel 插桩
• `redisotel/` — go-redis OTel 插桩

依赖关系

子项目矩阵与依赖方向（自底向上，19 仓）：

ekit-core            文本/数据工具 + governance/lifecycle/version      （零内部依赖）
ekit-concurrency     并发与流控原语                                     （零内部依赖）
ekit-logx            日志门面 + shutdown                                （零内部依赖）
ekit-istio           Istio Proxyless                                    （零内部依赖）
  ekit-metrics       Prometheus 门面                          → core
  ekit-tracing       OTel + traceid                           → logx
  ekit-registry      注册发现 + 配置                          → core, logx
    ekit-data        缓存抽象 + 定时任务                      → core, logx, concurrency
      ekit-gorm      SQL/GORM 全家                            → core, logx
      ekit-redis     Redis 全家                               → data, core, logx
    ekit-httpx       HTTP 客户端 + 负载均衡                   → core, concurrency, logx, metrics, tracing, registry
      ekit-nns       服务治理客户端                           → httpx, registry, core, logx, tracing, metrics
        ekit-bootstrap 应用引导
    ekit-middleware  Hertz 中间件栈                           → core, concurrency, logx, metrics, tracing, registry
    ekit-hertz       Hertz 运行时/适配/instrumentation        → middleware, gorm, nns, registry, metrics, tracing, logx, core
    ekit-kitex       Kitex 生态                               → nns, registry, core, concurrency, logx, metrics
  ekit-workflow      流程编排                                 → concurrency, logx

注：ekit-observability 已在 Round-2 深拆中解散——logx 迁 [ekit-logx]、metrics 迁 [ekit-metrics]、 tracing/traceid 迁 [ekit-tracing]、shutdown 迁 [ekit-logx]；原仓库已归档。

依赖：ekit-logx（traceid→logx）。框架专属 instrumentation（hertzotel/hertztracer 在 ekit-hertz、kitexotel 在 ekit-kitex）。

与 ekit 单体仓库的关系

• 代码与 ekit v0.34.0 等价，module 路径 git.enjoye.top/enjoydream/ekit/... → github.com/yi-nology/ekit-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

• 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 一次