《MMO 服务器开发》2.1 帧预算与性能剖析

// file: internal/profile/budget.go
// tier: L1
// verify: go test ./internal/profile/
// Package profile is chapter two's toolbox: a frame-budget accountant, a GC
// sampler, and a bounded-queue/hotspot-isolation layer. Everything here is
// standard library only.
package profile

import (
	"sort"
	"time"
)

// TargetTickHz is《晨曦大陆》's simulation rate. A 30 Hz server gets a fresh
// frame every 33.3ms; that frame is the budget everything else is measured
// against.
const TargetTickHz = 30

// FrameBudget is one tick's wall-clock allowance, split by phase. The numbers
// are a target for a scene node running《晨曦大陆》's combat map: broadcast
// (AOI) dominates because every entity's visibility delta fans out to
// neighbours, movement is cheap, combat is bursty, timers are steady.
type FrameBudget struct {
	Tick     time.Duration
	Movement time.Duration
	AOI      time.Duration
	Combat   time.Duration
	Timers   time.Duration
}

// DefaultFrameBudget is the section 2.1 budget table.
func DefaultFrameBudget() FrameBudget {
	return FrameBudget{
		Tick:     time.Second / TargetTickHz, // 33.33ms
		Movement: 6 * time.Millisecond,
		AOI:      12 * time.Millisecond,
		Combat:   8 * time.Millisecond,
		Timers:   3 * time.Millisecond,
	}
}

// Assigned is the sum of the phase budgets; Headroom is what is left of the
// tick after the phases. Headroom absorbs jitter and short spikes — a budget
// with zero headroom is a budget that is already overrun.
func (b FrameBudget) Assigned() time.Duration {
	return b.Movement + b.AOI + b.Combat + b.Timers
}

// Headroom returns the unassigned slice of the tick.
func (b FrameBudget) Headroom() time.Duration { return b.Tick - b.Assigned() }

// Phase names a stage of one tick.
type Phase string

const (
	PhaseMovement Phase = "movement"
	PhaseAOI      Phase = "aoi-broadcast"
	PhaseCombat   Phase = "combat"
	PhaseTimers   Phase = "timers"
)

// BudgetOf returns the wall-clock allowance for a phase.
func (b FrameBudget) BudgetOf(p Phase) time.Duration {
	switch p {
	case PhaseMovement:
		return b.Movement
	case PhaseAOI:
		return b.AOI
	case PhaseCombat:
		return b.Combat
	case PhaseTimers:
		return b.Timers
	default:
		return 0
	}
}

// FrameRecorder accumulates per-phase durations across ticks and reports how
// much of each phase's budget was actually used.
type FrameRecorder struct {
	budget FrameBudget
	total  map[Phase]time.Duration
	ticks  int
}

// NewFrameRecorder returns a recorder bound to a budget.
func NewFrameRecorder(b FrameBudget) *FrameRecorder {
	return &FrameRecorder{budget: b, total: make(map[Phase]time.Duration)}
}

// Observe records one phase's duration for one tick.
func (r *FrameRecorder) Observe(p Phase, d time.Duration) { r.total[p] += d }

// EndTick closes the tick counter.
func (r *FrameRecorder) EndTick() { r.ticks++ }

// TickCount returns how many ticks were recorded.
func (r *FrameRecorder) TickCount() int { return r.ticks }

// PhaseReport is one row of the frame-budget breakdown.
type PhaseReport struct {
	Phase     Phase
	Avg       time.Duration // average per tick
	Budget    time.Duration // allowance per tick
	PctOfTick float64       // Avg / Tick
	Used      float64       // Avg / Budget
}

// Report computes the per-phase average and its share of the tick and of its
// own budget, sorted by descending average.
func (r *FrameRecorder) Report() []PhaseReport {
	if r.ticks == 0 {
		return nil
	}
	out := make([]PhaseReport, 0, len(r.total))
	for p, d := range r.total {
		avg := d / time.Duration(r.ticks)
		bud := r.budget.BudgetOf(p)
		used := 0.0
		if bud > 0 {
			used = float64(avg) / float64(bud)
		}
		out = append(out, PhaseReport{
			Phase:     p,
			Avg:       avg,
			Budget:    bud,
			PctOfTick: float64(avg) / float64(r.budget.Tick),
			Used:      used,
		})
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Avg > out[j].Avg })
	return out
}

// Overruns returns the phases whose average exceeded their budget, worst first.
func (r *FrameRecorder) Overruns() []Phase {
	var out []Phase
	for _, row := range r.Report() {
		if row.Used > 1.0 {
			out = append(out, row.Phase)
		}
	}
	return out
}

// file: internal/profile/cpuprofile_test.go
// tier: L2
// verify: go test ./internal/profile/ -run TestHTTPPprof -v
package profile

import (
	"io"
	"net/http"
	"net/http/pprof"
	"net/http/httptest"
	"strings"
	"testing"
)

// TestHTTPPprof starts a real HTTP server with the net/http/pprof handlers
// mounted, keeps a worker busy, then pulls the index, the goroutine profile and
// a one-second CPU profile over HTTP — the same endpoints an ops engineer hits
// on a live scene node.
func TestHTTPPprof(t *testing.T) {
	mux := http.NewServeMux()
	mux.HandleFunc("/debug/pprof/", pprof.Index)
	mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
	mux.Handle("/debug/pprof/goroutine", pprof.Handler("goroutine"))
	mux.Handle("/debug/pprof/heap", pprof.Handler("heap"))
	srv := httptest.NewServer(mux)
	defer srv.Close()

	stop := make(chan struct{})
	go func() {
		for {
			select {
			case <-stop:
				return
			default:
				aoiBroadcast(2048)
			}
		}
	}()

	// 1) The index must list the built-in profiles.
	body := get(t, srv.URL+"/debug/pprof/")
	for _, want := range []string{"goroutine", "heap", "profile", "threadcreate"} {
		if !strings.Contains(body, want) {
			t.Errorf("/debug/pprof/ index missing %q", want)
		}
	}

	// 2) The goroutine profile must capture our running worker.
	g := get(t, srv.URL+"/debug/pprof/goroutine?debug=1")
	if !strings.Contains(g, "aoiBroadcast") {
		t.Errorf("goroutine profile did not capture aoiBroadcast")
	}

	// 3) A one-second CPU profile must be a non-empty gzip pprof blob.
	prof := get(t, srv.URL+"/debug/pprof/profile?seconds=1")
	close(stop)
	if len(prof) < 100 {
		t.Fatalf("cpu profile too small: %d bytes", len(prof))
	}
	if !(prof[0] == 0x1f && prof[1] == 0x8b) {
		t.Fatalf("cpu profile is not a gzip blob: % x", prof[:2])
	}
	t.Logf("pprof ok: goroutine profile %d bytes, cpu profile %d bytes (gzip)", len(g), len(prof))
}

func get(t *testing.T, url string) string {
	t.Helper()
	resp, err := http.Get(url)
	if err != nil {
		t.Fatalf("GET %s: %v", url, err)
	}
	defer resp.Body.Close()
	b, err := io.ReadAll(resp.Body)
	if err != nil {
		t.Fatalf("read %s: %v", url, err)
	}
	if resp.StatusCode != http.StatusOK {
		t.Fatalf("GET %s: status %d", url, resp.StatusCode)
	}
	return string(b)
}

=== RUN   TestHTTPPprof
    cpuprofile_test.go:63: pprof ok: goroutine profile 5282 bytes, cpu profile 2715 bytes (gzip)
--- PASS: TestHTTPPprof (1.12s)
PASS
ok  	aegis/internal/profile	1.465s

goos: darwin
goarch: arm64
pkg: aegis/internal/profile
cpu: Apple M1 Pro
BenchmarkTick-10    	     300	   1083475 ns/op	 2977816 B/op	   44679 allocs/op

    frame_budget_test.go:69: phase=aoi-broadcast avg=960.491µs budget=12ms      used=   8%
    frame_budget_test.go:69: phase=combat        avg=101.008µs budget=8ms       used=   1%
    frame_budget_test.go:69: phase=movement      avg=81.749µs  budget=6ms       used=   1%
    frame_budget_test.go:69: phase=timers        avg=10.351µs  budget=3ms       used=   0%

      flat  flat%   sum%        cum   cum%
     1.48s 27.87% 27.87%      1.48s 27.87%  runtime.madvise
     0.89s 16.76% 44.63%      0.89s 16.76%  runtime.kevent
     0.79s 14.88% 59.51%      0.79s 14.88%  runtime.pthread_cond_wait
     0.52s  9.79% 69.30%      0.52s  9.79%  runtime.pthread_cond_signal
     0.34s  6.40% 75.71%      0.34s  6.40%  runtime.usleep
     0.31s  5.84% 81.54%      0.31s  5.84%  runtime.pthread_kill
     0.11s  2.07% 83.62%      0.32s  6.03%  runtime.mallocgcSmallNoscan
     0.10s  1.88% 85.50%      0.48s  9.04%  runtime.mallocgc
     0.07s  1.32% 90.02%      0.54s 10.17%  aegis/internal/profile.aoiBroadcast