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:
Firehosethroughv2-telemetry-firehosePiiStripand raw-account-identifier rejectionWarehousethroughwarehouse.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/.