Documentation
¶
Overview ¶
anonymous.go 复刻官方 identity/anonymous-user-id:每个 Harness home 一个随机 UUID,持久化为 .anonymous-user-id 单行;文件缺失或损坏则新建,写入失败仍返回 可用 ID(best-effort),进程内按路径 memo。
本文件实现任务 S07:OTel Telemetry 导出(OTLP exporter 门面 + S05 挂钩 + 三 id baggage)。
对齐上游:packages/runtime-diagnostics/telemetry-otel
设计要点:
- 不强制绑定第三方 SDK:定义 Exporter 抽象(ExportSpan),即可对接真实 OTLP 网关, 也可在测试/本地用 InMemoryExporter 收集断言(N09 同为自研探针,保持依赖可控);
- Span 携带 Baggage(session/turn/step 三 id),保证下游可按事务链路聚合;
- OTelBridge 把 S05 的 SessionTelemetry 三类钩子(event/chunk/tool)接进来,每次 埋点 emit 一条带 baggage 的 span 到 Exporter。
Package telemetry 提供会话级可观测性挂钩(任务 S05:Session Telemetry hooks)。
对齐上游:packages/runtime-diagnostics/session-telemetry
设计要点:
- SessionTelemetry 是一个回调注册表,供上层(Agent Loop / Session)在三个 热路径埋点上报: 1) 事件追加(event)—— 每 append 一条 SessionEvent; 2) 流式分片(chunk)—— 每收到一个 assistant/chunk 文本分片; 3) 工具执行(tool)—— 每次工具调用结束(成功或失败)。
- 每个埋点都附「开始时间」,由 Record 方法自行计算 latency(毫秒),保证类似 钩子拿到的延迟口径一致;
- 全部回调以同步顺序调用;任何单个回调 panic 或拖慢都不影响主路径的其余 钩子与调用方(用 defer + recover 包裹),符合"埋点不能中断业务"的约定;
- latency 不强制非负,但自然时间流逝下恒为正;测试用可控 clock/时间戳断言 latency >= 0 且处于合理区间。
stats.go 复刻官方 session/session-stats 的纯 fold:从 step/tool 边界事件增量 统计回合数、步数以及模型耗时、首 token 延迟、工具耗时等墙钟时间。
Index ¶
- Constants
- func GetOrCreateAnonymousID(env map[string]string) (string, error)
- type Baggage
- type BaggageProvider
- type ChunkHook
- type ChunkHookData
- type EventHook
- type EventHookData
- type Exporter
- type InMemoryExporter
- type OTelBridge
- type SessionTelemetry
- func (t *SessionTelemetry) RecordChunk(ctx context.Context, seq uint64, textLen int, startedAt time.Time)
- func (t *SessionTelemetry) RecordEvent(ctx context.Context, eventType string, startedAt time.Time)
- func (t *SessionTelemetry) RecordTool(ctx context.Context, toolName string, ok bool, startedAt time.Time)
- func (t *SessionTelemetry) RegisterChunkHook(h ChunkHook)
- func (t *SessionTelemetry) RegisterEventHook(h EventHook)
- func (t *SessionTelemetry) RegisterToolHook(h ToolHook)
- type Span
- type Stats
- type StatsCollector
- func (c *StatsCollector) FirstToken(turn int, timeMs int64)
- func (c *StatsCollector) Message(turn int, timeMs int64)
- func (c *StatsCollector) Snapshot() Stats
- func (c *StatsCollector) StepEnd(turn int)
- func (c *StatsCollector) StepStart(turn int, timeMs int64)
- func (c *StatsCollector) ToolCall(callID string, timeMs int64)
- func (c *StatsCollector) ToolResult(callID string, timeMs int64)
- type ToolHook
- type ToolHookData
Constants ¶
const AnonymousIDFileName = ".anonymous-user-id"
AnonymousIDFileName 是存放匿名 ID 的文件名。
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Baggage ¶
type Baggage struct {
SessionID string `json:"sessionId"`
TurnID string `json:"turnId"`
StepID string `json:"stepId"`
}
Baggage 是跨量纲传递的链路上下文(session/turn/step 三 id)。
type BaggageProvider ¶
type BaggageProvider func() Baggage
BaggageProvider 提供当前链路 baggage(由上层按当前 session/turn/step 注入)。
type ChunkHook ¶
type ChunkHook func(ctx context.Context, d ChunkHookData)
type ChunkHookData ¶
type ChunkHookData struct {
Seq uint64 // 分片序号
TextLen int // 文本长度
LatencyMS time.Duration // 单分片耗时
}
ChunkHookData 是流式分片事件的载荷。
type EventHook ¶
type EventHook func(ctx context.Context, d EventHookData)
EventHook / ChunkHook / ToolHook 是三类钩子签名。
type EventHookData ¶
type EventHookData struct {
EventType string // 事件类型(如 "user/message",来自 pkg/session)
LatencyMS time.Duration // 单条事件追加耗时
}
EventHookData 是事件追加事件的载荷(目标:累计每类事件数量与延迟)。
type InMemoryExporter ¶
type InMemoryExporter struct {
Spans []Span
// contains filtered or unexported fields
}
InMemoryExporter 收集 span 到内存(测试断言用)。
func (*InMemoryExporter) Collect ¶
func (m *InMemoryExporter) Collect() []Span
Collect 返回已收集 span 的快照。
func (*InMemoryExporter) ExportSpan ¶
func (m *InMemoryExporter) ExportSpan(_ context.Context, span Span) error
ExportSpan 记录一条 span。
type OTelBridge ¶
type OTelBridge struct {
// contains filtered or unexported fields
}
OTelBridge 把 S05 遥测钩子桥接到 Exporter。
func NewOTelBridge ¶
func NewOTelBridge(exporter Exporter, baggage BaggageProvider) *OTelBridge
NewOTelBridge 创建桥接器。
func (*OTelBridge) Attach ¶
func (b *OTelBridge) Attach(tm *SessionTelemetry)
Attach 注册到 SessionTelemetry(S05),事件/分片/工具三类钩子都会 emit span。
type SessionTelemetry ¶
type SessionTelemetry struct {
// contains filtered or unexported fields
}
SessionTelemetry 是会话级遥测注册表(线程安全)。
func (*SessionTelemetry) RecordChunk ¶
func (t *SessionTelemetry) RecordChunk(ctx context.Context, seq uint64, textLen int, startedAt time.Time)
RecordChunk 记录一次流式分片。
func (*SessionTelemetry) RecordEvent ¶
RecordEvent 记录一次事件追加;startedAt 为事件开始时间(time.Time 或已算好的递减基准)。
func (*SessionTelemetry) RecordTool ¶
func (t *SessionTelemetry) RecordTool(ctx context.Context, toolName string, ok bool, startedAt time.Time)
RecordTool 记录一次工具执行结束。
func (*SessionTelemetry) RegisterChunkHook ¶
func (t *SessionTelemetry) RegisterChunkHook(h ChunkHook)
RegisterChunkHook 注册流式分片钩子。
func (*SessionTelemetry) RegisterEventHook ¶
func (t *SessionTelemetry) RegisterEventHook(h EventHook)
RegisterEventHook 注册事件追加钩子。
func (*SessionTelemetry) RegisterToolHook ¶
func (t *SessionTelemetry) RegisterToolHook(h ToolHook)
RegisterToolHook 注册工具执行钩子。
type Span ¶
type Span struct {
Name string `json:"name"`
Baggage Baggage `json:"baggage"`
Started time.Time `json:"started"`
Ended time.Time `json:"ended"`
Kind string `json:"kind,omitempty"` // event/chunk/tool
Attrs map[string]string `json:"attrs,omitempty"`
}
Span 是导出的一条可观测 span。
type Stats ¶
type Stats struct {
Turns int // 至少闭合一个 step 的不同 turn 数
Steps int // 闭合的 step 数
LLMMs int64 // 模型墙钟耗时累计(step/start→assistant/message)
TTFTMs int64 // 首 token 延迟累计
ToolMs int64 // 工具 call→result 耗时累计
}
Stats 是整段日志的累计统计。
type StatsCollector ¶
type StatsCollector struct {
// contains filtered or unexported fields
}
StatsCollector 增量统计器(非并发安全,单线程 fold 使用)。
func (*StatsCollector) FirstToken ¶
func (c *StatsCollector) FirstToken(turn int, timeMs int64)
FirstToken 记录当前 step 的首个非空 token(重复调用只认第一次)。
func (*StatsCollector) Message ¶
func (c *StatsCollector) Message(turn int, timeMs int64)
Message 在消息装配完成时结算模型耗时与首 token 延迟。
func (*StatsCollector) StepEnd ¶
func (c *StatsCollector) StepEnd(turn int)
StepEnd 记录 step 闭合,并按 turn 去重计数。
func (*StatsCollector) StepStart ¶
func (c *StatsCollector) StepStart(turn int, timeMs int64)
StepStart 记录 step 开始。
func (*StatsCollector) ToolCall ¶
func (c *StatsCollector) ToolCall(callID string, timeMs int64)
ToolCall 记录一次工具派发。
func (*StatsCollector) ToolResult ¶
func (c *StatsCollector) ToolResult(callID string, timeMs int64)
ToolResult 结算一次工具耗时(无对应 call 则忽略)。
type ToolHook ¶
type ToolHook func(ctx context.Context, d ToolHookData)