Sampling Profiler

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

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

dependencies {
    implementation "ru.ok.tracer:tracer-profiler-sampling:0.2.7"
}

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

Описание `SamplingProfilerConfiguration`

В вашем Application.kt

class MyApplication : Application(), HasTracerConfiguration {
    override val tracerConfiguration: List<TracerConfiguration>
        get() = listOf(
            SamplingProfilerConfiguration.build {
                // ваши опции
            },
        )
}

Опции SamplingProfilerConfiguration.Builder:

setEnabled — включает/выключает профилирование. По умолчанию включён.

Устаревшие или опасные опции SamplingProfilerConfiguration.Builder:

setBufferSizeMb — смотрите описание android.os.Debug.startMethodTracingSampling;
setSamplingIntervalUs — смотрите описание android.os.Debug.startMethodTracingSampling. По умолчанию 5000;
setDurationMs — время работы профайлера в ms;
addCondition — добавляет Condition для начала профилирования.

Описание `Condition`. Deprecated.

Конструкция Condition используется для управления запуском и отправкой результатов профилирования. Пример использования:

Condition.appStart(10_000, 7_000)

Включить профайлер при старте приложения с вероятностью 100% и отправить результат его работы на сервер, если время запуска приложения превысило 7000 мс.

Создание собственного события:

val condition = Condition.build { // ваши опции }

Опции Condition.Builder

setTag("my_tag") — Тег, с которым результат будет загружен в Tracer.
setTagLimit(n) — Максимальное количество отчетов в день для данного тега которое примет сервер.
setProbability(n) — Вероятность(1/n) с которой будет запущен профайлер при наступлении события из startEvent.
setStartEvent("my_event") — При наступлении этого события с указанной выше вероятностью будет запущен профайлер.
setInterestingEvent("my_other_event") — Опционально. Если присутствует, то результат профилирования будет отправлен на бекенд, только если данное событие встретилось за время работы профайлера.
setInterestingDuration(n) — Если время между стартовым и интересующим событием превысит это число, результат профилирования будет отправлен на бекенд.

Если интересующее событие будет иметь свой счётчик, сравнение будет происходить с ним. К примеру, app_freeze имеет счетчик — время которое UI поток висел. Следовательно, если interestingEvent == "app_freeze" и interestingDuration == 700, то отправка произойдет, если во время работы профайлера случился фриз на 700+ мс.

Ручное профилирование

Также есть возможность размечать в коде начало и конец профилирования.

SamplingProfiler.start() — Запускает профайлер. Принимает параметры:

context: Context — App context приложения.
tag: String — Тег, с которым результат будет загружен в трейсер.
duration: Long — Время работы профайлера в ms.

SamplingProfiler.abort() — Прекращает работу профайлера и очищает результат.

SamplingProfiler.commit() — Прекращает работу профайлера и отпавляет результат на бэкенд. Если на момент вызова профайлер ещё не закончил работу, то результирующий тег будет равен <tag>_<tagSuffix>

tagSuffix: String — Опционально. Суффикс, который будет добавлен к тегу в случае досрочной остановки профайлера.

Пример:
С вероятностью 1/100000 профайлер начнёт свою работу

if (Random.nextInt(100_000) == 0) {
        SamplingProfiler.start(
                context = appContext,
                tag = "stream_request",
                duration = 10_000,
        )
}
// ... Код. Например, загрузка ленты
SamplingProfiler.commit("loaded")

Описание «системных» событий

«Системные» события используются в классе Condition и ручном профилировании:

TracerEvents.EVENT_APP_START_BEGIN — "app_start_begin" — Начало работы приложения.
TracerEvents.EVENT_APP_START_END — "app_start_end" — Окончание работы метода Application.onCreate().
TracerEvents.EVENT_FIRST_ACTIVITY_CREATED — "app_first_activity_created" — Создана первая активити.
TracerEvents.EVENT_ACTIVITY_CREATED — "activity_created" — Любая активити перешла в состояние created.
TracerEvents.EVENT_FREEZE — "app_freeze" — UI поток завис на N мс. Если данный эвент используется как interesting event, тогда interesting duration будет сравниваться с N. К примеру, если N == 500, тогда результат профайлинга будет отправлен, если UI поток за время работы профайлера зависал на более чем 500 мс.
EVENT_ANR —"app_anr" — UI поток завис и не продолжил свою работу на момент окончания профайлера. Прошло N мс с момента обнаружения зависания до окончания работы профайлера. Если данный эвент используется как interesting event, тогда interesting duration будет сравниваться с N. К примеру, если N == 5000, тогда результат профайлинга будет отправлен, если UI поток за время работы профайлера завис на более чем 5000 мс.

Чтобы добавить пользовательское событие:

TracerEvents.addEvent(eventName, duration)

eventName — имя события. Используется в классе Condition в методах startEvent и interestingEvent.
duration — время ассоциированное с этим событием. Если задано, то interestingDuration будет вычисляться не как разница между startEvent и interestingEvent, а сравниваться с duration этого события.

Обновлено 22 сентября 2023 г.