metrics

package
v0.45.2 Latest Latest
Warning

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

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

Documentation

Overview

Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.

Index

Constants

View Source
const (
	// MaxReportObservations bounds one worker report.
	MaxReportObservations = 1024

	// DropReasonWorkerBuffer marks observations a worker discarded because
	// its controller was not taking them.
	DropReasonWorkerBuffer = "workerBuffer"
	// DropReasonStoreQueue marks observations the metrics.db writer had no
	// room for.
	DropReasonStoreQueue = "storeQueue"
	// DropReasonStoreWrite marks observations a metrics.db write lost.
	DropReasonStoreWrite = "storeWrite"
)
View Source
const OutcomeCancelled = outcomeCancelled

OutcomeCancelled names an operation ended by cancellation.

View Source
const OutcomeError = outcomeError

OutcomeError names an operation which returned an error.

View Source
const OutcomeSuccess = outcomeSuccess

OutcomeSuccess names a completed operation without an error.

Variables

This section is empty.

Functions

This section is empty.

Types

type Metrics

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

Metrics is the application-owned Prometheus registry. Its methods accept only labels that Peen controls, never request, session, workspace, command, path, prompt, or SQL values.

func New

func New() *Metrics

New constructs one isolated application registry. It intentionally does not use Prometheus's global registry, so tests and embedding programs cannot leak collectors into each other.

func (*Metrics) Collect added in v0.22.0

func (m *Metrics) Collect(values chan<- prometheus.Metric)

Collect forwards current values without using Prometheus's global registry.

func (*Metrics) DatabaseCompleted

func (m *Metrics) DatabaseCompleted(
	operation string,
	table string,
	outcome string,
	duration time.Duration,
)

DatabaseCompleted records one GORM operation. table is reduced to Peen's fixed schema vocabulary before becoming a label.

func (*Metrics) DatabasePool

func (m *Metrics) DatabasePool(stats sql.DBStats)

DatabasePool records a point-in-time SQLite pool snapshot.

func (*Metrics) Describe added in v0.22.0

func (m *Metrics) Describe(descriptions chan<- *prometheus.Desc)

Describe exposes the owned collectors to an embedding caller's registry.

func (*Metrics) EventDropped

func (m *Metrics) EventDropped(reason string)

EventDropped records a durable pending-event or live-subscriber drop.

func (*Metrics) HTTPCompleted

func (m *Metrics) HTTPCompleted(
	method string,
	route string,
	status string,
	outcome string,
	duration time.Duration,
)

HTTPCompleted records one public HTTP request and removes it from the in-flight gauge. route must be Echo's templated route, never a raw URL.

func (*Metrics) HTTPStarted

func (m *Metrics) HTTPStarted()

HTTPStarted marks one public HTTP request in flight.

func (*Metrics) Handler

func (m *Metrics) Handler() http.Handler

Handler returns the OpenMetrics text-compatible Prometheus scrape handler.

func (*Metrics) HookCompleted added in v0.44.0

func (m *Metrics) HookCompleted(
	ctx context.Context,
	event string,
	outcome string,
	duration time.Duration,
)

HookCompleted records one hook event run. event is a harness hook event name, a closed set.

func (*Metrics) JobCompleted

func (m *Metrics) JobCompleted(
	ctx context.Context,
	operation string,
	outcome string,
	duration time.Duration,
)

JobCompleted records one supervised process result and removes it from the active-job gauge.

func (*Metrics) JobOutputDropped

func (m *Metrics) JobOutputDropped(
	ctx context.Context,
	stream string,
	count int,
)

JobOutputDropped records lines discarded from a completed job's bounded stdout or stderr buffer.

func (*Metrics) JobStarted

func (m *Metrics) JobStarted(ctx context.Context)

JobStarted increments the number of supervised process jobs currently live.

func (*Metrics) ModelCompleted

func (m *Metrics) ModelCompleted(ctx context.Context, request ModelRequest)

ModelCompleted records one whole Elelem request. Token counts are the request's final run totals, already accumulated by Elelem across rounds.

func (*Metrics) NewWorkerIngest added in v0.44.0

func (m *Metrics) NewWorkerIngest(
	sessionID uuid.UUID,
	generationID uuid.UUID,
) *WorkerIngest

NewWorkerIngest binds reports to one authenticated worker generation.

func (*Metrics) ObservationsDropped added in v0.44.0

func (m *Metrics) ObservationsDropped(reason string, count int64)

ObservationsDropped records observations that never reached metrics.db or the controller. reason is one of the DropReason constants.

func (*Metrics) Record added in v0.44.0

func (m *Metrics) Record(observation Observation)

Record counts one observation and passes it to the sink. A missing At is the current time.

func (*Metrics) Registry

func (m *Metrics) Registry() *prometheus.Registry

Registry returns the registry owned by this Metrics instance.

func (*Metrics) SetSink added in v0.44.0

func (m *Metrics) SetSink(sink Sink)

SetSink installs where every recorded observation goes next. A worker forwards to its controller, and the controller stores to metrics.db.

func (*Metrics) SetSummaries added in v0.45.0

func (m *Metrics) SetSummaries(reader SummaryReader)

SetSummaries installs where a worker's metrics queries go. Nil, the state when metrics.db is unavailable, makes each query fail.

func (*Metrics) ToolCompleted

func (m *Metrics) ToolCompleted(
	ctx context.Context,
	tool string,
	outcome string,
	duration time.Duration,
)

ToolCompleted records one host tool invocation.

func (*Metrics) WatchFiles added in v0.44.0

func (m *Metrics) WatchFiles(paths map[string]string) error

WatchFiles publishes each named database file's size, write-ahead log included, on every scrape.

func (*Metrics) WatchQueuedMessages added in v0.45.0

func (m *Metrics) WatchQueuedMessages(count func() int64) error

WatchQueuedMessages publishes how many accepted messages wait for delivery, counted on every scrape.

func (*Metrics) WatchWebSocketClients added in v0.45.0

func (m *Metrics) WatchWebSocketClients(count func() int) error

WatchWebSocketClients publishes the connected client count on every scrape.

type ModelRequest added in v0.44.0

type ModelRequest struct {
	Stage            string
	Function         string
	Model            string
	Outcome          string
	Duration         time.Duration
	TimeToFirstToken time.Duration
	InputTokens      int64
	OutputTokens     int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	Retries          int64
}

ModelRequest is what ModelCompleted records for one provider request.

type Observation added in v0.44.0

type Observation struct {
	Kind ObservationKind `json:"kind"`
	At   time.Time       `json:"at"`

	SessionID          string `json:"sessionId,omitempty"`
	WorkerGenerationID string `json:"workerGenerationId,omitempty"`
	TurnID             string `json:"turnId,omitempty"`
	AgentRunID         string `json:"agentRunId,omitempty"`

	Name     string `json:"name,omitempty"`
	Stage    string `json:"stage,omitempty"`
	Function string `json:"function,omitempty"`
	Outcome  string `json:"outcome,omitempty"`

	DurationMS       int64 `json:"durationMs,omitempty"`
	FirstTokenMS     int64 `json:"firstTokenMs,omitempty"`
	InputTokens      int64 `json:"inputTokens,omitempty"`
	OutputTokens     int64 `json:"outputTokens,omitempty"`
	CacheReadTokens  int64 `json:"cacheReadTokens,omitempty"`
	CacheWriteTokens int64 `json:"cacheWriteTokens,omitempty"`
	Retries          int64 `json:"retries,omitempty"`
	Count            int64 `json:"count,omitempty"`
	Bytes            int64 `json:"bytes,omitempty"`
}

Observation is one measured fact. It is the unit a worker reports, the Prometheus registry counts, and metrics.db stores, so it carries labels, identifiers, and numbers only, never prompts, tool output, commands, paths, or credentials.

type ObservationKind added in v0.44.0

type ObservationKind string

ObservationKind names what one Observation recorded.

const (
	// KindModel is one whole provider request.
	KindModel ObservationKind = "model"
	// KindTool is one tool invocation.
	KindTool ObservationKind = "tool"
	// KindJobStarted is one supervised process starting.
	KindJobStarted ObservationKind = "jobStarted"
	// KindJob is one supervised process ending.
	KindJob ObservationKind = "job"
	// KindJobOutputDropped is job output lines a bounded buffer discarded.
	KindJobOutputDropped ObservationKind = "jobOutputDropped"
	// KindEventDropped is one event a bounded delivery path discarded.
	KindEventDropped ObservationKind = "eventDropped"
	// KindHook is one hook event run for a turn or a tool.
	KindHook ObservationKind = "hook"
	// KindWorkerSample is a periodic reading of a worker's Go runtime.
	KindWorkerSample ObservationKind = "workerSample"
	// KindTurnStarted is one turn admitted to a session.
	KindTurnStarted ObservationKind = "turnStarted"
	// KindTurn is one turn reaching a terminal state.
	KindTurn ObservationKind = "turn"
	// KindAgentRunStarted is one child agent recorded.
	KindAgentRunStarted ObservationKind = "agentRunStarted"
	// KindAgentRun is one child agent reaching a terminal state.
	KindAgentRun ObservationKind = "agentRun"
	// KindCompaction is one stored compaction.
	KindCompaction ObservationKind = "compaction"
	// KindWorkerStarted is one worker launch attempt finishing.
	KindWorkerStarted ObservationKind = "workerStarted"
	// KindWorkerExited is one worker process ending.
	KindWorkerExited ObservationKind = "workerExited"
)

type ReportSender added in v0.44.0

type ReportSender func(ctx context.Context, report WorkerReport) error

ReportSender delivers one report to the controller.

type Reporter added in v0.44.0

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

Reporter is a worker's sink. It buffers observations and sends them to the controller in batches, and a controller that is not taking them costs the oldest observations rather than a turn.

func NewReporter added in v0.44.0

func NewReporter(send ReportSender) *Reporter

NewReporter builds a reporter over the worker's controller connection.

func (*Reporter) Add added in v0.44.0

func (r *Reporter) Add(observation Observation)

Add buffers one observation. It never blocks on the controller.

func (*Reporter) Flush added in v0.44.0

func (r *Reporter) Flush(ctx context.Context) error

Flush sends everything buffered, for a worker that is about to stop.

func (*Reporter) Run added in v0.44.0

func (r *Reporter) Run(ctx context.Context, collector *Metrics)

Run reports on an interval and samples the worker's Go runtime until ctx ends.

type Server

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

Server exposes a Metrics registry on an operator-owned listener. It is intentionally separate from Peen's public API router.

func NewServer

func NewServer(metrics *Metrics) (*Server, error)

NewServer constructs a scraper-only HTTP server without opening a listener.

func (*Server) ServeListener

func (s *Server) ServeListener(
	ctx context.Context,
	listener net.Listener,
) error

ServeListener serves the scraper endpoint until the service context ends.

type Sink added in v0.44.0

type Sink func(Observation)

Sink receives every observation a Metrics instance records. It runs on the recording goroutine, so it must not block.

type SummaryKind added in v0.45.0

type SummaryKind string

SummaryKind names one fixed aggregation of stored observations. The set is closed: an agent reading metrics picks one of these and never supplies SQL.

const (
	SummaryTools  SummaryKind = "tools"
	SummaryModels SummaryKind = "models"
	SummaryTurns  SummaryKind = "turns"
	SummaryAgents SummaryKind = "agents"
	SummaryHooks  SummaryKind = "hooks"
	// SummarySessions groups model time by session, which says something only
	// to a reader that covers every session.
	SummarySessions SummaryKind = "sessions"

	// MaxSummaryRows bounds one result, because it goes into a model's context.
	MaxSummaryRows = 100
)

type SummaryQuery added in v0.45.0

type SummaryQuery struct {
	Summary       SummaryKind `json:"summary"`
	WindowMinutes int         `json:"windowMinutes"`
	Limit         int         `json:"limit"`
}

SummaryQuery asks for one aggregation over a recent window.

type SummaryReader added in v0.45.0

type SummaryReader interface {
	Summarize(
		ctx context.Context,
		scope SummaryScope,
		query SummaryQuery,
	) (SummaryResult, error)
}

SummaryReader answers a query over stored observations.

type SummaryResult added in v0.45.0

type SummaryResult struct {
	Summary       SummaryKind  `json:"summary"`
	WindowMinutes int          `json:"windowMinutes"`
	Rows          []SummaryRow `json:"rows"`
	Truncated     bool         `json:"truncated"`
}

SummaryResult is one aggregation, slowest name first. Truncated says rows were left out to stay within the query's limit.

type SummaryRow added in v0.45.0

type SummaryRow struct {
	Name             string `json:"name"`
	Count            int64  `json:"count"`
	Failures         int64  `json:"failures"`
	Cancelled        int64  `json:"cancelled"`
	TotalDurationMS  int64  `json:"totalDurationMs"`
	MaxDurationMS    int64  `json:"maxDurationMs"`
	InputTokens      int64  `json:"inputTokens,omitempty"`
	OutputTokens     int64  `json:"outputTokens,omitempty"`
	CacheReadTokens  int64  `json:"cacheReadTokens,omitempty"`
	CacheWriteTokens int64  `json:"cacheWriteTokens,omitempty"`
	Retries          int64  `json:"retries,omitempty"`
}

SummaryRow aggregates the observations that share one name. Which name that is depends on the summary: a tool, a model, a turn ID, or a child agent run.

type SummaryScope added in v0.45.0

type SummaryScope struct {
	SessionID   string
	AllSessions bool
}

SummaryScope is the set of sessions a read covers. The controller sets it from the connection, and a worker never supplies it.

type WorkerIngest added in v0.44.0

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

WorkerIngest takes one connected worker's reports. It stamps each observation with the identity the connection authenticated, so a worker can report only as itself, and it remembers the jobs the worker left running.

func (*WorkerIngest) Close added in v0.44.0

func (i *WorkerIngest) Close()

Close ends the worker's jobs on the active-job gauge. A worker that crashed reported no completion for them, and its processes died with it.

func (*WorkerIngest) Ingest added in v0.44.0

func (i *WorkerIngest) Ingest(report WorkerReport) error

Ingest records one report. A report over the size limit is refused whole, and an observation of a kind a worker may not report is skipped.

func (*WorkerIngest) ReadAllSessions added in v0.45.0

func (i *WorkerIngest) ReadAllSessions()

ReadAllSessions widens this connection's reads to every session. Only the system worker's connection gets it.

func (*WorkerIngest) Summarize added in v0.45.0

func (i *WorkerIngest) Summarize(
	ctx context.Context,
	query SummaryQuery,
) (SummaryResult, error)

Summarize answers a worker's query. The scope comes from this connection, so an ordinary worker reads only the session it authenticated.

type WorkerReport added in v0.44.0

type WorkerReport struct {
	Observations []Observation `json:"observations"`
	Dropped      int64         `json:"dropped,omitempty"`
}

WorkerReport is one batch of a worker's observations. Dropped counts the observations the worker lost since its last accepted report.

Jump to

Keyboard shortcuts

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