Fighting Game · Guides & deep dives

Client Telemetry SDK For Rust

batch.

4sections2 minread
Markdown source
On this page

maya-telemetry-sdk is the client-side telemetry SDK for Phase 72.5.1.2. It keeps the hot path synchronous and bounded: callers create TelemetryEvent values, enqueue them into a preallocated VecDeque, and drain TelemetryBatch values when their platform networking layer is ready to send.

Runtime Contract#

  • TelemetrySdkConfig.max_buffered_events bounds the live event buffer.
  • TelemetrySdkConfig.max_batch_events and max_batch_bytes bound each drained batch.
  • TelemetrySdkConfig.offline_queue_limit bounds replay storage for failed sends.
  • TelemetryTransport is caller-provided; the SDK does not create background threads, runtimes, sockets, or HTTP clients.
  • flush_with drains offline replay first, then live events, so failed sends do not starve old telemetry.

When the live buffer is full, best-effort events are dropped and counted in TelemetrySdk::dropped_events. Critical events can evict older non-critical events, but the SDK stays bounded even when every queued event is critical.

Batching And Offline Queueing#

drain_batch removes up to max_batch_events events while respecting max_batch_bytes. If a single event exceeds the byte budget, it is still sent alone so the queue cannot wedge behind one large record.

If a transport send fails, callers pass the TelemetryBatch to mark_batch_failed or use flush_with, which performs that step automatically. Failed live batches move into the offline queue. drain_offline_batch returns that replay work before live events. Failed replay batches are requeued at the front with offline_replay = true preserved for the next drain.

Taxonomy Integration#

The SDK exports constants for the eight Phase 72 standard topics from GameEventTaxonomy_V2_Contract.json:

  • 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
  • v2.player.error.reported

With validate_standard_topics enabled, enqueueing a standard topic requires the taxonomy's required payload fields. The SDK also rejects raw account IDs, email, IP address, platform user IDs, and raw log lines before they can enter the live or offline queue.

telemetry-sdk-event-catalog.md is the Phase 72.5.1.15 SDK-facing companion catalog. It maps every standard event to its Rust topic constant, required payload fields, reliability mode, and example payload so producers can author events without drifting from GameEventTaxonomy_V2_Contract.json.

Verification#

Targeted verification for this SDK is:

bash
cargo check --manifest-path libs/maya/engine-core/Cargo.toml -p maya-telemetry-sdk --all-targets
cargo test --manifest-path libs/maya/engine-core/Cargo.toml -p maya-telemetry-sdk
python V2/ue/Tools/check-v2-client-telemetry-sdk-rust.py