perf

Documentation

Overview

Package perf implements VORTEX's performance harness (build plan M9): a benchmark suite for continuous throughput/latency tracking with regression detection, OS-level tuning recommendations, and horizontal autoscale triggers. Standard library only.

Index

• func DetectOS() string
• func MaxGOMAXPROCS() int
• func RecommendedBufferSize() int
• func RecommendedSysctl() map[string]string
• type AutoscaleConfig
• type AutoscaleDecision
• type Autoscaler
  • func NewAutoscaler(cfg AutoscaleConfig) (*Autoscaler, error)
  • func (a *Autoscaler) Evaluate(cpuPercent float64, currentNodes int) AutoscaleDecision
  • func (a *Autoscaler) Execute(ctx context.Context, decision AutoscaleDecision) error
  • func (a *Autoscaler) Start(ctx context.Context, cpu CPUProvider, nodes func() int) error
• type BenchmarkResult
• type BenchmarkSuite
  • func NewBenchmarkSuite(name string) *BenchmarkSuite
  • func (s *BenchmarkSuite) Compare(baseline, current BenchmarkResult) RegressionReport
  • func (s *BenchmarkSuite) LoadBaseline(path string) (BenchmarkResult, error)
  • func (s *BenchmarkSuite) QuickBench() []BenchmarkResult
  • func (s *BenchmarkSuite) RunHTTPProxy(b *testing.B) BenchmarkResult
  • func (s *BenchmarkSuite) RunTCPTunnel(b *testing.B) BenchmarkResult
  • func (s *BenchmarkSuite) RunUDPTunnel(b *testing.B) BenchmarkResult
  • func (s *BenchmarkSuite) SaveBaseline(result BenchmarkResult, path string) error
• type CPUProvider
• type RegressionReport
• type TuneResult
  • func Apply(dry bool) TuneResult

Functions

func DetectOS

func DetectOS() string

DetectOS returns the current operating system: "linux", "darwin", or "windows".

func MaxGOMAXPROCS

func MaxGOMAXPROCS() int

MaxGOMAXPROCS returns the optimal GOMAXPROCS for this machine (the CPU count).

func RecommendedBufferSize

func RecommendedBufferSize() int

RecommendedBufferSize returns the optimal read-buffer size in bytes based on available system memory: 16KB under 1GB, 32KB for 1–4GB, 64KB above 4GB.

func RecommendedSysctl

func RecommendedSysctl() map[string]string

RecommendedSysctl returns the recommended kernel tuning settings for the current OS. Windows returns an empty map (tuning is not applied via sysctl).

Types

type AutoscaleConfig

type AutoscaleConfig struct {
	Provider    string        // "hetzner"|"digitalocean"|"vultr"|"linode"|"custom"
	APIKey      string        // from env — never a config file
	WebhookURL  string        // for "custom" provider
	MinNodes    int           // default 1
	MaxNodes    int           // default 10
	ScaleUpAt   float64       // CPU% to scale up (default 80)
	ScaleDownAt float64       // CPU% to scale down (default 20)
	Cooldown    time.Duration // min time between scale events (default 5m)
}

AutoscaleConfig configures horizontal autoscaling.

type AutoscaleDecision

type AutoscaleDecision struct {
	Action    string `json:"action"` // "scale-up"|"scale-down"|"none"
	Reason    string `json:"reason"`
	NodeCount int    `json:"node_count"` // desired node count
}

AutoscaleDecision is the outcome of an Evaluate call.

type Autoscaler

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

Autoscaler evaluates CPU pressure and triggers scale events.

func NewAutoscaler

func NewAutoscaler(cfg AutoscaleConfig) (*Autoscaler, error)

NewAutoscaler validates cfg and builds an Autoscaler.

func (*Autoscaler) Evaluate

func (a *Autoscaler) Evaluate(cpuPercent float64, currentNodes int) AutoscaleDecision

Evaluate decides whether to scale given current CPU usage and node count. It respects the cooldown and the min/max node bounds.

func (*Autoscaler) Execute

func (a *Autoscaler) Execute(ctx context.Context, decision AutoscaleDecision) error

Execute carries out a scale decision. For the "custom" provider it POSTs a JSON body to the webhook; cloud providers are stubbed (logged, non-fatal).

func (*Autoscaler) Start

func (a *Autoscaler) Start(ctx context.Context, cpu CPUProvider, nodes func() int) error

Start runs the autoscale loop every 30s until ctx is cancelled: it reads CPU via cpu, evaluates, and executes any non-none decision. nodes returns the current node count.

type BenchmarkResult

type BenchmarkResult struct {
	Name          string    `json:"name"`
	Timestamp     time.Time `json:"timestamp"`
	ReqPerSec     float64   `json:"req_per_sec"`
	P50Ms         float64   `json:"p50_ms"`
	P95Ms         float64   `json:"p95_ms"`
	P99Ms         float64   `json:"p99_ms"`
	ThroughputMBs float64   `json:"throughput_mbs"`
	AllocsPerOp   int64     `json:"allocs_per_op"`
	BytesPerOp    int64     `json:"bytes_per_op"`
	ErrorRate     float64   `json:"error_rate"`
}

BenchmarkResult captures one benchmark run's headline metrics.

type BenchmarkSuite

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

BenchmarkSuite runs and compares benchmarks for a named subject.

func NewBenchmarkSuite

func NewBenchmarkSuite(name string) *BenchmarkSuite

NewBenchmarkSuite returns a suite tagged with name.

func (*BenchmarkSuite) Compare

func (s *BenchmarkSuite) Compare(baseline, current BenchmarkResult) RegressionReport

Compare evaluates current against baseline. It reports a regression when a throughput-style metric drops, or a latency/error metric rises, by more than regressionThreshold percent. The worst offending metric is reported.

func (*BenchmarkSuite) LoadBaseline

func (s *BenchmarkSuite) LoadBaseline(path string) (BenchmarkResult, error)

LoadBaseline reads a baseline result from path.

func (*BenchmarkSuite) QuickBench

func (s *BenchmarkSuite) QuickBench() []BenchmarkResult

QuickBench runs a fixed-iteration version of each benchmark without a *testing.B, for the `vortex tune bench` command. It returns one result per subject (tcp, http, udp).

func (*BenchmarkSuite) RunHTTPProxy

func (s *BenchmarkSuite) RunHTTPProxy(b *testing.B) BenchmarkResult

RunHTTPProxy benchmarks an httptest backend behind a trivial proxy, reporting requests/sec.

func (*BenchmarkSuite) RunTCPTunnel

func (s *BenchmarkSuite) RunTCPTunnel(b *testing.B) BenchmarkResult

RunTCPTunnel benchmarks an in-memory TCP byte-copy tunnel using net.Pipe so there is no real network overhead, reporting MB/s and allocs/op.

func (*BenchmarkSuite) RunUDPTunnel

func (s *BenchmarkSuite) RunUDPTunnel(b *testing.B) BenchmarkResult

RunUDPTunnel benchmarks UDP forwarding over loopback, reporting packets/sec as ReqPerSec and MB/s.

func (*BenchmarkSuite) SaveBaseline

func (s *BenchmarkSuite) SaveBaseline(result BenchmarkResult, path string) error

SaveBaseline writes result to path as JSON.

type CPUProvider

type CPUProvider func() float64

CPUProvider returns the current cluster-wide CPU usage percentage.

type RegressionReport

type RegressionReport struct {
	Regressed bool    `json:"regressed"`
	Delta     float64 `json:"delta"`  // percentage change of the worst metric
	Metric    string  `json:"metric"` // which metric regressed
	Message   string  `json:"message"`
}

RegressionReport describes whether a current result regressed against a baseline.

type TuneResult

type TuneResult struct {
	Applied []string `json:"applied"`
	Skipped []string `json:"skipped"`
	Errors  []string `json:"errors"`
}

TuneResult records the outcome of applying OS tuning settings.

func Apply

func Apply(dry bool) TuneResult

Apply applies (or, with dry=true, simulates applying) the recommended sysctl settings on Linux. Settings that cannot be applied for lack of permissions go to Skipped; failures go to Errors. On non-Linux or in dry-run mode nothing is changed and all settings are reported as Skipped.