metrics

Documentation

Index

• func FormatDuration(d time.Duration) string
• func FormatTurnDigest(lang string, turn TurnSummary) string
• type Collector
  • func NewCollector(ctx context.Context, capacity int, persist func(MetricEvent)) *Collector
  • func (c *Collector) Emit(m MetricEvent)
  • func (c *Collector) Flush()
  • func (c *Collector) Stop()
• type MetricEvent
• type SessionSummary
  • func Summarize(events []MetricEvent) SessionSummary
  • func (s SessionSummary) HasData() bool
  • func (s SessionSummary) ToolFailureRate() int
• type ToolSummary
• type TurnSummary
  • func TurnSummaryForIndex(events []MetricEvent, turnIndex int) (TurnSummary, bool)

Functions

func FormatDuration

func FormatDuration(d time.Duration) string

FormatDuration formats a duration for human-readable display.

func FormatTurnDigest

func FormatTurnDigest(lang string, turn TurnSummary) string

FormatTurnDigest produces a single-line summary of a turn's metrics. lang is a BCP-47 language code (e.g. "en", "zh-CN").

Types

type Collector

type Collector struct {
	// contains filtered or unexported fields
}

Collector receives MetricEvents on a buffered channel and persists them asynchronously via a callback. Events are dropped (never blocked) if the channel is full, so the agent is never slowed down.

func NewCollector

func NewCollector(ctx context.Context, capacity int, persist func(MetricEvent)) *Collector

NewCollector starts a background goroutine that drains ch and calls persist for each event. cap is the channel buffer size (256 is a good default).

func (*Collector) Emit

func (c *Collector) Emit(m MetricEvent)

Emit sends a metric event to the collector. Non-blocking: drops if full.

func (*Collector) Flush

func (c *Collector) Flush()

Flush blocks until all currently queued events have been persisted.

func (*Collector) Stop

func (c *Collector) Stop()

Stop signals the collector goroutine to drain and exit.

type MetricEvent

type MetricEvent struct {
	Timestamp time.Time `json:"timestamp"`
	TurnIndex int       `json:"turn_index"`
	Type      string    `json:"type"` // "llm" or "tool"

	// LLM metrics
	TTFT      time.Duration `json:"ttft,omitempty"`       // time to first text/reasoning token
	ThinkTime time.Duration `json:"think_time,omitempty"` // cumulative reasoning/thinking duration
	Duration  time.Duration `json:"duration,omitempty"`   // total LLM call wall time

	// Tool metrics
	ToolName     string        `json:"tool_name,omitempty"`
	ToolSuccess  bool          `json:"tool_success,omitempty"`
	ToolError    string        `json:"tool_error,omitempty"`
	ToolDuration time.Duration `json:"tool_duration,omitempty"`

	// Metadata
	Model    string `json:"model,omitempty"`
	Vendor   string `json:"vendor,omitempty"`
	Endpoint string `json:"endpoint,omitempty"`
}

MetricEvent records a single performance measurement — either an LLM API call or a tool execution. Designed to be fire-and-forget: the agent emits these via a callback, and the caller persists them asynchronously.

type SessionSummary

type SessionSummary struct {
	TurnCount        int
	LLMCallCount     int
	ToolCallCount    int
	ToolFailureCount int

	AvgTTFT     time.Duration
	P95TTFT     time.Duration
	AvgDuration time.Duration
	P95Duration time.Duration
	AvgThink    time.Duration

	SlowTools []ToolSummary
	Turns     []TurnSummary
}

func Summarize

func Summarize(events []MetricEvent) SessionSummary

func (SessionSummary) HasData

func (s SessionSummary) HasData() bool

func (SessionSummary) ToolFailureRate

func (s SessionSummary) ToolFailureRate() int

type ToolSummary

type ToolSummary struct {
	Name        string
	Calls       int
	Failures    int
	AvgDuration time.Duration
	MaxDuration time.Duration
}

type TurnSummary

type TurnSummary struct {
	TurnIndex           int
	LLMCallCount        int
	ToolCallCount       int
	ToolFailureCount    int
	TTFT                time.Duration
	Duration            time.Duration
	ThinkTime           time.Duration
	SlowestTool         string
	SlowestToolDuration time.Duration
}

func TurnSummaryForIndex

func TurnSummaryForIndex(events []MetricEvent, turnIndex int) (TurnSummary, bool)