Спрятать

Кастомные семплы

Кастомные семплы – инструмент для загрузки, хранения и анализа уникальных пользовательских данных, связанных с работой вашего приложения. Фича позволяет прикреплять к ошибкам или событиям скриншоты, логи, дампы памяти и другие файлы, которые разработчик считает важными для диагностики, что особенно актуально при диагностике сложных сбоев, которые невозможно воспроизвести стандартными средствами.

В этой статье описано подключение и использование фичи в вашем проекте. Подробнее о функционале раздела «Кастомные семплы» читайте здесь.

Подключение зависимостей к проекту

В вашем <project>/<app-module>/build.gradle.kts:

dependencies {
    implementation(platform("ru.ok.tracer:tracer-platform:1.4.0"))
    implementation("ru.ok.tracer:tracer-user-sample")
}

или

dependencies {
    implementation("ru.ok.tracer:tracer-user-sample:1.4.0")
}

Более подробное описание зависимостей на странице Быстрый старт

Инициализация модуля

Модуль инициализируется автоматически при запуске приложения и не требует дополнительной настройки со стороны разработчика.

Возможности UserSampleUpload

UserSampleUpload предоставляет функцию для загрузки пользовательских файлов (семплов) в сервис для последующего анализа при помощи метода sample():

Параметр	Тип	Описание
`sampleFile`	`File`	Файл, который необходимо загрузить (например, лог, дамп памяти, скриншот и т.д.). Максимальный размер файла для загрузки — 100 МБ.
`tag`	`String`	Тег для идентификации или группировки семпла (например, разный тип контента или сценариев).
`attr1`	`Long?`	Дополнительный числовой атрибут, который можно передать вместе с семплом.
`attr2`	`Long?`	Второй дополнительный числовой атрибут.

Пример использования:

В вашем Application.kt

class MyApplication {
    fun someFunc() {
        // ... ваш код (н-р, загрузка ленты)
        val screenshotFile = File(context.cacheDir, "ui-error-screenshot.png")
        // ... код для создания и сохранения скриншота ...

        // Сохраняем кастомные логи в файл
        val logsFile = File(context.cacheDir, "ui-error-logs.txt")
        logsFile.writeText(collectCustomLogs()) // Ваша логика сбора логов

        // Загружаем файл в сервис для дальнейшего анализа
        UserSampleUpload.sample(
            sampleFile = screenshotFile,
            tag = "ui_error_screenshot",
            attr1 = System.currentTimeMillis(), // Время создания скриншота
            attr2 = userId                      // Идентификатор пользователя, если нужно
        )

        // Загружаем файл с логами в сервис для дальнейшего анализа
        UserSampleUpload.sample(
            sampleFile = logsFile,
            tag = "ui_error_logs",
            attr1 = System.currentTimeMillis(), // Время создания логов
            attr2 = userId                      // Идентификатор пользователя, если нужно
        )
    }
}

Прикрепление семплов к событиям

Метод UserSampleUpload.attachment() работает аналогично sample(), но возвращает объект AttachmentId — идентификатор загруженного файла. Этот идентификатор можно передать в метод TracerCrashReport.report() (см. Crash и ANR), чтобы прикрепить файл к событию NON_FATAL. Это позволяет связать ошибку с дополнительными данными (скриншот, логи, дамп памяти и т.д.), что упрощает диагностику сложных сбоев.

Метод принимает те же параметры, что и sample():

Параметр	Тип	Описание
`sampleFile`	`File`	Файл, который необходимо загрузить (например, лог, дамп памяти, скриншот и т.д.). Максимальный размер файла для загрузки — 100 МБ.
`tag`	`String`	Тег для идентификации или группировки семпла (например, разный тип контента или сценариев).
`attr1`	`Long?`	Дополнительный числовой атрибут, который можно передать вместе с семплом.
`attr2`	`Long?`	Второй дополнительный числовой атрибут.

Возвращаемое значение: AttachmentId — идентификатор загруженного файла, который передаётся в TracerCrashReport.report() для прикрепления к событию.

Пример использования:

// Загружаем файл и получаем идентификатор вложения
val attachmentId = UserSampleUpload.attachment(
    sampleFile = File(context.cacheDir, "crash-screenshot.png"),
    tag = "crash_screenshot",
)

// Прикрепляем файл к NON_FATAL-событию
TracerCrashReport.report(
    severity = Severity.ERROR,
    e = IllegalStateException("Something went wrong"),
    attachmentId = attachmentId,
)