Documentation
¶
Overview ¶
Package obsx 可观测性扩展：对齐 eino callbacks 体系的 LLM 调用追踪。
核心组件 TracingHandler 是 eino callbacks.Handler 的实现——通过 callbacks.InitCallbacks(ctx, nil, handler) 注入后，eino 各组件 （ChatModel 等）在调用时自动触发 OnStart/OnEnd/OnError，无需侵入业务代码：
ctx = obsx.InitLLMObservability(ctx, log, obsx.Options{}) // 一行启用
msg, err := client.Generate(ctx, "R1", msgs) // 自动产出结构化 trace
日志字段对齐可审计需求：stage（业务阶段）、component/model（哪个模型）、 duration、prompt/completion tokens（优先真实 usage）、慢调用告警。
Index ¶
- func DrainStreamUsage(sr *schema.StreamReader[callbacks.CallbackOutput]) (usage *model.TokenUsage, modelName string)
- func InitLLMObservability(ctx context.Context, log logx.Logger, opt Options) context.Context
- func NewTracingHandler(log logx.Logger, opt Options) callbacks.Handler
- func StageFromContext(ctx context.Context) string
- func TokenUsageOf(out *model.CallbackOutput) *model.TokenUsage
- func WithStage(ctx context.Context, stage string) context.Context
- type Options
- type TracingHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DrainStreamUsage ¶
func DrainStreamUsage(sr *schema.StreamReader[callbacks.CallbackOutput]) (usage *model.TokenUsage, modelName string)
DrainStreamUsage 排空回调副本流取末个非 nil usage 与末个非空模型名 （全仓单源——llm.NewUsageHandler 与本包 TracingHandler 共用；调用方负责 Close，本函数不关流。last-non-nil 语义：无 usage 的尾帧不清空已捕获值）。
func InitLLMObservability ¶
InitLLMObservability 一步启用：注入 TracingHandler 到 ctx。 之后该 ctx 链上的所有 eino 组件调用（ChatModel Generate 等）自动产出 trace。
func NewTracingHandler ¶
NewTracingHandler 创建 eino 追踪 handler（经 HandlerBuilder 组装）。 v0.12.1 起补 OnEndWithStreamOutput（第九轮审计 C 级：流式只触发该时机， 仅注册 OnEnd 的追踪在 agentrun 默认开流下 llm.call.end/slow 永不产出、 duration/tokens 全盲）——流式分支异步排空副本流取末帧 usage 后落 end （同步排空会把真流式阻塞成全量批出，与 llm.NewUsageHandler 同修法）。 组件过滤：非 ChatModel 组件（Tool/Lambda/Graph）的回调不产 llm.call.*—— 注入点在 run 边界时工具节点同样触发回调，此前混入 LLM 错误率与日志。
func StageFromContext ¶
StageFromContext 读取业务阶段（未标记返回空串）。
func TokenUsageOf ¶
func TokenUsageOf(out *model.CallbackOutput) *model.TokenUsage
TokenUsageOf 模型回调输出的真实 token 用量提取（全仓单源）： 优先 out.TokenUsage；compose 图节点对裸 ChatModel 只透传 Message 时回退读 ResponseMeta.Usage（缺该回退会静默漏采——v0.10.11 前仅 llm/usage 侧有， obsx 侧漏采已修）。llm.NewUsageHandler 与 TracingHandler 共用本函数。
Types ¶
type Options ¶
type Options struct {
// SlowThreshold 慢调用阈值：超过以 Warn 级落日志（默认 30s；0 = 不告警）。
SlowThreshold time.Duration
// PreviewLen 输入/输出消息内容预览长度（默认 0 = 不落内容，只落长度；
// 生产建议 0——消息可能含用户代码/凭证）。
PreviewLen int
}
Options TracingHandler 配置。
type TracingHandler ¶
type TracingHandler struct {
// contains filtered or unexported fields
}
TracingHandler eino 追踪 handler 的配置（经 NewTracingHandler 构建为 callbacks.Handler）。
Source Files