ctrlmetrics

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package ctrlmetrics scrapes and interprets the kgateway controller's Prometheus metrics. All metric names the UI depends on are declared here.

Index

Constants

View Source
const (
	XDSRejectsActive = "kgateway_envoy_xds_rejects_active"
	ResourcesManaged = "kgateway_resources_managed"
	// XDSRejectsTotal counts rejected xDS responses. On v2.3 and v2.4 it grows
	// on every re-push; on v2.5 and later it counts episodes.
	XDSRejectsTotal = "kgateway_envoy_xds_rejects_total"
	// UpdatesDropped counts dropped resources-metric updates. Above zero, the
	// kgateway_resources_* gauges are invalid until the controller restarts.
	UpdatesDropped = "kgateway_resources_updates_dropped_total"
	// XDSSnapshotResources is the controller's xDS snapshot per Gateway and
	// resource type: what it built, not what proxies accepted.
	XDSSnapshotResources = "kgateway_xds_snapshot_resources"
	// BuildInfo carries the controller version in its version label (v2.5 and later; pkg/version/metrics.go at v2.5.0).
	BuildInfo = "kgateway_build_info"
	// PerClientWithheld counts withheld clients per Gateway and state (v2.5 and later).
	PerClientWithheld = "kgateway_xds_snapshot_perclient_withheld_clients"
	// PerClientBounded counts publications a time bound released before every cluster was ready, per Gateway and mode.
	PerClientBounded = "kgateway_xds_snapshot_perclient_bounded_publishes_total"
	// PerClientDefers counts per-client snapshots built while a referenced cluster was not ready, per Gateway and reason.
	PerClientDefers = "kgateway_xds_snapshot_perclient_defers_total"
	// DeferredClients counts connected clients without a snapshot yet, per Gateway.
	DeferredClients = "kgateway_xds_snapshot_deferred_clients"
	// WarmWithheld is the PerClientWithheld state of a warm client withheld past the publish budget.
	WarmWithheld = "warm_withheld"
)

Metric families the UI depends on (verified on kgateway v2.3.x, v2.4.x and main).

Variables

This section is empty.

Functions

func NewHTTPClient

func NewHTTPClient() *http.Client

NewHTTPClient is the in-cluster client: a 5 s timeout, no proxy from the environment and no redirects.

Types

type Collector

type Collector struct {

	// OnResult, if set, is notified after a stored result that is the install's
	// first, differs in content from the previous one, or follows one that had
	// gone stale. A result that only renews CollectedAt does not notify; the
	// engine's staleness deadline reads it.
	OnResult *trigger.Signal
	// contains filtered or unexported fields
}

Collector periodically scrapes every install's ready controller pods.

func NewCollector

func NewCollector(s Scraper, opts ...CollectorOption) *Collector

NewCollector returns a Collector using s and the real clock unless an option says otherwise.

func (*Collector) Collect

func (c *Collector) Collect(ctx context.Context, in install.Install) Result

Collect scrapes all ready pods of in and aggregates them. It fails if any ready pod cannot be scraped: a partial sum of rejects must not look like zero.

func (*Collector) Get

func (c *Collector) Get(id string) (Result, bool)

Get implements Source.

func (*Collector) Run

func (c *Collector) Run(ctx context.Context, every time.Duration, installs func() []install.Install) error

Run collects every interval until ctx is done and returns nil then. It returns an error if every <= 0. Installs are scraped concurrently, each pod under a deadline of min(every/2, 5s); a tick waits for all installs.

type CollectorOption

type CollectorOption func(*Collector)

CollectorOption adjusts a Collector at construction.

func WithClock

func WithClock(clk clock.WithTicker) CollectorOption

WithClock makes the collector stamp results and tick with clk (tests).

func WithMaxAge

func WithMaxAge(d time.Duration) CollectorOption

WithMaxAge sets the staleness limit consumers use (3 × the metrics interval), so a result after a stale one notifies.

func WithResultHook

func WithResultHook(f func(id string, r Result, notified bool)) CollectorOption

WithResultHook makes Run call f after each result's notify decision (tests).

type GatewayKey

type GatewayKey struct{ Namespace, Name string }

GatewayKey identifies a Gateway in metric labels.

type HTTPScraper

type HTTPScraper struct{ Client *http.Client }

HTTPScraper scrapes the pod IP directly (in-cluster mode). A nil Client means NewHTTPClient(); a supplied one keeps its transport but never follows redirects.

func (HTTPScraper) Scrape

func (s HTTPScraper) Scrape(ctx context.Context, pod *corev1.Pod, port int32) (io.ReadCloser, error)

Scrape implements Scraper.

type ManagedKey

type ManagedKey struct{ Namespace, Resource string }

ManagedKey identifies a resources_managed series after summing over "parent".

type Metrics

type Metrics struct {
	// Rejects is the number of active xDS rejects per Gateway, summed over type_url.
	Rejects map[GatewayKey]float64
	// Managed is kgateway_resources_managed summed over the parent label.
	Managed map[ManagedKey]float64
	// ManagedPresent is true if the family appeared in the scrape. An absent
	// family with resources in scope suggests a rename upstream.
	ManagedPresent bool
	// PerPod holds each controller Pod's samples, sorted by Pod name.
	PerPod []PodMetrics
	// Snapshot is XDSSnapshotResources per Gateway; never a finding.
	Snapshot map[GatewayKey]SnapshotResources
}

Metrics is the interpreted subset of one or more controller scrapes.

func Aggregate

func Aggregate(replicas []Metrics) Metrics

Aggregate combines per-replica scrapes. Rejects are summed, because each proxy's xDS stream is served by one replica. Managed counts are maxed, because every replica computes the full set (D-012), and so is each snapshot count. PerPod is concatenated and sorted by Pod name, then UID.

func Parse

func Parse(r io.Reader) (Metrics, error)

Parse interprets a text-format /metrics payload. A gauge that has never been set has no series, so an absent family means zero, not an error.

func (Metrics) BuildVersion

func (m Metrics) BuildVersion() (v string, agreed bool)

BuildVersion is the build_info version every reporting Pod shares; "" when no Pod reports one. agreed is false when two Pods disagree, as during a rollout.

type ModeKey

type ModeKey struct {
	Gateway GatewayKey
	Mode    string
}

ModeKey identifies a bounded-publish series: one Gateway and one mode.

type PodBounded

type PodBounded map[string]map[ModeKey]float64

PodBounded is the last seen bounded_publishes_total per Pod UID.

func BoundedGrowth

func BoundedGrowth(prev PodBounded, cur []PodMetrics) (growth, next PodBounded)

BoundedGrowth is TotalGrowth for bounded_publishes_total, kept per Pod UID so callers can name the Pods: a first sight is a baseline and a lower value a reset.

type PodMetrics

type PodMetrics struct {
	UID, Name string
	// Active and Total are rejects_active and rejects_total per Gateway and type.
	Active, Total map[TypeKey]float64
	// Dropped is updates_dropped_total; DroppedPresent is false when the
	// family is absent, which never means zero.
	Dropped        float64
	DroppedPresent bool
	// BuildVersion is build_info's version label, such as "v2.5.0"; "" when absent.
	BuildVersion string
	// PerClientPresent is true when the scrape has a per-client family or
	// build_info (both kgateway 2.5). Withheld and bounded series exist only
	// while a client is held, so their absence alone proves nothing.
	PerClientPresent bool
	// Withheld is the warm_withheld client count per Gateway; nil when none.
	Withheld map[GatewayKey]float64
	// Bounded is bounded_publishes_total per Gateway and mode; nil when none.
	Bounded map[ModeKey]float64
}

PodMetrics is what one controller Pod reports. Parse leaves UID and Name empty; the collector fills them from the scraped Pod.

type PodProxyScraper

type PodProxyScraper struct{ Kube kubernetes.Interface }

PodProxyScraper scrapes through the API server's pods/proxy subresource (local mode; uses the user's kubeconfig rights). It sends one GET over the REST client's HTTP client without redirects; Request.Stream is not used, as it reads error bodies unbounded and retries on Retry-After.

func (PodProxyScraper) Scrape

func (s PodProxyScraper) Scrape(ctx context.Context, pod *corev1.Pod, port int32) (io.ReadCloser, error)

Scrape implements Scraper.

type PodTotals

type PodTotals map[string]map[TypeKey]float64

PodTotals is the last seen rejects_total per Pod UID.

func TotalGrowth

func TotalGrowth(prev PodTotals, cur []PodMetrics) (growth map[TypeKey]float64, next PodTotals)

TotalGrowth returns the rejects_total growth since prev, summed over Pods per type, and the totals to pass next time. Growth is taken per Pod UID: a Pod seen for the first time sets a baseline, a counter that went down is a reset, and neither counts as growth, so a restarted replica is never negative. A UID absent from cur is forgotten, so callers skip Err results (an empty cur forgets every UID). A series new under a seen UID counts its full value.

type Result

type Result struct {
	Metrics     Metrics
	CollectedAt time.Time
	// Err is non-empty when the metrics could not be collected completely.
	Err string
}

Result is the outcome of collecting one install's metrics.

func (Result) SameContent

func (r Result) SameContent(o Result) bool

SameContent reports whether r and o carry the same Err and Metrics. CollectedAt is not content: freshness is a deadline, not a change (D-019).

func (Result) Stale

func (r Result) Stale(now time.Time, maxAge time.Duration) bool

Stale reports whether r was collected more than maxAge before now. A zero maxAge never makes a result stale. Consumers use 3 × the metrics interval, so a stalled collector cannot keep an old zero-reject result green.

type Scraper

type Scraper interface {
	Scrape(ctx context.Context, pod *corev1.Pod, port int32) (io.ReadCloser, error)
}

Scraper fetches the /metrics payload of one controller pod.

type SnapshotResources

type SnapshotResources struct {
	Listeners, Routes, Clusters, Endpoints, Secrets int
}

SnapshotResources counts the resources of one Gateway's xDS snapshot.

type Source

type Source interface {
	Get(id string) (Result, bool)
}

Source returns the latest Result per install ID.

type Static

type Static map[string]Result

Static is a Source over fixed results, one per install ID, for a caller that collects once with Collector.Collect and computes over it (D-053). It never ages a result: the engine reads one older than its MetricsMaxAge as stale, as it reads the Collector's. It never waits or collects again. The engine copies its Config, so for fresher metrics the caller collects again and updates the map's entries; replacing the map has no effect.

func (Static) Get

func (s Static) Get(id string) (Result, bool)

Get implements Source.

type TypeKey

type TypeKey struct {
	Gateway GatewayKey
	TypeURL string
}

TypeKey identifies an xDS reject series: one Gateway and one resource type.

Jump to

Keyboard shortcuts

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