scrabble-game/backend/internal/game/metrics.go

package game

import (
	"context"
	"time"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/metric"
	"go.opentelemetry.io/otel/metric/noop"
	"go.uber.org/zap"

	"scrabble/backend/internal/engine"
)

// meterName scopes the game domain's OpenTelemetry instruments.
const meterName = "scrabble/backend/game"

// gameMetrics holds the game domain's operational instruments. Every game-scoped
// measurement carries a "variant" attribute (scrabble_en/scrabble_ru/erudit_ru). The
// instruments default to no-ops (see defaultGameMetrics), so recording is always
// safe; SetMetrics installs the real meter during startup wiring.
type gameMetrics struct {
	replay    metric.Float64Histogram
	validate  metric.Float64Histogram
	moveDur   metric.Float64Histogram
	started   metric.Int64Counter
	abandoned metric.Int64Counter
}

// defaultGameMetrics returns instruments backed by a no-op meter, recording
// nothing until SetMetrics installs a real one.
func defaultGameMetrics() *gameMetrics {
	return newGameMetrics(noop.NewMeterProvider().Meter(meterName))
}

// newGameMetrics builds the instruments on meter, falling back to no-op
// instruments on the (rare) construction error so the game domain never fails to
// start over telemetry.
func newGameMetrics(meter metric.Meter) *gameMetrics {
	return &gameMetrics{
		replay:    histogram(meter, "game_replay_duration", "Seconds to rebuild a live game from its journal on a cache miss."),
		validate:  histogram(meter, "game_move_validate_duration", "Seconds to validate and score a tentative play (EvaluatePlay)."),
		moveDur:   histogram(meter, "game_move_duration", "Seconds a seat spent on a committed move (play/pass/exchange), by variant and phase. Aggregates all seats including robots; per-human analysis lives in the admin console."),
		started:   counter(meter, "games_started_total", "Games created and started."),
		abandoned: counter(meter, "games_abandoned_total", "Player seats dropped by the turn-timeout sweeper."),
	}
}

// SetMetrics installs the meter the game domain records to and registers the
// observable gauge reporting the live games resident in the cache by variant. It
// must be called during startup wiring; the default is a no-op meter.
func (svc *Service) SetMetrics(meter metric.Meter) {
	if meter == nil {
		return
	}
	svc.metrics = newGameMetrics(meter)
	if _, err := meter.Int64ObservableGauge("game_cache_active",
		metric.WithDescription("Live games currently resident in the in-memory cache, by variant."),
		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
			for variant, n := range svc.cache.countByVariant() {
				o.Observe(int64(n), metric.WithAttributes(attribute.String("variant", variant)))
			}
			return nil
		}),
	); err != nil {
		svc.log.Warn("game: register cache gauge", zap.Error(err))
	}
}

// recordReplay records the duration of a cache-miss journal replay for variant.
func (m *gameMetrics) recordReplay(ctx context.Context, v engine.Variant, start time.Time) {
	m.replay.Record(ctx, time.Since(start).Seconds(), variantAttr(v))
}

// recordValidate records the duration of one play validation for variant.
func (m *gameMetrics) recordValidate(ctx context.Context, v engine.Variant, start time.Time) {
	m.validate.Record(ctx, time.Since(start).Seconds(), variantAttr(v))
}

// recordMoveDuration records how long a seat spent on a committed move, attributed by
// variant and the game phase derived from moveCount. A non-positive duration (a clock
// skew or a move with no recorded turn start) is dropped.
func (m *gameMetrics) recordMoveDuration(ctx context.Context, v engine.Variant, moveCount int, d time.Duration) {
	if d <= 0 {
		return
	}
	m.moveDur.Record(ctx, d.Seconds(),
		metric.WithAttributes(attribute.String("variant", v.String()), attribute.String("phase", phaseOf(moveCount))))
}

// phaseOf buckets a move ordinal into the game phase used as a metric attribute. The
// thresholds reflect a typical ~28-move game (docs/ARCHITECTURE.md §7).
func phaseOf(moveCount int) string {
	switch {
	case moveCount <= 8:
		return "opening"
	case moveCount <= 20:
		return "middle"
	default:
		return "endgame"
	}
}

// recordStarted counts one started game of variant.
func (m *gameMetrics) recordStarted(ctx context.Context, v engine.Variant) {
	m.started.Add(ctx, 1, variantAttr(v))
}

// recordAbandoned counts one seat dropped by the turn-timeout sweeper in a game of
// variant.
func (m *gameMetrics) recordAbandoned(ctx context.Context, v engine.Variant) {
	m.abandoned.Add(ctx, 1, variantAttr(v))
}

// variantAttr is the shared "variant" attribute option, usable for both Record and
// Add measurements.
func variantAttr(v engine.Variant) metric.MeasurementOption {
	return metric.WithAttributes(attribute.String("variant", v.String()))
}

func histogram(m metric.Meter, name, desc string) metric.Float64Histogram {
	h, err := m.Float64Histogram(name, metric.WithUnit("s"), metric.WithDescription(desc))
	if err != nil {
		h, _ = noop.NewMeterProvider().Meter(meterName).Float64Histogram(name)
	}
	return h
}

func counter(m metric.Meter, name, desc string) metric.Int64Counter {
	c, err := m.Int64Counter(name, metric.WithDescription(desc))
	if err != nil {
		c, _ = noop.NewMeterProvider().Meter(meterName).Int64Counter(name)
	}
	return c
}