OpenTelemetry Android

• About
• Getting Started
• Features
• Contributing

About

The repository contains the OpenTelemetry Android Agent, which initializes the OpenTelemetry Java SDK and provides auto-instrumentation of Android apps for real user monitoring (RUM).

While this project isn't 100% Kotlin, it has a "Kotlin-First" policy where usage in Kotlin-based Android apps will be prioritized in terms of API and idioms. More details about this policy can be found here.

Getting Started

If your project's minSdk is lower than 26, then you must enable corelib desugaring. See #73 for more information. Further, you must use AGP 8.3.0+ and set the android.useFullClasspathForDexingTransform property in gradle.properties to true to ensure desugaring runs properly. For the full context for this workaround, please see this issue.

Gradle Setup

To use the Android Agent in your application, you will first need to add a dependency in your application's build.gradle.kts. We publish a bill of materials (BOM) that helps to coordinate versions of the this project's components and the upstream opentelemetry-java-instrumentation and opentelemetry-java dependencies. We recommend using the BOM as a platform dependency, and then omitting explicit version information from all other opentelemetry dependencies:

dependencies {
    //...
    api(platform("io.opentelemetry.android:opentelemetry-android-bom:1.0.0-rc.1-alpha"))
    implementation("io.opentelemetry.android:android-agent") // Version is resolved through the BOM
    //...
}

Agent Initialization

To initialize the Agent, call OpenTelemetryRumInitializer.initialize() in the onCreate() function in your app's Application object, ideally as early as possible after calling super.onCreate().

class MainApplication: Application() {
    var otelRum: OpenTelemetryRum? = null
    
    override fun onCreate() {
        super.onCreate()
        otelRum = initOTel(this)
    }
}

private fun initOTel(context: Context): OpenTelemetryRum? =
    runCatching {
        OpenTelemetryRumInitializer.initialize(
            context = context,
            configuration = {
                httpExport {
                    baseUrl = "http://10.0.2.2:4318"
                    baseHeaders = mapOf("foo" to "bar")
                }
                instrumentations {
                    activity {
                        enabled(true)
                    }
                    fragment {
                        enabled(false)
                    }
                }
                session {
                    backgroundInactivityTimeout = 5.minutes
                    maxLifetime = 1.days
                }
                globalAttributes {
                    Attributes.of(stringKey("demo-version"), "test")
                }
            }
        )
    }.onFailure {
        Log.e("OpenTelemetryRumInitializer", "Initialization failed", it)
    }.getOrNull()

This call will return an OpenTelemetryRum instance with which you can use the Agent and OTel APIs.

Features

In addition to exposing the OTel Java API for manual instrumentation, agent also offers the following features:

• Streamlined initialization and configuration of the Java SDK instance
• Installation and management of bundled instrumentation
• Offline buffering of telemetry via disk persistence
• Redact and change span attributes before export

Instrumentation

The following instrumentation modules are bundled with the Android Agent:

• Activity lifecycle
• ANR detection
• Crash reporting
• Fragment lifecycle
• Network change detection
• Slow/frozen frame render detection
• Startup
• Sessions
• Screen orientation
• View click

There are also other additional instrumentation modules that application developers can include through a gradle dependency. Instrumentations are detected at runtime via the classpath, and are installed automatically.

Additional Documentation

See the following pages for details about the related topics:

• Kotlin-First Policy
• StrictMode Guidance
• Exporter Management

Contributing

For an overview of how to contribute, see the contributing guide in CONTRIBUTING.md.

We are also available in the #otel-android channel in the CNCF Slack. Please join us there for further discussions.

Maintainers

• Cesar Munoz, Elastic
• Jason Plumb, Splunk

For more information about the maintainer role, see the community repository.

Approvers

• Hanson Ho, Embrace
• Jamie Lynch, Embrace
• Manoel Aranda Neto, PostHog

For more information about the Approver role, see the community repository.