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
- func NewHTTPClient() *http.Client
- type Collector
- type CollectorOption
- type GatewayKey
- type HTTPScraper
- type ManagedKey
- type Metrics
- type ModeKey
- type PodBounded
- type PodMetrics
- type PodProxyScraper
- type PodTotals
- type Result
- type Scraper
- type SnapshotResources
- type Source
- type Static
- type TypeKey
Constants ¶
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 ¶
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 ¶
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) 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 ¶
HTTPScraper scrapes the pod IP directly (in-cluster mode). A nil Client means NewHTTPClient(); a supplied one keeps its transport but never follows redirects.
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 ¶
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 ¶
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 ¶
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 ¶
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.
type PodTotals ¶
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 ¶
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).
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 Static ¶
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.
type TypeKey ¶
type TypeKey struct {
Gateway GatewayKey
TypeURL string
}
TypeKey identifies an xDS reject series: one Gateway and one resource type.