《互联网产品的服务端架构·规模化与架构演进》3.1 热点事件的流量特征

// file: internal/burst/classify.go
// tier: L1
// verify: go test ./internal/burst/

package burst

import (
	"errors"
	"fmt"
	"math"
)

// ErrNotEnoughSamples 表示样本不足以建立基线。
// 少于 3 个样本时，均值和标准差都没有统计意义，宁可报错也不要给调用方一个假阈值。
var ErrNotEnoughSamples = errors.New("burst: at least 3 samples are required")

// Baseline 返回样本均值和总体标准差。
// 这里用总体标准差而不是样本标准差：传入的是同一个统计窗口内的完整观测，
// 不是从更大总体里抽出的样本。
func Baseline(samples []int64) (mean, std float64, err error) {
	if len(samples) < 3 {
		return 0, 0, ErrNotEnoughSamples
	}
	var sum float64
	for _, v := range samples {
		if v < 0 {
			return 0, 0, fmt.Errorf("burst: sample must not be negative: %d", v)
		}
		sum += float64(v)
	}
	mean = sum / float64(len(samples))

	var sq float64
	for _, v := range samples {
		d := float64(v) - mean
		sq += d * d
	}
	std = math.Sqrt(sq / float64(len(samples)))
	return mean, std, nil
}

// ZScore 返回 v 相对基线的标准分。
// std 为 0 时返回 0：常量基线没有离散度，任何偏离都不能被解释成统计显著。
func ZScore(v int64, mean, std float64) float64 {
	if std == 0 || math.IsNaN(std) || math.IsInf(std, 0) {
		return 0
	}
	return (float64(v) - mean) / std
}

// IsBurst 判断 v 是否相对样本构成突发。
// 判定条件是严格大于 z，而不是大于等于：阈值本身是容忍上限，
// 恰好踩线不算突发，否则阈值会被端点样本反复触发。
func IsBurst(samples []int64, v int64, z float64) (bool, error) {
	mean, std, err := Baseline(samples)
	if err != nil {
		return false, err
	}
	return ZScore(v, mean, std) > z, nil
}

// file: internal/burst/classify_test.go
// tier: L1
// verify: go test ./internal/burst/

package burst

import (
	"errors"
	"math"
	"testing"
)

func almostEqual(a, b, tol float64) bool {
	return math.Abs(a-b) <= tol
}

func TestBaselineMeanAndStd(t *testing.T) {
	mean, std, err := Baseline([]int64{10, 20, 30})
	if err != nil {
		t.Fatalf("Baseline returned error: %v", err)
	}
	if !almostEqual(mean, 20, 1e-9) {
		t.Fatalf("mean = %v, want 20", mean)
	}
	want := math.Sqrt(200.0 / 3.0)
	if !almostEqual(std, want, 1e-9) {
		t.Fatalf("std = %v, want %v", std, want)
	}
}

func TestBaselineRejectsShortSamples(t *testing.T) {
	for _, samples := range [][]int64{nil, {1}, {1, 2}} {
		if _, _, err := Baseline(samples); !errors.Is(err, ErrNotEnoughSamples) {
			t.Fatalf("Baseline(%v) error = %v, want ErrNotEnoughSamples", samples, err)
		}
	}
}

func TestBaselineRejectsNegativeSample(t *testing.T) {
	if _, _, err := Baseline([]int64{1, -1, 3}); err == nil {
		t.Fatal("Baseline accepted a negative sample")
	}
}

func TestZScoreZeroStdReturnsZero(t *testing.T) {
	if got := ZScore(999, 100, 0); got != 0 {
		t.Fatalf("ZScore with zero std = %v, want 0", got)
	}
}

func TestZScoreValue(t *testing.T) {
	if got := ZScore(30, 20, 10); !almostEqual(got, 1, 1e-9) {
		t.Fatalf("ZScore = %v, want 1", got)
	}
}

func TestIsBurstRequiresStrictlyGreater(t *testing.T) {
	samples := []int64{0, 10, 20}
	mean, std, err := Baseline(samples)
	if err != nil {
		t.Fatalf("Baseline returned error: %v", err)
	}
	v := int64(30)
	z := ZScore(v, mean, std)

	burst, err := IsBurst(samples, v, z)
	if err != nil {
		t.Fatalf("IsBurst returned error: %v", err)
	}
	if burst {
		t.Fatalf("value exactly at threshold %v was reported as a burst", z)
	}

	burst, err = IsBurst(samples, v, math.Nextafter(z, 0))
	if err != nil {
		t.Fatalf("IsBurst returned error: %v", err)
	}
	if !burst {
		t.Fatal("value just above the threshold was not reported as a burst")
	}
}

func TestIsBurstDetectsSpike(t *testing.T) {
	samples := []int64{10, 12, 14, 10, 14}
	burst, err := IsBurst(samples, 30, 3)
	if err != nil {
		t.Fatalf("IsBurst returned error: %v", err)
	}
	if !burst {
		t.Fatal("30 QPS against a ~12 QPS baseline was not reported as a burst")
	}
}

func TestIsBurstPropagatesSampleError(t *testing.T) {
	if _, err := IsBurst([]int64{1, 2}, 100, 3); !errors.Is(err, ErrNotEnoughSamples) {
		t.Fatalf("error = %v, want ErrNotEnoughSamples", err)
	}
}

cd .local/checks/webapp-lab && go test ./internal/burst/ -count=1 -run 'TestBaseline|TestZScore|TestIsBurst' -v

=== RUN   TestBaselineMeanAndStd
--- PASS: TestBaselineMeanAndStd (0.00s)
=== RUN   TestBaselineRejectsShortSamples
--- PASS: TestBaselineRejectsShortSamples (0.00s)
=== RUN   TestBaselineRejectsNegativeSample
--- PASS: TestBaselineRejectsNegativeSample (0.00s)
=== RUN   TestZScoreZeroStdReturnsZero
--- PASS: TestZScoreZeroStdReturnsZero (0.00s)
=== RUN   TestZScoreValue
--- PASS: TestZScoreValue (0.00s)
=== RUN   TestIsBurstRequiresStrictlyGreater
--- PASS: TestIsBurstRequiresStrictlyGreater (0.00s)
=== RUN   TestIsBurstDetectsSpike
--- PASS: TestIsBurstDetectsSpike (0.00s)
=== RUN   TestIsBurstPropagatesSampleError
--- PASS: TestIsBurstPropagatesSampleError (0.00s)
PASS
ok  	webapp/internal/burst	0.227s