《MMO 服务器开发》3.3 链路追踪与告警

client ──frame──▶ gateway-03 ──frame──▶ scene-01 ──frame──▶ battle-02
  (起根 span)        │ 转发, 附 ctx        │ 转发, 附 ctx        │ 计算, 记 result
                     ▼                     ▼                     ▼
  trace_id = T  ┌──────────┐  ┌──────────┐  ┌──────────┐
  共享同一条 T  │ span A   │  │ span B   │  │ span C   │
                │ parent=∅ │  │ parent=A │  │ parent=B │
                └──────────┘  └──────────┘  └──────────┘

// file: internal/telemetry/trace.go
// tier: L1
// verify: go test ./internal/telemetry/
package telemetry

import (
	"crypto/rand"
	"encoding/hex"
)

// TraceContext 是要在服务之间传播的最小上下文：trace_id 标识整条链路，
// span_id 标识「当前这一段」。跨进程时这两样必须跟着帧一起走。
type TraceContext struct {
	TraceID string
	SpanID  string
}

// Span 是链路里的一段。ParentID 为空表示它是整条链路的根。
type Span struct {
	TraceID  string
	SpanID   string
	ParentID string
	Service  string
	Cmd      uint16
	CostMS   float64
	Err      bool
}

// Tracer 负责生成 span。每个服务一个实例，Service 就是节点名（如 gateway-03）。
type Tracer struct {
	Service string
}

func newID() string {
	var b [8]byte
	_, _ = rand.Read(b[:])
	return hex.EncodeToString(b[:]) // 16 个十六进制字符
}

// StartTrace 起一条全新链路，返回它的根上下文与根 span。
func (t *Tracer) StartTrace() (*TraceContext, Span) {
	tc := TraceContext{TraceID: newID(), SpanID: newID()}
	return &tc, Span{TraceID: tc.TraceID, SpanID: tc.SpanID, Service: t.Service}
}

// StartSpan 在父上下文下开一段子 span。返回的新上下文里 span_id 已经换成子段，
// 网关把它转发给下游时，下游看到的自然就是「子」，父子关系由此自动拼出来。
func (t *Tracer) StartSpan(parent TraceContext) (*TraceContext, Span) {
	tc := TraceContext{TraceID: parent.TraceID, SpanID: newID()}
	return &tc, Span{TraceID: tc.TraceID, SpanID: tc.SpanID, ParentID: parent.SpanID, Service: t.Service}
}

// Trace 收集同一条链路的所有 span，负责把散落的段拼成树。
type Trace struct {
	TraceID string
	Spans   []Span
}

// Add 收一段 span。
func (tr *Trace) Add(s Span) { tr.Spans = append(tr.Spans, s) }

// Roots 返回所有根 span（ParentID 为空）。
func (tr *Trace) Roots() []Span {
	var out []Span
	for _, s := range tr.Spans {
		if s.ParentID == "" {
			out = append(out, s)
		}
	}
	return out
}

// Children 返回某个 span 的直接子段。
func (tr *Trace) Children(spanID string) []Span {
	var out []Span
	for _, s := range tr.Spans {
		if s.ParentID == spanID {
			out = append(out, s)
		}
	}
	return out
}

// Depth 返回某段相对根的层级：根为 0，逐级 +1。找不到返回 -1。
func (tr *Trace) Depth(spanID string) int {
	byID := map[string]Span{}
	for _, s := range tr.Spans {
		byID[s.SpanID] = s
	}
	d, cur, guard := 0, spanID, 0
	for {
		s, ok := byID[cur]
		if !ok {
			return -1
		}
		if s.ParentID == "" {
			return d
		}
		cur = s.ParentID
		d++
		if guard++; guard > len(tr.Spans)+1 {
			return -1 // 防环
		}
	}
}

// metaSize 是注入到 aegis 帧 payload 头部的固定长度：
// traceID(16 字符) + spanID(16 字符) = 32 字节。固定头 11 字节不动。
const metaSize = 32

// InjectMeta 把 trace 上下文塞进 payload 头部，返回新 payload。
func InjectMeta(payload []byte, tc TraceContext) []byte {
	out := make([]byte, 0, metaSize+len(payload))
	out = append(out, []byte(tc.TraceID)...)
	out = append(out, []byte(tc.SpanID)...)
	return append(out, payload...)
}

// ExtractMeta 从 payload 头部取出 trace 上下文，返回剩余的业务载荷。
// ok=false 表示这段载荷没有携带 trace 信息（老客户端 / 心跳）。
func ExtractMeta(frame []byte) (tc TraceContext, rest []byte, ok bool) {
	if len(frame) < metaSize {
		return TraceContext{}, frame, false
	}
	return TraceContext{TraceID: string(frame[:16]), SpanID: string(frame[16:32])}, frame[metaSize:], true
}

// snippet: 节选自 internal/telemetry/trace_test.go（完整文件已随 go test 跑通）
gw := &Tracer{Service: "gateway-03"}
tc, root := gw.StartTrace()          // 根 span
scene := &Tracer{Service: "scene-01"}
sc, sceneSpan := scene.StartSpan(*tc) // 子 span
battle := &Tracer{Service: "battle-02"}
_, battleSpan := battle.StartSpan(*sc) // 孙 span

// 三段共享同一 trace_id；有且仅有一个根
// Children(root) == scene，Children(scene) == battle
// Depth: root=0, scene=1, battle=2

// file: internal/telemetry/alert.go
// tier: L1
// verify: go test ./internal/telemetry/
package telemetry

import "math"

// Kind 是告警判据的类型。
type Kind int

const (
	// Threshold：绝对值越过上限。适合「内存使用 > 90%」这类有明确红线的量。
	Threshold Kind = iota
	// RateChange：相对上一次的变化率越过上限。适合「错误率 5 分钟翻了 3 倍」
	// 这类没有绝对红线、但突变一定要报的量。
	RateChange
)

// Rule 是一条告警规则。
type Rule struct {
	Name     string
	Kind     Kind
	Limit    float64 // Threshold 是上限；RateChange 是变化率上限（0.5 表示 50%）
	For      int     // 连续满足多少次才触发，用来抑制抖动
	Severity int     // 越大越严重，供抑制关系使用
}

// Evaluator 维护每条规则的「连续满足计数」，实现「持续 N 次才触发」的抖动抑制。
type Evaluator struct {
	streak map[string]int
}

// NewEvaluator 构造一个判定器。
func NewEvaluator() *Evaluator { return &Evaluator{streak: map[string]int{}} }

// Eval 用当前样本（以及变化率需要的上一值）判断规则是否触发。
// prev 只在 RateChange 时用；Threshold 忽略它。
func (e *Evaluator) Eval(r Rule, prev, cur float64) bool {
	hit := false
	switch r.Kind {
	case Threshold:
		hit = cur > r.Limit
	case RateChange:
		if prev != 0 {
			hit = math.Abs(cur-prev)/math.Abs(prev) > r.Limit
		}
	}
	if hit {
		e.streak[r.Name]++
	} else {
		e.streak[r.Name] = 0
	}
	forN := r.For
	if forN < 1 {
		forN = 1
	}
	return e.streak[r.Name] >= forN
}

// Inhibit 应用抑制关系：当某条更严重的告警正在触发时，被它抑制的告警不发出。
// higher 的 key 是抑制者，value 是被它抑制的告警名列表。
func Inhibit(firing map[string]bool, higher map[string][]string) map[string]bool {
	out := map[string]bool{}
	for name, on := range firing {
		if on {
			out[name] = true
		}
	}
	for inhibitor, victims := range higher {
		if !out[inhibitor] {
			continue
		}
		for _, v := range victims {
			delete(out, v)
		}
	}
	return out
}