《游戏服务端架构·平台化与架构治理》5.1 日志、指标与链路追踪

// file: internal/obscontract/contract.go
// tier: L1
// verify: go test ./internal/obscontract/
package obscontract

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

// Signal is the telemetry leg a record belongs to. Logs, metrics and traces
// answer different questions and must not be collapsed into one stream.
type Signal string

const (
	SignalLog    Signal = "log"
	SignalMetric Signal = "metric"
	SignalTrace  Signal = "trace"
)

// Stage is one step of the player journey. The order is part of the contract:
// a chain that skips or reorders stages is broken even if every span exists.
type Stage string

const (
	StageLogin  Stage = "login"
	StageMatch  Stage = "match"
	StageRoom   Stage = "room"
	StageBattle Stage = "battle"
	StageSettle Stage = "settle"
)

var stageOrder = map[Stage]int{
	StageLogin:  0,
	StageMatch:  1,
	StageRoom:   2,
	StageBattle: 3,
	StageSettle: 4,
}

// Field names are stable identifiers used in errors, dashboards and sampling
// rules. Renaming one is a breaking change for every consumer.
type Field string

const (
	FieldTraceID  Field = "trace_id"
	FieldSpanID   Field = "span_id"
	FieldPlayerID Field = "player_id"
	FieldServerID Field = "server_id"
	FieldRoomID   Field = "room_id"
	FieldMatchID  Field = "match_id"
)

// Record is the minimum a log line, metric sample or span must carry to be
// joinable with the other two. Optional fields become required by stage.
type Record struct {
	Signal   Signal
	Stage    Stage
	TraceID  string
	SpanID   string
	ParentID string
	PlayerID string
	ServerID string
	RoomID   string
	MatchID  string
	At       time.Time
	Duration time.Duration
	Err      bool
}

// ValidationError lists every failed field, so a producer can fix one batch
// instead of rediscovering the contract one error at a time.
type ValidationError struct {
	Missing   []Field
	Malformed []Field
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("obscontract: missing=%v malformed=%v", e.Missing, e.Malformed)
}

var (
	ErrEmptyChain    = errors.New("obscontract: chain has no records")
	ErrMixedTrace    = errors.New("obscontract: chain mixes trace ids")
	ErrDuplicateSpan = errors.New("obscontract: duplicate span id")
	ErrBrokenLink    = errors.New("obscontract: parent span missing")
	ErrOutOfOrder    = errors.New("obscontract: stage order violated")
)

// Required returns the fields a stage cannot omit. Match and room identifiers
// start at the stage where they are allocated, not earlier.
func Required(stage Stage) []Field {
	switch stage {
	case StageLogin:
		return []Field{FieldTraceID, FieldSpanID, FieldPlayerID, FieldServerID}
	case StageMatch:
		return []Field{FieldTraceID, FieldSpanID, FieldPlayerID, FieldServerID, FieldMatchID}
	case StageRoom, StageBattle, StageSettle:
		return []Field{FieldTraceID, FieldSpanID, FieldPlayerID, FieldServerID, FieldMatchID, FieldRoomID}
	default:
		return []Field{FieldTraceID, FieldSpanID, FieldServerID}
	}
}

func fieldValue(r Record, f Field) string {
	switch f {
	case FieldTraceID:
		return r.TraceID
	case FieldSpanID:
		return r.SpanID
	case FieldPlayerID:
		return r.PlayerID
	case FieldServerID:
		return r.ServerID
	case FieldRoomID:
		return r.RoomID
	case FieldMatchID:
		return r.MatchID
	default:
		return ""
	}
}

func isLowerHex(s string, n int) bool {
	if len(s) != n {
		return false
	}
	for i := 0; i < len(s); i++ {
		c := s[i]
		if (c < '0' || c > '9') && (c < 'a' || c > 'f') {
			return false
		}
	}
	return true
}

// Validate checks presence by stage, then the two identifiers whose format
// every tracing backend assumes: 32-hex trace id and 16-hex span id.
func Validate(r Record) error {
	var bad ValidationError
	for _, f := range Required(r.Stage) {
		if fieldValue(r, f) == "" {
			bad.Missing = append(bad.Missing, f)
		}
	}
	if r.TraceID != "" && !isLowerHex(r.TraceID, 32) {
		bad.Malformed = append(bad.Malformed, FieldTraceID)
	}
	if r.SpanID != "" && !isLowerHex(r.SpanID, 16) {
		bad.Malformed = append(bad.Malformed, FieldSpanID)
	}
	if len(bad.Missing)+len(bad.Malformed) > 0 {
		return &bad
	}
	return nil
}

// file: internal/obscontract/chain.go
// tier: L1
// verify: go test ./internal/obscontract/
package obscontract

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

// Segment is one finished span placed on the player journey.
type Segment struct {
	Stage    Stage
	SpanID   string
	Start    time.Time
	Duration time.Duration
}

type Chain struct {
	TraceID  string
	Segments []Segment
	Total    time.Duration
	Slowest  Stage
}

// Assemble joins records belonging to one trace. It sorts by start time and
// rejects a missing parent, a duplicate span or a stage that moves backwards.
func Assemble(records []Record) (Chain, error) {
	if len(records) == 0 {
		return Chain{}, ErrEmptyChain
	}
	traceID := records[0].TraceID
	seen := make(map[string]bool, len(records))
	for _, r := range records {
		if r.TraceID != traceID {
			return Chain{}, ErrMixedTrace
		}
		if r.SpanID == "" {
			continue
		}
		if seen[r.SpanID] {
			return Chain{}, fmt.Errorf("%w: %s", ErrDuplicateSpan, r.SpanID)
		}
		seen[r.SpanID] = true
	}
	for _, r := range records {
		if r.ParentID != "" && !seen[r.ParentID] {
			return Chain{}, fmt.Errorf("%w: span=%s parent=%s", ErrBrokenLink, r.SpanID, r.ParentID)
		}
	}

	ordered := append([]Record(nil), records...)
	sort.SliceStable(ordered, func(i, j int) bool { return ordered[i].At.Before(ordered[j].At) })

	start := ordered[0].At
	maxEnd := start
	chain := Chain{TraceID: traceID}
	lastOrder := -1
	var lastStage Stage
	var slowest time.Duration
	for _, r := range ordered {
		order, ok := stageOrder[r.Stage]
		if !ok {
			return Chain{}, fmt.Errorf("obscontract: unknown stage %q", r.Stage)
		}
		if order < lastOrder {
			return Chain{}, fmt.Errorf("%w: %s after %s", ErrOutOfOrder, r.Stage, lastStage)
		}
		lastOrder, lastStage = order, r.Stage
		seg := Segment{Stage: r.Stage, SpanID: r.SpanID, Start: r.At, Duration: r.Duration}
		chain.Segments = append(chain.Segments, seg)
		if seg.Duration > slowest {
			slowest = seg.Duration
			chain.Slowest = seg.Stage
		}
		if end := r.At.Add(r.Duration); end.After(maxEnd) {
			maxEnd = end
		}
	}
	chain.Total = maxEnd.Sub(start)
	return chain, nil
}