https://github.com/open-telemetry/opentelemetry-android
OpenTelemetry Tooling for Android
https://github.com/open-telemetry/opentelemetry-android
Last synced: 5 months ago
JSON representation
OpenTelemetry Tooling for Android
- Host: GitHub
- URL: https://github.com/open-telemetry/opentelemetry-android
- Owner: open-telemetry
- License: apache-2.0
- Created: 2023-07-21T16:31:27.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-14T04:22:12.000Z (about 1 year ago)
- Last Synced: 2025-05-15T00:11:56.332Z (about 1 year ago)
- Language: Java
- Size: 4.75 MB
- Stars: 203
- Watchers: 26
- Forks: 64
- Open Issues: 88
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 
OpenTelemetry Android
[![Continuous Build][ci-image]][ci-url]
[![Maven Central][maven-image]][maven-url]
[](https://scorecard.dev/viewer/?uri=github.com/open-telemetry/opentelemetry-android)
[](VERSIONING.md)
* [About](#about)
* [Getting Started](#getting-started)
* [Features](#features)
* [Contributing](#contributing)
# About
The repository contains the `OpenTelemetry Android Agent`, which initializes the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) 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](./docs/KOTLIN_FIRST.md).
> [!IMPORTANT]
> We are currently seeking additional contributors! See [Contributing](#contributing) for details.
# Getting Started
> If your project's minSdk is lower than 26, then you must enable
> [corelib desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring).
> See [#73](https://github.com/open-telemetry/opentelemetry-android/issues/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](https://issuetracker.google.com/issues/230454566#comment18).
## 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:
```kotlin
dependencies {
//...
api(platform("io.opentelemetry.android:opentelemetry-android-bom:1.1.0-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()`.
```kotlin
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](./instrumentation/activity/)
* [ANR detection](./instrumentation/anr/)
* [Crash reporting](./instrumentation/crash/)
* [Fragment lifecycle](./instrumentation/fragment)
* [Network change detection](./instrumentation/network/)
* [Slow/frozen frame render detection](./instrumentation/slowrendering)
* [Startup](./instrumentation/startup)
* [Sessions](./instrumentation/sessions)
* [Screen orientation](./instrumentation/screen-orientation)
* [View click](./instrumentation/view-click/)
There are also other
[additional instrumentation modules](https://github.com/open-telemetry/opentelemetry-android/tree/main/instrumentation)
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](./docs/KOTLIN_FIRST.md)
- [StrictMode Guidance](./docs/STRICTMODE.md)
- [Exporter Management](./docs/EXPORTER_CHAIN.md)
# Contributing
We are currently resource constrained and are actively seeking new contributors interested in working towards [approver](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver) / [maintainer](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer) roles.
In addition to the documentation for approver / maintainer roles and the [contributing](./CONTRIBUTING.md) guide, here are some additional notes on engaging:
- [Pull request](https://github.com/open-telemetry/opentelemetry-android/pulls) 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](https://github.com/open-telemetry/community?tab=readme-ov-file#implementation-sigs) Special Interest Group (SIG) is a great way to get to know community members and learn about project priorities.
- Issues labeled [help wanted](https://github.com/open-telemetry/opentelemetry-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) 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](https://cloud-native.slack.com/archives/C05J0T9K27Q) channel in the [CNCF Slack](https://slack.cncf.io/). Please join us there for further discussions.
### Thanks to all of our contributors!
## Maintainers
- [Cesar Munoz](https://github.com/likethesalad), Elastic
- [Jason Plumb](https://github.com/breedx-splk), Splunk
For more information about the maintainer role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer).
## Approvers
- [Hanson Ho](https://github.com/bidetofevil), Embrace
- [Jamie Lynch](https://github.com/fractalwrench), Embrace
- [Manoel Aranda Neto](https://github.com/marandaneto), PostHog
For more information about the Approver role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver).
[ci-image]: https://github.com/open-telemetry/opentelemetry-android/actions/workflows/build.yaml/badge.svg
[ci-url]: https://github.com/open-telemetry/opentelemetry-android/actions?query=workflow%3Abuild+branch%3Amain
[maven-image]: https://img.shields.io/maven-central/v/io.opentelemetry.android/android-agent.svg
[maven-url]: https://central.sonatype.com/artifact/io.opentelemetry.android/android-agent