SpitfireLoad Testing & APMWhat's new

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, where settings.gradle.kts is), the app module app and its package (here com.example.app, the package line of MainActivity.kt)

Android

  1. Create the key: Admin → Integrations → Add integration → Browser and app key, leave Allowed origins empty; copy sfrum_… (APM).

  2. In /srv/app/app/build.gradle.kts, add the plugin to plugins { } and the packages to dependencies { }:

kotlin
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")
}
  1. Create /srv/app/app/src/main/java/com/example/app/OtelApp.kt and paste:
kotlin
// 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()
    }
}
  1. In /srv/app/app/src/main/AndroidManifest.xml, give <application> the class:
xml
<application
    android:name=".OtelApp"
  1. Build the release:
bash
cd /srv/app && ./gradlew :app:assembleRelease

What 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

  1. Spitfire takes the key from an app (no Origin):
bash
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
  1. The app starts OpenTelemetry:
bash
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
  1. 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

  1. Turn off: in OtelApp.kt write private const val IS_OTEL_ENABLED = "false", then build again.
  2. Remove: delete OtelApp.kt, the android: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>