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.

Important

We are currently seeking additional contributors! See Contributing for details.

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

We are currently resource constrained and are actively seeking new contributors interested in working towards approver / maintainer roles. In addition to the documentation for approver / maintainer roles and the contributing guide, here are some additional notes on engaging:

• Pull request reviews are equally or more helpful than code contributions. Comments and approvals are valuable with or without a formal project role. They're also a great forcing function to explore a fairly complex codebase.
• Attending the Android: SDK + Automatic Instrumentation Special Interest Group (SIG) is a great way to get to know community members and learn about project priorities.
• Issues labeled help wanted are project priorities. Code contributions (or pull request reviews when a PR is linked) for these issues are particularly important.
• Triaging / responding to new issues and discussions is a great way to engage with the project.
• We are available in the #otel-android channel in the CNCF Slack. Please join us there for further discussions.

Thanks to all of our contributors!

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.