DOCSEARCHbyAlgolia
Submit Docs

OpenTelemetry Android

repository·main·Indexed 43 days ago

https://github.com/open-telemetry/opentelemetry-android

Provides an Android Agent and libraries for automating the initialization of the OpenTelemetry Java SDK and providing auto-instrumentation for Real User Monitoring (RUM). Includes support for Activity lifecycle tracking, Android Log transformation, ANR (Application Not Responding) detection, Compose Click and Navigation instrumentation, and Kotlin coroutine context propagation.

Tokens
28.6K
Snippets
81
Records
135
Agent score
55%

What's inside OpenTelemetry Android

  5. Limitations of Native Crash Snapshot Version 1

    main

    Developers using Version 1 should be aware of the following constraints:

    • Unwinding: Does not interpret DWARF or compact unwind metadata. It relies on frame pointers. If optimized builds omit frame pointers, recovery may only contain the crashing frame and a link-register candidate.
    • Capacity: Limited to 128 executable segments and 4 KiB of captured stack memory.
    • Dynamic Loading: Modules loaded after the initial module table preparation (during handler installation) are not captured.
    • Concurrency: Only one pending crash can be handled at a time. While recovery is pending, new native crashes in that process are not captured because the fixed destination files would be overwritten.

  6. Understand the Kotlin-First Policy

    main

    The OpenTelemetry Android Agent is designed with a Kotlin-First approach. The project prioritizes Kotlin language idioms and structures to provide a native experience for modern Android developers.

    Key implications for users:

    • The primary target use case is apps written in Kotlin.
    • Both public APIs and internal code are being progressively converted to Kotlin.
    • API design decisions prioritize Kotlin ergonomics over Java consistency.

  8. How Native Crash Instrumentation works

    main

    Native crash instrumentation records fatal native signals and replays the persisted crash as an app.crash event during the application's next startup.

    Signal Handling

    The instrumentation uses a signal handler to record the following signals:

    • SIGILL
    • SIGTRAP
    • SIGABRT
    • SIGBUS
    • SIGFPE
    • SIGSEGV
    • SIGSYS

    When a signal is caught, the handler records the event, restores the previous action for that signal, and re-delivers it through the kernel. This ensures that the previous handler's signal mask, flags, and fault details are preserved without interfering with other signal registrations. Signals that were already ignored remain ignored.

    Telemetry Data

    The replayed app.crash event uses the original crash timestamp and includes the following attributes:

    • exception.type
    • exception.message
    • exception.stacktrace (if a matching snapshot contains recoverable frames)
    • session.id (when available)
    • service.version (when available)
    • os.name
    • os.version

    Note that OS and app fields are read from the persisted crash-time context to ensure the event describes the process that actually crashed.

  9. Understand OpenTelemetry Android versioning and releases

    main

    OpenTelemetry Android follows Semantic Versioning. All modules in the repository are released together using the same version number.

    Until version 1.0.0 is reached, releases typically increment the minor version. Patch releases are rare and reserved for critical issues.

    Because this library depends on opentelemetry-java, opentelemetry-java-instrumentation, and opentelemetry-java-contrib, its release schedule is tied to theirs, typically following a monthly cycle.

  11. How Power Save Mode Instrumentation works

    main

    This instrumentation monitors the Android system for power management changes. Instead of polling the system state, it listens for PowerManager.ACTION_POWER_SAVE_MODE_CHANGED broadcasts. When a broadcast is received, it reads the current state using PowerManager.isPowerSaveMode() and emits a device.power_save_mode.change event.

    Note: This instrumentation is currently in development status and is not enabled by default.

  12. Understand coroutine instrumentation limitations and scope

    main

    The coroutine instrumentation has specific boundaries regarding what it covers and how it behaves:

    Supported API

    • CoroutineScope.launch (both default-parameter and explicit forms).

    Explicit Exclusions

    • async
    • withContext
    • runBlocking
    • Flow
    • All other coroutine builders.
    • External dependencies and sibling library modules.

    Transformation Scope

    Only classes local to the module applying the ByteBuddy plugin are transformed. External library and dependency classes remain unchanged.

    Context Precedence and Flow

    • Precedence: If CoroutineScope.launch is called with an explicit, non-root OpenTelemetry coroutine context element already present in the supplied CoroutineContext, the user-supplied context takes precedence and automatic capture is skipped.
    • Direction: Propagation is one-directional. Context flows from the calling thread into the coroutine at launch time.
    • Boundaries: Work dispatched from within a coroutine to a plain Java Executor or thread starts with a fresh context (no automatic propagation).