metrics

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package metrics is the single owner of the controller's launch metric set (DESIGN §6): every Prometheus collector the reconciler and the poller record against is created and registered here, exactly once, so that no other package registers a metric of its own.

Index

Constants

View Source
const LabelWavefront = "wavefront"

LabelWavefront is the label every per-Wavefront collector carries: the name of the owning Wavefront. Wavefronts are cluster-scoped and may be co-resident, and the per-pass gauges are recomputed wholesale on each pass — without this label a pass would have to Reset() the collector and would erase a sibling's series until its next pass. With it, a pass retires exactly its own series (DeletePartialMatch) and a cross-fleet total is a PromQL sum(). WavefrontScope is the only place this label's position is spelled out; every collector puts it first.

Variables

This section is empty.

Functions

This section is empty.

Types

type Instruments

type Instruments struct {
	// AdmissionsTotal counts pin admissions by owning Wavefront and result:
	// "admitted" (an ancestor-gated advance), "initial"
	// (initial-pin-on-discovery), "shadow" (would-be admission in Shadow
	// mode, no write) or "conflict" (blocked by a foreign field-manager
	// hold). Attributed like every other per-Wavefront collector, but —
	// being cumulative — its series are never retired by a pass; only
	// Forget (on Wavefront deletion) deletes them, since there is no
	// wholesale recomputation for a pass to reconcile a counter against.
	AdmissionsTotal *prometheus.CounterVec // wavefront_admissions_total{wavefront,result}
	// PinLagSeconds is the age, in seconds, of each node's currently
	// unadmitted observed revision. Recomputed wholesale every pass, per
	// Wavefront: the owning Wavefront's name is a label so that one
	// Wavefront's pass can retire only its own series (DeletePartialMatch)
	// rather than Reset()ting a co-resident Wavefront's series away.
	PinLagSeconds *prometheus.GaugeVec // wavefront_node_pin_lag_seconds{wavefront,kind,namespace,name}
	// AdmissionWaitSeconds is observed→admitted latency at the moment an
	// admission actually executes (DESIGN D13, the starvation signal), by
	// owning Wavefront. Cumulative like AdmissionsTotal: a pass never
	// retires its series, only Forget does (on Wavefront deletion).
	AdmissionWaitSeconds *prometheus.HistogramVec // wavefront_admission_wait_seconds{wavefront}
	// BlockedNodes is the current blocked-node count by BlockedReason,
	// per Wavefront. Recomputed wholesale every pass (per-Wavefront, as
	// PinLagSeconds); a fleet total is sum() across the wavefront label.
	BlockedNodes *prometheus.GaugeVec // wavefront_blocked_nodes{wavefront,reason}
	// RefListFailures counts ref-advertisement listing failures by git host
	// (owned here; the poller only records against it).
	RefListFailures *prometheus.CounterVec // wavefront_ref_list_failures_total{host}
	// PinnedFetchFailures is the current count of pinned sources with a
	// sourcev1 FetchFailed condition (§10 force-push detection), per
	// Wavefront. Recomputed wholesale every pass; a fleet total is sum()
	// across the wavefront label.
	PinnedFetchFailures *prometheus.GaugeVec // wavefront_pinned_fetch_failures{wavefront}
	// CredentialReadFailures counts failures reading git credential Secrets
	// during ref-advertisement sweeps (owned here; the poller only records
	// against it). Not per-Wavefront: a credential read happens ahead of
	// any one Wavefront's evaluation.
	CredentialReadFailures prometheus.Counter // wavefront_credential_read_failures_total
}

Instruments is the fixed set of collectors the controller records against (DESIGN §6, names and labels verbatim).

func New

New registers the launch metric set on reg and returns the handles the reconciler and poller record against.

Calling New more than once on the same reg (e.g. a second controller wiring against the shared ctrlmetrics.Registry) does not panic: each collector already registered is reused rather than re-registered, so every caller ends up recording against the same underlying series. main wires this exactly once regardless.

New fails if reg already holds a same-named collector that register cannot reuse: either a genuinely incompatible descriptor (different labels or help text — not an AlreadyRegisteredError at all) or a name collision with a collector of a different Go type (an AlreadyRegisteredError whose ExistingCollector fails the type assertion). Both are name collisions on the shared registry that must reach the caller rather than silently vanish, so every collector is registered before New returns — errors.Join reports every collision in one call instead of stopping at the first.

func Nop

func Nop() *Instruments

Nop returns Instruments backed by a fresh, isolated registry: tests and fixtures that need something to record against without touching the process's default registry.

func (*Instruments) Wavefront

func (i *Instruments) Wavefront(name string) WavefrontScope

Wavefront returns the scope through which the reconciler and poller record every per-Wavefront collector for the Wavefront named name. Label order (wavefront first, always) lives only inside WavefrontScope's methods, not at each call site.

type WavefrontScope

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

WavefrontScope binds every per-Wavefront collector to one Wavefront's name.

func (WavefrontScope) CountAdmission

func (s WavefrontScope) CountAdmission(result string)

CountAdmission increments s's Wavefront's admissions counter for result.

func (WavefrontScope) Forget

func (s WavefrontScope) Forget()

Forget deletes every series this Wavefront has ever contributed: Retire's per-pass gauges, plus the cumulative counter and histogram (AdmissionsTotal, AdmissionWaitSeconds) that a pass leaves alone because there is no wholesale recomputation to reconcile a cumulative series against. Call once, when the Wavefront itself is deleted.

func (WavefrontScope) ObserveAdmissionWait

func (s WavefrontScope) ObserveAdmissionWait(seconds float64)

ObserveAdmissionWait records one observed→admitted latency sample for s's Wavefront.

func (WavefrontScope) Retire

func (s WavefrontScope) Retire()

Retire deletes s's series from every gauge a pass recomputes wholesale (PinLagSeconds, BlockedNodes, PinnedFetchFailures) via DeletePartialMatch on this Wavefront's own label — never Reset(), which would erase a co-resident Wavefront's series until its own next pass. Call at the start of a pass, before recomputing, so a node or reason that dropped out of the fleet since the last pass does not linger.

func (WavefrontScope) SetBlocked

func (s WavefrontScope) SetBlocked(reason string, count int)

SetBlocked sets s's Wavefront's blocked-node count for one BlockedReason.

func (WavefrontScope) SetPinLag

func (s WavefrontScope) SetPinLag(kind, namespace, name string, seconds float64)

SetPinLag sets s's Wavefront's pin-lag gauge for one node.

func (WavefrontScope) SetPinnedFetchFailures

func (s WavefrontScope) SetPinnedFetchFailures(count int)

SetPinnedFetchFailures sets s's Wavefront's pinned-fetch-failures gauge.

Jump to

Keyboard shortcuts

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