Documentation
¶
Overview ¶
Package metrics is the agent's in-process, Prometheus-style metrics registry. Every subsystem that wants to record something (runs, the plugin supervisor, the scheduler, connector tests) does so through a small, intention-revealing method on Registry — never by importing client_golang directly — so the exact metric names and label vocabulary stay defined in one place.
The same Registry backs two different exposures: a raw Prometheus text-exposition endpoint (GET /metrics, see Handler) for an external Prometheus/Grafana to scrape, and a JSON snapshot (GET /v1/system/metrics, see Snapshot) the TypeScript SDK consumes to build dashboards. Metrics are in-memory only and reset on every process restart — there is no persistence here, and none is planned; see ADR-0070.
Index ¶
- type ConnectorMetrics
- type PluginMetrics
- type Registry
- func (r *Registry) ActiveRunsDec()
- func (r *Registry) ActiveRunsInc()
- func (r *Registry) Handler() http.Handler
- func (r *Registry) PluginHealthCheckFailed(pluginID string)
- func (r *Registry) PluginQuarantined(pluginID string)
- func (r *Registry) PluginRestarted(pluginID string)
- func (r *Registry) PluginStarted(pluginID string)
- func (r *Registry) PluginStopped(pluginID string)
- func (r *Registry) RecordConnectorTest(result string)
- func (r *Registry) RecordRunTransition(status string, duration time.Duration)
- func (r *Registry) RecordStepTransition(status string, duration time.Duration)
- func (r *Registry) ScheduleFired()
- func (r *Registry) ScheduleSkipped(reason string)
- func (r *Registry) SetActiveSchedules(n int)
- func (r *Registry) Snapshot() Snapshot
- type RunMetrics
- type SchedulerMetrics
- type Snapshot
- type StepMetrics
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConnectorMetrics ¶
type ConnectorMetrics struct {
// TestTotal maps a test result ("ok", "failed", "error") to how many
// attempts ended with it.
TestTotal map[string]uint64 `json:"test_total"`
}
ConnectorMetrics summarizes connector test attempts recorded so far.
type PluginMetrics ¶
type PluginMetrics struct {
PluginID string `json:"plugin_id"`
Running bool `json:"running"`
RestartsTotal uint64 `json:"restarts_total"`
HealthCheckFailuresTotal uint64 `json:"health_check_failures_total"`
QuarantinedTotal uint64 `json:"quarantined_total"`
}
PluginMetrics summarizes one plugin's supervision history. A plugin only appears here once it has been observed at least once by the Supervisor (typically: launched) — a plugin that has never successfully started does not have an entry.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry owns every metric the agent records and the private *prometheus.Registry they are registered against. It is never a global singleton — like every other shared dependency in this codebase (*slog.Logger, *sql.DB), it is built once (New, typically in internal/runtime.NewAgent) and passed explicitly into the constructors that need it. A private registry, rather than prometheus.DefaultRegisterer, also means table-driven tests that build several Supervisor/Runner instances in the same test binary each get their own Registry and never collide on a duplicate registration.
func New ¶
func New() *Registry
New builds a Registry with every metric registered under the "patchcord" namespace, plus the standard Go runtime/process collectors (memory, GC, file descriptors, ...) client_golang provides for free — generic process health, not business-specific, so registering them here does not touch the core's non-negotiable #3 (no concrete business service in internal/). Registration can only fail on a programming bug (e.g. two metrics declared with the same name), so New panics rather than returning an error a caller could plausibly ignore — exactly like an invalid regexp literal would; go test ./... catches it immediately.
func OrNoop ¶
OrNoop returns m, or a freshly built, privately held Registry when m is nil — the same nil-safe-default convention used throughout this codebase for *slog.Logger (see Deps.logger in internal/api). Resolving nil exactly once at construction time means every recording method below is always safe to call unconditionally, with no nil check scattered across call sites in internal/runs, internal/plugins or internal/scheduler.
func (*Registry) ActiveRunsDec ¶
func (r *Registry) ActiveRunsDec()
ActiveRunsDec records one run leaving the running state for a terminal one.
func (*Registry) ActiveRunsInc ¶
func (r *Registry) ActiveRunsInc()
ActiveRunsInc records one more run entering the running state.
func (*Registry) Handler ¶
Handler returns the Prometheus text-exposition HTTP handler for this registry's metrics — mounted at GET /metrics by internal/api.
func (*Registry) PluginHealthCheckFailed ¶
PluginHealthCheckFailed records one failed periodic health check for pluginID.
func (*Registry) PluginQuarantined ¶
PluginQuarantined records pluginID as quarantined after exhausting its restart attempts.
func (*Registry) PluginRestarted ¶
PluginRestarted records one restart attempt for pluginID — incremented when the attempt is made, regardless of whether the relaunch itself then succeeds, since "how many restarts has this plugin needed" is the operationally interesting signal.
func (*Registry) PluginStarted ¶
PluginStarted records pluginID as currently running — called both after its initial launch and after a successful restart.
func (*Registry) PluginStopped ¶
PluginStopped records pluginID as no longer running — called on crash and on a failed health check, before a restart is attempted.
func (*Registry) RecordConnectorTest ¶
RecordConnectorTest records one connector test attempt's outcome: "ok" (the connector answered successfully), "failed" (it was reached but reported itself unhealthy) or "error" (the test could not even be attempted, e.g. no running plugin declares that connector type).
func (*Registry) RecordRunTransition ¶
RecordRunTransition records a run transitioning to status. duration is the run's total elapsed time and is only observed into the duration histogram when non-zero — a non-terminal transition (e.g. into "running") has no meaningful duration yet, so callers pass zero for those.
func (*Registry) RecordStepTransition ¶
RecordStepTransition records a step transitioning to status, following the same duration convention as RecordRunTransition.
func (*Registry) ScheduleFired ¶
func (r *Registry) ScheduleFired()
ScheduleFired records the scheduler deciding to fire a due schedule.
func (*Registry) ScheduleSkipped ¶
ScheduleSkipped records the scheduler deciding not to fire a due schedule occurrence, e.g. because it caught up on a backlog under the "skip" on_missed policy.
func (*Registry) SetActiveSchedules ¶
SetActiveSchedules sets the current number of workflows registered with a schedule trigger.
func (*Registry) Snapshot ¶
Snapshot gathers this registry's current values into a Snapshot. It goes through the same prometheus.Gatherer interface promhttp's text handler uses internally — client_golang deliberately does not expose a "read the current value" method on a live Counter/Gauge/HistogramVec, since its instrumentation API is write-only by design.
type RunMetrics ¶
type RunMetrics struct {
// Transitions maps a run status (e.g. "running", "succeeded", "failed",
// "cancelled") to how many times a run has transitioned into it.
Transitions map[string]uint64 `json:"transitions"`
// Active is the number of runs currently in the running state.
Active int64 `json:"active"`
Steps StepMetrics `json:"steps"`
}
RunMetrics summarizes run and step transitions recorded so far.
type SchedulerMetrics ¶
type SchedulerMetrics struct {
FiresTotal uint64 `json:"fires_total"`
// SkippedTotal maps a skip reason (e.g. "caught_up") to how many times
// a due occurrence was skipped for it.
SkippedTotal map[string]uint64 `json:"skipped_total"`
// Active is the number of workflows currently registered with a
// schedule trigger.
Active int64 `json:"active"`
}
SchedulerMetrics summarizes the scheduler's activity so far.
type Snapshot ¶
type Snapshot struct {
Runs RunMetrics `json:"runs"`
Plugins []PluginMetrics `json:"plugins"`
Scheduler SchedulerMetrics `json:"scheduler"`
Connectors ConnectorMetrics `json:"connectors"`
}
Snapshot is a point-in-time, JSON-friendly view of everything a Registry has recorded — the shape internal/api's GET /v1/system/metrics handler serializes. It deliberately carries less detail than the Prometheus text exposition (no histogram buckets): a JSON snapshot is for a dashboard widget or a quick status check, not for the same kind of querying an external Prometheus server does over the text endpoint.
type StepMetrics ¶
type StepMetrics struct {
// Transitions maps a step status to how many times a step has
// transitioned into it.
Transitions map[string]uint64 `json:"transitions"`
}
StepMetrics summarizes step transitions recorded so far.
Source Files