trace

README

trace

trace 是 Genesis 的 L0 链路追踪组件，基于 OpenTelemetry 提供全局 tracing 初始化、Gin/gRPC 中间件包装，以及 MQ 场景下的传播辅助函数。它面向微服务和组件库场景，解决 tracing 初始化、上下文传播和消息消费关系建模的统一问题。

组件定位

trace 当前采用全局模式工作：

• Init() 会创建 TracerProvider
• 同时会把它安装为 OpenTelemetry 全局 TracerProvider
• 也会安装全局 TextMapPropagator

这意味着它更适合作为应用启动时初始化一次的基础组件，而不是在运行时反复调用。

Discard() 也是全局模式：它不是一个局部 helper，而是安装一个“不导出数据”的全局 provider，仅在本地生成 TraceID 并维持传播链路。

快速开始

shutdown, err := trace.Init(&trace.Config{
    ServiceName: "my-service",
    Endpoint:    "localhost:4317",
    Sampler:     1.0,
})
if err != nil {
    return err
}
defer shutdown(context.Background())

配置边界

trace.Config 当前是一个最小 OTLP gRPC 初始化器，支持：

• ServiceName
• Endpoint
• Sampler
• Batcher，可选 batch 或 simple
• Insecure

其中 Batcher 在默认配置里会设置为 batch，而空字符串行为也等同于 batch，适合常规服务；simple 更适合测试或需要更直接刷出的场景。组件当前不负责更复杂的 exporter 能力，例如 TLS、认证头和附加 resource attributes。

HTTP / gRPC 中间件

r := gin.New()
r.Use(trace.GinMiddleware("gateway"))

conn, _ := grpc.NewClient(
    "localhost:9090",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
    grpc.WithStatsHandler(trace.GRPCClientStatsHandler()),
)

MQ 传播与链路关系

组件提供统一的生产/消费 helper，消费侧支持两种关系：

• link：默认值，适合异步、批处理、多消费者组
• child_of：适合端到端演示和串成单条 trace 的排障场景

pubCtx, pubSpan, headers := trace.StartProducerSpan(
    ctx,
    tracer,
    trace.SpanNameMQPublish("orders.created"),
    trace.MessagingMeta{
        System:      trace.MessagingSystemNATS,
        Destination: "orders.created",
        Operation:   trace.MessagingOperationPublish,
    },
)
defer pubSpan.End()

consumeCtx, consumeSpan := trace.StartConsumerSpanFromHeaders(
    msg.Context(),
    tracer,
    trace.SpanNameMQConsume("orders.created"),
    msg.Headers(),
    trace.MessagingMeta{
        System:        trace.MessagingSystemNATS,
        Destination:   "orders.created",
        Operation:     trace.MessagingOperationProcess,
        ConsumerGroup: "workers",
        TraceRelation: trace.MessagingTraceRelationLink,
    },
)
defer consumeSpan.End()

生命周期

• Init() 通常应在应用启动时调用一次
• 返回的 shutdown 函数由调用方负责执行；关闭后若全局状态仍指向该实例，会回退到安全默认值
• Discard() 虽然不导出 trace 数据，但仍然会修改全局 tracing 状态

推荐实践

• 应用启动时统一初始化一次 trace
• HTTP、gRPC、MQ 传播都共用同一套全局 tracing 状态
• 异步消息默认使用 link，只在确实需要单条 trace 演示时使用 child_of
• 不要把 Discard() 当成“无副作用的局部 tracer helper”

相关文档

• 包文档
• 可观测性实践
• Genesis 文档目录

Documentation

Overview

Package trace 提供 Genesis 的 OpenTelemetry 链路追踪初始化与传播辅助能力。

这个组件当前采用“全局模式”工作：Init 和 Discard 都会安装全局 TracerProvider 与 TextMapPropagator。这样做便于 Gin、gRPC、数据库插件和 MQ helper 共享同一套全局 tracing 状态；代价是重复初始化会覆盖之前安装的 全局 provider。

因此推荐的使用方式是：应用启动时只初始化一次 trace，并在退出时调用返回的 shutdown 函数。对于只需要本地生成 TraceID 的场景，也应明确知道 Discard 仍然会修改全局 tracing 状态。

Index

• Constants
• func Discard(serviceName string) (func(context.Context) error, error)
• func Extract(ctx context.Context, carrier map[string]string) context.Context
• func GRPCClientStatsHandler() stats.Handler
• func GRPCServerStatsHandler() stats.Handler
• func GinMiddleware(serviceName string) gin.HandlerFunc
• func Init(cfg *Config) (func(context.Context) error, error)
• func Inject(ctx context.Context, carrier map[string]string)
• func MarkSpanError(span oteltrace.Span, err error)
• func SpanNameMQConsume(destination string) string
• func SpanNameMQPublish(destination string) string
• func StartConsumerSpanFromHeaders(ctx context.Context, tracer oteltrace.Tracer, spanName string, ...) (context.Context, oteltrace.Span)
• func StartProducerSpan(ctx context.Context, tracer oteltrace.Tracer, spanName string, ...) (context.Context, oteltrace.Span, map[string]string)
• type Config
  • func DefaultConfig(serviceName string) *Config
• type MessagingMeta
• type MessagingTraceRelation

Constants

const (
	// Messaging 语义属性键
	AttrMessagingSystem        = "messaging.system"
	AttrMessagingDestination   = "messaging.destination"
	AttrMessagingOperation     = "messaging.operation"
	AttrMessagingConsumerGroup = "messaging.consumer.group"
)

const (
	// 常见的消息操作
	MessagingOperationPublish = "publish"
	MessagingOperationConsume = "consume"
	MessagingOperationProcess = "process"
)

const (
	// 常见的消息系统
	MessagingSystemNATS = "nats"
)

Functions

func Discard

func Discard(serviceName string) (func(context.Context) error, error)

Discard 创建一个不导出数据的 TracerProvider，仅用于本地生成 TraceID。

Discard 仍然采用全局模式：它会安装全局 TracerProvider 和全局传播器。 因此它不是“局部无副作用”的 helper，而是“安装一个不导出的全局 provider”。 返回的 shutdown 在关闭该 provider 后，会在必要时把全局 tracing 状态重置为 安全默认值。

func Extract

func Extract(ctx context.Context, carrier map[string]string) context.Context

Extract 从 carrier 中提取 Trace 信息并返回新的 Context 用于 MQ 消费者等场景，还原上游的链路追踪信息

func GRPCClientStatsHandler

func GRPCClientStatsHandler() stats.Handler

GRPCClientStatsHandler 返回一个可重用的 gRPC 客户端状态处理程序用于跟踪

func GRPCServerStatsHandler

func GRPCServerStatsHandler() stats.Handler

GRPCServerStatsHandler 返回一个可重用的 gRPC 服务器状态处理程序用于跟踪

func GinMiddleware

func GinMiddleware(serviceName string) gin.HandlerFunc

GinMiddleware 返回一个可重用的 Gin 跟踪中间件

func Init

func Init(cfg *Config) (func(context.Context) error, error)

Init 初始化全局 TracerProvider，返回 shutdown 函数。

Init 当前采用全局模式：它会创建一个新的 TracerProvider，并安装为 OpenTelemetry 全局 TracerProvider 和全局传播器。调用方通常应在应用启动时 调用一次，并负责在退出时执行返回的 shutdown 函数。

返回的 shutdown 会关闭底层 provider；若当前全局 TracerProvider 仍指向该 实例，还会将全局 tracing 状态重置为安全默认值。

func Inject

func Inject(ctx context.Context, carrier map[string]string)

Inject 将当前 Context 的 Trace 信息注入到 carrier 中 用于 MQ 等场景，将链路追踪信息传递给下游

func MarkSpanError

func MarkSpanError(span oteltrace.Span, err error)

MarkSpanError 记录并将 Span 标记为错误，当 err 不为 nil 时

func SpanNameMQConsume

func SpanNameMQConsume(destination string) string

SpanNameMQConsume 返回用于从主题/主题消费的标准 Span Name

func SpanNameMQPublish

func SpanNameMQPublish(destination string) string

SpanNameMQPublish 返回用于发布到主题/主题的标准 Span Name

func StartConsumerSpanFromHeaders

func StartConsumerSpanFromHeaders(
	ctx context.Context,
	tracer oteltrace.Tracer,
	spanName string,
	headers map[string]string,
	meta MessagingMeta,
	attrs ...attribute.KeyValue,
) (context.Context, oteltrace.Span)

StartConsumerSpanFromHeaders 从传入的 headers 启动一个标准化的消费者 Span 关系默认是 link，可通过 MessagingMeta.TraceRelation 切换为 child_of

func StartProducerSpan

func StartProducerSpan(
	ctx context.Context,
	tracer oteltrace.Tracer,
	spanName string,
	meta MessagingMeta,
	attrs ...attribute.KeyValue,
) (context.Context, oteltrace.Span, map[string]string)

StartProducerSpan 启动一个标准化的生产者 Span，并将上下文注入到 headers

Types

type Config

type Config struct {
	ServiceName string  `mapstructure:"service_name"`
	Endpoint    string  `mapstructure:"endpoint"`
	Sampler     float64 `mapstructure:"sampler"`
	Batcher     string  `mapstructure:"batcher"`
	Insecure    bool    `mapstructure:"insecure"`
}

Config 定义全局 tracing 初始化参数。

当前实现是一个最小 OTLP gRPC 初始化器，不包含 TLS、认证头和附加 resource 属性等更复杂的 exporter 配置能力。

func DefaultConfig

func DefaultConfig(serviceName string) *Config

DefaultConfig 返回默认配置

type MessagingMeta

type MessagingMeta struct {
	System        string
	Destination   string
	Operation     string
	ConsumerGroup string
	// TraceRelation 控制消费端与上游生产端的关系建模方式，默认 link。
	TraceRelation MessagingTraceRelation
}

MessagingMeta 描述标准化的消息属性

type MessagingTraceRelation

type MessagingTraceRelation string

MessagingTraceRelation 表示消费者 Span 与上游消息 Span 的关系建模方式

const (
	// MessagingTraceRelationLink 使用 Span Link 关联上游（默认，适合异步/批处理/多消费者）
	MessagingTraceRelationLink MessagingTraceRelation = "link"
	// MessagingTraceRelationChildOf 使用 parent/child 关系串成单条 Trace（适合端到端演示）
	MessagingTraceRelationChildOf MessagingTraceRelation = "child_of"
)