《后端架构设计·高性能与高可用》2.3 压测结果解读与容量余量

// file: internal/capacity/histogram.go
// tier: L1
// verify: go test ./internal/capacity/ -count=1 -v
package capacity

import (
	"errors"
	"math"
	"sort"
	"time"
)

var (
	ErrNoBuckets      = errors.New("histogram needs at least one bucket")
	ErrBounds         = errors.New("bounds must be positive and strictly increasing")
	ErrBucketMismatch = errors.New("histograms have different bucket layouts")
	ErrEmpty          = errors.New("histogram has no observations")
	ErrQuantileRange  = errors.New("quantile must be within [0,1]")
	ErrOverflow       = errors.New("quantile falls in the overflow bucket")
)

// Histogram 是有序桶计数；Bounds 是闭区间上界，超出者进入 Overflow。
type Histogram struct {
	Bounds   []time.Duration
	Counts   []uint64
	Overflow uint64
}

func NewHistogram(bounds []time.Duration) (*Histogram, error) {
	if len(bounds) == 0 {
		return nil, ErrNoBuckets
	}
	for i, b := range bounds {
		if b <= 0 || (i > 0 && b <= bounds[i-1]) {
			return nil, ErrBounds
		}
	}
	return &Histogram{Bounds: append([]time.Duration(nil), bounds...), Counts: make([]uint64, len(bounds))}, nil
}

func (h *Histogram) Observe(d time.Duration) {
	idx := sort.Search(len(h.Bounds), func(i int) bool { return d <= h.Bounds[i] })
	if idx == len(h.Bounds) {
		h.Overflow++
		return
	}
	h.Counts[idx]++
}

func (h Histogram) Total() uint64 {
	total := h.Overflow
	for _, c := range h.Counts {
		total += c
	}
	return total
}

// Merge 先逐桶相加计数，再算分位数；不是把各实例分位数取平均。
func (h Histogram) Merge(others ...Histogram) (Histogram, error) {
	out := Histogram{Bounds: append([]time.Duration(nil), h.Bounds...),
		Counts: append([]uint64(nil), h.Counts...), Overflow: h.Overflow}
	for _, other := range others {
		if len(other.Bounds) != len(out.Bounds) {
			return Histogram{}, ErrBucketMismatch
		}
		for i := range out.Bounds {
			if other.Bounds[i] != out.Bounds[i] {
				return Histogram{}, ErrBucketMismatch
			}
		}
		for i, c := range other.Counts {
			out.Counts[i] += c
		}
		out.Overflow += other.Overflow
	}
	return out, nil
}

// Quantile 返回最近秩所在桶的上界；ok=false 表示排名落在 Overflow。
func (h Histogram) Quantile(q float64) (time.Duration, bool, error) {
	if q < 0 || q > 1 {
		return 0, false, ErrQuantileRange
	}
	total := h.Total()
	if total == 0 {
		return 0, false, ErrEmpty
	}
	rank := uint64(math.Ceil(q * float64(total)))
	rank = max(1, rank)
	var cumulative uint64
	for i, c := range h.Counts {
		cumulative += c
		if cumulative >= rank {
			return h.Bounds[i], true, nil
		}
	}
	return 0, false, nil
}

// AverageQuantile 保留“各实例分位数取平均”的错误做法，仅用于对照测试。
func AverageQuantile(hs []Histogram, q float64) (time.Duration, error) {
	if len(hs) == 0 {
		return 0, ErrEmpty
	}
	var sum time.Duration
	for _, h := range hs {
		v, ok, err := h.Quantile(q)
		if err != nil {
			return 0, err
		}
		if !ok {
			return 0, ErrOverflow
		}
		sum += v
	}
	return sum / time.Duration(len(hs)), nil
}

// file: internal/capacity/histogram_test.go
// tier: L1
// verify: go test ./internal/capacity/ -count=1 -v
package capacity

import (
	"errors"
	"testing"
	"time"
)

func mustHist(t *testing.T, bounds ...time.Duration) *Histogram {
	t.Helper()
	h, err := NewHistogram(bounds)
	if err != nil {
		t.Fatal(err)
	}
	return h
}

func TestHistogramQuantile(t *testing.T) {
	h := mustHist(t, 10*time.Millisecond, 100*time.Millisecond, time.Second)
	for i := 0; i < 99; i++ {
		h.Observe(5 * time.Millisecond)
	}
	h.Observe(2 * time.Second)
	for _, tt := range []struct {
		q    float64
		want time.Duration
		ok   bool
	}{
		{0.50, 10 * time.Millisecond, true},
		{0.99, 10 * time.Millisecond, true},
		{1.00, 0, false},
	} {
		got, ok, err := h.Quantile(tt.q)
		if err != nil || got != tt.want || ok != tt.ok {
			t.Fatalf("P%.2f=(%s,%v,%v) want (%s,%v)", tt.q, got, ok, err, tt.want, tt.ok)
		}
	}
	if _, _, err := h.Quantile(1.1); !errors.Is(err, ErrQuantileRange) {
		t.Fatalf("range err=%v", err)
	}
}

func TestMergedP99IsNotAverageOfP99(t *testing.T) {
	a := mustHist(t, 10*time.Millisecond, 100*time.Millisecond, time.Second)
	b := mustHist(t, 10*time.Millisecond, 100*time.Millisecond, time.Second)
	for i := 0; i < 999; i++ {
		a.Observe(time.Millisecond)
	}
	a.Observe(time.Second)
	b.Observe(time.Millisecond)
	for i := 0; i < 999; i++ {
		b.Observe(time.Second)
	}
	avg, err := AverageQuantile([]Histogram{*a, *b}, 0.99)
	if err != nil {
		t.Fatal(err)
	}
	merged, err := a.Merge(*b)
	if err != nil {
		t.Fatal(err)
	}
	p99, ok, err := merged.Quantile(0.99)
	if err != nil || !ok {
		t.Fatalf("merged quantile ok=%v err=%v", ok, err)
	}
	if avg != 505*time.Millisecond || p99 != time.Second || p99 <= avg {
		t.Fatalf("avg=%s merged=%s", avg, p99)
	}
	t.Logf("instance_a_p99=10ms instance_b_p99=1s average_of_p99=%s merged_p99=%s total=%d",
		avg, p99, merged.Total())
}

func TestMergeRejectsDifferentBuckets(t *testing.T) {
	a := mustHist(t, time.Millisecond, time.Second)
	b := mustHist(t, time.Millisecond, 2*time.Second)
	if _, err := a.Merge(*b); !errors.Is(err, ErrBucketMismatch) {
		t.Fatalf("err=%v", err)
	}
}

=== RUN   TestHistogramQuantile
--- PASS: TestHistogramQuantile (0.00s)
=== RUN   TestMergedP99IsNotAverageOfP99
    histogram_test.go:69: instance_a_p99=10ms instance_b_p99=1s average_of_p99=505ms merged_p99=1s total=2000
--- PASS: TestMergedP99IsNotAverageOfP99 (0.00s)
=== RUN   TestMergeRejectsDifferentBuckets
--- PASS: TestMergeRejectsDifferentBuckets (0.00s)
PASS
ok  	archlab/internal/capacity	0.508s

单实例安全容量 C_safe = C × U
所需实例数 N = ceil(Q / C_safe)
实际部署数 D = N + F
容量余量 H = D × C_safe / Q - 1
故障后利用率 U_fail = Q / (N × C_safe)