Skip to main content
Technology & EngineeringAndroid Kotlin29 lines

Trace Android App Performance with Perfetto

Capture comparable Android system traces and use Perfetto to investigate startup latency, app rendering, jank, and scheduling delays.

Quick Summary9 lines
Record the device and Android version, build identifier, launch route, expected refresh mode, and whether the test is cold, warm, or hot. Use the same device, build type, power mode, input sequence, and data setup for baseline and candidate. A debug build may include work that release users never see. For an app startup problem, define the trigger and first displayed frame. If the first frame displays a placeholder, separately record when the intended content becomes usable. Keep those two timings distinct throughout the comparison.

## Key Points

- [Android on-device system tracing](https://developer.android.com/topic/performance/tracing/on-device)
- [Perfetto system tracing guide](https://github.com/google/perfetto/blob/main/docs/getting-started/system-tracing.md)
- [Perfetto FrameTimeline](https://perfetto.dev/docs/data-sources/frametimeline)
skilldb get android-kotlin-skills/perfetto-app-performance-tracingFull skill: 29 lines
Paste into your CLAUDE.md or agent config

Trace Android App Performance with Perfetto

Plan a comparable capture

Record the device and Android version, build identifier, launch route, expected refresh mode, and whether the test is cold, warm, or hot. Use the same device, build type, power mode, input sequence, and data setup for baseline and candidate. A debug build may include work that release users never see. For an app startup problem, define the trigger and first displayed frame. If the first frame displays a placeholder, separately record when the intended content becomes usable. Keep those two timings distinct throughout the comparison.

Capture an idle interval before the action and enough time afterward to observe work on the critical path. Enable the system tracing categories needed for the question. CPU scheduling and frequency help explain time on or off a CPU. Graphics and app annotations expose work nearer the rendering pipeline. Use on-device System Tracing or the supported Perfetto capture utility for the environment. On a shared device, limit the capture to a synthetic account and avoid collecting private notification text or unrelated activity. Use a local analysis environment if the trace must stay on the device or workstation.

Attribute the delay

Open the trace and locate the target app process. Set the visible interval to the trigger and endpoint. For slow startup, mark the launch and UI milestones and separate app startup work from time waiting on the system. Expand the main thread, relevant worker threads, and RenderThread. A long elapsed interval can contain runnable time waiting for a CPU, sleeping while waiting on another thread, or active CPU work. Align that interval with scheduler evidence and any known binder, resource-load, or I/O activity before attributing cause.

On devices and captures with FrameTimeline, align a visibly slow frame with expected and actual frames. Follow the app frame through to the display frame and distinguish app-side work from compositor-side delay. Consider multiple layers and repeated frame tokens when comparing app and compositor rows. If the app finished early but presentation was delayed, carry compositor or system load forward as a separate hypothesis. Confirm suspected code paths by adding bounded trace annotations or changing one variable and capturing again.

Check for missing trace data. Verify the relevant data sources and timeline tracks exist, that the test action is inside the capture, and that the capture did not lose the section needed to make the claim. An absent track or empty query cannot prove that the associated work never happened. When saving a PerfettoSQL report, include the table or standard-library module version and the exact duration units. A second reviewer should be able to reopen the trace and recover the same interval.

Retain a result for each comparable run and report median and spread with sample count. Attach the device, build, trace references and causal evidence to the proposed change. Repeat the same action after the change and check a neighboring path for regressions.

References

Install this skill directly: skilldb add android-kotlin-skills

Get CLI access →