# V2 Telemetry, Analytics, And Balance Tooling

`FV2TelemetryAnalyticsFeatureSet` is the source-of-truth contract for §55. It
collects runtime event schemas, ingest pipeline rules, Maat balance dashboard
metrics, ghost sharing, crash/perf, privacy, segmentation, public balance
publication, and tournament archive configuration.
`GameEventTaxonomy_V2_Contract.json` defines the Phase 72 standard event
taxonomy for SDK, schema migration, ingestion, replay, export, and warehouse
work. `maya-telemetry-sdk` implements the Phase 72 Rust client SDK contract in
`client-telemetry-sdk-rust.md`, including bounded buffering, batched
transmission, and offline replay. `telemetry-sdk-event-catalog.md` defines the
`v2-telemetry-sdk-event-catalog-v1` SDK-facing catalog that maps standard events
to Rust topic constants, required payload fields, and example payloads.
`telemetry-event-schema.md` defines the versioned proto3 wire schema used for
compact batched transmission. `telemetry-ingestion-endpoint.md` defines the
server-side endpoint that accepts validated telemetry batches and writes them to
the firehose queue. `telemetry-data-pipeline.md` defines the Kafka/Kinesis
transform path from that firehose queue into warehouse rows.
`telemetry-session-reconstruction.md` defines the player timeline builder that
turns warehouse rows into reconstructed session documents.
`telemetry-privacy-compliance.md` defines consent, GDPR opt-in, CCPA opt-out,
retention, and PII redaction enforcement before optional analytics processing.
`telemetry-rate-limiting.md` defines deterministic per-session sampling and
token-bucket rate limiting for production volume control.
`telemetry-schema-migrations.md` defines the additive-only
`v2-telemetry-schema-migrations-additive-v1` workflow for adding event types and
optional fields without breaking existing readers. `telemetry-debug-mode.md`
defines the `v2-telemetry-debug-mode-dev-only-v1` workflow for verbose local
event logging that is disabled in release builds. `telemetry-event-replay.md`
defines the `v2-telemetry-event-replay-reingest-v1` workflow for replaying
historical warehouse events through updated ingestion and pipeline code.
`telemetry-data-export-api.md` defines the
`v2-telemetry-data-export-governed-v1` workflow for governed raw event queries
by approved researchers and analysts. `analytics-self-service-query-guide.md`
defines the `v2-analytics-self-service-query-guide-v1` workflow for the
self-service query guide, SQL templates, privacy guardrails, and BI handoff.
`client-performance-telemetry.md` defines the
`v2-client-performance-telemetry-v1` workflow for FPS, frame-time histogram,
CPU/GPU load, and memory telemetry per session. `telemetry-integration-tests.md`
defines the `v2-telemetry-client-to-warehouse-integration-v1` workflow that
verifies client events flow through ingestion, firehose, transform, and
warehouse rows. `realtime-player-count-dashboard.md` defines the
`v2-realtime-player-count-dashboard-v1` operational dashboard for concurrent
players by region, game mode, and platform. `player-behavior-heatmaps.md`
defines the `v2-player-behavior-heatmaps-v1` surface for 2D movement/death/
linger grids and 3D voxel density maps. `session-funnel-analysis.md` defines the
`v2-session-funnel-analysis-v1` new-player funnel from tutorial to first
purchase with drop-off rates. `retention-cohort-analysis.md` defines the
`v2-retention-cohort-analysis-v1` day-1, day-7, and day-30 retention cohort
surface by acquisition source. `engagement-metrics-dashboard.md` defines the
`v2-engagement-metrics-dashboard-v1` surface for session length distribution,
sessions per week, and time between sessions. `economy-analytics.md` defines the
`v2-economy-analytics-v1` surface for currency earn/spend rates, inflation
tracking, and item price effectiveness. `economy-analytics-dashboard.md` defines
the `v2-economy-analytics-dashboard-v1` operator dashboard for currency supply
velocity, average player wealth by level, item price trends, and sink/source
ratios. `difficulty-analytics.md` defines the `v2-difficulty-analytics-v1`
surface for per-encounter win/loss rates, retry counts, time-to-complete, and
difficulty spike detection. `crash-analytics-dashboard.md` defines the
`v2-crash-analytics-dashboard-v1` surface for crash rate by version, platform,
hardware, and top crash stacks. `performance-analytics.md` defines the
`v2-performance-analytics-v1` surface for FPS distribution by hardware tier,
settings preset adoption, and hitching frequency.

## Ingest Path

V2 publishes canonical `@oshun/event-bus` topics. The backend ingest path is:

1. `Firehose` through `v2-telemetry-firehose`
2. `PiiStrip` and raw-account-identifier rejection
3. `Warehouse` through `warehouse.v2_telemetry.events`

Events must not use a V2-only telemetry endpoint. Analytics consumers read from
the warehouse or governed Maat surfaces, not from rollback simulation.

## Event Coverage

The launch schema covers standard game event types for session start, session
end, level load, death, achievement, purchase, UI interaction, and error. The
canonical topics are `v2.player.session.started`, `v2.player.session.ended`,
`v2.match.level.loaded`, `v2.match.player.death`,
`v2.player.achievement.unlocked`, `v2.cosmetic.purchased`,
`v2.player.ui.interacted`, and `v2.player.error.reported`.

## Client SDK

The Rust client SDK lives at `libs/maya/engine-core/crates/maya-telemetry-sdk`.
It exposes `TelemetrySdk`, `TelemetryEvent`, `TelemetryBatch`, and a
caller-provided `TelemetryTransport`. The SDK does not own a runtime or socket;
it keeps the live buffer and offline queue bounded with `max_buffered_events`,
`max_batch_events`, `max_batch_bytes`, and `offline_queue_limit`.

## SDK Event Catalog

`telemetry-sdk-event-catalog.md` applies the `v2-telemetry-sdk-event-catalog-v1`
policy. It maps every standard telemetry topic to its `maya-telemetry-sdk`
constant, required payload fields, reliability mode, and minimal example payload
while preserving the `GameEventTaxonomy_V2_Contract.json` source vocabulary.

## Event Schema

`V2/ue/Build/Telemetry/v2-telemetry-event-schema.proto` is the canonical compact
wire schema. `TelemetryEventBatch` carries `wire_schema_major`,
`wire_schema_minor`, `wire_schema_patch`, `min_reader_schema_major`, `batch_id`,
`offline_replay`, `approx_bytes`, and repeated `TelemetryEvent` records. Readers
must reject unsupported major versions and skip unknown protobuf fields for
forward-compatible additive changes.

## Ingestion Endpoint

`@v2/telemetry-ingestion` owns `POST /v2/telemetry/ingest`. It accepts
`application/json` and protobuf telemetry batches, validates schema version
`1.0.0`, enforces standard topic fields, rejects PII payload fields, and writes
accepted batches to `v2-telemetry-firehose`.

## Data Pipeline

`@v2/telemetry-data-pipeline` consumes Kafka or Kinesis envelopes from
`v2-telemetry-firehose`, transforms validated batches into deterministic
`TelemetryWarehouseRow` records, and writes to `warehouse.v2_telemetry.events`
through ClickHouse, BigQuery, or Redshift sink adapters.

## Session Reconstruction

`@v2/telemetry-session-reconstruction` reads `warehouse.v2_telemetry.events`,
groups rows by `sessionId`, orders each timeline by sequence, event time, and
event ID, and writes reconstructed session documents to
`warehouse.v2_telemetry.player_sessions`. The session document preserves all
source event IDs, topic counts, start/end/duration metadata, and anomalies such
as missing boundaries, sequence gaps, duplicate sequence numbers, malformed
payload JSON, and payload/session mismatches.

## Privacy Compliance

`@v2/telemetry-privacy-compliance` composes `@aphrodite/consent-engine` with the
telemetry ingestion PII rules. GDPR-region optional telemetry requires explicit
opt-in, CCPA/CPRA Do-Not-Sell/Share suppresses behavioral telemetry, and
persisted `Privacy.TelemetryOptOut` suppresses optional analytics across save
reset boundaries. Accepted events receive the
`v2-telemetry-privacy-retention-v1` policy: 7 days for required operational
telemetry, 30 days for optional matchplay telemetry, and 14 days for behavioral
telemetry.

## Rate Limiting

`@v2/telemetry-rate-limiting` applies the `v2-telemetry-rate-limit-policy-v1`
policy before production analytics handoff. It assigns deterministic per-session
sample rates between 1 and 100 percent, uses per-session/topic token buckets,
and bypasses both sampling and rate limits for critical crash, cheat-detection,
and player error topics.

## Schema Migrations

`@v2/telemetry-schema-migrations` owns additive telemetry schema migration
plans. Plans use the `v2-telemetry-schema-migrations-additive-v1` policy and
document new event types, optional fields, deprecated fields, and reader rollout
gates in `telemetry-schema-migrations.md` before protobuf or warehouse pipelines
change.

## Debug Mode

`@v2/telemetry-debug-mode` applies the `v2-telemetry-debug-mode-dev-only-v1`
policy. It emits sanitized verbose records for every development, test, QA, or
staging event when explicitly enabled, and hard-disables logging for release,
production, and shipping builds.

## Event Replay

`@v2/telemetry-event-replay` applies the `v2-telemetry-event-replay-reingest-v1`
policy. It reconstructs events from `warehouse.v2_telemetry.events`, verifies
payload hashes, builds deterministic offline replay batches, and sends them back
through `/v2/telemetry/ingest`.

## Data Export API

`@v2/telemetry-data-export-api` applies the
`v2-telemetry-data-export-governed-v1` policy. It serves
`GET /v2/telemetry/export/events` for researcher, analyst, and admin principals
with approved purposes, scoped filters, cursor pagination, and raw `payloadJson`
rows from `warehouse.v2_telemetry.events`.

## Client Performance

`@v2/client-performance-telemetry` applies the
`v2-client-performance-telemetry-v1` policy. It emits
`v2.client.performance.sampled` events with FPS summaries, frame-time histogram
JSON, CPU/GPU load, and memory usage so the existing ingestion and warehouse
pipeline can process client performance samples.

## Integration Tests

`@v2/telemetry-integration-tests` applies the
`v2-telemetry-client-to-warehouse-integration-v1` policy. It posts client
`TelemetryEventBatch` values to the in-memory ingestion endpoint, drains the
queued `v2-telemetry-firehose` batch through `runTelemetryDataPipelineOnce`, and
asserts the resulting `warehouse.v2_telemetry.events` rows.

## Real-Time Player Counts

`@v2/realtime-player-count-dashboard` applies the
`v2-realtime-player-count-dashboard-v1` policy. It computes current concurrent
players, matchmaking players, and in-match players from latest
region/game-mode/platform segment samples, labels feed freshness as `fresh`,
`stale`, or `empty`, and uses `@iris/analytics-realtime` for realtime widgets
and spike alerts.

## Player Behavior Heatmaps

`@v2/player-behavior-heatmaps` applies the `v2-player-behavior-heatmaps-v1`
policy. It composes `@galatea/analytics/heatmap-engine` for 2D movement and
dwell density, adds death and linger overlays, emits 3D voxel density maps, and
suppresses raw player IDs and raw trajectory points from operator surfaces.

## Session Funnel Analysis

`@v2/session-funnel-analysis` applies the `v2-session-funnel-analysis-v1`
policy. It composes `@iris/analytics-funnel` for the new-player tutorial, first
mission, open world, and first purchase path, then emits conversion rates,
drop-off rates, drop-off reasons, and chart-ready funnel bars without exposing
raw account IDs.

## Retention Cohort Analysis

`@v2/retention-cohort-analysis` applies the `v2-retention-cohort-analysis-v1`
policy. It composes `@iris/analytics-cohort` for daily cohorts, day-1, day-7,
and day-30 retention curves, acquisition source segmentation, and
immature-cohort guards without exposing raw account IDs.

## Engagement Metrics Dashboard

`@v2/engagement-metrics-dashboard` applies the
`v2-engagement-metrics-dashboard-v1` policy. It uses `@iris/analytics`
engagement metric names and computes session length distribution, sessions per
week, and time between sessions from V2 session telemetry without exposing raw
account IDs.

## Economy Analytics

`@v2/economy-analytics` applies the `v2-economy-analytics-v1` policy. It anchors
to `@maat/finance` and computes currency earn/spend rates, inflation tracking,
and item price effectiveness from V2 economy telemetry without exposing raw
account IDs.

## Economy Analytics Dashboard

`@v2/economy-analytics-dashboard` applies the
`v2-economy-analytics-dashboard-v1` policy. It anchors to `@maat/finance` and
computes currency supply velocity, average player wealth by level, item price
trends, and sink/source ratios from V2 economy telemetry without exposing raw
account IDs.

## Difficulty Analytics

`@v2/difficulty-analytics` applies the `v2-difficulty-analytics-v1` policy. It
composes `@iris/analytics-realtime` for difficulty spike alert snapshots and
computes per-encounter win/loss rates, retry counts, time-to-complete
percentiles, and difficulty spike detection without exposing raw account IDs.

## Crash Analytics Dashboard

`@v2/crash-analytics-dashboard` applies the `v2-crash-analytics-dashboard-v1`
policy. It anchors to `@tara/monitoring` and computes crash rate by version,
platform, hardware tier, and top crash stacks without exposing raw account IDs
or raw stack traces.

## Performance Analytics

`@v2/performance-analytics` applies the `v2-performance-analytics-v1` policy. It
composes `@v2/client-performance-telemetry` and computes FPS distribution by
hardware tier, settings preset adoption, and hitching frequency without exposing
raw account IDs.

## A/B Test Analysis Pipeline

`@v2/ab-test-analysis-pipeline` applies the `v2-ab-test-analysis-pipeline-v1`
policy. It composes `@iris/analytics-ab` and computes statistical significance
testing, effect size estimation, and automatic winner detection for
hashed-account experiment telemetry. See `ab-test-analysis-pipeline.md`.

## Churn Prediction Model

`@v2/churn-prediction-model` applies the `v2-churn-prediction-model-v1` policy.
It composes `@iris/analytics` retention thresholds and computes 7-day churn
probability, risk banding, and feature driver attribution for hashed-account
engagement telemetry. See `churn-prediction-model.md`.

## Player Segmentation

`@v2/player-segmentation` applies the `v2-player-segmentation-v1` policy. It
composes `@iris/analytics` metric identifiers and assigns spend tiers (`whale`,
`dolphin`, `minnow`, `non_spender`), motivation segments (`explorer`,
`achiever`, `socializer`, `killer`), and custom rule segments from
hashed-account telemetry. See `player-segmentation.md`.

## Telemetry Alerting Rules

`@v2/telemetry-alerting-rules` applies the `v2-telemetry-alerting-rules-v1`
policy. It composes `@iris/analytics-realtime` alert rule types and evaluates
aggregate crash rate, player count, and matchmaking wait samples for
`crash-rate-spike-2x`, `player-count-drop-20pct`, and
`matchmaking-wait-time-3min` alerts. See `telemetry-alerting-rules.md`.

## Telemetry BI Export Connectors

`@v2/telemetry-bi-export-connectors` applies the
`v2-telemetry-bi-export-connectors-v1` policy. It composes the governed
`@v2/telemetry-data-export-api` and emits Grafana JSON data frames, Tableau Web
Data Connector rows and schema, and Looker LookML/rows for authorized telemetry
exports. See `telemetry-bi-export-connectors.md`.

## Analytics Self-Service Query Guide

`analytics-self-service-query-guide.md` applies the
`v2-analytics-self-service-query-guide-v1` policy. It documents the self-service
query guide for approved analysts and researchers, including the data map, SQL
templates, privacy guardrails, review checklist, and Grafana, Tableau, and
Looker BI handoff.

The broader analytics schema covers match start/end, move usage frequency,
damage dealt/received per move, combo length, drive/heat/hype/stun resource
usage, finisher trigger rate, rage quits, crashes, frame-budget exceedance,
ghost capture and consent, opt-out persistence, segmentation, churn, match
acceptance, per-fighter retention, balance A/B, the A/B test analysis pipeline,
the churn prediction model, player segmentation, telemetry alerting rules, BI
export connectors, the self-service query guide, PTB balance signals, and
tournament archive facts.

## Balance Dashboards

`@v2/maat-balance-dashboard` composes `@maat/intelligence`, `@maat/dashboard`,
and `@maat/reporting`. Required panels include per-move pick rate,
win-rate-on-hit, win-rate-on-block, authoring/runtime frame-data drift, hot/cold
fighter heatmaps, public A/B publication, PTB signal coverage, and frame-budget
release gates.

Balance experiments are off rollback authority. They must declare a rollback
runbook, publish public before/after results, and consume PTB play-data before
release approval.

## Privacy And Ghost Data

Telemetry opt-out persists across save reset and is documented in
`V2/docs/legal/privacy-policy.md`. The string keys `Privacy.TelemetryOptOut` and
`Privacy.GhostSharingOptIn` are included in the §54 localization string table.

Ghost match capture and sharing are opt-in. Friends and global pools have
separate consent states.

## Player Analytics

Player segmentation includes Casual, Competitive, CosmeticBuyer, Completionist,
Spectator, EsportsAspirant, Returning, and AtRisk. Churn risk is updated weekly.
Ethical re-engagement is limited to cosmetic grants and free-weekend invites;
paywall pressure is forbidden.

Dashboards include the match-acceptance funnel and per-fighter retention: queue
time, accept rate, first-match completion, retention after first match, pick
rate over time, fighter drop-off, and mastery completion.

## Public Records

Public balance results live under `V2/balance/public-results/`. Per-fighter
framedata changes live under `V2/balance/changelog/<fighter>.md`. Tournament
records and the Crown-linked power-ranking calculator live at
`apps/v2/web/esports/results/`.