puma-plus-core 0.1.0

data/go/internal/control/sim/cooldown_test.go

@@ -0,0 +1,74 @@
+package sim
+
+import (
+	"testing"
+	"time"
+)
+
+// TestCooldownTradeoff is the experiment that set SpawnCooldown.
+//
+// A live Phase 4 run showed the controller sitting out fifteen consecutive
+// breaching ticks logging "spawn cooldown has N left". This quantified the cost
+// and the trade, and is kept as a permanent artifact so the next person to touch
+// the cooldown can see the shape of the decision rather than guess at it.
+//
+// The two blocks below are the two sides: fast forks, where a short cooldown is
+// strictly better, and slow forks, where the cooldown is irrelevant because the
+// settled gate binds first.
+func TestCooldownTradeoff(t *testing.T) {
+	step := []Phase{
+		{Duration: 30 * time.Second, Rate: 40},
+		{Duration: 120 * time.Second, Rate: 400},
+		{Duration: 60 * time.Second, Rate: 40},
+	}
+
+	t.Log("fork  cooldown | spawns maxW | p95      shed    time-over-target")
+	t.Log("---------------------------------------------------------------")
+	for _, fork := range []time.Duration{time.Second, 8 * time.Second} {
+		for _, cd := range []time.Duration{2, 3, 5, 15} {
+			cooldown := cd * time.Second
+			p := DefaultParams()
+			p.ForkLatency = fork
+			p.Workload = Workload{ServiceMean: 25 * time.Millisecond, ServiceCV: 0.8, CPUFraction: 0.15}
+			p.Workload.Phases = step
+			p.Config.MinWorkers, p.Config.MaxWorkers = 1, 16
+			p.Config.SpawnCooldown = cooldown
+
+			r := Run(p)
+			over := 0
+			for _, s := range r.Samples {
+				if s.QueueP95 > p.Config.TargetQueueP95 {
+					over++
+				}
+			}
+			t.Logf("%-5s %-8s | %-6d %-4d | %-8s %-7d %ds",
+				fork, cooldown, r.Spawns, r.MaxWorkers,
+				r.QueueP95.Round(time.Millisecond), r.Shed, over)
+		}
+	}
+}
+
+// TestAlternatingLoadByCooldown checks the other side of the trade: a short
+// cooldown must not turn flapping load into fork thrash.
+func TestAlternatingLoadByCooldown(t *testing.T) {
+	var flap []Phase
+	for i := 0; i < 20; i++ {
+		flap = append(flap,
+			Phase{Duration: 5 * time.Second, Rate: 400},
+			Phase{Duration: 5 * time.Second, Rate: 20})
+	}
+
+	t.Log("cooldown | spawns retires maxW  (alternating 400/20 rps every 5s)")
+	t.Log("----------------------------------------------------------------")
+	for _, cd := range []time.Duration{2, 5, 10, 15, 30} {
+		cooldown := cd * time.Second
+		p := DefaultParams()
+		p.Workload = Workload{ServiceMean: 25 * time.Millisecond, ServiceCV: 0.8, CPUFraction: 0.15}
+		p.Workload.Phases = flap
+		p.Config.MinWorkers, p.Config.MaxWorkers = 1, 16
+		p.Config.SpawnCooldown = cooldown
+
+		r := Run(p)
+		t.Logf("%-8s | %-6d %-7d %d", cooldown, r.Spawns, r.Retires, r.MaxWorkers)
+	}
+}

data/go/internal/control/sim/sim.go

@@ -0,0 +1,599 @@
+// Package sim is a discrete-event simulation of the puma-plus plant: arrivals,
+// a queue, worker threads with service times, and fork latency.
+//
+// Its purpose is to let the controller be tuned and regression-tested without
+// forking a single Ruby process. Oscillation, fork thrash and death spirals are
+// all cheap to find here and expensive to find under load; the simulator runs a
+// ten-minute scenario in milliseconds and is fully deterministic, so a failure
+// reproduces exactly.
+//
+// It is genuinely event-driven -- arrivals, completions and controller ticks are
+// scheduled on a priority queue and time jumps between them. An earlier
+// fixed-timestep version was quietly wrong: with a 1s step and 25ms service
+// times each slot could complete at most one request per step, capping capacity
+// at one request per slot per second instead of forty, so every scenario looked
+// hopelessly overloaded. Event-driven has no such coupling between the
+// controller's tick rate and the plant's throughput.
+//
+// It models the parts that change controller behavior and ignores the rest.
+// Notably it does model the GVL: a worker process gets at most one core's worth
+// of CPU regardless of thread count, which is the single most important reason
+// naive thread scaling backfires on Ruby.
+package sim
+
+import (
+	"container/heap"
+	"math"
+	"math/rand"
+	"sort"
+	"time"
+
+	"github.com/evanphx/puma-plus/internal/control"
+)
+
+// Workload describes the offered load and the work itself.
+type Workload struct {
+	// Phases are (duration, arrival rate) segments, walked in order.
+	Phases []Phase
+	// ServiceMean is mean time inside the app.
+	ServiceMean time.Duration
+	// ServiceCV is the coefficient of variation of service time. 0 is
+	// deterministic; 1 is exponential; >1 is the heavy tail that makes tail
+	// latency interesting.
+	ServiceCV float64
+	// CPUFraction is how much of service time is on-CPU rather than blocked on
+	// IO. 0.05 is a database-bound request; 1.0 is a pure compute loop. This is
+	// what decides whether adding threads to a process helps at all.
+	CPUFraction float64
+}
+
+// Phase is one segment of the arrival schedule.
+type Phase struct {
+	Duration time.Duration
+	Rate     float64 // requests per second
+}
+
+// Params configures the simulated plant.
+type Params struct {
+	Workload Workload
+	Config   control.Config
+
+	// ForkLatency is how long a spawned worker takes before it can serve. This
+	// is the controller's dead time and the main source of overshoot.
+	ForkLatency time.Duration
+	// WorkerRSS is the memory each worker occupies, for the memory guard.
+	WorkerRSS int64
+	// CoresPerWorker caps a worker's parallelism. 1.0 models MRI's GVL.
+	CoresPerWorker float64
+
+	// ControlTick is how often the controller runs. Independent of the plant's
+	// resolution, which is continuous.
+	ControlTick time.Duration
+	Seed        int64
+	Start       time.Time
+}
+
+// DefaultParams returns a plausible plant: a Rails-ish IO-bound request, a
+// one-second fork, MRI's single-core-per-process constraint.
+func DefaultParams() Params {
+	return Params{
+		Workload: Workload{
+			ServiceMean: 25 * time.Millisecond,
+			ServiceCV:   0.8,
+			CPUFraction: 0.2,
+		},
+		Config:         control.DefaultConfig(),
+		ForkLatency:    time.Second,
+		WorkerRSS:      120 << 20,
+		CoresPerWorker: 1.0,
+		ControlTick:    time.Second,
+		Start:          time.Unix(1700000000, 0),
+	}
+}
+
+// --- event queue ---------------------------------------------------------
+
+type eventKind int
+
+const (
+	evArrival eventKind = iota
+	evCompletion
+	evWorkerReady
+	evControlTick
+	evEnd
+)
+
+type event struct {
+	at   time.Time
+	kind eventKind
+	seq  int64 // tie-breaker, so equal timestamps resolve deterministically
+	req  *request
+	wid  int
+}
+
+type eventQueue []*event
+
+func (q eventQueue) Len() int { return len(q) }
+func (q eventQueue) Less(i, j int) bool {
+	if q[i].at.Equal(q[j].at) {
+		return q[i].seq < q[j].seq
+	}
+	return q[i].at.Before(q[j].at)
+}
+func (q eventQueue) Swap(i, j int) { q[i], q[j] = q[j], q[i] }
+func (q *eventQueue) Push(x any)   { *q = append(*q, x.(*event)) }
+func (q *eventQueue) Pop() any     { old := *q; n := len(old); e := old[n-1]; *q = old[:n-1]; return e }
+
+type request struct {
+	runnable time.Time
+	started  time.Time
+	service  time.Duration
+	worker   int
+}
+
+type worker struct {
+	id       int
+	born     time.Time
+	ready    bool
+	slots    int
+	busy     int
+	draining bool
+}
+
+// Result is what a run reports.
+type Result struct {
+	Completed  int
+	Shed       int
+	QueueP50   time.Duration
+	QueueP95   time.Duration
+	QueueP99   time.Duration
+	QueueMax   time.Duration
+	Spawns     int
+	Retires    int
+	MaxWorkers int
+	MinWorkers int
+	// WorkerSeconds is the integral of worker count over time: the cost side of
+	// the ledger, for comparing an autoscaler against a statically provisioned
+	// server at equal latency.
+	WorkerSeconds float64
+	Samples       []Sample
+}
+
+// Sample is one controller tick of observable state, for plotting and for
+// assertions about behavior over time.
+type Sample struct {
+	T        time.Duration
+	Rate     float64
+	Workers  int
+	Capacity int
+	Depth    int
+	QueueP95 time.Duration
+	Actions  []control.Action
+}
+
+type sim struct {
+	p   Params
+	rng *rand.Rand
+	now time.Time
+	seq int64
+
+	q        eventQueue
+	queue    []*request
+	workers  []*worker
+	nextID   int
+	st       control.State
+	res      Result
+	recent   []recentDone // rolling window of completions for the measured p95
+	allQueue []time.Duration
+
+	lastWorkerChange time.Time
+}
+
+type recentDone struct {
+	at    time.Time
+	queue time.Duration
+}
+
+func (s *sim) push(kind eventKind, at time.Time, req *request, wid int) {
+	s.seq++
+	heap.Push(&s.q, &event{at: at, kind: kind, seq: s.seq, req: req, wid: wid})
+}
+
+// Run executes the simulation and returns the outcome.
+func Run(p Params) Result {
+	if p.ControlTick == 0 {
+		p.ControlTick = time.Second
+	}
+	if p.CoresPerWorker == 0 {
+		p.CoresPerWorker = 1.0
+	}
+
+	var total time.Duration
+	for _, ph := range p.Workload.Phases {
+		total += ph.Duration
+	}
+	if total == 0 {
+		total = time.Minute
+	}
+
+	s := &sim{
+		p:      p,
+		rng:    rand.New(rand.NewSource(p.Seed)),
+		now:    p.Start,
+		nextID: 1,
+	}
+	s.lastWorkerChange = p.Start
+
+	for i := 0; i < p.Config.MinWorkers; i++ {
+		s.workers = append(s.workers, &worker{
+			id: s.nextID, born: s.now, ready: true, slots: p.Config.ThreadsPerWorker,
+		})
+		s.nextID++
+	}
+	s.res.MinWorkers = len(s.workers)
+	s.res.MaxWorkers = len(s.workers)
+
+	heap.Init(&s.q)
+	s.push(evEnd, p.Start.Add(total), nil, 0)
+	s.push(evControlTick, p.Start.Add(p.ControlTick), nil, 0)
+	s.scheduleArrival(p.Start, total)
+
+	for s.q.Len() > 0 {
+		e := heap.Pop(&s.q).(*event)
+		s.accrueWorkerSeconds(e.at)
+		s.now = e.at
+
+		switch e.kind {
+		case evEnd:
+			s.finish()
+			return s.res
+		case evArrival:
+			s.onArrival(e.req, total)
+		case evCompletion:
+			s.onCompletion(e.req)
+		case evWorkerReady:
+			s.onWorkerReady(e.wid)
+		case evControlTick:
+			s.onControlTick(total)
+		}
+	}
+	s.finish()
+	return s.res
+}
+
+// scheduleArrival draws the next inter-arrival gap from an exponential
+// distribution, giving a Poisson process. Constant-rate arrivals would
+// understate queueing badly, because real clients do not coordinate.
+func (s *sim) scheduleArrival(after time.Time, total time.Duration) {
+	elapsed := after.Sub(s.p.Start)
+	rate := rateAt(s.p.Workload.Phases, elapsed)
+	if rate <= 0 {
+		// No load in this phase; look again at the next phase boundary.
+		next := nextPhaseBoundary(s.p.Workload.Phases, elapsed)
+		if next < 0 || next > total {
+			return
+		}
+		s.push(evArrival, s.p.Start.Add(next), nil, 0)
+		return
+	}
+
+	gap := s.rng.ExpFloat64() / rate
+	at := after.Add(time.Duration(gap * float64(time.Second)))
+	if at.Sub(s.p.Start) > total {
+		return
+	}
+	r := &request{runnable: at, service: sampleService(s.rng, s.p.Workload)}
+	s.push(evArrival, at, r, 0)
+}
+
+func (s *sim) onArrival(r *request, total time.Duration) {
+	s.scheduleArrival(s.now, total)
+	if r == nil {
+		return // phase-boundary wakeup, no request attached
+	}
+
+	// Admission control, evaluated once per request at arrival. Keyed off the
+	// predicted wait rather than a measured percentile, because a percentile
+	// only knows about requests that already suffered.
+	if control.ShouldShed(s.p.Config, s.predictedWait()) {
+		s.res.Shed++
+		return
+	}
+
+	s.queue = append(s.queue, r)
+	s.dispatch()
+}
+
+func (s *sim) onCompletion(r *request) {
+	for _, w := range s.workers {
+		if w.id == r.worker {
+			w.busy--
+			break
+		}
+	}
+	s.res.Completed++
+	qt := r.started.Sub(r.runnable)
+	s.allQueue = append(s.allQueue, qt)
+	s.recent = append(s.recent, recentDone{at: s.now, queue: qt})
+
+	s.reapDraining()
+	s.dispatch()
+}
+
+func (s *sim) onWorkerReady(id int) {
+	for _, w := range s.workers {
+		if w.id == id {
+			w.ready = true
+		}
+	}
+	s.dispatch()
+}
+
+// dispatch hands queued work to any free slot.
+func (s *sim) dispatch() {
+	for len(s.queue) > 0 {
+		w := s.freeWorker()
+		if w == nil {
+			return
+		}
+		r := s.queue[0]
+		s.queue = s.queue[1:]
+		r.started = s.now
+		r.worker = w.id
+		w.busy++
+		s.push(evCompletion, s.now.Add(s.stretched(r.service, w)), r, 0)
+	}
+}
+
+// freeWorker picks the least-loaded ready worker, which is what a dispatcher
+// with per-thread connections naturally does.
+func (s *sim) freeWorker() *worker {
+	var best *worker
+	for _, w := range s.workers {
+		if !w.ready || w.draining || w.busy >= w.slots {
+			continue
+		}
+		if best == nil || w.busy < best.busy {
+			best = w
+		}
+	}
+	return best
+}
+
+// stretched models GVL contention. Only the CPU portion of service time
+// stretches, and only once a process runs more concurrent requests than it has
+// cores. IO-bound work scales with threads; CPU-bound work does not -- which is
+// exactly why the right scaling answer inverts between workload types.
+func (s *sim) stretched(base time.Duration, w *worker) time.Duration {
+	concurrency := float64(w.busy) // already incremented for this request
+	if concurrency <= s.p.CoresPerWorker {
+		return base
+	}
+	factor := concurrency / s.p.CoresPerWorker
+	cpu := float64(base) * s.p.Workload.CPUFraction
+	io := float64(base) * (1 - s.p.Workload.CPUFraction)
+	return time.Duration(cpu*factor + io)
+}
+
+func (s *sim) reapDraining() {
+	out := s.workers[:0]
+	for _, w := range s.workers {
+		if w.draining && w.busy == 0 {
+			continue
+		}
+		out = append(out, w)
+	}
+	if len(out) != len(s.workers) {
+		s.workers = out
+		s.noteWorkerCount()
+	}
+}
+
+func (s *sim) onControlTick(total time.Duration) {
+	elapsed := s.now.Sub(s.p.Start)
+	if elapsed < total {
+		s.push(evControlTick, s.now.Add(s.p.ControlTick), nil, 0)
+	}
+
+	// Trim the measured window to the last 5 seconds, matching the real
+	// collector's scaling window.
+	cut := s.now.Add(-5 * time.Second)
+	keep := s.recent[:0]
+	for _, d := range s.recent {
+		if !d.at.Before(cut) {
+			keep = append(keep, d)
+		}
+	}
+	s.recent = keep
+
+	in := control.Inputs{
+		Now:           s.now,
+		QueueP95:      windowPct(s.recent, 0.95),
+		PredictedWait: s.predictedWait(),
+		Depth:         len(s.queue),
+		Capacity:      s.capacity(),
+		Busy:          s.busy(),
+		ArrivalRate:   rateAt(s.p.Workload.Phases, elapsed),
+		ServiceMean:   s.p.Workload.ServiceMean.Seconds(),
+		Workers:       s.snapshot(),
+	}
+
+	actions, next := control.Decide(s.p.Config, in, s.st)
+	s.st = next
+
+	for _, a := range actions {
+		switch a.Kind {
+		case control.ActionSpawnWorker:
+			w := &worker{id: s.nextID, born: s.now, slots: s.p.Config.ThreadsPerWorker}
+			s.nextID++
+			s.workers = append(s.workers, w)
+			s.push(evWorkerReady, s.now.Add(s.p.ForkLatency), nil, w.id)
+			s.res.Spawns++
+			s.noteWorkerCount()
+		case control.ActionRetireWorker:
+			for _, w := range s.workers {
+				if w.id == a.WorkerID {
+					w.draining = true
+					s.res.Retires++
+				}
+			}
+			s.reapDraining()
+		}
+	}
+
+	s.res.Samples = append(s.res.Samples, Sample{
+		T: elapsed, Rate: in.ArrivalRate, Workers: len(s.workers),
+		Capacity: in.Capacity, Depth: in.Depth, QueueP95: in.QueueP95, Actions: actions,
+	})
+}
+
+func (s *sim) predictedWait() time.Duration {
+	c := s.capacity()
+	if c <= 0 {
+		return time.Hour
+	}
+	return time.Duration(float64(len(s.queue)+1) *
+		s.p.Workload.ServiceMean.Seconds() / float64(c) * float64(time.Second))
+}
+
+func (s *sim) capacity() int {
+	total := 0
+	for _, w := range s.workers {
+		if w.ready && !w.draining {
+			total += w.slots
+		}
+	}
+	return total
+}
+
+func (s *sim) busy() int {
+	total := 0
+	for _, w := range s.workers {
+		total += w.busy
+	}
+	return total
+}
+
+func (s *sim) snapshot() []control.WorkerInfo {
+	out := make([]control.WorkerInfo, 0, len(s.workers))
+	for _, w := range s.workers {
+		out = append(out, control.WorkerInfo{
+			ID: w.id, StartedAt: w.born, Booted: w.ready, Slots: w.slots,
+			Busy: w.busy, RSSBytes: s.p.WorkerRSS, LastSeen: s.now, Draining: w.draining,
+		})
+	}
+	return out
+}
+
+func (s *sim) noteWorkerCount() {
+	if n := len(s.workers); n > s.res.MaxWorkers {
+		s.res.MaxWorkers = n
+	} else if n < s.res.MinWorkers {
+		s.res.MinWorkers = n
+	}
+}
+
+func (s *sim) accrueWorkerSeconds(until time.Time) {
+	if until.After(s.lastWorkerChange) {
+		s.res.WorkerSeconds += float64(len(s.workers)) * until.Sub(s.lastWorkerChange).Seconds()
+		s.lastWorkerChange = until
+	}
+}
+
+func (s *sim) finish() {
+	sort.Slice(s.allQueue, func(i, j int) bool { return s.allQueue[i] < s.allQueue[j] })
+	s.res.QueueP50 = pct(s.allQueue, 0.50)
+	s.res.QueueP95 = pct(s.allQueue, 0.95)
+	s.res.QueueP99 = pct(s.allQueue, 0.99)
+	if len(s.allQueue) > 0 {
+		s.res.QueueMax = s.allQueue[len(s.allQueue)-1]
+	}
+}
+
+// --- helpers -------------------------------------------------------------
+
+func rateAt(phases []Phase, elapsed time.Duration) float64 {
+	var acc time.Duration
+	for _, ph := range phases {
+		acc += ph.Duration
+		if elapsed < acc {
+			return ph.Rate
+		}
+	}
+	if len(phases) > 0 {
+		return phases[len(phases)-1].Rate
+	}
+	return 0
+}
+
+func nextPhaseBoundary(phases []Phase, elapsed time.Duration) time.Duration {
+	var acc time.Duration
+	for _, ph := range phases {
+		acc += ph.Duration
+		if elapsed < acc {
+			return acc
+		}
+	}
+	return -1
+}
+
+// sampleService draws a service time with the requested mean and coefficient of
+// variation, using a gamma distribution so CV is controllable independently of
+// the mean.
+func sampleService(rng *rand.Rand, w Workload) time.Duration {
+	if w.ServiceCV <= 0 {
+		return w.ServiceMean
+	}
+	mean := w.ServiceMean.Seconds()
+	shape := 1 / (w.ServiceCV * w.ServiceCV)
+	scale := mean / shape
+	v := gamma(rng, shape) * scale
+	if v < 0 {
+		v = 0
+	}
+	return time.Duration(v * float64(time.Second))
+}
+
+// gamma samples from Gamma(shape, 1) via Marsaglia-Tsang.
+func gamma(rng *rand.Rand, shape float64) float64 {
+	if shape < 1 {
+		return gamma(rng, shape+1) * math.Pow(rng.Float64(), 1/shape)
+	}
+	d := shape - 1.0/3.0
+	c := 1 / math.Sqrt(9*d)
+	for {
+		x := rng.NormFloat64()
+		v := 1 + c*x
+		if v <= 0 {
+			continue
+		}
+		v = v * v * v
+		u := rng.Float64()
+		if u < 1-0.0331*x*x*x*x || math.Log(u) < 0.5*x*x+d*(1-v+math.Log(v)) {
+			return d * v
+		}
+	}
+}
+
+func windowPct(done []recentDone, q float64) time.Duration {
+	if len(done) == 0 {
+		return 0
+	}
+	vals := make([]time.Duration, len(done))
+	for i, d := range done {
+		vals[i] = d.queue
+	}
+	sort.Slice(vals, func(i, j int) bool { return vals[i] < vals[j] })
+	return pct(vals, q)
+}
+
+func pct(sorted []time.Duration, q float64) time.Duration {
+	if len(sorted) == 0 {
+		return 0
+	}
+	i := int(q * float64(len(sorted)))
+	if i >= len(sorted) {
+		i = len(sorted) - 1
+	}
+	return sorted[i]
+}