# Client Telemetry SDK For Rust

`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
```