Documentation
¶
Overview ¶
Anonymous identity matches identity/anonymous-user-id: persist one random UUID per Harness home in .anonymous-user-id. Missing or corrupt files are recreated; persistence failures still return a usable ID. Results are memoized by path.
Telemetry export (S07) bridges S05 hooks to an OTLP-style exporter with session, turn, and step baggage, matching telemetry-otel. The Exporter interface avoids a mandatory third-party SDK: implementations can use real gateways or an InMemoryExporter for tests. OTelBridge emits one span per event, chunk, or tool hook, carrying baggage for downstream correlation.
Package telemetry provides session-level observability hooks (S05), matching session-telemetry. Agent and session code record event appends, assistant text chunks, and completed tool calls. Record methods compute milliseconds from the supplied start time for consistent latency measurements. Hooks run synchronously in sequence, with individual panic recovery so failures do not interrupt other hooks or the caller. Latency is not clamped; tests use controlled clocks.
Session statistics match session/session-stats: fold step and tool boundaries into turn/step counts, model wall time, first-token latency, and tool wall time.
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 stores the anonymous 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 carries session, turn, and step IDs across telemetry dimensions.
type BaggageProvider ¶
type BaggageProvider func() Baggage
BaggageProvider supplies current session, turn, and step context.
type ChunkHook ¶
type ChunkHook func(ctx context.Context, d ChunkHookData)
type ChunkHookData ¶
type ChunkHookData struct {
Seq uint64 // Chunk sequence number.
TextLen int // Text length.
LatencyMS time.Duration // Elapsed time for one chunk.
}
ChunkHookData describes a streamed chunk.
type EventHook ¶
type EventHook func(ctx context.Context, d EventHookData)
EventHook, ChunkHook, and ToolHook define the three callback signatures.
type EventHookData ¶
type EventHookData struct {
EventType string // Session event type, such as user/message.
LatencyMS time.Duration // Elapsed time for one event append.
}
EventHookData records event type counts and append latency.
type InMemoryExporter ¶
type InMemoryExporter struct {
Spans []Span
// contains filtered or unexported fields
}
InMemoryExporter collects spans for test assertions.
func (*InMemoryExporter) Collect ¶
func (m *InMemoryExporter) Collect() []Span
Collect returns a snapshot of collected spans.
func (*InMemoryExporter) ExportSpan ¶
func (m *InMemoryExporter) ExportSpan(_ context.Context, span Span) error
ExportSpan records a span.
type OTelBridge ¶
type OTelBridge struct {
// contains filtered or unexported fields
}
OTelBridge connects S05 telemetry hooks to an Exporter.
func NewOTelBridge ¶
func NewOTelBridge(exporter Exporter, baggage BaggageProvider) *OTelBridge
NewOTelBridge creates a telemetry bridge.
func (*OTelBridge) Attach ¶
func (b *OTelBridge) Attach(tm *SessionTelemetry)
Attach registers event, chunk, and tool hooks that emit spans.
type SessionTelemetry ¶
type SessionTelemetry struct {
// contains filtered or unexported fields
}
SessionTelemetry is a concurrency-safe session telemetry registry.
func (*SessionTelemetry) RecordChunk ¶
func (t *SessionTelemetry) RecordChunk(ctx context.Context, seq uint64, textLen int, startedAt time.Time)
RecordChunk records one streaming chunk.
func (*SessionTelemetry) RecordEvent ¶
RecordEvent records an append using startedAt as its latency origin.
func (*SessionTelemetry) RecordTool ¶
func (t *SessionTelemetry) RecordTool(ctx context.Context, toolName string, ok bool, startedAt time.Time)
RecordTool records completion of a tool call.
func (*SessionTelemetry) RegisterChunkHook ¶
func (t *SessionTelemetry) RegisterChunkHook(h ChunkHook)
RegisterChunkHook registers a streaming-chunk hook.
func (*SessionTelemetry) RegisterEventHook ¶
func (t *SessionTelemetry) RegisterEventHook(h EventHook)
RegisterEventHook registers an event-append hook.
func (*SessionTelemetry) RegisterToolHook ¶
func (t *SessionTelemetry) RegisterToolHook(h ToolHook)
RegisterToolHook registers a tool-execution hook.
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 represents an exported telemetry span.
type Stats ¶
type Stats struct {
Turns int // Distinct turns with at least one completed step.
Steps int // Completed steps.
LLMMs int64 // Total model wall time from step/start to assistant/message.
TTFTMs int64 // Total first-token latency.
ToolMs int64 // Total tool call-to-result duration.
}
Stats holds cumulative statistics for a log.
type StatsCollector ¶
type StatsCollector struct {
// contains filtered or unexported fields
}
StatsCollector incrementally folds statistics; it is not concurrency-safe.
func NewStatsCollector ¶
func NewStatsCollector() *StatsCollector
NewStatsCollector creates a collector.
func (*StatsCollector) FirstToken ¶
func (c *StatsCollector) FirstToken(turn int, timeMs int64)
FirstToken records the first nonempty token only; repeated calls are ignored.
func (*StatsCollector) Message ¶
func (c *StatsCollector) Message(turn int, timeMs int64)
Message settles model duration and first-token latency when message assembly completes.
func (*StatsCollector) Snapshot ¶
func (c *StatsCollector) Snapshot() Stats
Snapshot returns the current statistics.
func (*StatsCollector) StepEnd ¶
func (c *StatsCollector) StepEnd(turn int)
StepEnd closes a step and counts its turn once.
func (*StatsCollector) StepStart ¶
func (c *StatsCollector) StepStart(turn int, timeMs int64)
StepStart records the beginning of a step.
func (*StatsCollector) ToolCall ¶
func (c *StatsCollector) ToolCall(callID string, timeMs int64)
ToolCall records a tool dispatch.
func (*StatsCollector) ToolResult ¶
func (c *StatsCollector) ToolResult(callID string, timeMs int64)
ToolResult settles tool duration, ignoring results without a matching call.
type ToolHook ¶
type ToolHook func(ctx context.Context, d ToolHookData)