《游戏服务端架构·平台化与架构治理》5.2 游戏专属指标：帧、房间、匹配、经济

// file: internal/gamemetrics/metrics.go
// tier: L1
// verify: go test ./internal/gamemetrics/
package gamemetrics

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

var (
	ErrEmpty   = errors.New("gamemetrics: empty sample")
	ErrInvalid = errors.New("gamemetrics: invalid sample")
)

// Quantile uses linear interpolation between the two closest ranks, the same
// definition as numpy's default. q must be in (0,1] and samples must be >= 0.
func Quantile(samples []float64, q float64) (float64, error) {
	if len(samples) == 0 {
		return 0, ErrEmpty
	}
	if q <= 0 || q > 1 {
		return 0, fmt.Errorf("gamemetrics: quantile %g outside (0,1]", q)
	}
	xs := append([]float64(nil), samples...)
	sort.Float64s(xs)
	for _, x := range xs {
		if x < 0 || math.IsNaN(x) {
			return 0, ErrInvalid
		}
	}
	pos := q * float64(len(xs)-1)
	lo := int(math.Floor(pos))
	hi := int(math.Ceil(pos))
	if lo == hi {
		return xs[lo], nil
	}
	frac := pos - float64(lo)
	return xs[lo]*(1-frac) + xs[hi]*frac, nil
}

func durationQuantile(samples []time.Duration, q float64) (time.Duration, error) {
	xs := make([]float64, len(samples))
	for i, d := range samples {
		xs[i] = float64(d)
	}
	v, err := Quantile(xs, q)
	if err != nil {
		return 0, err
	}
	return time.Duration(v), nil
}

// TickReport summarises server tick health against a frame budget. P99 is the
// tail players actually feel; LateRatio is how often the budget was missed.
type TickReport struct {
	Budget  time.Duration
	Samples int
	Late    int
	P99     time.Duration
	Max     time.Duration
}

func AnalyzeTicks(samples []time.Duration, budget time.Duration) (TickReport, error) {
	if len(samples) == 0 {
		return TickReport{}, ErrEmpty
	}
	if budget <= 0 {
		return TickReport{}, fmt.Errorf("gamemetrics: budget must be positive")
	}
	rep := TickReport{Budget: budget, Samples: len(samples)}
	for _, d := range samples {
		if d < 0 {
			return TickReport{}, ErrInvalid
		}
		if d > budget {
			rep.Late++
		}
		if d > rep.Max {
			rep.Max = d
		}
	}
	p99, err := durationQuantile(samples, 0.99)
	if err != nil {
		return TickReport{}, err
	}
	rep.P99 = p99
	return rep, nil
}

func (r TickReport) LateRatio() float64 {
	if r.Samples == 0 {
		return 0
	}
	return float64(r.Late) / float64(r.Samples)
}

// file: internal/gamemetrics/economy.go
// tier: L1
// verify: go test ./internal/gamemetrics/
package gamemetrics

import (
	"fmt"
	"sort"
	"time"
)

// MatchSummary keeps attempts as the denominator, not the number of recorded
// matches: cancelled and timed-out requests never produce a match record.
type MatchSummary struct {
	Attempts  int
	Failures  map[string]int
	Durations []time.Duration
}

func (m MatchSummary) SuccessRate() (float64, error) {
	if m.Attempts <= 0 {
		return 0, fmt.Errorf("gamemetrics: attempts must be positive")
	}
	failed := 0
	for _, n := range m.Failures {
		if n < 0 {
			return 0, ErrInvalid
		}
		failed += n
	}
	if failed > m.Attempts {
		return 0, fmt.Errorf("gamemetrics: failures %d exceed attempts %d", failed, m.Attempts)
	}
	return float64(m.Attempts-failed) / float64(m.Attempts), nil
}

// FailureShare divides by failures, not attempts: it answers "of the players
// who failed, why did they fail", which is the routing decision for a fix.
func (m MatchSummary) FailureShare() (map[string]float64, error) {
	failed := 0
	for _, n := range m.Failures {
		if n < 0 {
			return nil, ErrInvalid
		}
		failed += n
	}
	if failed == 0 {
		return map[string]float64{}, nil
	}
	out := make(map[string]float64, len(m.Failures))
	for reason, n := range m.Failures {
		out[reason] = float64(n) / float64(failed)
	}
	return out, nil
}

func (m MatchSummary) P(q float64) (time.Duration, error) {
	return durationQuantile(m.Durations, q)
}

type Flow struct {
	Produced int64 // faucet: drops, quest rewards, compensation
	Consumed int64 // sink: upgrades, repairs, fees
}

// Inflation is net issuance over consumption. A zero denominator is undefined,
// not infinite: a server with production but no sink has no equilibrium yet.
func (f Flow) Inflation() (float64, error) {
	if f.Produced < 0 || f.Consumed < 0 {
		return 0, ErrInvalid
	}
	if f.Consumed == 0 {
		return 0, fmt.Errorf("gamemetrics: consumed must be positive")
	}
	return float64(f.Produced-f.Consumed) / float64(f.Consumed), nil
}

// SinkCoverage is the share of production removed by sinks. Above 1 means the
// economy is draining, which is a problem in the other direction.
func (f Flow) SinkCoverage() (float64, error) {
	if f.Produced <= 0 {
		return 0, fmt.Errorf("gamemetrics: produced must be positive")
	}
	if f.Consumed < 0 {
		return 0, ErrInvalid
	}
	return float64(f.Consumed) / float64(f.Produced), nil
}

// Gini measures asset inequality in [0,1]. An all-zero economy is defined as
// 0 rather than undefined, because a fresh server is not an incident.
func Gini(assets []int64) (float64, error) {
	if len(assets) == 0 {
		return 0, ErrEmpty
	}
	var sum int64
	for _, a := range assets {
		if a < 0 {
			return 0, ErrInvalid
		}
		sum += a
	}
	if sum == 0 {
		return 0, nil
	}
	xs := append([]int64(nil), assets...)
	sort.Slice(xs, func(i, j int) bool { return xs[i] < xs[j] })
	var weighted float64
	for i, a := range xs {
		weighted += float64(i+1) * float64(a)
	}
	n := float64(len(xs))
	g := 2*weighted/(n*float64(sum)) - (n+1)/n
	if g < 0 {
		return 0, nil
	}
	return g, nil
}