SpitfireYük Testi ve APMYenilikler

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.kts dosyasının olduğu yer), uygulama modülü app ve paketi (burada com.example.app, MainActivity.kt dosyasındaki package satırı)

Android

  1. 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).

  2. /srv/app/app/build.gradle.kts dosyasında plugin'i plugins { } içine, paketleri dependencies { } içine ekleyin:

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. /srv/app/app/src/main/java/com/example/app/OtelApp.kt dosyasını oluşturup yapıştırın:
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. /srv/app/app/src/main/AndroidManifest.xml dosyasında <application> etiketine sınıfı verin:
xml
<application
    android:name=".OtelApp"
  1. Release build alın:
bash
cd /srv/app && ./gradlew :app:assembleRelease

Ne 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

  1. Spitfire anahtarı bir uygulamadan (Origin olmadan) kabul ediyor:
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. Uygulama OpenTelemetry'yi başlatıyor:
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. 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

  1. Kapatma: OtelApp.kt dosyasında private const val IS_OTEL_ENABLED = "false" yazın, yeniden build alın.
  2. Kaldırma: OtelApp.kt dosyası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

İlgili sayfalar