《MMO 服务器开发》3.2 指标与 Prometheus 打点

// file: internal/telemetry/metrics.go
// tier: L2
// verify: go test ./internal/telemetry/
package telemetry

import (
	"net/http"

	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

// CmdName 把命令号映射成稳定、低基数的标签值。
// 绝不把 cmd 的原始数值直接当标签（数值散乱），也绝不把 player_id 当标签（基数爆炸）。
func CmdName(cmd uint16) string {
	switch cmd {
	case 0x0010:
		return "login"
	case 0x0101:
		return "world_enter"
	case 0x0401:
		return "battle_cast"
	case 0x0B01:
		return "trade_create"
	default:
		return "other"
	}
}

// Metrics 聚合三类指标：Counter（只增）、Gauge（可增可减）、Histogram（分桶分布）。
type Metrics struct {
	reg *prometheus.Registry

	// Counter：累计请求数。语义是「只增不减」，重启才归零。
	RequestsTotal *prometheus.CounterVec
	// Gauge：当前在线人数。语义是「瞬时值」，可上可下。
	OnlinePlayers prometheus.Gauge
	// Histogram：命令耗时分布。分桶给出 p50/p95/p99 的近似。
	FrameCost *prometheus.HistogramVec
}

// NewMetrics 在给定 registry 上注册三类指标。传 nil 则新建一个私有 registry，
// 避免污染全局默认 registry（测试里尤其重要）。
func NewMetrics(reg *prometheus.Registry) *Metrics {
	if reg == nil {
		reg = prometheus.NewRegistry()
	}
	m := &Metrics{reg: reg}
	m.RequestsTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "aegis",
		Name:      "requests_total",
		Help:      "Total handled commands, by cmd and result.",
	}, []string{"cmd", "result"})
	m.OnlinePlayers = prometheus.NewGauge(prometheus.GaugeOpts{
		Namespace: "aegis",
		Name:      "online_players",
		Help:      "Current online player count.",
	})
	m.FrameCost = prometheus.NewHistogramVec(prometheus.HistogramOpts{
		Namespace: "aegis",
		Name:      "frame_cost_seconds",
		Help:      "Command handling cost in seconds.",
		Buckets:   []float64{0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1},
	}, []string{"cmd"})
	reg.MustRegister(m.RequestsTotal, m.OnlinePlayers, m.FrameCost)
	return m
}

// Observe 是「一次命令处理完」的统一打点入口：计数 + 计时一起做。
func (m *Metrics) Observe(cmd uint16, costSeconds float64, result string) {
	name := CmdName(cmd)
	m.RequestsTotal.WithLabelValues(name, result).Inc()
	m.FrameCost.WithLabelValues(name).Observe(costSeconds)
}

// Handler 返回暴露 /metrics 的 HTTP handler，供 Prometheus 真拉取。
func (m *Metrics) Handler() http.Handler {
	return promhttp.HandlerFor(m.reg, promhttp.HandlerOpts{})
}

// file: internal/telemetry/metrics_test.go
// tier: L2
// verify: go test ./internal/telemetry/
package telemetry

import (
	"bytes"
	"io"
	"net/http"
	"net/http/httptest"
	"testing"

	dto "github.com/prometheus/client_model/go"
	"github.com/prometheus/common/expfmt"
	"github.com/prometheus/common/model"
)

func labelValue(m *dto.Metric, name string) string {
	for _, lp := range m.GetLabel() {
		if lp.GetName() == name {
			return lp.GetValue()
		}
	}
	return ""
}

// L2：真起 HTTP server 暴露 /metrics，再用 HTTP 真拉取并解析，断言关键指标存在。
func TestMetricsExposedOverHTTP(t *testing.T) {
	m := NewMetrics(nil)
	m.Observe(0x0401, 0.003, ResultOK)
	m.Observe(0x0401, 0.020, ResultOK)
	m.Observe(0x0010, 0.001, ResultErr)
	m.OnlinePlayers.Set(1234)

	srv := httptest.NewServer(m.Handler())
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/metrics")
	if err != nil {
		t.Fatalf("GET /metrics: %v", err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		t.Fatalf("status = %d", resp.StatusCode)
	}

	body, _ := io.ReadAll(resp.Body)
	parser := expfmt.NewTextParser(model.UTF8Validation)
	families, err := parser.TextToMetricFamilies(bytes.NewReader(body))
	if err != nil {
		t.Fatalf("parse exposition: %v", err)
	}

	// Counter：battle_cast / ok 至少出现过 2 次。
	rt := families["aegis_requests_total"]
	if rt == nil {
		t.Fatal("aegis_requests_total not exposed")
	}
	var battleOK float64 = -1
	for _, met := range rt.GetMetric() {
		if labelValue(met, "cmd") == "battle_cast" && labelValue(met, "result") == ResultOK {
			battleOK = met.GetCounter().GetValue()
		}
	}
	if battleOK != 2 {
		t.Fatalf("battle_cast/ok counter = %v, want 2", battleOK)
	}

	// Gauge：在线人数就是刚 Set 的值。
	op := families["aegis_online_players"]
	if op == nil || len(op.GetMetric()) == 0 {
		t.Fatal("aegis_online_players not exposed")
	}
	if v := op.GetMetric()[0].GetGauge().GetValue(); v != 1234 {
		t.Fatalf("online_players = %v, want 1234", v)
	}

	// Histogram：必须带 _bucket / _sum / _count，且 count=2。
	fc := families["aegis_frame_cost_seconds"]
	if fc == nil {
		t.Fatal("aegis_frame_cost_seconds not exposed")
	}
	if fc.GetType() != dto.MetricType_HISTOGRAM {
		t.Fatalf("frame_cost type = %v", fc.GetType())
	}
	for _, met := range fc.GetMetric() {
		if labelValue(met, "cmd") == "battle_cast" {
			if c := met.GetHistogram().GetSampleCount(); c != 2 {
				t.Fatalf("histogram sample count = %d, want 2", c)
			}
		}
	}
}

// 基数陷阱：请求指标只允许 cmd/result 两个标签，绝不能带 player_id。
func TestRequestCounterLabelCardinality(t *testing.T) {
	m := NewMetrics(nil)
	m.Observe(0x0401, 0.001, ResultOK)

	srv := httptest.NewServer(m.Handler())
	defer srv.Close()
	resp, err := http.Get(srv.URL + "/metrics")
	if err != nil {
		t.Fatalf("GET /metrics: %v", err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	parser := expfmt.NewTextParser(model.UTF8Validation)
	families, _ := parser.TextToMetricFamilies(bytes.NewReader(body))

	rt := families["aegis_requests_total"]
	if rt == nil || len(rt.GetMetric()) == 0 {
		t.Fatal("no metric")
	}
	seen := map[string]bool{}
	for _, lp := range rt.GetMetric()[0].GetLabel() {
		seen[lp.GetName()] = true
	}
	if seen["player_id"] {
		t.Fatal("player_id must never be a metric label")
	}
	if !seen["cmd"] || !seen["result"] {
		t.Fatalf("expected cmd/result labels, got %v", seen)
	}
}