《游戏服务端架构·平台化与架构治理》6.1 游戏服务端怎么定义 SLO

// file: internal/slodefinition/slo.go
// tier: L1
// verify: go test ./internal/slodefinition/

package slodefinition

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

var (
	ErrInvalidSpec       = errors.New("slodefinition: invalid spec")
	ErrInvalidTarget     = errors.New("slodefinition: target must be in (0,1]")
	ErrInvalidWindow     = errors.New("slodefinition: window end must be after start")
	ErrInvalidOutcome    = errors.New("slodefinition: unknown outcome")
	ErrInvalidPercentile = errors.New("slodefinition: percentile must be in (0,1]")
)

// SLI names the user-visible action being promised. Each one has a different
// denominator; mixing them produces a number that cannot drive a decision.
type SLI string

const (
	LoginSuccess      SLI = "login_success"
	EnterRoomSuccess  SLI = "enter_room_success"
	MatchCompletion   SLI = "match_completion"
	SettlementSuccess SLI = "settlement_success"
	ShopOrderSuccess  SLI = "shop_order_success"
)

type Outcome string

const (
	Good Outcome = "good"
	Bad  Outcome = "bad"
)

// Exclusion marks events that are removed from both numerator and denominator.
// The exclusion must be a property of the event, not a post-hoc judgement made
// after the SLO has already missed.
type Exclusion string

const (
	NoExclusion    Exclusion = ""
	Maintenance    Exclusion = "maintenance"
	PlayerQuit     Exclusion = "player_quit"
	DuplicateRetry Exclusion = "duplicate_retry"
)

type Event struct {
	SLI       SLI
	Outcome   Outcome
	Exclusion Exclusion
	At        time.Time
	Region    string
	Channel   string
}

type Spec struct {
	SLI    SLI
	Target float64
	Start  time.Time
	End    time.Time
}

type Report struct {
	SLI        SLI
	Target     float64
	Good       int
	Bad        int
	Excluded   int
	Eligible   int
	Attainment float64
	Met        bool
	BadAllowed int
	BadLeft    int
	NoData     bool
}

func validateSpec(spec Spec) error {
	if spec.Target <= 0 || spec.Target > 1 {
		return ErrInvalidTarget
	}
	if !spec.End.After(spec.Start) {
		return ErrInvalidWindow
	}
	return nil
}

func allowedBad(target float64, eligible int) int {
	if eligible == 0 {
		return 0
	}
	// The epsilon absorbs binary floating point error such as 1-0.9 = 0.0999...
	return int(math.Floor((1-target)*float64(eligible) + 1e-9))
}

// Evaluate computes one SLI over the half-open window [Start, End).
// Events of other SLIs and events outside the window are ignored. An excluded
// event never enters the denominator, even when its outcome is bad.
func Evaluate(events []Event, spec Spec) (Report, error) {
	if err := validateSpec(spec); err != nil {
		return Report{}, err
	}
	r := Report{SLI: spec.SLI, Target: spec.Target, NoData: true}
	for _, e := range events {
		if e.SLI != spec.SLI {
			continue
		}
		if e.At.Before(spec.Start) || !e.At.Before(spec.End) {
			continue
		}
		if e.Exclusion != NoExclusion {
			r.Excluded++
			continue
		}
		switch e.Outcome {
		case Good:
			r.Good++
		case Bad:
			r.Bad++
		default:
			return Report{}, fmt.Errorf("%w: %q", ErrInvalidOutcome, e.Outcome)
		}
	}
	r.Eligible = r.Good + r.Bad
	if r.Eligible == 0 {
		return r, nil
	}
	r.NoData = false
	r.Attainment = float64(r.Good) / float64(r.Eligible)
	r.Met = r.Attainment >= spec.Target
	r.BadAllowed = allowedBad(spec.Target, r.Eligible)
	r.BadLeft = r.BadAllowed - r.Bad
	return r, nil
}

type Dimension string

const (
	ByRegion  Dimension = "region"
	ByChannel Dimension = "channel"
)

// Breakdown evaluates the same spec per region or per channel. A merged
// global number can hide one region that misses the target every day.
func Breakdown(events []Event, spec Spec, dim Dimension) (map[string]Report, error) {
	if err := validateSpec(spec); err != nil {
		return nil, err
	}
	if dim != ByRegion && dim != ByChannel {
		return nil, fmt.Errorf("%w: unknown dimension %q", ErrInvalidSpec, dim)
	}
	groups := make(map[string][]Event)
	for _, e := range events {
		key := e.Region
		if dim == ByChannel {
			key = e.Channel
		}
		if key == "" {
			key = "unknown"
		}
		groups[key] = append(groups[key], e)
	}
	out := make(map[string]Report, len(groups))
	for key, group := range groups {
		r, err := Evaluate(group, spec)
		if err != nil {
			return nil, err
		}
		out[key] = r
	}
	return out, nil
}