ctrllogs

package
v0.7.1 Latest Latest
Warning

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

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

Documentation

Overview

Package ctrllogs reads controller logs when the user opts in, and keeps only fixed fields (design §8.9, D-037). A Source finds the controller replicas and opens their logs; the Collector follows one stream per replica, drops every line without a parser marker unparsed and publishes derived events under Key.

Index

Constants

View Source
const (
	// FollowSince is how far back a replica's first stream starts.
	FollowSince = 900 * time.Second
	// PreviousTailLines asks for the previous log's tail, where a crash ends; no byte
	// limit is sent, as the API would cut the tail's end (R101). Under GOTRACEBACK=all
	// a panic's first line can sit above this tail: no event then, which never means no panic.
	PreviousTailLines = 200
	// PreviousLimit is the client's safety cap on that read.
	PreviousLimit = 4 << 20
	// MaxFailures marked lines in a row that fail to parse make the format unrecognised.
	MaxFailures = 10
)
View Source
const (
	CollectorName = "controller-logs"
	ValueKey      = "events"
	Key           = CollectorName + "/" + ValueKey
)

The collected key checks declare (design §8.9).

View Source
const MaxEvents = 1000

MaxEvents is how many derived events one install keeps; the oldest go first.

Variables

View Source
var (
	// ErrDenied: the UI may not read the Pod's log.
	ErrDenied = errors.New("controller logs: access denied")
	// ErrNotReady: the container has no log to follow yet, or its Pod is gone.
	ErrNotReady = errors.New("controller logs: container not ready")
)

Errors a Source wraps, so the Collector can tell them apart.

Functions

This section is empty.

Types

type Collector

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

Collector follows each controller replica's log and keeps derived events per install.

func New

func New(cfg Config) *Collector

New returns a Collector for cfg.

func (*Collector) Reconcile

func (c *Collector) Reconcile(ctx context.Context) bool

Reconcile starts a stream for each new replica and a previous read for each new restart, and stops, and waits for, the streams of replicas that went. It returns false when there is no model or no proxy stats value yet.

func (*Collector) Run

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

Run reconciles and publishes now and every interval until ctx is done, under ValueKey with a TTL of three intervals; a change a stream makes is published within publishDelay. Every stream has ended when it returns.

func (*Collector) Streams

func (c *Collector) Streams() int

Streams is how many replica streams run.

func (*Collector) Value

func (c *Collector) Value() (Logs, uint64)

Value is a copy of every install's events and state, and its fingerprint.

type Config

type Config struct {
	Source Source
	// Every is how often replicas are reconciled and the events published.
	Every time.Duration
	// Clock drives the ticker and back-off and stamps lines without a time; nil means the real clock.
	Clock clock.WithTicker
	// Installs returns the installs to read; false means no model yet.
	Installs func() ([]Install, bool)
	// Stats returns the latest proxy stats and their state; nil means unavailable.
	Stats func() (proxystats.Stats, StatsState)
}

Config configures a Collector.

type Event

type Event struct {
	Time time.Time
	// Marker is the parser's marker the line matched.
	Marker  string
	Gateway objects.Ref
	TypeURL string
	// Names are Envoy resource names that equal one in the Gateway's proxy stats, sorted.
	Names []string
	Class string
	// Object is the known object a deployer error names, nil when none.
	Object *objects.Ref
	// Frame is a panic's top frame function, from the previous container only.
	Frame string
	// Pod is the ID of the replica whose previous container logged a panic. It is
	// empty on other events, so one line logged by two replicas stays one event.
	Pod string
}

Event is one derived signal from a controller log line. Every field is from a closed set or a known name; log text never is (D-037).

type Install

type Install struct {
	Resolved install.Resolved
	// Parser reads its kgateway version's lines; nil means no log is read.
	Parser computed.LogParser
	// Gateways are the install's Gateways; an event naming another is dropped.
	Gateways []objects.Ref
	// Known reports whether the UI sees an object a deployer error names; nil keeps none.
	Known func(objects.Ref) bool
}

Install is one install whose controller logs are read.

type InstallLogs

type InstallLogs struct {
	Events []Event
	State  State
}

InstallLogs are one install's derived events, oldest first, and how its reading goes.

type Kube

type Kube struct{ Client kubernetes.Interface }

Kube is the Kubernetes Source: the install's controller Pods, read through pods/log with the UI's own Role (design §8.9).

func (Kube) Follow

func (k Kube) Follow(ctx context.Context, t Target, since time.Duration) (io.ReadCloser, error)

Follow implements Source.

func (Kube) Previous

func (k Kube) Previous(ctx context.Context, t Target) (io.ReadCloser, error)

Previous implements Source.

func (Kube) Targets

func (Kube) Targets(in install.Resolved) []Target

Targets implements Source: the install's controller Pods that have started.

type Logs

type Logs map[string]InstallLogs

Logs is the value under Key, per install ID.

type Source

type Source interface {
	// Targets are the install's controller replicas.
	Targets(in install.Resolved) []Target
	// Follow streams t's current container log from since ago until ctx ends.
	Follow(ctx context.Context, t Target, since time.Duration) (io.ReadCloser, error)
	// Previous reads the tail of t's previous container log; the Collector caps the bytes it reads.
	Previous(ctx context.Context, t Target) (io.ReadCloser, error)
}

Source finds an install's controller replicas and opens their logs. Kube is the default.

type State

type State string

State is how an install's log reading goes.

const (
	StateOn State = "on"
	// StateNoParser: the install's rule set reads no logs, so nothing is read.
	StateNoParser State = "no-parser"
	// StateFailing: a stream cannot be read.
	StateFailing State = "failing"
	// StateUnrecognised: 10 marked lines in a row failed to parse.
	StateUnrecognised State = "unrecognised"
	// StateDenied: the UI may not read a controller Pod's log.
	StateDenied State = "denied"
	// StatePending: the first round has not connected a stream yet.
	StatePending State = "pending"
	// StateNotConnected: no stream has connected after the first round.
	StateNotConnected State = "not-connected"
)

Reading states; Availability ranks on, not connected, failing, unrecognised, denied from best to worst.

func Availability

func Availability(snap collect.Snapshot) (State, bool)

Availability is the controllerLogs capability's state from the collected value: the worst state of the installs that read logs, no-parser when none does, failing when the value is not current, and false before the first publication or while every reading install is pending.

type StatsState

type StatsState int

StatsState is how the latest proxy stats stand for the name check.

const (
	StatsUnavailable StatsState = iota
	StatsReady
	StatsPending
)

Proxy stats states. While pending, no stream starts, so the backfill meets the first scrape.

type Target

type Target struct {
	// ID is stable for the replica's life, such as a Pod UID.
	ID, Namespace, Name, Container string
	// Restarts is the container's restart count; each new one gets one previous read.
	Restarts int32
}

Target is one controller replica.

Directories

Path Synopsis
Package ctrllogstest serves controller logs for benchmarks and scale tests: a ctrllogs.Source whose follow streams write marked lines at a fixed rate.
Package ctrllogstest serves controller logs for benchmarks and scale tests: a ctrllogs.Source whose follow streams write marked lines at a fixed rate.

Jump to

Keyboard shortcuts

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