How open-telemetry/opentelemetry-android works
Project type and purpose
• This is a multi-module Android SDK (library) project. Its goal is to provide real-user monitoring (RUM) on Android by instrumenting app components (activities, fragments, network, crashes, ANRs, view clicks, slow renders, sessions) and exporting telemetry via the OpenTelemetry Java SDK.
Top-level module breakdown
• android-agent: entry point artifact that auto-loads instrumentation at runtime
• common: shared constants, data models, helper functions
• core: SDK API & implementation (OpenTelemetryRum, builders, span processors, exporters)
• instrumentation/*: a family of feature plugins (activity, fragment, network, crash, ANR, view-click, slowrendering, sessions, etc.)
• services: background support (app lifecycle watcher, network detector, periodic work, visible screen tracker, caching)
• session: session API and publisher for session-scoped telemetry
• demo-app: a sample Android app demonstrating integration
• test-common & buildSrc: supporting test utilities and Gradle conventions
How data flows at runtime
1. At app start, android-agent initializes via a custom Application subclass or byte-buddy agent.
2. Loaded instrumentation modules hook into Android framework callbacks (ActivityLifecycle, FragmentLifecycle, View callbacks, Network interceptors, Crash handlers, ANR detectors, render frame listeners).
3. Each instrumentation module captures events and produces spans or log records via the core OpenTelemetryRum API.
4. The core SDK enriches spans (global attributes, screen attributes, session IDs), then passes them to exporters.
5. Services layer handles persistence (disk buffering), periodic export scheduling, and network state monitoring.
6. Exporters (BufferDelegatingSpanExporter, log/metric exporters) send data to configured back-end endpoints.
7. Session module tracks user sessions and annotates telemetry accordingly.
8. demo-app shows how to add the android-agent dependency, configure RUM, and view sample telemetry.
Architectural patterns and design principles
• Modular “plugin” pattern: each instrumentation feature is a separate sub-module, auto-discovered/loaded by the agent.
• Layered design:
• Instrumentation layer (hooks) → core API/implementation → services (support) → exporters (I/O)
• Separation of concerns: instrumentation modules do only hook & event capture; core does processing; services handle persistence and scheduling.
• Use of ServiceLoader or custom registry in android-agent to load instrumentation without manual wiring.
• Resilience: disk buffering and network detector to handle offline scenarios.
Detail level
• For each instrumentation module, optionally annotate the hook point (e.g., ActivityLifecycleCallbacks, Choreographer frame callback, UncaughtExceptionHandler).
• Session generation and attachment as a separate sub-flow.