《游戏服务端编程实践》15.3 ELK / Loki / Prometheus 集成

// file: ch15/exporter/exporter.go
// tier: L1
// verify: go test ./ch15/exporter/

// Package exporter 用标准库输出 Prometheus 文本格式。
// 它只负责校验、转义和格式化，抓取与服务发现属于采集链路的其他环节。
package exporter

import (
	"errors"
	"fmt"
	"io"
	"math"
	"sync"
)

var (
	ErrDuplicateLabel  = errors.New("exporter: duplicate label name")
	ErrDuplicateMetric = errors.New("exporter: duplicate metric name")
	ErrInvalidName     = errors.New("exporter: invalid metric name")
	ErrInvalidLabel    = errors.New("exporter: invalid label name")
	ErrLabelCount      = errors.New("exporter: label value count mismatch")
	ErrNonFinite       = errors.New("exporter: non-finite sample value")
	ErrBucketOrder     = errors.New("exporter: histogram buckets must strictly increase")
	ErrNegativeCounter = errors.New("exporter: counter cannot decrease")
)

type metricType string

const (
	typeGauge     metricType = "gauge"
	typeCounter   metricType = "counter"
	typeHistogram metricType = "histogram"
)

// Registry 保存一组指标族，并按注册顺序输出。
type Registry struct {
	mu       sync.Mutex
	order    []string
	families map[string]*family
}

func NewRegistry() *Registry { return &Registry{families: map[string]*family{}} }

type family struct {
	name    string
	help    string
	typ     metricType
	labels  []string
	buckets []float64

	mu      sync.Mutex
	order   []string
	samples map[string]*sample
}

type sample struct {
	values []string
	value  float64
	counts []uint64
	sum    float64
	count  uint64
}

func (r *Registry) newFamily(name, help string, typ metricType, labels []string, buckets []float64) (*family, error) {
	if err := validateName(name, true); err != nil {
		return nil, err
	}
	seen := make(map[string]bool, len(labels))
	for _, label := range labels {
		if err := validateName(label, false); err != nil {
			return nil, err
		}
		if seen[label] {
			return nil, fmt.Errorf("%w: %s", ErrDuplicateLabel, label)
		}
		seen[label] = true
	}
	if typ == typeHistogram {
		if len(buckets) == 0 {
			return nil, fmt.Errorf("%w: no buckets", ErrBucketOrder)
		}
		for i := 1; i < len(buckets); i++ {
			if buckets[i] <= buckets[i-1] {
				return nil, fmt.Errorf("%w: %g after %g", ErrBucketOrder, buckets[i], buckets[i-1])
			}
		}
	}
	r.mu.Lock()
	defer r.mu.Unlock()
	if _, ok := r.families[name]; ok {
		return nil, fmt.Errorf("%w: %s", ErrDuplicateMetric, name)
	}
	f := &family{
		name: name, help: help, typ: typ,
		labels:  append([]string(nil), labels...),
		buckets: append([]float64(nil), buckets...),
		samples: make(map[string]*sample),
	}
	r.families[name] = f
	r.order = append(r.order, name)
	return f, nil
}

// Gauge 是可增可减的瞬时值，例如在线人数。
type Gauge struct{ fam *family }

func (r *Registry) Gauge(name, help string, labels ...string) (*Gauge, error) {
	f, err := r.newFamily(name, help, typeGauge, labels, nil)
	if err != nil {
		return nil, err
	}
	return &Gauge{fam: f}, nil
}

func (g *Gauge) Set(value float64, labelValues ...string) error { return g.fam.set(value, labelValues) }
func (g *Gauge) Add(delta float64, labelValues ...string) error { return g.fam.add(delta, labelValues) }

func (f *family) sampleLocked(values []string) (*sample, error) {
	if len(values) != len(f.labels) {
		return nil, fmt.Errorf("%w: %s got %d, want %d", ErrLabelCount, f.name, len(values), len(f.labels))
	}
	key := encodeKey(values)
	if s, ok := f.samples[key]; ok {
		return s, nil
	}
	s := &sample{values: append([]string(nil), values...)}
	if f.typ == typeHistogram {
		s.counts = make([]uint64, len(f.buckets))
	}
	f.samples[key] = s
	f.order = append(f.order, key)
	return s, nil
}

func (f *family) set(value float64, labelValues []string) error {
	if err := checkValue(value); err != nil {
		return err
	}
	f.mu.Lock()
	defer f.mu.Unlock()
	s, err := f.sampleLocked(labelValues)
	if err != nil {
		return err
	}
	s.value = value
	return nil
}

func (f *family) add(delta float64, labelValues []string) error {
	if err := checkValue(delta); err != nil {
		return err
	}
	f.mu.Lock()
	defer f.mu.Unlock()
	s, err := f.sampleLocked(labelValues)
	if err != nil {
		return err
	}
	next := s.value + delta
	if math.IsInf(next, 0) || math.IsNaN(next) {
		return fmt.Errorf("%w: %s overflow", ErrNonFinite, f.name)
	}
	s.value = next
	return nil
}

// WriteText 按注册顺序输出文本格式。
func (r *Registry) WriteText(w io.Writer) error {
	r.mu.Lock()
	names := append([]string(nil), r.order...)
	families := make([]*family, 0, len(names))
	for _, name := range names {
		families = append(families, r.families[name])
	}
	r.mu.Unlock()
	for _, f := range families {
		if err := f.writeText(w); err != nil {
			return err
		}
	}
	return nil
}

func (f *family) writeText(w io.Writer) error {
	f.mu.Lock()
	defer f.mu.Unlock()
	if _, err := fmt.Fprintf(w, "# HELP %s %s\n", f.name, escapeHelp(f.help)); err != nil {
		return err
	}
	if _, err := fmt.Fprintf(w, "# TYPE %s %s\n", f.name, f.typ); err != nil {
		return err
	}
	for _, key := range f.order {
		s := f.samples[key]
		if f.typ == typeHistogram {
			if err := f.writeHistogram(w, s); err != nil {
				return err
			}
			continue
		}
		line := fmt.Sprintf("%s%s %s\n", f.name, renderLabels(f.labels, s.values, "", ""), formatValue(s.value))
		if _, err := io.WriteString(w, line); err != nil {
			return err
		}
	}
	return nil
}