proxystats

package
v0.7.0-alpha.1 Latest Latest
Warning

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

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

Documentation

Overview

Package proxystats reads Envoy stats from each Gateway proxy's stats listener (design §8.8, D-037). A Source finds the proxies and reads their stats; the Collector scrapes every source on the metrics interval and publishes what checks read under Key.

Index

Constants

View Source
const (
	CollectorName = "proxy-stats"
	ValueKey      = "stats"
	Key           = CollectorName + "/" + ValueKey
)

The collected key checks declare (design §8.8).

View Source
const (
	// MaxBody bounds one stats body; a larger one fails the Pod, never a truncated parse.
	MaxBody = 1 << 20
)
View Source
const OffReason = "Proxy stats are turned off"

OffReason is the reason published when proxy stats are turned off.

View Source
const StatsFilter = `^(control_plane\.connected_state|cluster_manager\.warming_clusters|listener_manager\.total_listeners_warming|` +
	`listener_manager\.lds\.update_(rejected|success)|cluster_manager\.cds\.update_(rejected|success)|` +
	`http\..*\.rds\..*\.update_rejected|cluster\..*\.update_rejected|server\.state|server\.uptime)$`

StatsFilter is the one regex of the §8.8 table: the request sends it as /stats?filter=, and ParseEnvoy keeps only names it matches in full.

View Source
const StatsPort = 9091

StatsPort is the kgateway proxy's stats listener; Envoy's admin port is never read.

Variables

This section is empty.

Functions

func NewHTTPClient

func NewHTTPClient() *http.Client

NewHTTPClient is the in-cluster client: no proxy from the environment, no redirects; the collector bounds each request through its context.

Types

type Collector

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

Collector scrapes each install's proxies and turns their counters into rejects observed since the previous scrape per Pod UID (Review Focus 2).

func New

func New(cfg Config) *Collector

New returns a Collector for cfg.

func (*Collector) Round

func (c *Collector) Round(ctx context.Context) (Stats, uint64, bool)

Round scrapes every install once and returns the value, its fingerprint and true; false when there is no model yet.

func (*Collector) Run

func (c *Collector) Run(ctx context.Context, publish func(key string, v any, fp uint64, ttl time.Duration), fail func(key string, st collect.State, reason string)) error

Run scrapes now and every interval until ctx is done, publishing under ValueKey with a TTL of three intervals; Off publishes collect.Off once.

func (*Collector) Tracked

func (c *Collector) Tracked() int

Tracked is how many Pods have counters held; a vanished Pod is dropped on the next round.

type Config

type Config struct {
	Source Source
	// Every is the scrape interval, the metrics interval.
	Every time.Duration
	// Clock drives the ticker and stamps Rejects.Since; nil means the real clock.
	Clock clock.WithTicker
	// Installs returns the installs and the snapshot they were resolved from;
	// a nil snapshot (no model yet) skips the round.
	Installs func() ([]Install, *cache.Snapshot)
	// Off publishes collect.Off once and scrapes nothing.
	Off bool
}

Config configures a Collector.

type Gateway

type Gateway struct {
	Gateway objects.Ref
	// Observed is false when the source knows no proxies for the Gateway, as
	// for a self-managed one; that is "not observed", never failing.
	Observed bool
	// Pods are in name order. A Pod with Err is failing; the others keep their stats.
	Pods []Pod
}

Gateway is one Gateway's proxies.

type Install

type Install struct {
	Resolved install.Resolved
	Gateways []objects.Ref
}

Install is one install to scrape and the Gateways it owns.

type Kube

type Kube struct {
	// Client fetches over the Pod IP, in-cluster; nil means NewHTTPClient(). It never
	// follows redirects, but a supplied client keeps its transport: set Proxy: nil yourself.
	Client *http.Client
	// Kube, when set, fetches through pods/proxy with the user's own rights
	// instead, over its REST client's HTTP client without redirects or retries.
	Kube kubernetes.Interface
	// Port is the stats listener port; zero means StatsPort.
	Port int32
}

Kube is the Kubernetes Source: the running Pods of each Gateway's proxy Deployment, their stats listener's /stats, and Envoy's text format.

func KubeFor added in v0.6.0

func KubeFor(kube kubernetes.Interface, inCluster bool) Kube

KubeFor is the Kube source: the Pod IP in-cluster, pods/proxy with the user's rights otherwise (D-037).

func (Kube) Fetch

func (k Kube) Fetch(ctx context.Context, t Target) ([]byte, error)

Fetch implements Source. It reads at most MaxBody + 1 bytes, and its errors are fixed text: the response body never reaches an error or a log.

func (Kube) Interpret

func (Kube) Interpret(t Target, body []byte) (PodStats, error)

Interpret implements Source with Envoy's text format.

func (Kube) Targets

func (k Kube) Targets(in install.Resolved, gw objects.Ref, snap *cache.Snapshot) ([]Target, bool)

Targets implements Source: the running, non-terminating Pods of gw's proxy Deployment. Without the Deployment or the proxy Pod watch, as for a self-managed Gateway, they are not observed.

type Pair

type Pair struct{ Rejected, Success int64 }

Pair is a type's update_rejected and update_success counters.

type Pod

type Pod struct {
	UID, Name string
	// Err is a fixed-text reason when the scrape failed; the other fields are then empty.
	Err                               string
	Connected                         *bool
	WarmingListeners, WarmingClusters *int64
	ServerState                       string
	// LDS and CDS say whether update_rejected grew since this UID's previous scrape.
	LDS, CDS Rejects
	// RDS and Clusters are the Envoy names whose update_rejected grew since
	// the previous scrape, sorted. Names are evidence, never Gateway API objects.
	RDS, Clusters []string
	// RDSTruncated and ClustersTruncated are set when names were dropped from that list.
	RDSTruncated, ClustersTruncated bool
	// Names are every Envoy route config and cluster name this scrape reported, grown
	// or not, sorted; the controller log reader matches log names against them.
	Names []string
}

Pod is one proxy's latest scrape. Nil fields were not reported.

type PodStats

type PodStats struct {
	UID, Name string
	Gateway   objects.Ref
	// Connected is control_plane.connected_state.
	Connected *bool
	// WarmingListeners and WarmingClusters are Envoy's warming gauges.
	WarmingListeners, WarmingClusters *int64
	LDS, CDS                          Pair
	// RDS and Clusters are update_rejected per Envoy route config and cluster name.
	RDS, Clusters map[string]int64
	// RDSTruncated and ClustersTruncated are set when the source dropped names.
	RDSTruncated, ClustersTruncated bool
	// ServerState is "live", "draining", "pre-initializing" or "initializing".
	ServerState string
	// Uptime is server.uptime in seconds; zero when not reported.
	Uptime int64
	Err    string
}

PodStats are one proxy's raw counters as Interpret reads them; nil and empty fields were not reported, and no field means "rejecting now".

func ParseEnvoy

func ParseEnvoy(body []byte) (PodStats, error)

ParseEnvoy reads Envoy's /stats text format ("name: value" lines). Names outside StatsFilter and values that are not integers are ignored.

type Rejects

type Rejects struct {
	Seen  bool
	Since time.Time
}

Rejects are a type's rejects observed since the previous scrape; never "rejecting now" (review finding 4). Since starts the current run of growth.

type Source

type Source interface {
	// Targets are gw's proxies; false means the source knows none (not observed).
	Targets(in install.Resolved, gw objects.Ref, snap *cache.Snapshot) ([]Target, bool)
	// Fetch reads one proxy's stats. The collector bounds its time through ctx and
	// rejects a body over MaxBody; error texts must not carry response content.
	Fetch(ctx context.Context, t Target) ([]byte, error)
	// Interpret reads body into raw counters.
	Interpret(t Target, body []byte) (PodStats, error)
}

Source finds a Gateway's proxies, fetches their stats and interprets them. Kube is the default; a downstream with other proxies or another stats format supplies its own through extension.WithProxyStatsSource.

type Stats

type Stats map[string][]Gateway

Stats is the value under Key: per install ID, its Gateways in Ref order. It holds observed rejects, not counters, so steady rejects keep one value.

type Target

type Target struct {
	// ID is stable for the process's life, such as a Pod UID; Name is shown.
	ID, Name string
	Gateway  objects.Ref
	// Addr is where the source fetches from, such as "podIP:9091".
	Addr string
}

Target is one proxy to scrape.

Jump to

Keyboard shortcuts

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