core

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

错误码定义：统一以 TRACEX_ 为前缀（errx 家族规范）。

Package tracex 提供 OpenTelemetry 链路追踪基座： TracerProvider 管理、HTTP 中间件、logx 日志字段与内存导出器。

Index

Constants

View Source 
const (
	CodeInvalidConfig  errx.Code = "TRACEX_INVALID_CONFIG"
	CodeExporterFailed errx.Code = "TRACEX_EXPORTER_FAILED"
	CodeShutdownFailed errx.Code = "TRACEX_SHUTDOWN_FAILED"
)
View Source 
const Version = "v1.3.0"

Version 是当前库版本，与 git tag 保持一致。

Variables

This section is empty.

Functions

func AddSpanEvent 

func AddSpanEvent(ctx context.Context, name string, attrs ...attribute.KeyValue)

AddSpanEvent 向当前 span 记录事件；无活动 span 时忽略。

func BaggageValue 

func BaggageValue(ctx context.Context, key string) string

BaggageValue 读取上下文中的 bag 成员值；不存在返回空串。

func LogFields 

func LogFields(ctx context.Context) logx.FieldGroup

LogFields 从上下文提取链路信息生成 logx 字段； 无有效链路时返回空字段组。

func RecordError 

func RecordError(ctx context.Context, err error)

RecordError 将错误记录到当前 span：记录异常事件并标记 Error 状态。

func WithBaggage 

func WithBaggage(ctx context.Context, key, value string) context.Context

WithBaggage 返回携带 bag 成员的上下文；非法键值被忽略。

Types

type Config 

type Config struct {
	// ServiceName 服务名（必填）。
	ServiceName string
	// Version 服务版本（可选）。
	Version string
	// Environment 部署环境（可选）。
	Environment string
	// SampleRatio 采样率 0~1，0 使用默认 1（全采样）。
	SampleRatio float64
	// BatchTimeout 批量导出间隔，0 使用默认 5s。
	BatchTimeout time.Duration
	// Exporter 导出器类型，空使用 stdout。
	Exporter ExporterKind
	// Writer stdout 导出器输出目标，nil 使用 os.Stdout。
	Writer io.Writer
	// OTLPEndpoint OTLP/HTTP 端点（host:port）。
	OTLPEndpoint string
	// OTLPInsecure 是否使用明文 HTTP。
	OTLPInsecure bool
	// OTLPHeaders OTLP/HTTP 附加请求头。
	OTLPHeaders map[string]string
	// OTLPTimeout OTLP/HTTP 请求超时，0 使用默认 10s。
	OTLPTimeout time.Duration
	// SlowThreshold 慢请求阈值；超过时记录 slow 事件，0 关闭。
	SlowThreshold time.Duration
	// RouteNamer 可选：从请求中提取路由模板（如 /users/{id}）用于
	// span 命名；返回空串时保持默认命名。
	RouteNamer func(r *http.Request) string
	// Sampler 可选采样器；nil 使用 TraceIDRatioBased(SampleRatio)。
	Sampler sdktrace.Sampler
	// SetGlobal 是否注册为 OTel 全局 TracerProvider 与传播器。
	SetGlobal bool
}

Config 追踪器配置。

type ExporterKind 

type ExporterKind string

ExporterKind 导出器类型。 

const (
	// ExporterMemory 内存导出器（测试/调试）。
	ExporterMemory ExporterKind = "memory"
	// ExporterStdout 标准输出导出器（默认）。
	ExporterStdout ExporterKind = "stdout"
	// ExporterOTLPHTTP OTLP/HTTP 导出器（生产采集）。
	ExporterOTLPHTTP ExporterKind = "otlp-http"
)

type LogHook 

type LogHook struct{}

LogHook logx 日志钩子：把日志写入当前 span 的 log 事件， 实现日志与链路事件关联。

func NewLogHook 

func NewLogHook() *LogHook

NewLogHook 构造日志钩子。

func (*LogHook) OnLog 

func (h *LogHook) OnLog(e *logx.Entry)

OnLog 在日志写入后调用（logx 异步触发）。

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager 追踪管理器：持有 TracerProvider、导出器与传播器。

func New 

func New(cfg Config) (*Manager, error)

New 构造追踪管理器。

func (*Manager) Config 

func (m *Manager) Config() Config

Config 返回配置副本。

func (*Manager) Extract 

func (m *Manager) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context

Extract 从 carrier 提取链路上下文（入站请求）。

func (*Manager) Inject 

func (m *Manager) Inject(ctx context.Context, carrier propagation.TextMapCarrier)

Inject 将链路上下文写入 carrier（出站请求）。

func (*Manager) Middleware 

func (m *Manager) Middleware(next http.Handler) http.Handler

Middleware 返回标准 net/http 链路追踪中间件： 提取入站链路上下文、记录请求属性与状态码，5xx 标记错误。

func (*Manager) Propagator 

func (m *Manager) Propagator() propagation.TextMapPropagator

Propagator 返回组合传播器（TraceContext + Baggage）。

func (*Manager) RoundTripper 

func (m *Manager) RoundTripper(next http.RoundTripper) http.RoundTripper

RoundTripper 返回出站 HTTP 链路注入器：自动携带 traceparent、 记录客户端 span，并按状态码/错误标记结果。

func (*Manager) Shutdown 

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown 刷新并关闭追踪器（幂等）。

func (*Manager) Spans 

func (m *Manager) Spans() []SpanSnapshot

Spans 返回内存导出器中的 Span 快照（非内存导出器返回 nil）。

func (*Manager) Start 

func (m *Manager) Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

Start 启动一个 Span（便捷封装）。

func (*Manager) Tracer 

func (m *Manager) Tracer() trace.Tracer

Tracer 返回管理器持有的 Tracer。

type MemoryExporter 

type MemoryExporter struct {
	// contains filtered or unexported fields
}

MemoryExporter 内存导出器：供测试与调试读取 Span。

func NewMemoryExporter 

func NewMemoryExporter() *MemoryExporter

NewMemoryExporter 构造内存导出器。

func (*MemoryExporter) ExportSpans 

func (e *MemoryExporter) ExportSpans(_ context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans 接收并快照 Span。

func (*MemoryExporter) Reset 

func (e *MemoryExporter) Reset()

Reset 清空已收集的 Span。

func (*MemoryExporter) Shutdown 

func (e *MemoryExporter) Shutdown(context.Context) error

Shutdown 关闭导出器（后续导出被忽略）。

func (*MemoryExporter) Spans 

func (e *MemoryExporter) Spans() []SpanSnapshot

Spans 返回 Span 快照副本。

type SpanEvent 

type SpanEvent struct {
	// Name 事件名。
	Name string
	// Attributes 事件属性。
	Attributes map[string]string
}

SpanEvent Span 事件快照。

type SpanSnapshot 

type SpanSnapshot struct {
	// Name Span 名称。
	Name string
	// TraceID 十六进制链路 ID。
	TraceID string
	// SpanID 十六进制 Span ID。
	SpanID string
	// ParentSpanID 父 Span ID（根 Span 为空）。
	ParentSpanID string
	// Attributes 属性快照。
	Attributes map[string]string
	// StatusCode 状态码（Unset/Ok/Error）。
	StatusCode string
	// StatusMessage 状态描述。
	StatusMessage string
	// Events 事件快照。
	Events []SpanEvent
}

SpanSnapshot Span 快照（内存导出器返回的只读视图）。

type TraceAttr 

type TraceAttr = contract.TraceAttr

TraceAttr 是链路追踪属性键值对（契约定义见 tracex/contract）。

type TraceHook 

type TraceHook = contract.TraceHook

TraceHook 是家族库通用的链路追踪钩子契约（定义见 tracex/contract）： 各库只依赖该接口，不绑定任何追踪后端；tracex 实现负责接入 OpenTelemetry 等具体后端。

func NewHook 

func NewHook(m *Manager) TraceHook

NewHook 返回标准的 TraceHook 实现：基于 Manager 创建 OpenTelemetry span。 可供任意家族库或第三方库通过各自的 WithTraceHook 选项接入，无需任何适配子包。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.