telemetry

package
v0.1.14 Latest Latest
Warning

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

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

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

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

AnonymousIDFileName stores the anonymous ID.

Variables

This section is empty.

Functions

func GetOrCreateAnonymousID

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

GetOrCreateAnonymousID reads or creates and persists a Harness home's anonymous ID.

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 Exporter

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

Exporter receives spans, corresponding to an OTLP exporter.

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 New

func New() *SessionTelemetry

New creates an empty 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

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

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)

type ToolHookData

type ToolHookData struct {
	ToolName  string        // Tool name, such as bash or todo_write.
	Ok        bool          // Whether execution succeeded (err == nil).
	LatencyMS time.Duration // Tool execution duration.
}

ToolHookData describes a tool execution.

Jump to

Keyboard shortcuts

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