analyze

Documentation

Overview

Package analyze provides read-only pipeline constraint analysis. It identifies the bottleneck stage from interval telemetry and recommends worker allocation. Does not actuate — shadow mode only.

Index

• type Analyzer
  • func NewAnalyzer(interval time.Duration, opts ...Option) *Analyzer
  • func (a *Analyzer) AddStage(spec StageSpec)
  • func (a *Analyzer) CurrentSnapshot() *Snapshot
  • func (a *Analyzer) Run(ctx context.Context)
• type Option
  • func WithLogger(l *log.Logger) Option
• type Snapshot
• type StageAnalysis
• type StageSpec
• type StageState
  • func (s StageState) String() string

Types

type Analyzer

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

Analyzer periodically evaluates pipeline stages and logs constraint identification + worker allocation recommendations. Read-only.

func NewAnalyzer

func NewAnalyzer(interval time.Duration, opts ...Option) *Analyzer

NewAnalyzer creates an analyzer that evaluates every interval. Panics if interval <= 0.

func (*Analyzer) AddStage

func (a *Analyzer) AddStage(spec StageSpec)

AddStage registers a stage for analysis. Must be called before Run. Panics if Name is empty, Stats is nil, or Run has started.

func (*Analyzer) CurrentSnapshot

func (a *Analyzer) CurrentSnapshot() *Snapshot

Snapshot returns the most recent analysis. Nil before the first interval.

func (*Analyzer) Run

func (a *Analyzer) Run(ctx context.Context)

Run blocks, analyzing every interval until ctx is canceled. Panics if called twice.

type Option

type Option func(*Analyzer)

Option configures an Analyzer.

func WithLogger

func WithLogger(l *log.Logger) Option

WithLogger sets the logger for analyzer output.

type Snapshot

type Snapshot struct {
	At         time.Time
	Constraint string  // empty if none identified
	Confidence float64 // 0.0-1.0
	Stages     map[string]StageAnalysis
}

Snapshot is the analyzer's output for one interval. Immutable after creation.

type StageAnalysis

type StageAnalysis struct {
	State           StageState
	Utilization     float64
	IdleRatio       float64
	BlockedRatio    float64
	QueueGrowth     float64
	ErrorRate       float64
	CurrentWorkers  int
	Recommendation  int    // suggested workers; 0 = no recommendation
	RecommendReason string // human-readable explanation
}

StageAnalysis holds the analysis of a single stage for one interval.

type StageSpec

type StageSpec struct {
	Name       string
	Stats      func() toc.Stats
	MinWorkers int  // default 1
	MaxWorkers int  // 0 = unlimited
	Scalable   bool // false = don't recommend changes
}

StageSpec describes a stage for analysis.

type StageState

type StageState int

StageState classifies a stage's operational state from interval signals.

const (
	StateUnknown   StageState = iota // insufficient data
	StateHealthy                     // normal operation
	StateStarved                     // high idle, waiting for input
	StateBlocked                     // high output-blocked, downstream-limited
	StateSaturated                   // high busy, low idle/blocked — constraint candidate
	StateBroken                      // elevated errors
)

func (StageState) String

func (s StageState) String() string