Android

OpenTelemetry Android забезпечує спостережуваність для нативних Android-застосунків. Створений на основі екосистеми OpenTelemetry Java, він пропонує автоматичну інструментацію, моніторинг реальних користувачів (RUM) і можливості ручного інструментування, адаптовані для мобільних середовищ.

Функції

OpenTelemetry Android включає такі ключові можливості:

• Автоматичне інструментування: вбудовані модулі для поширених шаблонів Android:
  • життєвий цикл Activity
  • життєвий цикл Fragment
  • виявлення ANR (Application Not Responding)
  • звітність про збої
  • виявлення змін мережі
  • виявлення повільного/замороженого рендерингу
  • час запуску
  • орієнтація екрана
  • події кліків на переглядах
• Управління сесіями: відстежуйте сесії користувачів із налаштованими часовими проміжками неактивності та максимальним часом сесії.
• Офлайн-буферизація: постійне зберігання на диску для буферизації даних телеметрії, коли пристрій не в мережі, що забезпечує відсутність втрати даних під час перебоїв у мережі.
• Редагування атрибутів: можливість редагувати або змінювати атрибути діапазонів перед експортом для забезпечення відповідності вимогам конфіденційності.

Початок роботи

Передумови

• Android SDK 21 (Lollipop) або новішої версії
• Проєкт Gradle, що використовує Kotlin (також може бути Java)

Налаштування Gradle

Додайте залежність OpenTelemetry Android Agent до файлу build.gradle.kts вашого застосунку. Використовуйте Bill of Materials (BOM) для керування версіями:

dependencies {
    implementation(platform("io.opentelemetry.android:opentelemetry-android-bom:1.2.0"))
    implementation("io.opentelemetry.android:android-agent")
}

Ініціалізація агента

Ініціалізуйте OpenTelemetry в методі onCreate() вашого класу Application:

class MyApplication : Application() {
    lateinit var openTelemetryRum: OpenTelemetryRum

    override fun onCreate() {
        super.onCreate()
        openTelemetryRum = initializeOpenTelemetry(this)
    }
}

private fun initializeOpenTelemetry(context: Context): OpenTelemetryRum =
    OpenTelemetryRumInitializer.initialize(
        context = context,
        configuration = {
            httpExport {
                baseUrl = "https://your-collector-endpoint:4318"
                baseHeaders = mapOf("Authorization" to "Bearer <token>")
            }
            instrumentations {
                // Усі інструментації типово ввімкнено.
                // Вимкніть певні за потреби:
                slowRendering { enabled(false) }
            }
            session {
                backgroundInactivityTimeout = 15.minutes
                maxLifetime = 4.days
            }
        }
    )

Конфігурація

OpenTelemetry Android використовує DSL Kotlin для конфігурації, як показано в прикладі ініціалізації вище. У наступній таблиці описано доступні параметри конфігурації:

Параметри конфігурації

Автоматична інструментація

OpenTelemetry Android надає модулі автоматичної інструментації, які можна ввімкнути або вимкнути. Для отримання детальної інформації про кожну інструментацію, включно з вихідними даними телеметрії та параметрами конфігурації, див. відповідну документацію.

Життєвий цикл Activity

Автоматично фіксує відрізки для подій життєвого циклу Activity (onCreate, onStart, onResume, onPause, onStop, onDestroy). Див. інструментацію Activity.

Життєвий цикл Fragment

Фіксує діапазони для подій життєвого циклу Fragment, що корисно для відстеження навігації в архітектурах з одним Activity. Див. інструментацію Fragment.

Виявлення ANR

Виявляє умови Application Not Responding (ANR) і повідомляє про них як діапазони, допомагаючи виявити проблеми, пов’язані з блокуванням основного потоку. Див. інструментацію ANR.

Звітність про збої

Фіксує необроблені винятки та повідомляє про них зі стеками трейсів, що дозволяє корелювати збої з сесіями користувачів і трасуваннями. Див. інструментацію збоїв.

Моніторинг мережі

Виявляє зміни стану мережі та додає інформацію про підключення до даних телеметрії, що допомагає зрозуміти умови мережі під час виникнення помилок. Див. інструментацію мережі.

Повільний і заморожений рендеринг

Відстежує продуктивність рендерингу кадрів і повідомляє про повільний рендеринг (>16 мс) і заморожені кадри (>700 мс), щоб допомогти виявити вузькі місця в продуктивності інтерфейсу. Див. інструментацію повільного рендерингу.

Ручна інструментація

Отримайте доступ до API OpenTelemetry для ручної інструментації:

val openTelemetry = openTelemetryRum.openTelemetry
val tracer = openTelemetry.getTracer("com.example.myapp")

val span = tracer.spanBuilder("my-operation")
    .startSpan()

try {
    span.makeCurrent().use {
        // Ваш код тут
    }
} finally {
    span.end()
}

Інструментація HTTP-клієнта

Інструментуйте клієнти OkHttp для відстеження мережевих запитів:

val okHttpClient = OkHttpTelemetry.builder(openTelemetryRum.openTelemetry)
    .build()
    .newCallFactory(OkHttpClient.Builder().build())

Поради

Обмеження ресурсів

Мобільні пристрої мають обмежені ресурси. Розгляньте ці поради:

• Пакетний експорт: Пакетна обробка типово увімкнена, щоб зменшити кількість мережевих викликів і споживання енергії.
• Семплювання: Реалізуйте стратегії семплювання, щоб зменшити обсяг даних, зберігаючи при цьому репрезентативні дані телеметрії.
• Офлайн-буферизація: Постійне зберігання на диску типово увімкнено, щоб обробляти ненадійні з’єднання.

Питання конфіденційності

• Використовуйте редагування атрибутів, щоб видалити конфіденційні дані перед експортом.
• Розгляньте вимоги щодо згоди користувачів на збір даних телеметрії.
• Уникайте захоплення персонально ідентифікованої інформації (PII) в іменах діапазонів або атрибутах.

Тестування

Під час тестування з емулятором використовуйте 10.0.2.2 як адресу хосту, щоб отримати доступ до вашого локального колектора:

httpExport {
    baseUrl = "http://10.0.2.2:4318"
}

Ресурси

• GitHub OpenTelemetry Android
• Документація OpenTelemetry Java
• Семантичні домовленості Android
• Прикладні застосунків

Допомога та відгуки

Якщо у вас виникли запитання, зверніться через GitHub Issues або канал #otel-android у CNCF Slack.