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.

backend/internal/config/config.go

@@ -42,13 +42,20 @@ type Config struct {
 	// side-service, used by the admin console to send operator broadcasts. Empty
 	// disables broadcasts (the admin broadcast actions report "not configured").
 	ConnectorAddr string
+	// GuestReapInterval is the cadence of the abandoned-guest reaper sweep.
+	GuestReapInterval time.Duration
+	// GuestRetention is the account age past which an unused guest (no game seat)
+	// is eligible for deletion by the reaper.
+	GuestRetention time.Duration
 }
 
 // Defaults applied when the corresponding environment variable is unset.
 const (
-	defaultHTTPAddr = ":8080"
-	defaultGRPCAddr = ":9090"
-	defaultLogLevel = "info"
+	defaultHTTPAddr          = ":8080"
+	defaultGRPCAddr          = ":9090"
+	defaultLogLevel          = "info"
+	defaultGuestReapInterval = time.Hour
+	defaultGuestRetention    = 30 * 24 * time.Hour
 )
 
 // Load reads the configuration from the environment, applies defaults for unset
@@ -98,6 +105,15 @@ func Load() (Config, error) {
 		return Config{}, err
 	}
 
+	guestReapInterval, err := envDuration("BACKEND_GUEST_REAP_INTERVAL", defaultGuestReapInterval)
+	if err != nil {
+		return Config{}, err
+	}
+	guestRetention, err := envDuration("BACKEND_GUEST_RETENTION", defaultGuestRetention)
+	if err != nil {
+		return Config{}, err
+	}
+
 	smtp := account.SMTPConfig{
 		Host:     os.Getenv("BACKEND_SMTP_HOST"),
 		Port:     envOr("BACKEND_SMTP_PORT", "587"),
@@ -107,16 +123,18 @@ func Load() (Config, error) {
 	}
 
 	c := Config{
-		HTTPAddr:      envOr("BACKEND_HTTP_ADDR", defaultHTTPAddr),
-		GRPCAddr:      envOr("BACKEND_GRPC_ADDR", defaultGRPCAddr),
-		LogLevel:      envOr("BACKEND_LOG_LEVEL", defaultLogLevel),
-		Postgres:      pg,
-		Telemetry:     tel,
-		Game:          gm,
-		Lobby:         lb,
-		Robot:         rb,
-		SMTP:          smtp,
-		ConnectorAddr: os.Getenv("BACKEND_CONNECTOR_ADDR"),
+		HTTPAddr:          envOr("BACKEND_HTTP_ADDR", defaultHTTPAddr),
+		GRPCAddr:          envOr("BACKEND_GRPC_ADDR", defaultGRPCAddr),
+		LogLevel:          envOr("BACKEND_LOG_LEVEL", defaultLogLevel),
+		Postgres:          pg,
+		Telemetry:         tel,
+		Game:              gm,
+		Lobby:             lb,
+		Robot:             rb,
+		SMTP:              smtp,
+		ConnectorAddr:     os.Getenv("BACKEND_CONNECTOR_ADDR"),
+		GuestReapInterval: guestReapInterval,
+		GuestRetention:    guestRetention,
 	}
 	if err := c.validate(); err != nil {
 		return Config{}, err
@@ -152,6 +170,12 @@ func (c Config) validate() error {
 	if err := c.Robot.Validate(); err != nil {
 		return fmt.Errorf("config: %w", err)
 	}
+	if c.GuestReapInterval <= 0 {
+		return fmt.Errorf("config: BACKEND_GUEST_REAP_INTERVAL must be positive")
+	}
+	if c.GuestRetention <= 0 {
+		return fmt.Errorf("config: BACKEND_GUEST_RETENTION must be positive")
+	}
 	return nil
 }
 

backend/internal/config/config_test.go

@@ -151,12 +151,54 @@ func TestLoadRejectsMalformedDuration(t *testing.T) {
 	}
 }
 
-// TestLoadRejectsUnsupportedExporter verifies that an exporter outside the MVP
-// set is rejected.
+// TestLoadRejectsUnsupportedExporter verifies that an exporter outside the
+// supported set is rejected.
 func TestLoadRejectsUnsupportedExporter(t *testing.T) {
 	t.Setenv("BACKEND_POSTGRES_DSN", testDSN)
-	t.Setenv("BACKEND_OTEL_TRACES_EXPORTER", "otlp")
+	t.Setenv("BACKEND_OTEL_TRACES_EXPORTER", "prometheus")
 	if _, err := Load(); err == nil {
 		t.Fatal("Load: expected an error for an unsupported exporter, got nil")
 	}
 }
+
+// TestLoadAcceptsOTLPExporter verifies that the otlp exporter is now accepted
+// (the collector is stood up with the deploy; the default stays none).
+func TestLoadAcceptsOTLPExporter(t *testing.T) {
+	t.Setenv("BACKEND_POSTGRES_DSN", testDSN)
+	t.Setenv("BACKEND_DICT_DIR", "/dict")
+	t.Setenv("BACKEND_OTEL_TRACES_EXPORTER", "otlp")
+	t.Setenv("BACKEND_OTEL_METRICS_EXPORTER", "otlp")
+	if _, err := Load(); err != nil {
+		t.Fatalf("Load with otlp exporters: %v", err)
+	}
+}
+
+// TestLoadGuestReaperDefaultsAndOverride covers the guest-reaper knobs: defaults
+// when unset, an override, and rejection of a non-positive value.
+func TestLoadGuestReaperDefaultsAndOverride(t *testing.T) {
+	t.Setenv("BACKEND_POSTGRES_DSN", testDSN)
+	t.Setenv("BACKEND_DICT_DIR", "/dict")
+
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if c.GuestReapInterval != defaultGuestReapInterval {
+		t.Errorf("GuestReapInterval = %s, want %s", c.GuestReapInterval, defaultGuestReapInterval)
+	}
+	if c.GuestRetention != defaultGuestRetention {
+		t.Errorf("GuestRetention = %s, want %s", c.GuestRetention, defaultGuestRetention)
+	}
+
+	t.Setenv("BACKEND_GUEST_RETENTION", "168h")
+	if c, err = Load(); err != nil {
+		t.Fatalf("Load (override): %v", err)
+	} else if c.GuestRetention != 168*time.Hour {
+		t.Errorf("GuestRetention = %s, want 168h", c.GuestRetention)
+	}
+
+	t.Setenv("BACKEND_GUEST_REAP_INTERVAL", "0s")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for a non-positive reap interval, got nil")
+	}
+}