Native Android uygulamasını OTel ile bağlamak
Native Android uygulaması (Kotlin ya da Java) OpenTelemetry'nin Android agent'ı ile bağlanır. Çağrılar backend'e traceparent ile bağlanır, sonuç APM → Son kullanıcı sayfasında görünür. Ortak değerler: genel bakış.
Sürüm tablosu
| Parça | Paket | Sürüm |
|---|---|---|
| Android agent | io.opentelemetry.android:opentelemetry-android-bom |
1.8.1-alpha |
io.opentelemetry.android:android-agent (BOM'dan) |
1.8.1 | |
| OkHttp çağrıları | io.opentelemetry.android.instrumentation:okhttp3-library, okhttp3-agent (BOM'dan) |
1.8.1-alpha |
Gradle plugin net.bytebuddy.byte-buddy-gradle-plugin |
1.18.15 | |
| Uygulama | minSdk |
23 ve sonrası (26 altında core library desugaring açık) |
Sürümünüzü bulun: grep -rn minSdk /srv/app/app/build.gradle.kts. OTel, Android agent'ını hâlâ alpha sayıyor. Rehberi agent'ın 1.8.1 dokümanına ve kaynak koduna göre yazdık, gerçek cihazda çalıştırmadık.
Doğrulandı: 2026-11-09. Kaynak: opentelemetry-android README, OkHttp instrumentation.
Gerekenler
- Spitfire adresi
https://<spitfire>(HTTPS: Android düz HTTP'yi reddeder); servis adı<service-name>, sürüm<service-version>, ortam<environment> - Proje klasörü (burada
/srv/app,settings.gradle.ktsdosyasının olduğu yer), uygulama modülüappve paketi (buradacom.example.app,MainActivity.ktdosyasındakipackagesatırı)
Android
Anahtarı oluşturun: Yönetim → Entegrasyonlar → Entegrasyon ekle → Tarayıcı ve uygulama anahtarı, İzin verilen kökenler boş kalsın;
sfrum_…anahtarını kopyalayın (APM)./srv/app/app/build.gradle.ktsdosyasında plugin'iplugins { }içine, paketleridependencies { }içine ekleyin:
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")
}/srv/app/app/src/main/java/com/example/app/OtelApp.ktdosyasını oluşturup yapıştırın:
// 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()
}
}/srv/app/app/src/main/AndroidManifest.xmldosyasında<application>etiketine sınıfı verin:
<application
android:name=".OtelApp"- Release build alın:
cd /srv/app && ./gradlew :app:assembleReleaseNe gönderir
Uygulama açılışı AppStart span'i olarak gelir (start.type: cold, warm, hot), ekranlar app.screen.name taşıyan activity span'leri olarak. OkHttp (ve onu kullanan Retrofit) çağrıları traceparent taşıyan client span'leridir. Crash app.crash, ANR device.anr log event'i olarak düşer. Her şeyde bir session.id vardır; arka planda 30 dakika ya da toplam 4 saat sonra yenilenir.
Okunur crash stack'i (R8 / ProGuard)
minifyEnabled true iken crash stack'leri küçültülmüş sınıfları adlandırır (a.b.a(SourceFile:2)). Her release build'inden sonra app/build/outputs/mapping/release/mapping.txt dosyasını uygulamanın gönderdiği service.name ve service.version ile yükleyin (Sembol dosyaları). Önerimiz: bunu CI'da release build'inin son adımı yapın; elle yüklemede sürüm atlanır ve o sürümün crash'leri okunmaz kalır.
Doğrulama
- Spitfire anahtarı bir uygulamadan (
Originolmadan) kabul ediyor:
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- Uygulama OpenTelemetry'yi başlatıyor:
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- Uygulamayı telefonda açın, sonra APM → Son kullanıcı:
<service-name>uygulaması bir dakika içinde bir açılış gösterir.
Kapatma ve kaldırma
- Kapatma:
OtelApp.ktdosyasındaprivate const val IS_OTEL_ENABLED = "false"yazın, yeniden build alın. - Kaldırma:
OtelApp.ktdosyasını,android:name=".OtelApp"satırını ve adım 2'de eklenen satırları silin.
Sık karşılaşılan sorunlar
| Belirti | Çözüm |
|---|---|
minSdk 23 hatası |
minSdk değerini 23 yapın; 26 altında core library desugaring'i açın |
Logcat: OpenTelemetry did not start |
Altındaki mesaj nedenini söyler |
401 |
Anahtar sfrum_… olmalı ve açık olmalı; OTEL_KEY onu Bearer olmadan tutar |
429 |
Anahtarın Dakikada gönderim değerini artırın |
| Çağrılar backend trace'ine bağlanmıyor | Çağrılar OkHttp (ya da Retrofit) ile gitmeli; Byte Buddy plugin'i plugins { } içinde olmalı |
| Telefondan veri gelmiyor | Telefon https://<spitfire> adresine ulaşabilmeli |