Documentation
¶
Overview ¶
Package metrics owns Peen's application Prometheus registry and its bounded runtime collectors.
Index ¶
- Constants
- type Metrics
- func (m *Metrics) Collect(values chan<- prometheus.Metric)
- func (m *Metrics) DatabaseCompleted(operation string, table string, outcome string, duration time.Duration)
- func (m *Metrics) DatabasePool(stats sql.DBStats)
- func (m *Metrics) Describe(descriptions chan<- *prometheus.Desc)
- func (m *Metrics) EventDropped(reason string)
- func (m *Metrics) HTTPCompleted(method string, route string, status string, outcome string, ...)
- func (m *Metrics) HTTPStarted()
- func (m *Metrics) Handler() http.Handler
- func (m *Metrics) HookCompleted(ctx context.Context, event string, outcome string, duration time.Duration)
- func (m *Metrics) JobCompleted(ctx context.Context, operation string, outcome string, duration time.Duration)
- func (m *Metrics) JobOutputDropped(ctx context.Context, stream string, count int)
- func (m *Metrics) JobStarted(ctx context.Context)
- func (m *Metrics) ModelCompleted(ctx context.Context, request ModelRequest)
- func (m *Metrics) NewWorkerIngest(sessionID uuid.UUID, generationID uuid.UUID) *WorkerIngest
- func (m *Metrics) ObservationsDropped(reason string, count int64)
- func (m *Metrics) Record(observation Observation)
- func (m *Metrics) Registry() *prometheus.Registry
- func (m *Metrics) SetSink(sink Sink)
- func (m *Metrics) SetSummaries(reader SummaryReader)
- func (m *Metrics) ToolCompleted(ctx context.Context, tool string, outcome string, duration time.Duration)
- func (m *Metrics) WatchFiles(paths map[string]string) error
- func (m *Metrics) WatchQueuedMessages(count func() int64) error
- func (m *Metrics) WatchWebSocketClients(count func() int) error
- type ModelRequest
- type Observation
- type ObservationKind
- type ReportSender
- type Reporter
- type Server
- type Sink
- type SummaryKind
- type SummaryQuery
- type SummaryReader
- type SummaryResult
- type SummaryRow
- type SummaryScope
- type WorkerIngest
- type WorkerReport
Constants ¶
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" )
const OutcomeCancelled = outcomeCancelled
OutcomeCancelled names an operation ended by cancellation.
const OutcomeError = outcomeError
OutcomeError names an operation which returned an error.
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 ¶
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 ¶
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 ¶
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 ¶
JobOutputDropped records lines discarded from a completed job's bounded stdout or stderr buffer.
func (*Metrics) JobStarted ¶
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
NewWorkerIngest binds reports to one authenticated worker generation.
func (*Metrics) ObservationsDropped ¶ added in v0.44.0
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
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
WatchFiles publishes each named database file's size, write-ahead log included, on every scrape.
func (*Metrics) WatchQueuedMessages ¶ added in v0.45.0
WatchQueuedMessages publishes how many accepted messages wait for delivery, counted on every scrape.
func (*Metrics) WatchWebSocketClients ¶ added in v0.45.0
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.
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.
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
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.