Crate livekit_telemetry

Expand description

§LiveKit Telemetry

Important: This is an internal crate for client telemetry in LiveKit client SDKs and is not meant to be used directly.

It currently holds the shared data model and its encoding:

Records. TelemetryEvent, LogRecord, Attribute / AttributeValue, Severity and SpanOutcome: the events, log lines and span outcomes a platform SDK hands over.
Buffers. Bounded, drop-oldest queues for records and spans, each filed under the session (trace) it belongs to; every drop is counted.
Encoding. OTLP/HTTP protobuf logs and traces, using the opentelemetry-proto message types only (no gRPC stack).
Transport and destinations. TelemetryTransport, the seam that moves an encoded batch off the device (NetTransport over livekit-net with the net feature), and the routing that turns a Room’s server URL and token into its LiveKit Cloud ingest URL and credential.

The pipeline that batches, caches and uploads records is not part of the crate yet.

Event names, attributes and span rules are defined in SPEC.md. It is the contract for the whole crate, including the parts not implemented yet.

Collector responses are limited to 65,536 decoded body bytes. Overflow is retryable and preserves a valid Retry-After delay; no truncated body is used to classify acceptance or a project refusal. NetTransport uses livekit-net’s opt-in bounded client view. Its native backend stops during the read, including gzip decoding; ordinary HTTP requests remain uncapped. A host TelemetryTransport must enforce the same limit in its reader. The core also checks already-buffered custom/FFI/pulled responses, but this cannot bound allocation that already occurred in the host.

Structs§

Attribute: A key/value attribute on an event or on the resource.
DeviceState: What the host observes about the device; pushed with Telemetry::set_device_state whenever anything changes.
ExportRequest: One fully composed OTLP/HTTP export request.
ExportResponse: What the collector answered. A transport moves bytes both ways and never interprets them: status classification, Retry-After, the google.rpc.Status body and the Cloud “disabled” contract are read once, here, for every platform (Verdict::of).
FileCache: On-disk BatchCache: one file per encoded batch, so a crash or an offline shutdown loses nothing and the next launch replays what is left.
LogRecord: A log line as the platform captured it, where it happened. The core turns it into a record: semconv code.* attributes, lk.log.source, lk.log.logger, filed under the span’s session. Stamp timestamp_ns at capture; the record may cross an executor hop before it gets here.
MemoryCache: In-memory BatchCache: batches that could not be uploaded wait for the next attempt, bounded by max_bytes and 512 batches (MAX_BATCHES, oldest evicted). The newest batch always stays, even when it alone is larger than max_bytes. Lost with the process.
RtcStat: One entry of a WebRTC RTCStatsReport, as the platform got it: the entry’s type, id and its standard members (W3C webrtc-stats names; nested maps flattened with a dot, e.g. qualityLimitationDurations.cpu). Numbers may arrive as Int, Double or numeric Str.
RtcStatsSample: One reading of a track’s RTP statistics, as getStats() reports them.
TelemetryEvent: A discrete telemetry event.
TelemetryStats: Pipeline health as seen by the SDK: Telemetry::stats.

Enums§

AppState: Whether the app is in front of the user.
AttributeValue: Attribute value: the scalar subset of OTLP AnyValue.
AudioOutput: Where the audio goes, in platform-neutral terms (AVAudioSession port types, Android’s AudioDevice; the web’s MediaDeviceInfo.kind only ever gives other).
AudioRouteReason: Why the audio route changed, in platform-neutral terms (AVAudioSession reasons; Android’s device added/removed callbacks map to NewDevice / OldDeviceUnavailable).
CaptureDevice: Which capture device a failure is about.
CaptureFailure: Why a capture device could not be used: the getUserMedia failure taxonomy, which every platform maps onto (authorization status, onCameraDisconnected, NotReadableError, …).
DeviceEvent: Things that happen to the device mid-call and explain what the media did next. Not state (see DeviceState): each one is a record with a display body.
ExportError: Why a transport could not get an answer. A 4xx/5xx is an answer, not an error: return it as an ExportResponse and the core classifies it.
LogSource: Where a log line came from. WebRTC is chatty at warn, so only its errors become records; the SDK and the core use the configured floor.
MemoryPressure: Memory pressure as the OS reports it (DISPATCH_MEMORYPRESSURE_*, onTrimMemory levels: RUNNING_LOW/BACKGROUND → warning, RUNNING_CRITICAL/COMPLETE → critical).
NetworkType: The active network path, in OTel network.connection.type terms.
Severity: Event severity, mapped onto the OTel severity numbers (TRACE=1 … ERROR=17).
SpanOutcome: How an attempt ended. OTel status knows only Unset/Ok/Error, so Cancelled travels as status = Unset plus the lk.outcome attribute — every span carries lk.outcome so rollups never have to infer it (a user hanging up mid-connect is not a failure).
StreamDirection: Received (inbound) or sent (outbound) media.
TelemetryStatus: What the upload policy is doing right now.
ThermalState: Thermal pressure as the OS reports it (ProcessInfo.thermalState, PowerManager thermal status, the web Compute Pressure API — all four share this vocabulary).
TrackKind: Audio or video.

Constants§

ENDPOINT_OVERRIDE_ENV: The environment variable that points every upload at a collector of your own — a local OpenTelemetry collector for end-to-end tests. Not part of any platform API: set it in the test process’s environment before the pipeline starts. Either a URL with a logs path segment (its traces URL replaces that segment with traces) or a base URL (http://localhost:4318, OTLP paths /v1/logs and /v1/traces are appended).

Traits§

BatchCache: Queue of encoded OTLP batches between the exporter (Exporter) and the transport.
TelemetryTransport: Moves an encoded batch off the device and hands back whatever came back.