# open-telemetry/opentelemetry-android architecture

> Architecture diagram of the GitHub repository open-telemetry/opentelemetry-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-telemetry/opentelemetry-android
- Repository: https://github.com/open-telemetry/opentelemetry-android

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    AF["Android Framework"]:::external

    %% Loader
    androidAgent["android-agent (Loader)"]:::loader
    click androidAgent "https://github.com/open-telemetry/opentelemetry-android/blob/main/android-agent/src/main/kotlin/io/opentelemetry/android/agent/OpenTelemetryRumInitializer.kt"

    %% Instrumentation Modules
    subgraph "Instrumentation Modules"
        activity["ActivityInstrumentation"]:::instrumentation
        click activity "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/activity/src/main/java/io/opentelemetry/android/instrumentation/activity/ActivityLifecycleInstrumentation.kt"
        fragment["FragmentInstrumentation"]:::instrumentation
        click fragment "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/fragment/src/main/java/io/opentelemetry/android/instrumentation/fragment/FragmentLifecycleInstrumentation.kt"
        network["NetworkInstrumentation"]:::instrumentation
        click network "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/network/src/main/java/io/opentelemetry/android/instrumentation/network/NetworkChangeInstrumentation.kt"
        crash["CrashInstrumentation"]:::instrumentation
        click crash "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/crash/src/main/java/io/opentelemetry/android/instrumentation/crash/CrashReporterInstrumentation.java"
        anr["ANRInstrumentation"]:::instrumentation
        click anr "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/anr/src/main/java/io/opentelemetry/android/instrumentation/anr/AnrInstrumentation.java"
        viewClick["ViewClickInstrumentation"]:::instrumentation
        click viewClick "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/view-click/src/main/kotlin/io/opentelemetry/android/instrumentation/view/click/ViewClickInstrumentation.kt"
        slowRendering["SlowRenderingInstrumentation"]:::instrumentation
        click slowRendering "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/slowrendering/src/main/java/io/opentelemetry/android/instrumentation/slowrendering/SlowRenderingInstrumentation.java"
        sessionsInstr["SessionInstrumentation"]:::instrumentation
        click sessionsInstr "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/sessions/src/main/kotlin/io/opentelemetry/android/instrumentation/sessions/SessionInstrumentation.kt"
        startup["StartupInstrumentation"]:::instrumentation
        click startup "https://github.com/open-telemetry/opentelemetry-android/blob/main/instrumentation/startup/src/main/java/io/opentelemetry/android/instrumentation/startup/StartupInstrumentation.kt"
    end

    %% Core SDK
    subgraph "core SDK" 
        coreAPI["API & Impl"]:::core
        click coreAPI "https://github.com/open-telemetry/opentelemetry-android/blob/main/core/src/main/java/io/opentelemetry/android/OpenTelemetryRum.java"
        spanProcessors["Span Processors"]:::core
        click spanProcessors "https://github.com/open-telemetry/opentelemetry-android/blob/main/core/src/main/java/io/opentelemetry/android/ScreenAttributesSpanProcessor.kt"
        exportersCore["Exporters"]:::core
        click exportersCore "https://github.com/open-telemetry/opentelemetry-android/blob/main/core/src/main/java/io/opentelemetry/android/export/BufferDelegatingSpanExporter.kt"
        config["Configuration"]:::core
        click config "https://github.com/open-telemetry/opentelemetry-android/blob/main/core/src/main/java/io/opentelemetry/android/config/OtelRumConfig.java"
    end

    %% Services Layer
    subgraph "Services Layer"
        disk["DiskManager"]:::services
        click disk "https://github.com/open-telemetry/opentelemetry-android/blob/main/services/src/main/java/io/opentelemetry/android/internal/features/persistence/DiskManager.kt"
        registry["Services Registry"]:::services
        click registry "https://github.com/open-telemetry/opentelemetry-android/blob/main/services/src/main/java/io/opentelemetry/android/internal/services/Services.kt"
        appLifecycle["ApplicationStateWatcher"]:::services
        click appLifecycle "https://github.com/open-telemetry/opentelemetry-android/blob/main/services/src/main/java/io/opentelemetry/android/internal/services/applifecycle/ApplicationStateWatcher.kt"
        networkDetector["SimpleNetworkDetector"]:::services
        click networkDetector "https://github.com/open-telemetry/opentelemetry-android/blob/main/services/src/main/java/io/opentelemetry/android/internal/services/network/detector/SimpleNetworkDetector.kt"
        periodicWork["PeriodicWork Scheduler"]:::services
        click periodicWork "https://github.com/open-telemetry/opentelemetry-android/blob/main/services/src/main/java/io/opentelemetry/android/internal/services/periodicwork/PeriodicWork.kt"
        visibleScreen["VisibleScreenTracker"]:::services
        click visibleScreen "https://github.com/open-telemetry/opentelemetry-android/blob/main/services/src/main/java/io/opentelemetry/android/internal/services/visiblescreen/VisibleScreenTracker.kt"
    end

    %% Session Module
    sessionMod["Session Module"]:::services
    click sessionMod "https://github.com/open-telemetry/opentelemetry-android/blob/main/session/src/main/kotlin/io/opentelemetry/android/session/SessionProvider.kt"

    %% Exporter Endpoint
    exporters["Export Pipeline"]:::core
    remoteCollector["Remote Collector/Backend"]:::external

    %% Demo App
    demoApp["demo-app (Sample)"]:::demo
    click demoApp "https://github.com/open-telemetry/opentelemetry-android/blob/main/demo-app/src/main/java/io/opentelemetry/android/demo/OtelDemoApplication.kt"

    %% Data Flow
    AF -->|"init"| androidAgent
    AF -->|"hooks"| activity
    AF -->|"hooks"| fragment
    AF -->|"hooks"| network
    AF -->|"hooks"| crash
    AF -->|"hooks"| anr
    AF -->|"hooks"| viewClick
    AF -->|"hooks"| slowRendering
    AF -->|"hooks"| sessionsInstr
    AF -->|"hooks"| startup

    activity -->|"capture"| coreAPI
    fragment -->|"capture"| coreAPI
    network -->|"capture"| coreAPI
    crash -->|"capture"| coreAPI
    anr -->|"capture"| coreAPI
    viewClick -->|"capture"| coreAPI
    slowRendering -->|"capture"| coreAPI
    sessionsInstr -->|"capture"| coreAPI
    startup -->|"capture"| coreAPI

    coreAPI -->|enrich| spanProcessors
    spanProcessors -->|"to exporters"| exportersCore
    exportersCore -->|"buffer"| disk
    disk -->|"schedule"| periodicWork
    periodicWork -->|"trigger export"| exporters
    networkDetector -->|"network state"| periodicWork
    appLifecycle -->|"app state"| disk
    visibleScreen -->|"screen info"| coreAPI
    sessionMod -->|"attach session"| spanProcessors

    exporters -->|"export"| remoteCollector

    demoApp -->|"uses"| androidAgent

    %% Styles
    classDef instrumentation fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef services fill:#FFA500,stroke:#000,stroke-width:1px
    classDef loader fill:#DA70D6,stroke:#000,stroke-width:1px
    classDef demo fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
