《MMO 服务器开发》3.1 日志该记什么

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

import (
	"context"
	"log/slog"
	"math/rand/v2"
	"regexp"
)

// Field names are frozen: 日志查询、告警规则、看板全部按这几个 key 过滤，
// 一旦改名就等于全站查询失效。
const (
	FieldTraceID  = "trace_id"
	FieldPlayerID = "player_id"
	FieldCmd      = "cmd"
	FieldSeq      = "seq"
	FieldCostMS   = "cost_ms"
	FieldResult   = "result"
)

// 结果取值。只有这三种，不允许自由发挥，否则采样与告警没法按 result 聚合。
const (
	ResultOK      = "ok"
	ResultErr     = "err"
	ResultTimeout = "timeout"
)

// Event 是「一条请求日志」的最小字段集。字段少不是偷懒：
// 多一个字段就多一份 cardinality、多一份脱敏责任，先定死这六个。
type Event struct {
	TraceID  string
	PlayerID uint64
	Cmd      uint16
	Seq      uint32
	CostMS   float64
	Result   string
}

// Sampler 决定一条日志是否落盘：错误全留，成功按比例采。
// 用确定性 PRNG，同一个 seed 序列可复现，便于测试与回放。
type Sampler struct {
	OKRatio float64
	rng     *rand.Rand
}

// NewSampler 构造采样器。okRatio=0 表示成功全丢，=1 表示成功全留。
func NewSampler(okRatio float64, seed1, seed2 uint64) *Sampler {
	return &Sampler{OKRatio: okRatio, rng: rand.New(rand.NewPCG(seed1, seed2))}
}

// Keep 报告一条事件是否应当写出。
func (s *Sampler) Keep(e Event) bool {
	if e.Result != ResultOK {
		return true // 错误与超时永远不采，宁可多写也不漏
	}
	if s.OKRatio >= 1 {
		return true
	}
	if s.OKRatio <= 0 {
		return false
	}
	return s.rng.Float64() < s.OKRatio
}

// 隐私脱敏：手机号与邮箱是玩家日志里最常见的两种 PII。
// 规则在写盘之前执行，绝不把原始值交给 Handler。
var (
	rePhone = regexp.MustCompile(`1[3-9]\d{9}`)
	reEmail = regexp.MustCompile(`[\w.+-]+@[\w-]+\.[\w.-]+`)
)

// Redact 抹掉自由文本里的手机号与邮箱。注意 player_id 是内部数值 ID，
// 用于链路关联，本身不是隐私；真正要防的是账号 uid、手机号、邮箱、聊天原文。
func Redact(msg string) string {
	msg = rePhone.ReplaceAllString(msg, "1**********")
	msg = reEmail.ReplaceAllString(msg, "***@***")
	return msg
}

// level 把业务 result 映射到日志级别：成功 Info，超时 Warn，其余 Error。
func level(result string) slog.Level {
	switch result {
	case ResultOK:
		return slog.LevelInfo
	case ResultTimeout:
		return slog.LevelWarn
	default:
		return slog.LevelError
	}
}

// RequestLogger 是「一条请求一行日志」的唯一出口：先采样、再脱敏、最后写。
type RequestLogger struct {
	log *slog.Logger
	smp *Sampler
}

// NewRequestLogger 组装请求日志器。
func NewRequestLogger(log *slog.Logger, smp *Sampler) *RequestLogger {
	return &RequestLogger{log: log, smp: smp}
}

// Log 写出一条事件，返回是否真的写了（被采样丢弃时返回 false）。
func (rl *RequestLogger) Log(ctx context.Context, e Event, msg string) bool {
	if rl.smp != nil && !rl.smp.Keep(e) {
		return false
	}
	rl.log.LogAttrs(ctx, level(e.Result), Redact(msg),
		slog.String(FieldTraceID, e.TraceID),
		slog.Uint64(FieldPlayerID, e.PlayerID),
		slog.Int(FieldCmd, int(e.Cmd)),
		slog.Int(FieldSeq, int(e.Seq)),
		slog.Float64(FieldCostMS, e.CostMS),
		slog.String(FieldResult, e.Result),
	)
	return true
}

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

import (
	"bytes"
	"context"
	"encoding/json"
	"log/slog"
	"strings"
	"testing"
)

// 断言：一条请求日志必须同时带齐六个字段，且值正确。
func TestRequestLoggerEmitsAllFields(t *testing.T) {
	var buf bytes.Buffer
	lg := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug}))
	rl := NewRequestLogger(lg, NewSampler(1.0, 1, 2))

	e := Event{TraceID: "tr-abc123", PlayerID: 10086, Cmd: 0x0401, Seq: 7, CostMS: 3.5, Result: ResultOK}
	if !rl.Log(context.Background(), e, "battle hit") {
		t.Fatal("success event should be kept when ratio=1")
	}

	var got map[string]any
	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
		t.Fatalf("log is not valid JSON: %v (%q)", err, buf.String())
	}
	for _, k := range []string{FieldTraceID, FieldPlayerID, FieldCmd, FieldSeq, FieldCostMS, FieldResult} {
		if _, ok := got[k]; !ok {
			t.Fatalf("missing field %q in %v", k, got)
		}
	}
	if got[FieldTraceID] != "tr-abc123" {
		t.Fatalf("trace_id = %v", got[FieldTraceID])
	}
	if got[FieldResult] != ResultOK {
		t.Fatalf("result = %v", got[FieldResult])
	}
	if got["level"] != "INFO" {
		t.Fatalf("ok should log at INFO, got %v", got["level"])
	}
}

// 断言：错误事件级别为 ERROR，且永不采样丢弃。
func TestErrorAlwaysLoggedAtError(t *testing.T) {
	var buf bytes.Buffer
	lg := slog.New(slog.NewJSONHandler(&buf, nil))
	rl := NewRequestLogger(lg, NewSampler(0.0, 1, 2)) // 成功全丢

	if rl.Log(context.Background(), Event{Result: ResultOK, Cmd: 0x0401}, "ok line") {
		t.Fatal("ok event must be sampled out when ratio=0")
	}
	if !rl.Log(context.Background(), Event{Result: ResultErr, Cmd: 0x0401}, "boom") {
		t.Fatal("error event must always be kept")
	}

	var got map[string]any
	_ = json.Unmarshal(buf.Bytes(), &got)
	if got["level"] != "ERROR" {
		t.Fatalf("err should log at ERROR, got %v", got["level"])
	}
}

// 断言：脱敏函数抹掉手机号与邮箱，player_id 数值保留。
func TestRedactStripsPII(t *testing.T) {
	in := "player 13812345678 mail foo.bar@game.com login"
	out := Redact(in)
	if strings.Contains(out, "13812345678") {
		t.Fatalf("phone leaked: %q", out)
	}
	if strings.Contains(out, "foo.bar@game.com") {
		t.Fatalf("email leaked: %q", out)
	}
	if !strings.Contains(out, "1**********") || !strings.Contains(out, "***@***") {
		t.Fatalf("mask not applied: %q", out)
	}
}

// 断言：采样是确定性的——同一 seed 得到同一结果序列。
func TestSamplerDeterministic(t *testing.T) {
	a := NewSampler(0.5, 42, 99)
	b := NewSampler(0.5, 42, 99)
	for i := 0; i < 200; i++ {
		e := Event{Result: ResultOK}
		if a.Keep(e) != b.Keep(e) {
			t.Fatalf("sampler not deterministic at step %d", i)
		}
	}
}