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 ¶
const ( CollectorName = "proxy-stats" ValueKey = "stats" Key = CollectorName + "/" + ValueKey )
The collected key checks declare (design §8.8).
const (
// MaxBody bounds one stats body; a larger one fails the Pod, never a truncated parse.
MaxBody = 1 << 20
)
const OffReason = "Proxy stats are turned off"
OffReason is the reason published when proxy stats are turned off.
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.
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 ¶
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 (*Collector) Round ¶
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.
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 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 (Kube) Fetch ¶
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.
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 ¶
ParseEnvoy reads Envoy's /stats text format ("name: value" lines). Names outside StatsFilter and values that are not integers are ignored.
type Rejects ¶
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.