Telemetry, Events & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The Telemetry, Events & Logging system provides a unified infrastructure for tracking SDK behavior, auditing AI model performance, and surfacing diagnostic information to both developers and the backend services. The system utilizes a C++ core implementation to ensure cross-platform consistency across Swift, Kotlin, Flutter, React Native, and Web SDKs.
This system manages three distinct data flows: public events for application-level integration, telemetry for centralized analytics, and diagnostic logging for debugging. By utilizing a dual event system, the SDK can distribute Protobuf-encoded payloads to multiple destinations based on bitmask-defined routing.
Event System Architecture
The event system manages the lifecycle of AI capabilities by emitting typed events for model downloads, LLM token generation, STT transcriptions, and general lifecycle changes. The core utilizes a Protobuf IDL schema to generate type-safe bindings for every supported language.
Dual Event Infrastructure
The C++ core implements two event mechanisms to handle internal tracking and public SDK surfaces:
- Legacy Struct-Based System: Emits analytics breadcrumbs through categories and structured data. Engine plugins like LlamaCPP and Sherpa use this to track internal performance metrics.
- Canonical Proto System: Constructs
runanywhere.v1.SDKEventpayloads. These payloads contain a destination bitmask that determines if the event reaches the public SDK stream, the telemetry manager, or the diagnostic logs.
Sources: core/AGENTS.md:162-171, core/src/infrastructure/events/sdk_event_publish.cpp:15-35
Event Distribution Flow
When a component emits an event, the route() function evaluates the bitmask and fans the payload to the appropriate handlers.
The SDK routes events to specific destinations based on the EVENT_DESTINATION bitmask definitions.
Sources: core/src/infrastructure/events/sdk_event_publish.cpp:18-32, idl/sdk_events.proto:11-16
Telemetry Management
The Telemetry Manager collects, buffers, and flushes data to backend services. It operates during "Phase 2" of the SDK initialization process, which occurs asynchronously after the native libraries have loaded and the platform adapter is registered.
Telemetry Lifecycle
- Phase 1 Initialization: The SDK registers the C++ telemetry callbacks via the
CppBridge. - Buffering: Events marked with the
TELEMETRYbitmask are stored in an internal manager. - Phase 2 Flushing: The SDK flushes the buffered telemetry once it establishes network connectivity and authenticates with the backend.
Sources: bindings/kotlin/AGENTS.md:68-81, core/src/infrastructure/telemetry/telemetry_manager.cpp:10-25
Event Types and Payloads
The canonical event envelope, SDKEvent, uses a oneof field to carry specialized data for different AI modalities.
| Event Type | Description |
|---|---|
LLMEvent | Tracks token generation, thinking tokens, and tool calls. |
ModelEvent | Monitors model download progress, loading, and unloading. |
VoiceEvent | Reports speech segments, turn detection, and agent replies. |
ErrorEvent | Carries structured SDKError payloads for diagnostic tracking. |
Sources: idl/sdk_events.proto:35-65, bindings/kotlin/AGENTS.md:129-136
Diagnostic Logging
Logging behavior is controlled via the rac_platform_adapter_t, a flat C struct populated by each platform SDK. The C++ core never calls platform APIs directly; instead, it uses the function pointers in this adapter to output log data.
Platform Adapters
Each SDK implementation maps C++ logs to the native logging utility of the host operating system:
- iOS/macOS: Uses
OSLogwith the subsystemcom.runanywhere.reactnativeor equivalent. - Android: Maps to
android.util.Logclasses. - Kotlin SDK: Registers C++ logging during phase-1 of
RunAnywhere.initialize.
Sources: bindings/react-native/AGENTS.md:139-145, bindings/kotlin/AGENTS.md:70-75, core/AGENTS.md:136-150
Logging Configuration
Developers can configure logging verbosity through public SDK namespaces.
// Example Kotlin Logging Configuration
RunAnywhere.logging.setLevel(SDKLogLevel.DEBUG)
RunAnywhere.logging.setLocalEnabled(true)
Sources: bindings/react-native/AGENTS.md:183-186, bindings/react-native/Docs/Documentation.md:38-45
Thread Safety and Invariants
The Telemetry and Event systems implement specific patterns to prevent deadlocks and data loss:
- Lock-Copy-Dispatch: The event publisher snapshots subscribers under a mutex and then dispatches outside the lock to prevent re-entry deadlocks.
- Meyers Singleton: Global state for the Telemetry Manager and Event Registry uses the Meyers singleton pattern to avoid static initialization order issues.
- Atomic Level-Checks: Logging uses atomic checks on the hot path to avoid mutex overhead during high-frequency inference events.
Sources: core/AGENTS.md:180-192
Summary
The Telemetry, Events & Logging system ensures that all RunAnywhere AI activities are observable and traceable. By standardizing on Protobuf-encoded SDKEvent messages and a centralized C++ routing engine, the project maintains parity across all five platform SDKs. This infrastructure supports both the public-facing EventBus for application logic and the internal TelemetryManager for long-term AI performance optimization.