metrics

Documentation

Overview

Package metrics defines the assistant's application-level Prometheus collectors — conversation turns, tool calls, model calls, history compaction, and capability-gap reports — and the Metrics handle used to record them.

This package exists separately from internal/server (which owns the HTTP-level metrics and the /metrics endpoint) so that internal/agent, internal/history, and internal/capability — none of which import internal/server, and none of which internal/server may ever import without creating a cycle once it depends on the agent runner — can record these events without any import-direction hazard. A Metrics is a plain collector holder: it does not own a registry or an HTTP handler. The caller that owns the exposition endpoint (internal/server) registers a shared instance's collectors into its own *prometheus.Registry, and that same instance is injected into agent.Deps (and, through it, capability.ComposeOptions) so both sides observe the identical metric state — the same dependency-injection convention this codebase already uses for internal/usage.Emitter (see internal/agent.Deps.Emitter).

Metrics are not an optional, nil-disables-the-feature collaborator the way internal/memory.Store or internal/gapreport.Store are: a *Metrics is always non-nil in a constructed [agent.Conversation] (New backs an unset Deps.Metrics with a fresh instance, mirroring the Logger fallback), and every exported Record* method also tolerates a nil receiver so a caller that constructs a bare struct literal without New cannot panic.

Index

• type Metrics
  • func New() *Metrics
  • func (m *Metrics) Collectors() []prometheus.Collector
  • func (m *Metrics) RecordCompaction(outcome string)
  • func (m *Metrics) RecordGapReport(outcome string)
  • func (m *Metrics) RecordModelCall(outcome string, d time.Duration)
  • func (m *Metrics) RecordToolCall(tool, outcome string)
  • func (m *Metrics) RecordTurn(state string, d time.Duration)

Types

type Metrics

type Metrics struct {
	// TurnDuration is assistant_conversation_turn_duration_seconds, labeled
	// by state (completed/failed/canceled) — see internal/agent.State.
	TurnDuration *prometheus.HistogramVec
	// ToolCalls is assistant_tool_call_total, labeled by tool and outcome
	// (success/error).
	ToolCalls *prometheus.CounterVec
	// ModelCallDuration is assistant_model_call_duration_seconds, labeled by
	// outcome (success/error).
	ModelCallDuration *prometheus.HistogramVec
	// CompactionTotal is assistant_history_compaction_total, labeled by
	// outcome (success/failed_open) — see internal/agent.Conversation.maybeCompact.
	CompactionTotal *prometheus.CounterVec
	// GapReportTotal is assistant_gap_report_total, labeled by outcome
	// (success/error) — see internal/capability's report_capability_gap tool.
	GapReportTotal *prometheus.CounterVec
}

Metrics holds the assistant's application-level collectors, following the same CounterVec/HistogramVec construction and "assistant_" naming convention as internal/server/metrics.go. Names and label sets are pinned to what config/components/observability/grafana-dashboard-{sre,product}.json and config/components/observability/alerts.yaml already assume — do not rename either without updating those files.

func New

func New() *Metrics

New builds an unregistered Metrics set. The caller that owns a Prometheus registry (internal/server) registers its collectors via Metrics.Collectors; nothing in this package touches the default global registry.

func (*Metrics) Collectors

func (m *Metrics) Collectors() []prometheus.Collector

Collectors returns every collector so the caller that owns a *prometheus.Registry (internal/server) can MustRegister them alongside its own HTTP metrics, exposing all of them on the same /metrics endpoint.

func (*Metrics) RecordCompaction

func (m *Metrics) RecordCompaction(outcome string)

RecordCompaction counts one history-compaction attempt under outcome ("success"/"failed_open").

func (*Metrics) RecordGapReport

func (m *Metrics) RecordGapReport(outcome string)

RecordGapReport counts one capability-gap-report tool call under outcome ("success"/"error").

func (*Metrics) RecordModelCall

func (m *Metrics) RecordModelCall(outcome string, d time.Duration)

RecordModelCall observes one model inference call's duration under outcome ("success"/"error").

func (*Metrics) RecordToolCall

func (m *Metrics) RecordToolCall(tool, outcome string)

RecordToolCall counts one tool execution under tool/outcome ("success"/"error").

func (*Metrics) RecordTurn

func (m *Metrics) RecordTurn(state string, d time.Duration)

RecordTurn observes one conversation turn's duration under state (completed/failed/canceled).