Documentation
¶
Overview ¶
Package trace 提供基于 OpenTelemetry 的分布式链路追踪: OTLP 导出配置化 (gRPC/HTTP 双协议)、HTTP 服务端 span 中间件与 trace_id 日志联动。
初始化即接入——app.Boot 场景经 Wire 一行(放首位: 组件逆序释放时 trace 最后关闭, 其余资源关停产生的在途 span 得以全量刷盘), span 中间件随装配 自动注入并接管 X-Request-Id, server.trace_id 配置节无需再设置:
type Conf struct {
app.Base
Trace trace.Config `yaml:"trace"`
}
app.MustRun(&app.Boot[Conf]{
Wire: func(c *Conf) []app.Component {
return []app.Component{
trace.NewBoot(c.Trace), // Wire 首位
database.NewBoot(&c.Database),
}
},
})
对应 yaml 配置节:
trace: service_name: tata # 服务名(默认 basic-go), tracing 后端按服务聚合 protocol: grpc # OTLP 导出协议 grpc(默认, 4317)/http(4318) endpoint: 127.0.0.1:4317 # collector 地址(默认按协议取本地端口) secure: false # 默认明文连接; 生产开启 TLS 或经代理终结
span 经 W3C traceparent 头跨服务传递, trace id(32 位 hex)自动桥接 X-Request-Id 约定, middleware.TraceIDOf/TraceIDField 照常可用。
本包依赖 OpenTelemetry SDK 与 gin; 未 import 本包时 otel 依赖不进依赖树。 独立使用(不经 app.Boot)时手动调用: 启动时 Init(cfg) + 路由挂载 Middleware(), 退出前最后调用 Close()。
Index ¶
Constants ¶
const ( // ProtocolGRPC OTLP over gRPC, 默认协议 ProtocolGRPC = "grpc" // ProtocolHTTP OTLP over HTTP(Protobuf 载荷) ProtocolHTTP = "http" )
OTLP 导出协议与默认约定
Variables ¶
This section is empty.
Functions ¶
func Close ¶
func Close()
Close 刷盘并关闭全局 TracerProvider: 等待在途 span 导出完成(至多 ShutdownTimeout)。 通常在 app.Boot 的 Close 钩子中最后调用(其余资源释放之后, 在途 span 全量导出)。 幂等: 未初始化时为空操作, 重复调用安全。
func Init ¶
Init 初始化全局 TracerProvider 并注册 W3C 传播协议(TraceContext + Baggage)。 exporter 懒连接: collector 暂不可达不影响启动, 后台批量导出自动重试。 通常在 app.Boot 的 Init 钩子中调用; 重复调用需先 Close, 否则返回错误。
func Middleware ¶
func Middleware() gin.HandlerFunc
Middleware 构建链路追踪中间件, 经 ginx.Gin.Middlewares(或原生 gin Use)注入:
提取 W3C traceparent(跨服务串联上游) -> 按路由模板启动 server span -> 桥接 X-Request-Id 约定 -> c.Next
span 上下文经 c.Request.WithContext 回写, handler 侧无感知, 后续创建的 子 span 与 Tracer 调用均挂到当前链路。otel trace id 为 16 字节 32 位 hex, 与 X-Request-Id 约定格式一致: 注入 gin context 后 middleware.TraceIDOf / TraceIDField 照常可用, 日志聚合复用既有约定; 与 TraceID 中间件同时启用时, 本中间件后执行并覆盖其写入的随机 id(建议只启用其一)。
未调用 Init 时全局 provider 为 noop, span 上下文无效, 本中间件优雅降级为无副作用。
Types ¶
type Boot ¶
type Boot struct {
// Config 链路追踪配置
Config Config
}
Boot 组件适配器: 一行接入 app.Boot 的 Wire 装配钩子(结构化匹配 app.Component 与 app.Middlewarer 约定, 无需 import app)。
装配位置约定: Wire 列表中放首位——组件逆序释放时 trace 最后关闭, 其余资源关停操作产生的在途 span 得以全量刷盘(与 Close 的"最后调用"约定一致)。 span 中间件接管 X-Request-Id 约定, server.trace_id 配置节无需再设置。
func NewBoot ¶
NewBoot 构建链路追踪组件适配器: Init 初始化全局 TracerProvider, Middlewares 贡献 HTTP 服务端 span 中间件, Close 刷盘并释放。
trace.NewBoot(c.Trace) // OTLP 导出 + span 中间件 + 关停刷盘, 一行接入
func (*Boot) Middlewares ¶
func (b *Boot) Middlewares() []gin.HandlerFunc
Middlewares 贡献 HTTP 服务端 span 中间件, 由装配方在路由构建前注入引擎。
type Config ¶
type Config struct {
// ServiceName 服务名, 作为 span 的资源标识(service.name 属性),
// 同一服务的所有实例应保持一致, 在 tracing 后端按服务聚合
ServiceName string `yaml:"service_name" toml:"service_name" json:"service_name" mapstructure:"service_name"`
// Protocol OTLP 导出协议: "grpc"(默认) | "http", 非法值归一为 grpc
Protocol string `yaml:"protocol" toml:"protocol" json:"protocol" mapstructure:"protocol"`
// Endpoint collector 地址(host:port); 未设置时按协议取默认端口
// (grpc 127.0.0.1:4317, http 127.0.0.1:4318)
Endpoint string `yaml:"endpoint" toml:"endpoint" json:"endpoint" mapstructure:"endpoint"`
// Secure 是否使用 TLS 加密连接 collector: 默认 false 明文连接,
// 面向本地/内网 collector 的快速接入; 生产环境务必开启,
// 或经由 sidecar/网关终结 TLS 后再对接
Secure bool `yaml:"secure" toml:"secure" json:"secure" mapstructure:"secure"`
// SampleRatio 采样率, 取值 0.0~1.0(默认 1.0 全量); 非法值回退全量。
// 被采样丢弃的 span 仍产生有效 TraceID, 日志聚合与跨服务传递不受影响
SampleRatio float64 `yaml:"sample_ratio" toml:"sample_ratio" json:"sample_ratio" mapstructure:"sample_ratio"`
// Headers OTLP 导出的附加请求头(如 collector 鉴权凭证);
// 注意 grpc 仅在建连时发送, http 每次请求携带, 鉴权场景建议 http 协议
Headers map[string]string `yaml:"headers" toml:"headers" json:"headers" mapstructure:"headers"`
// ExportTimeout 单次导出的超时时间(默认 5s)
ExportTimeout time.Duration `yaml:"export_timeout" toml:"export_timeout" json:"export_timeout" mapstructure:"export_timeout"`
// ShutdownTimeout Close 时等待在途 span 刷盘的最大时长(默认 5s)
ShutdownTimeout time.Duration `yaml:"shutdown_timeout" toml:"shutdown_timeout" json:"shutdown_timeout" mapstructure:"shutdown_timeout"`
}
Config 链路追踪配置, 内嵌到业务配置结构体后经 app.Boot 加载, 或独立使用时直接构造字面量; 未设置(零值)时 applyDefaults 兜底。