《MMO 服务器开发》1.1 压测口径：不要只看在线人数

// file: internal/loadtest/metrics.go
// tier: L1
// verify: go test ./internal/loadtest/
// This file is the section 1.1 "what a carrying metric is" table in code. The
// whole point of chapter one is that "online players" is not a carrying metric;
// these are the ones that are. A metric qualifies only if it has a unit, a
// direction that is worse, and a failure mode when it is exceeded.
package loadtest

// Metric is one carrying metric with a unit and the failure it predicts.
type Metric struct {
	Name string
	Unit string
	// Why is what the number tells you that "online players" does not.
	Why string
	// Bad is the failure mode once the metric is pushed past its budget.
	Bad string
}

// carryingMetrics is the section 1.1 metric definition table. Order is the
// order they should appear on a load-test report.
var carryingMetrics = []Metric{
	{
		Name: "connections",
		Unit: "count",
		Why:  "the real ceiling for a gateway: one socket, one fd, one accept-queue slot",
		Bad:  "accept backlog overflows and the kernel resets new sockets",
	},
	{
		Name: "message throughput",
		Unit: "msg/s",
		Why:  "how much work the single-writer world can actually retire per second",
		Bad:  "requests queue up behind the world loop and latency grows without bound",
	},
	{
		Name: "p50 latency",
		Unit: "ms",
		Why:  "what the median player feels on a normal action",
		Bad:  "the game feels sluggish even though nothing is technically broken",
	},
	{
		Name: "p99 latency",
		Unit: "ms",
		Why:  "the tail a tenth of actions land in; the number players complain about",
		Bad:  "hit registration and skill casts feel unreliable under peak load",
	},
	{
		Name: "error rate",
		Unit: "percent",
		Why:  "how many requests never got a valid reply at all",
		Bad:  "players see disconnects and lost actions; a green p99 hides this",
	},
	{
		Name: "resident memory",
		Unit: "MiB",
		Why:  "the per-connection and per-entity footprint multiplied by scale",
		Bad:  "the process is OOM-killed right when the most players are online",
	},
	{
		Name: "gc pause",
		Unit: "ms (max)",
		Why:  "the stall a stop-the-world collection adds to every in-flight request",
		Bad:  "a spike in p99 that has nothing to do with request volume",
	},
}

// AllMetrics returns the metric definition table in report order.
func AllMetrics() []Metric { return append([]Metric(nil), carryingMetrics...) }

// MetricByName returns the definition for a metric name.
func MetricByName(name string) (Metric, bool) {
	for _, m := range carryingMetrics {
		if m.Name == name {
			return m, true
		}
	}
	return Metric{}, false
}

// file: internal/loadtest/pitfalls.go
// tier: L1
// verify: go test ./internal/loadtest/
// The section 1.1 "common mistakes" table in code. Each row is a way to report
// a passing load test that says nothing about production, paired with the fix.
package loadtest

// Pitfall is one common way a load test lies to you.
type Pitfall struct {
	Name  string
	Wrong string
	Right string
}

// pitfalls is the section 1.1 "common mistakes" table.
var pitfalls = []Pitfall{
	{
		Name:  "only watching online players",
		Wrong: "5000 people are online, so the server is fine",
		Right: "5000 idle connections prove nothing; measure messages per second at that count",
	},
	{
		Name:  "reporting only the mean",
		Wrong: "average latency is 26 ms, all good",
		Right: "a 26 ms mean can hide a 1.6 s p99; always report the tail",
	},
	{
		Name:  "ignoring the error rate",
		Wrong: "throughput held at 3000 msg/s, test passed",
		Right: "if 2% of those never got a reply, the real throughput was lower and players lost actions",
	},
	{
		Name:  "leaving slow connections in the pool",
		Wrong: "one connection that reads at 1 KiB/s is just one connection",
		Right: "a slow reader back-pressures its send queue and can stall a shared writer",
	},
}

// AllPitfalls returns the pitfall table.
func AllPitfalls() []Pitfall { return append([]Pitfall(nil), pitfalls...) }

// file: internal/loadtest/metrics_test.go
// tier: L1
// verify: go test ./internal/loadtest/
package loadtest

import "testing"

func TestEveryMetricHasUnitAndFailure(t *testing.T) {
	// A number is only a carrying metric if it has a unit and a known failure
	// mode. "online players" fails both tests, which is why it is not in the
	// table.
	for _, m := range AllMetrics() {
		if m.Name == "" || m.Unit == "" {
			t.Errorf("metric %q missing name or unit", m.Name)
		}
		if m.Why == "" || m.Bad == "" {
			t.Errorf("metric %q must state why it matters and how it fails", m.Name)
		}
	}
}

func TestOnlinePlayersIsNotAMetric(t *testing.T) {
	if _, ok := MetricByName("online players"); ok {
		t.Fatal("online players must not be a carrying metric")
	}
}

func TestPitfallsAllHaveFix(t *testing.T) {
	for _, p := range AllPitfalls() {
		if p.Name == "" || p.Wrong == "" || p.Right == "" {
			t.Errorf("pitfall %q must describe both the wrong and the right way", p.Name)
		}
	}
}