feat(uniffi): expose the telemetry core

.cargo/config.toml

@@ -8,16 +8,18 @@ rustflags = ["-C", "target-feature=+crt-static"]
 [target.aarch64-pc-windows-msvc]
 rustflags = ["-C", "target-feature=+crt-static"]
 
+# `-headerpad_max_install_names` on macOS: Flutter's native-assets step rewrites the cdylib's
+# install name with install_name_tool, which fails without the padding.
 # `-ObjC` must also be passed to rustdoc: doctest binaries are linked by rustdoc
 # and do not inherit `rustflags`. Without it the ObjC categories in libwebrtc's
 # static lib (e.g. `NSString (StdString)`) are not loaded, and static
 # initializers such as RTCH264ProfileLevelId.mm abort at process startup.
 [target.x86_64-apple-darwin]
-rustflags = ["-C", "link-args=-ObjC"]
+rustflags = ["-C", "link-args=-ObjC -Wl,-headerpad_max_install_names"]
 rustdocflags = ["-C", "link-args=-ObjC"]
 
 [target.aarch64-apple-darwin]
-rustflags = ["-C", "link-args=-ObjC"]
+rustflags = ["-C", "link-args=-ObjC -Wl,-headerpad_max_install_names"]
 rustdocflags = ["-C", "link-args=-ObjC"]
 
 [target.aarch64-apple-ios]

.changeset/uniffi-telemetry.md

@@ -0,0 +1,5 @@
+---
+livekit-uniffi: minor
+---
+
+Expose the client telemetry core over UniFFI: `telemetry_configure` / `telemetry_configure_pulled` (a bounded pull queue for bindings with thread-bound callbacks, served with `next` or polled with `try_next`), `telemetry_scope` with `TelemetryScope.set_server` (connect and every token refresh), spans, the subscribe lifecycle, `record_peer_stats` + `stats_poll_interval_ms`, `track_ended`, `emit_custom` / `set_attribute` (the Room-scoped app API), `telemetry_disable` (a synchronous opt-out, in effect when it returns), device state and log forwarding, with a host-implemented `TelemetryTransport` or the `livekit-net` HTTP client.

.gitignore

@@ -6,3 +6,4 @@ soxr-sys/test-output.wav
 .env
 .cursor
 __pycache__
+/target-*/

Cargo.toml

@@ -42,6 +42,7 @@ members = [
     "examples/rpc",
     "examples/save_to_disk",
     "examples/screensharing",
+    "examples/telemetry_ping",
     "examples/token_source",
     "examples/webhooks",
 ]

examples/telemetry_ping/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "telemetry_ping"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+livekit-telemetry = { workspace = true, features = ["net"] }
+livekit-net = { workspace = true, features = ["native", "rustls-tls-native-roots"] }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros"] }
+env_logger = { workspace = true }

examples/telemetry_ping/src/main.rs

@@ -0,0 +1,91 @@
+// Copyright 2026 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Records a small session through the telemetry core — an `lk.connect` span with its
+//! checkpoints, an `lk.publish`, an `lk.subscribe` ended by first media, and a custom event —
+//! and exports it.
+//!
+//! - A local OpenTelemetry collector: `LK_TELEMETRY_ENDPOINT=http://localhost:4318` (the core's
+//!   test-only override; any server URL and token are accepted).
+//! - A LiveKit Cloud project: `LK_URL=wss://<project>.livekit.cloud` and `LK_TOKEN=<participant
+//!   token with the observability grant>`.
+
+use std::{env, sync::Arc};
+
+use livekit_telemetry::{
+    Attribute, NetTransport, RoomIdentity, RtcStatsSample, SpanName, SpanOutcome, SpanStep,
+    SpanTrack, StreamDirection, Telemetry, TelemetryConfig, TrackKind, TrackSource,
+    ENDPOINT_OVERRIDE_ENV,
+};
+
+#[tokio::main]
+async fn main() {
+    env_logger::init();
+    let url = env::var("LK_URL").unwrap_or_else(|_| "ws://localhost:7880".to_owned());
+    let token = env::var("LK_TOKEN").unwrap_or_default();
+    if env::var(ENDPOINT_OVERRIDE_ENV).is_err() && env::var("LK_URL").is_err() {
+        eprintln!("set {ENDPOINT_OVERRIDE_ENV}=http://localhost:4318, or LK_URL and LK_TOKEN");
+        return;
+    }
+
+    let config = TelemetryConfig {
+        resource: vec![
+            Attribute::new("service.name", "telemetry_ping"),
+            Attribute::new("os.name", env::consts::OS),
+        ],
+        // Optional on-disk cache: run once with the collector down, once with it up.
+        storage_dir: env::var("LK_TELEMETRY_DIR").ok(),
+        ..Default::default()
+    };
+    let transport = NetTransport::from_registry().expect("livekit-net has no HTTP client");
+    let (telemetry, exporter) = Telemetry::new(config, Arc::new(transport));
+    tokio::spawn(exporter.run());
+
+    let room = telemetry.begin_scope();
+    room.set_server(&url, &token);
+    room.set_room(RoomIdentity { name: Some("telemetry-ping".into()), ..Default::default() });
+
+    let connect = room.start(SpanName::Connect, None);
+    for step in [SpanStep::WsOpen, SpanStep::Signal, SpanStep::JoinRecv, SpanStep::PcCreated] {
+        connect.step(step);
+    }
+    connect.end(SpanOutcome::Ok, None);
+
+    let microphone = SpanTrack {
+        sid: Some("TR_ping_mic".into()),
+        kind: TrackKind::Audio,
+        source: TrackSource::Microphone,
+        remote_identity: None,
+    };
+    let publish = room.start(SpanName::Publish, None);
+    publish.set_track(microphone);
+    publish.end(SpanOutcome::Ok, None);
+
+    let remote = SpanTrack {
+        sid: Some("TR_ping_remote".into()),
+        kind: TrackKind::Video,
+        source: TrackSource::Camera,
+        remote_identity: Some("bob".into()),
+    };
+    room.subscribe_started(remote.clone());
+    room.subscribed(remote);
+    let mut media =
+        RtcStatsSample::new("TR_ping_remote", TrackKind::Video, StreamDirection::Inbound);
+    media.bytes = Some(1_500);
+    room.record_stats(media); // first media: the lk.subscribe span ends ok
+
+    room.emit_custom("ping", vec![Attribute::new("seq", 1i64)]);
+    telemetry.shutdown().await;
+    println!("trace {} — {}", room.trace_id(), telemetry.stats());
+}

livekit-telemetry/README.md

@@ -59,6 +59,24 @@ println!("{}", telemetry.stats()); // drops by reason, uploads, cached batches
 
 Event names, attributes, cadences and the upload policy are defined in [`SPEC.md`](SPEC.md).
 
+## Local testing
+
+Set `LK_TELEMETRY_ENDPOINT` in the process environment to send every upload to an OpenTelemetry
+backend of your own instead of LiveKit Cloud — the test-only override, not part of any platform
+API. A base URL gets the standard OTLP paths (`/v1/logs`, `/v1/traces`).
+
+```sh
+docker run -d --name lk-lgtm -p 3000:3000 -p 4318:4318 grafana/otel-lgtm   # OTLP/HTTP :4318, UI :3000
+LK_TELEMETRY_ENDPOINT=http://localhost:4318 cargo run -p telemetry_ping        # prints the trace id
+```
+
+`telemetry_ping` records a small session (an `lk.connect` span with its checkpoints, an
+`lk.publish`, an `lk.subscribe` ended by first media, a custom event). In the UI
+(http://localhost:3000 → Explore): Loki `{service_name="telemetry_ping"}` for the log records,
+Tempo with the printed trace id for the spans. Add `LK_TELEMETRY_DIR=/tmp/lk-telemetry` to use
+the file cache: stop the container, run once, start it again and run once more to watch the
+cached batches replay. Platform end-to-end tests set the same variable before the SDK starts.
+
 ## Design notes
 
 - **The room decides the destination.** A platform passes only the server URL and the token

livekit-uniffi/Cargo.toml

@@ -16,6 +16,7 @@ livekit-protocol = { workspace = true }
 livekit-common = { workspace = true, features = ["uniffi"] }
 livekit-token = { workspace = true }
 livekit-datatrack = { workspace = true, features = ["uniffi"] }
+livekit-telemetry = { workspace = true, features = ["uniffi", "net"] }
 livekit-net = { workspace = true, features = ["uniffi"] }
 livekit-data-stream = { workspace = true }
 uniffi = { workspace = true, features = ["scaffolding-ffi-buffer-fns", "tokio"] }

livekit-uniffi/src/lib.rs

@@ -21,6 +21,9 @@ pub mod data_stream;
 /// Access token generation and verification from [`livekit-api::access_token`].
 pub mod access_token;
 
+/// Client telemetry core from [`livekit-telemetry`].
+pub mod telemetry;
+
 /// Forward log messages from Rust.
 pub mod log_forward;