telemetry

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 8 Imported by: 0

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

View Source
const AnonymousIDFileName = ".anonymous-user-id"

AnonymousIDFileName 是存放匿名 ID 的文件名。

Variables

This section is empty.

Functions

func GetOrCreateAnonymousID

func GetOrCreateAnonymousID(env map[string]string) (string, error)

GetOrCreateAnonymousID 返回 Harness home 下的匿名 ID,必要时创建并持久化。

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 Exporter

type Exporter interface {
	ExportSpan(ctx context.Context, span Span) error
}

Exporter 是 span 的导出目标(对应 OTLP exporter)。

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 New

func New() *SessionTelemetry

New 创建空遥测注册表。

func (*SessionTelemetry) RecordChunk

func (t *SessionTelemetry) RecordChunk(ctx context.Context, seq uint64, textLen int, startedAt time.Time)

RecordChunk 记录一次流式分片。

func (*SessionTelemetry) RecordEvent

func (t *SessionTelemetry) RecordEvent(ctx context.Context, eventType string, startedAt time.Time)

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 NewStatsCollector

func NewStatsCollector() *StatsCollector

NewStatsCollector 创建统计器。

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) Snapshot

func (c *StatsCollector) Snapshot() Stats

Snapshot 返回当前统计快照。

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)

type ToolHookData

type ToolHookData struct {
	ToolName  string        // 工具名(如 "bash" / "todo_write")
	Ok        bool          // 是否成功(err == nil)
	LatencyMS time.Duration // 工具执行耗时
}

ToolHookData 是工具执行事件的载荷。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL