# Telemetry Event Schema

Phase 72.5.1.3 standardizes the compact telemetry wire format as proto3 package
`oshun.v2.telemetry.v1`. The canonical schema is
`V2/ue/Build/Telemetry/v2-telemetry-event-schema.proto`, with
`TelemetryEventBatch` as the root message.

## Versioning

Every batch carries `wire_schema_major`, `wire_schema_minor`,
`wire_schema_patch`, and `min_reader_schema_major`. The current SDK emits
`1.0.0` with minimum reader major `1`. Readers must reject unsupported major
versions and must skip unknown protobuf fields for forward-compatible additive
changes.

Breaking changes require a new major version. Minor and patch changes are
reserved for additive fields, new optional payload values, or documentation-only
schema clarifications.

## Messages

- `TelemetryEventBatch` contains the schema version, `batch_id`,
  `offline_replay`, `approx_bytes`, repeated `TelemetryEvent` records, and a
  producer string.
- `TelemetryEvent` contains `event_id`, canonical `topic`,
  `payload_schema_version`, `unix_seconds`, `session_id`, `sequence`, repeated
  `TelemetryField` payload entries, and `critical`.
- `TelemetryField` stores payload data as a keyed oneof: `string_value`,
  `int_value`, `double_value`, or `bool_value`.

Field numbers 10-19 on batches, 9-19 on events, and 6-19 on payload fields are
reserved for the next schema pass. New readers must keep those reservations
intact.

## Rust SDK Codec

`maya-telemetry-sdk` exposes `encode_batch_protobuf`, `decode_batch_protobuf`,
and `TelemetryBatch::to_protobuf_bytes`. The codec is protobuf-wire compatible
and deliberately avoids build-time code generation in the engine workspace. It
validates the Phase 72 standard topics before encoding, rejects forbidden PII
payload keys, and revalidates decoded events before returning them to callers.

Targeted verification:

```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-telemetry-event-schema.py
```