This page is for engineers changing schema definitions or regenerating their outputs. Installing Client Monitor and sending samples does not require this pipeline. If you arrived here while setting up monitoring, continue with Send samples to your backend.

Authoritative definitions#

Authoritative sources are sources/samples/ClientSample.avsc and PeerConnectionSample.chunk.avsc. The first defines the root and discrete records, the second the PC envelope, tracks and browser-stat families. Every field/type/default is in the schema field reference. Root includes timestamp, optional clientId/callId, attachments, score/reasons, PCs, events, issues, metadata and extensions. Optional at schema level does not imply accepted by Observer: Observer rejects missing clientId or callId.

ClientIssue is intentionally extensible by string type and payload, rather than a closed enum of detector issues; adding a new issue type usually does not require changing the Avro structure. New raw/stat fields do. ClientMonitorIssues is a local discriminated union for built-in issue handling, not the universal wire schema.

Generation pipeline#

The generation path is src/cli.ts → runPipeline() → JSONC Avro loading/chunk expansion/validation → TypeScript, normalized Avro, Markdown, protobuf and npm targets. src/config.ts defines deliberate format overrides:

• Avro attachments are nullable string, but TypeScript exposes Record<string,unknown>.
• Payload is modeled with recursive AnyValue in Avro, exposed as Record in TS, and serialized as JSON string in protobuf.
• SFU extension payload is a specific string exception.
• Proto UUID-like identifier fields become bytes; timestamps become double; enum spelling overrides include candidate-pair in-progress variants.

Do not compare these representations with naive textual equivalence.

Generated artifacts#

Generated outputs appear under outputs/typescript, outputs/avsc, protobuf outputs and npm package source directories. observer-js’s checked-in ClientSample.ts is byte-identical to the current generated TS; client-monitor’s type field sets match but its file differs textually. Both advertise 3.7.0. Do not edit just one copied ClientSample file as if it were authoritative.

Codec compatibility#

JSON/protobuf codec packages are stream-stateful. One encoder per client/receiver, ordered complete delivery, resets for reconnect/snapshot boundaries. Deltas are not complete ClientSamples.

Exact source revisions · Historical schema releases