feat(telemetry): add the crate with its event model and OTLP encoding

.changeset/add-livekit-telemetry-crate.md

@@ -0,0 +1,5 @@
+---
+livekit-telemetry: minor
+---
+
+Add `livekit-telemetry`, the internal client telemetry core shared by the LiveKit client SDKs.

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "livekit-ffi",
     "livekit-uniffi",
     "livekit-datatrack",
+    "livekit-telemetry",
     "livekit-token",
     "livekit-token-source",
     "livekit-ffi-node-bindings",
@@ -60,6 +61,7 @@ livekit-api = { version = "0.8.1", path = "livekit-api" }
 livekit-capture = { version = "0.1.3", path = "livekit-capture" }
 livekit-ffi = { version = "0.12.81", path = "livekit-ffi" }
 livekit-datatrack = { version = "0.2.1", path = "livekit-datatrack" }
+livekit-telemetry = { version = "0.1.0", path = "livekit-telemetry" }
 livekit-signaling = { version = "0.1.4", path = "livekit-signaling" }
 livekit-token = { version = "0.2.1", path = "livekit-token" }
 livekit-token-source = { version = "0.1.3", path = "livekit-token-source" }

knope.toml

@@ -178,6 +178,14 @@ versioned_files = [
 ]
 changelog = "livekit-datatrack/CHANGELOG.md"
 
+[packages.livekit-telemetry]
+versioned_files = [
+  "livekit-telemetry/Cargo.toml",
+  "Cargo.lock",
+  { path = "Cargo.toml", dependency = "livekit-telemetry" },
+]
+changelog = "livekit-telemetry/CHANGELOG.md"
+
 [packages.livekit-common]
 versioned_files = [
   "livekit-common/Cargo.toml",

livekit-telemetry/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

livekit-telemetry/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "livekit-telemetry"
+description = "Client telemetry core for LiveKit: buffers events on-device and exports them as OTLP"
+version = "0.1.0"
+readme = "README.md"
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+[dependencies]
+log = { workspace = true }
+prost = { workspace = true }
+rand = { workspace = true }
+# OTLP message types only (`gen-tonic-messages` = prost structs, no tonic). Same prost as
+# livekit-protocol so a single prost is linked.
+opentelemetry-proto = { version = "0.32", default-features = false, features = ["logs", "trace", "gen-tonic-messages"] }
+uniffi = { workspace = true, features = ["scaffolding-ffi-buffer-fns"], optional = true }
+
+[features]
+uniffi = ["dep:uniffi"]
+
+# How CI checks this crate's features, read by
+# `.github/workflows/feature-combinations-curated.yml` via `cargo metadata`.
+[package.metadata.feature-combinations]
+mode = "powerset"

livekit-telemetry/README.md

@@ -0,0 +1,19 @@
+# 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](https://opentelemetry.io/docs/specs/otlp/) protobuf logs and traces,
+  using the `opentelemetry-proto` message types only (no gRPC stack).
+
+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`](SPEC.md). It is the contract
+for the whole crate, including the parts not implemented yet.