Stage 12: observability & performance (OTel/OTLP, domain metrics, guest GC)

- pkg/telemetry: shared OTel provider bootstrap (none/stdout/otlp + W3C
  propagators + Go runtime metrics); backend/internal/telemetry becomes a thin
  facade keeping its gin middleware.
- Telemetry parity: gateway and the Telegram connector gain telemetry runtimes
  and config (GATEWAY_/TELEGRAM_ SERVICE_NAME + OTEL_*); otelgrpc instruments the
  backend push server, the gateway's backend+connector clients and the connector
  server. Default exporter stays none (collector/dashboards are Stage 14).
- Operational metrics (variant attribute on game-scoped ones): game_replay_duration,
  game_move_validate_duration, games_started_total, games_abandoned_total,
  game_cache_active, chat_messages_total{kind}, gateway edge_request_duration.
  Wired via the SetMetrics setter pattern (default no-op meter).
- TODO-3: account.GuestReaper deletes guests with no game seat past
  BACKEND_GUEST_RETENTION (default 30d, swept every BACKEND_GUEST_REAP_INTERVAL).
- Tests: pkg/telemetry exporter selection; game/social/edge metric recording via
  a manual reader; config (otlp accepted, guest knobs); inttest guest reaper.
- Docs: PLAN.md re-scopes Stage 12 and adds Stage 13 (alphabet-on-wire) + Stage 14
  (CI/deploy) with the agreed dictionary-versioning resolution; ARCHITECTURE 11/13,
  TESTING, the three READMEs and FUNCTIONAL(+ru) updated.

gateway/internal/config/config.go

@@ -7,6 +7,8 @@ import (
 	"os"
 	"strconv"
 	"time"
+
+	pkgtel "scrabble/pkg/telemetry"
 )
 
 // Config holds the gateway's runtime configuration.
@@ -38,6 +40,8 @@ type Config struct {
 	PushHeartbeatInterval time.Duration
 	// RateLimit configures the in-memory anti-abuse limiter.
 	RateLimit RateLimitConfig
+	// Telemetry configures the OpenTelemetry providers (shared bootstrap).
+	Telemetry pkgtel.Config
 }
 
 // RateLimitConfig holds the token-bucket limits per class. Public and admin are
@@ -64,6 +68,7 @@ const (
 	defaultSessionTTL            = 10 * time.Minute
 	defaultSessionCacheMax       = 50000
 	defaultPushHeartbeatInterval = 15 * time.Second
+	defaultServiceName           = "scrabble-gateway"
 )
 
 // DefaultRateLimit returns the built-in anti-abuse limits.
@@ -91,6 +96,11 @@ func Load() (Config, error) {
 		SessionCacheMax: defaultSessionCacheMax,
 		RateLimit:       DefaultRateLimit(),
 	}
+	tel := pkgtel.DefaultConfig(defaultServiceName)
+	tel.ServiceName = envOr("GATEWAY_SERVICE_NAME", tel.ServiceName)
+	tel.TracesExporter = envOr("GATEWAY_OTEL_TRACES_EXPORTER", tel.TracesExporter)
+	tel.MetricsExporter = envOr("GATEWAY_OTEL_METRICS_EXPORTER", tel.MetricsExporter)
+	c.Telemetry = tel
 	if c.BackendTimeout, err = envDuration("GATEWAY_BACKEND_TIMEOUT", defaultBackendTimeout); err != nil {
 		return Config{}, err
 	}
@@ -131,6 +141,9 @@ func (c Config) validate() error {
 	if c.BackendGRPCAddr == "" {
 		return fmt.Errorf("config: GATEWAY_BACKEND_GRPC_ADDR must not be empty")
 	}
+	if err := c.Telemetry.Validate(); err != nil {
+		return fmt.Errorf("config: %w", err)
+	}
 	return nil
 }
 

gateway/internal/config/config_test.go

@@ -0,0 +1,31 @@
+package config
+
+import (
+	"testing"
+
+	pkgtel "scrabble/pkg/telemetry"
+)
+
+// TestLoadTelemetryDefaults verifies the gateway telemetry defaults: the
+// "scrabble-gateway" service name and both exporters off.
+func TestLoadTelemetryDefaults(t *testing.T) {
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if c.Telemetry.ServiceName != defaultServiceName {
+		t.Errorf("Telemetry.ServiceName = %q, want %q", c.Telemetry.ServiceName, defaultServiceName)
+	}
+	if c.Telemetry.TracesExporter != pkgtel.ExporterNone || c.Telemetry.MetricsExporter != pkgtel.ExporterNone {
+		t.Errorf("exporters = %q/%q, want none/none", c.Telemetry.TracesExporter, c.Telemetry.MetricsExporter)
+	}
+}
+
+// TestLoadRejectsUnsupportedExporter verifies an exporter outside the supported
+// set fails validation.
+func TestLoadRejectsUnsupportedExporter(t *testing.T) {
+	t.Setenv("GATEWAY_OTEL_METRICS_EXPORTER", "prometheus")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for an unsupported exporter, got nil")
+	}
+}