Documentation
¶
Overview ¶
Package trace 提供请求级别的结构化日志追踪。
设计原则：
- 基于 Go 标准库 log/slog，不引入第三方日志框架
- 每个请求在入口生成 trace ID，通过 context 贯穿全链路
- 所有日志自动携带 trace_id / user_id / session 等结构化字段
- 通过 CollectorHandler 桥接到 LogCollector（前端日志面板 + 文件持久化）
用法:
// 入口层（WebSocket/HTTP handler）
logger := trace.NewRequest(traceID, userID, sessionID)
ctx = trace.WithLogger(ctx, logger)
// 业务层
trace.L(ctx).Info("LLM 调用开始", "provider", p, "model", m, "tools", n)
trace.L(ctx).Error("流式输出失败", "err", err, "stage", "llm_stream")
Index ¶
- func Detach(parent context.Context) context.Context
- func Go(parent context.Context, task string, fn func(ctx context.Context))
- func ID() string
- func L(ctx context.Context) *slog.Logger
- func NewRequest(userID, sessionID string) *slog.Logger
- func Recover(ctx context.Context, task string) func(errOut *error)
- func WithLogger(ctx context.Context, l *slog.Logger) context.Context
- type Collector
- type CollectorHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Detach ¶
Detach 返回一个新 context：
- 保留父 ctx 的**所有** Values（logger / trace_id / user_id / session_id / tenant 等）
- 不继承 cancel/deadline（异步任务不受父请求生命周期影响）
直接复用 toolkit/lang/contextx.Detach（保留所有 Values 的正确实现）。 历史版本（v0.3.12 早期）只保留 logger 丢了其他 Values，已修复。
用途：fire-and-forget 的 goroutine、保存钩子、远端通知等， 既要日志链路追得上，又不希望父请求一超时就把异步工作也取消。
func Go ¶
Go 启动一个带 recover 和 logger 链路的 goroutine。
相比裸 `go func() { fn(context.Background()) }()`：
- panic 会被 recover 并记录到日志（不静默吞）
- context.Background() 换成 Detach(parent)，保留 trace_id / session_id
- task 名字用于日志定位
典型场景：异步保存 / 消息推送 / 清理任务 / 通知
trace.Go(ctx, "save-session", func(ctx context.Context) {
db.Save(ctx, sess)
})
func NewRequest ¶
NewRequest 创建请求级 logger，携带 trace_id 和身份信息。
Types ¶
type Collector ¶
type Collector interface {
AddTrace(level, source, message, traceID string, fields map[string]any)
}
Collector 是 LogCollector 需要实现的接口（避免循环依赖 trace → api）。
type CollectorHandler ¶
type CollectorHandler struct {
// contains filtered or unexported fields
}
CollectorHandler 是 slog.Handler 的实现，将结构化日志写入 LogCollector。
职责：
- 把 slog 的 Attr 转换为 LogCollector 的 fields map
- 从 attrs 中提取 trace_id 填入 LogEntry.TraceID
- source 默认为 "trace"，可通过 WithSource 覆盖
func NewCollectorHandler ¶
func NewCollectorHandler(c Collector, level slog.Leveler) *CollectorHandler
NewCollectorHandler 创建桥接 slog → LogCollector 的 Handler。
Source Files
Click to show internal directories.
Click to hide internal directories.