Connecting a native Android app with OTel
A native Android app (Kotlin or Java) connects with OpenTelemetry's Android agent. Calls link to your backend with traceparent, and the result shows under APM → End users. Shared values: overview.
Version table
| Part | Package | Version |
|---|---|---|
| Android agent | io.opentelemetry.android:opentelemetry-android-bom |
1.8.1-alpha |
io.opentelemetry.android:android-agent (from the BOM) |
1.8.1 | |
| OkHttp calls | io.opentelemetry.android.instrumentation:okhttp3-library, okhttp3-agent (from the BOM) |
1.8.1-alpha |
Gradle plugin net.bytebuddy.byte-buddy-gradle-plugin |
1.18.15 | |
| App | minSdk |
23 and later (below 26: core library desugaring on) |
Find your version: grep -rn minSdk /srv/app/app/build.gradle.kts. OTel still marks the Android agent as alpha. We wrote this guide from the agent's 1.8.1 documentation and source and did not run it on a device.
Verified: 2026-11-09. Source: opentelemetry-android README, OkHttp instrumentation.
What you need
- Spitfire address
https://<spitfire>(HTTPS: Android refuses plain HTTP); service name<service-name>, version<service-version>, environment<environment> - The project folder (here
/srv/app, wheresettings.gradle.ktsis), the app moduleappand its package (herecom.example.app, thepackageline ofMainActivity.kt)
Android
Create the key: Admin → Integrations → Add integration → Browser and app key, leave Allowed origins empty; copy
sfrum_…(APM).In
/srv/app/app/build.gradle.kts, add the plugin toplugins { }and the packages todependencies { }:
plugins {
id("net.bytebuddy.byte-buddy-gradle-plugin") version "1.18.15"
}
dependencies {
implementation(platform("io.opentelemetry.android:opentelemetry-android-bom:1.8.1-alpha"))
implementation("io.opentelemetry.android:android-agent")
implementation("io.opentelemetry.android.instrumentation:okhttp3-library")
byteBuddy("io.opentelemetry.android.instrumentation:okhttp3-agent")
}- Create
/srv/app/app/src/main/java/com/example/app/OtelApp.ktand paste:
// IS_OTEL_ENABLED=true: OTel on; any other value: off.
package com.example.app
import android.app.Application
import android.util.Log
import io.opentelemetry.android.OpenTelemetryRum
import io.opentelemetry.android.agent.OpenTelemetryRumInitializer
import kotlin.time.Duration.Companion.hours
import kotlin.time.Duration.Companion.minutes
private const val IS_OTEL_ENABLED = "true"
private const val OTEL_ENDPOINT = "https://<spitfire>/otlp"
private const val OTEL_KEY = "sfrum_…"
class OtelApp : Application() {
var otelRum: OpenTelemetryRum? = null
override fun onCreate() {
super.onCreate()
if (IS_OTEL_ENABLED != "true") return
otelRum = runCatching {
OpenTelemetryRumInitializer.initialize(context = this) {
httpExport {
baseUrl = OTEL_ENDPOINT
baseHeaders = mapOf("Authorization" to "Bearer $OTEL_KEY")
}
resource {
put("service.name", "<service-name>")
put("service.version", "<service-version>")
put("deployment.environment.name", "<environment>")
put("spitfire.eum.platform", "android")
}
session {
backgroundInactivityTimeout = 30.minutes
maxLifetime = 4.hours
}
disableMetrics()
}
}.onFailure { Log.e("OtelApp", "OpenTelemetry did not start", it) }.getOrNull()
}
}- In
/srv/app/app/src/main/AndroidManifest.xml, give<application>the class:
<application
android:name=".OtelApp"- Build the release:
cd /srv/app && ./gradlew :app:assembleReleaseWhat it sends
The app start arrives as an AppStart span (start.type: cold, warm, hot), screens as activity spans with app.screen.name. OkHttp calls (and Retrofit, which uses OkHttp) are client spans carrying traceparent. A crash lands as an app.crash log event, an ANR as device.anr. Everything carries a session.id, renewed after 30 minutes in the background or 4 hours in total.
Readable crash stacks (R8 / ProGuard)
With minifyEnabled true, crash stacks name shrunk classes (a.b.a(SourceFile:2)). After each release build upload app/build/outputs/mapping/release/mapping.txt under the service.name and service.version the app sends (Symbol files). Our advice: make this the last step of the release build in CI; by hand, versions get skipped and their crashes stay unreadable.
Verify
- Spitfire takes the key from an app (no
Origin):
curl -s -o /dev/null -w '%{http_code}' -X POST https://<spitfire>/otlp/v1/logs -H 'Authorization: Bearer sfrum_…' -H 'Content-Type: application/json' -d '{}' | grep -q '^200$' && echo OK- The app starts OpenTelemetry:
grep -q 'android:name=".OtelApp"' /srv/app/app/src/main/AndroidManifest.xml && grep -q 'IS_OTEL_ENABLED = "true"' /srv/app/app/src/main/java/com/example/app/OtelApp.kt && echo OK- Open the app on a phone, then APM → End users: the app
<service-name>shows an app start within a minute.
Turning off and removing
- Turn off: in
OtelApp.ktwriteprivate const val IS_OTEL_ENABLED = "false", then build again. - Remove: delete
OtelApp.kt, theandroid:name=".OtelApp"line, and the lines step 2 added.
Common problems
| Symptom | Fix |
|---|---|
minSdk 23 error |
Raise minSdk to 23; below 26 turn on core library desugaring |
Logcat: OpenTelemetry did not start |
The message under it says why |
401 |
The key is sfrum_… and enabled; OTEL_KEY holds it without Bearer |
429 |
Raise the key's Exports per minute |
| Calls are not linked to a backend trace | The calls must go through OkHttp (or Retrofit); check the Byte Buddy plugin is in plugins { } |
| No data from the phone | The phone must reach https://<spitfire> |