Sampling Profiler

Connecting dependencies to your project

In your <project>/<app-module>/build.gradle.

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

For a detailed description of the dependencies see “Quickstart”.

SamplingProfilerConfiguration description

In your Application.kt.

class MyApplication : Application(), HasTracerConfiguration {
    override val tracerConfiguration: List<TracerConfiguration>
        get() = listOf(
            SamplingProfilerConfiguration.build {
                // your options
            },
        )
}

Below are the SamplingProfilerConfiguration.Builder options.

• setEnabled — enables/disables profiling. By default: enabled.

Below are the SamplingProfilerConfiguration.Builder options that are deprecated or dangerous.

• setBufferSizeMb — see the android.os.Debug.startMethodTracingSampling description;
• setSamplingIntervalUs — see the android.os.Debug.startMethodTracingSampling description. By default: 5000.
• setDurationMs — profiler performance time in milliseconds.
• addCondition — adds a Condition that triggers profiling.

Condition.Deprecated description.

Condition is used to manage profiling start and send profiling results. Below is a usage example.

Condition.appStart(10_000, 7_000)

Start profiler with a 100% probability and send its performance result to the server if the app startup time exceeds a threshold of 7000 ms.

Creating own event.

val condition = Condition.build { // your options }

Below are the Condition.Builder options.

• setTag("my_tag") — tag for the result to be loaded to Tracer.
• setTagLimit(n) — maximum amount of the reports per day that will be accepted by the server.
• setProbability(n) — the probability (1/n) of starting the profiler on startEvent occurrence.
• setStartEvent("my_event") — the profiler will start on this event occurrence with the probability set above.
• setInterestingEvent("my_other_event") — optional. If set, the profiling result will be sent to the backend only if the event occurs during profiler performance.
• setInterestingDuration(n) — if the time between the start event and the interesting event exceeds this value, the profiling result will be sent to the backend.

info

If an interesting event has its own counter, the comparison will be done against this counter. For example, app_freeze has a counter — the time the UI flow "hangs". Therefore, if interestingEvent == "app_freeze" and interestingDuration == 700, the report will be sent if there is a 700+ ms freeze during the profiler performance.

Manual profiling

There is an option to set profiling start/stop in code manually.

• SamplingProfiler.start() — runs the profiler. Accepts the following parameters:
  • context: Context — App context;
  • tag: String — tag with which the result will be loaded to the tracer;
  • duration: Long — profiler performance time in milliseconds.
• SamplingProfiler.abort() — stops the profiler and clears the result.
• SamplingProfiler.commit() — stops the profiler and sends the result to the backend. If by the time of call the profiler is still active, the resulting tag will be <tag>_<tagSuffix>.
• tagSuffix: String — suffix that will be added to the tag if the profiler stops prematurely (optional).

See the example below.

The profiler will start with the probability of 1/100000.

if (Random.nextInt(100 _ 0 0 0) == 0) {
        SamplingProfiler.start(
                context = appContext,
                tag =  "stream_request" ,
                duration =  10 _ 0 0 0 ,
        )
}
// ... Code. For example, feed loading
SamplingProfiler.commit("loaded")

Description of “system” events

“System” events are used in the Condition class and manual profiling:

• TracerEvents.EVENT_APP_START_BEGIN — "app_start_begin": app start.
• TracerEvents.EVENT_APP_START_END — "app_start_end": Application.onCreate() method stop.
• TracerEvents.EVENT_FIRST_ACTIVITY_CREATED — "app_first_activity_created": first activity created.
• TracerEvents.EVENT_ACTIVITY_CREATED — "activity_created" — an activity is now in the created state.
• TracerEvents.EVENT_FREEZE — "app_freeze" — UI flow froze for N ms. If this event is used as an interesting event, then, the interesting duration will be compared against N. For example, if N == 500, then, the profiling result will be sent if the UI flow freezes for more than 500 ms during the profiler performance.
• EVENT_ANR — "app_anr": UI flow froze and didn't recover by the time the profiler stopped. N ms passed from freeze detection to the time the profiler stopped. If this event is used as an interesting event, then, the interesting duration will be compared against N. For example, if N == 5000, then, the profiling result will be sent if the UI flow freezes for more than 5000 ms during the profiler performance.

Adding user event (see below).

TracerEvents.addEvent(eventName, duration)

• eventName — event name. Used in the Condition class and in the startEvent and interestingEvent methods.
• duration — duration time of this event. If set, then, interestingDuration will not be calculated as difference between startEvent and interestingEvent, instead, it will be compared against the duration of this event.