Documentation
¶
Overview ¶
Package traceid 提供 HTTP 请求链路追踪 ID（trace_id）的生成、存储键与 context 提取/注入/桥接原语。
trace_id 贯穿整个请求链路（日志、响应体、下游 RPC/MQ），是 ekit 可观测性的基石。 本包是 trace_id 的唯一真相源（single source of truth）：
- Key: 标准库 context 与 RequestContext 中存储 trace_id 的键名
- HeaderKey: HTTP 头名称（X-Trace-Id），用于跨服务透传
- IDLength: trace_id 的标准长度
- NewID: 生成一条符合本包规范的 trace_id（IDLength 位十六进制，#102）—— 生成点唯一，hmw 标准栈与无框架入口都经此取新 ID，不留第二生成点
- ContextWith/FromContext: 标准 context 的注入/提取原语
- FromSpanContext: OTel SpanContext → trace_id 桥接——日志与 APM 双 ID 的关联点（#102）
本包通过 init() 向 logx 注册 trace 提取器，使 logx.Ctx* 方法能从 context 自动提取 trace_id，从而避免 logx 反向依赖 middleware（参见 logx 包文档）。
HTTP 中间件正身（请求进入时透传 + RequestContext 注入）在 oekit/middleware 的 hmw 标准栈；本包只提供生成/key/提取/桥接原语，不做框架绑定。
用法:
// service 层：把 APM trace 桥接进日志链（日志 trace_id = APM trace id）
if sc := trace.SpanContextFromContext(ctx); sc.IsValid() {
ctx = traceid.ContextWith(ctx, traceid.FromSpanContext(sc))
}
traceID := traceid.FromContext(ctx)
// 无上游 trace 的入口（定时任务/MQ 消费等）：先生成再注入
ctx = traceid.ContextWith(ctx, traceid.NewID())
Index ¶
Constants ¶
const ( // Key 是 trace_id 在 Hertz RequestContext 与标准 context 中存储使用的键名。 Key = "trace_id" // HeaderKey 是 trace_id 透传使用的请求/响应头名称。 HeaderKey = "X-Trace-Id" // IDLength 是 trace_id 的标准长度（取自 UUID 前缀，碰撞概率极低）。 IDLength = 12 )
Variables ¶
This section is empty.
Functions ¶
func ContextWith ¶
ContextWith 将 trace_id 注入到标准 context.Context 中。 适用于 service 层、NATS publisher 等不持有 RequestContext 的场景需要向下传递 trace_id 时。
func FromContext ¶
FromContext 从标准 context.Context 中提取 trace_id。 返回空字符串表示上下文中没有 trace_id（中间件未注册或尚未注入）。
func FromSpanContext ¶ added in v0.4.0
func FromSpanContext(sc trace.SpanContext) string
FromSpanContext 把 OTel SpanContext 桥接为本包语义的 trace_id（#102）： 取 APM（OTel）侧的 32 位十六进制 TraceID。调用方经 ContextWith 注入后， logx 输出的 trace_id 与 APM trace 同源——「日志里的 trace_id 和 APM trace 对不上」的双 ID 断轨就此闭合。SpanContext 无效（无 trace）时返回空串， 与 FromContext 的空值口径一致。
反方向（X-Trace-Id → SpanContext）不提供：IDLength 位短 ID 不足 16 字节， 反推不出合法 OTel TraceID；跨进程恢复链路由 HTTP traceparent 头与 OTel 传播器承担，本包不做猜测式重建。
func NewID ¶ added in v0.4.0
func NewID() string
NewID 生成一条新的 trace_id（#102）：IDLength 位十六进制随机串 （crypto/rand 驱动，与既有 X-Trace-Id 的「UUID 前缀」形态一致）。 本包是 trace_id 的唯一真相源，生成也归此包——hmw 标准栈与无框架入口 （定时任务/MQ 消费等）都应经本函数取新 ID，避免第二生成点。OTel span 已在场时优先用 FromSpanContext 桥接 APM trace：日志 trace_id 与 APM trace 同源，双 ID 不断轨。
Types ¶
This section is empty.
Source Files