TIP: If you are unfamiliar with the word “tracing” or in general, are new to the world of performance, we suggest reading the What is Tracing? page first. If you are not quite sure what Perfetto is and why it's useful, check out the Perfetto homepage first.
Perfetto is a large project and it can be daunting for someone new to understand what parts of the documentation are relevant to them. By focusing on what technology you are using and what you are trying to accomplish, this page will guide you through our documentation and help you solve problems with Perfetto as quickly as possible.
Our docs make use of the terms “Tutorials”, “Cookbooks” and “Case Studies”:
Based on what technology you are interested in, please choose one of the following sections to go to next:
graph TD A[Start here] --> B{What is your role?}; B --> C["<a href='#android-developers'>Android App/Platform Developer</a>"]; B --> D["<a href='#linux-kernel-developers'>Linux Kernel Developer</a>"]; B --> E["<a href='#c-cpp-developers'>C/C++ Developer (non-Android)</a>"]; B --> F["<a href='#chromium-developers'>Chromium Developer</a>"]; B --> G["<a href='#trace-like-data'>I have trace-like data</a>"]; B --> H["<a href='#not-listed'>None of the above</a>"];
graph TD A[Android App & Platform Developers] --> B{What is your goal?}; B --> C["<a href='#android-understanding-system-behavior'>Understand system behavior / debug functional issues</a>"]; B --> D["<a href='#android-optimizing-performance'>Optimize performance / address latency</a>"]; B --> E["<a href='#android-diagnosing-memory-issues'>Diagnose memory issues</a>"];
Perfetto is the default tracing system on Android. It provides a powerful way to understand the intricate workings of the Android OS and applications, enabling developers to diagnose not only performance bottlenecks but also complex functional issues and unexpected behaviors. By capturing a detailed, chronological record of system and application activity, Perfetto helps you see how different components interact over time.
If you are a developer working on an Android app or on Android platform code (i.e. the Android OS itself), Perfetto can help you answer a wide array of questions:
When you need to understand how different parts of the system interact, debug a complex functional bug, or see the sequence of events leading to an unexpected state, Perfetto provides powerful insights.
How do different components interact? What is the sequence of events leading to an issue? System traces provide a detailed, time-correlated view of activity across the kernel, system services, and applications. This is invaluable for understanding complex interactions and debugging issues that span multiple components. The Perfetto UI is the primary tool for visualizing these traces.
How can I see the detailed flow of execution and state within my own code? To understand the timing and sequence of specific operations within your codebase (app or platform service), add custom trace points via instrumentation (android.os.Trace or ATrace NDK). These appear as distinct slices in the trace, helping you debug logic flows and measure internal durations.
How can I use existing diagnostic files like bugreports or logcat with Perfetto? Perfetto tools can often work with common Android diagnostic outputs, allowing you to leverage its visualization and analysis capabilities.
bugreport.zip files often contain Perfetto traces. The Perfetto UI can open these directly, automatically extracting and loading the traces.adb logcat output alongside trace data. Perfetto can also be configured to include logcat directly into new traces.When a component is slow, exhibits jank, or critical operations take too long, Perfetto provides the tools to investigate. This can involve direct CPU/GPU work, but often on Android, latency stems from inter-process communication (IPC) like Binder, lock contention, I/O waits, or inefficient scheduling. For issues primarily related to memory consumption, see the “Diagnosing Memory Issues” section below.
What is causing delays or jank in my component or user interaction? System traces are essential for understanding many types of latency. By visualizing thread states (Running, Runnable, Sleeping, Blocked on I/O or locks), scheduling decisions, and the timing of userspace events (like ATrace markers or custom SDK events), you can pinpoint where time is being spent. This is key for identifying:
Starting points includes:
Why is the UI specifically janky or dropping frames? For detailed analysis of UI rendering pipelines, Android's FrameTimeline data source is invaluable. It tracks frames from app rendering through composition to display, pinpointing which stage missed its deadline.
Which parts of my code are consuming the most CPU time (if CPU is indeed a bottleneck)? If system traces indicate your component is spending significant time on-CPU, then CPU profiling helps identify the specific functions responsible. Perfetto can capture these profiles or visualize profiles collected from simpleperf.
High memory usage can lead to poor performance, increased garbage collection pauses (for Java/Kotlin), and even apps or services being killed by the Low Memory Killer (LMK). For a comprehensive approach to these problems, start with our detailed case study:
Perfetto also provides specific tools to investigate and attribute memory usage:
How do I find out which Java/Kotlin objects are using the most memory or identify potential leaks? Java/Kotlin heap dumps provide a snapshot of all objects on the managed heap at a point in time. You can analyze this to see object counts, sizes, and retention paths (what's keeping an object alive), helping you find memory leaks or unexpectedly large objects.
Where is native (C/C++) memory being allocated in my code? For native code, heap profiling tracks malloc and free calls (or new/delete in C++), attributing allocations to specific function callstacks. This helps identify areas of high native memory usage or churn (frequent allocations and deallocations).
How does my component's overall memory footprint (RSS, PSS) change over time, and what are system-wide memory events? System traces can include memory counters (like Resident Set Size, Proportional Set Size) for your component and others, polled periodically. They can also capture critical kernel memory events, providing context on overall system memory pressure.
Perfetto offers deep integration with the Linux kernel, providing powerful tools for kernel developers to understand system behavior, debug issues, and optimize performance. It interfaces with:
Here's how Perfetto can assist Linux kernel development and debugging:
How can I understand kernel-level activity, such as scheduling, syscalls, or specific driver behavior? System traces captured by Perfetto provide a detailed timeline of kernel operations. You can configure Perfetto to record a wide array of ftrace events, giving you insights into kernel subsystems like the scheduler, interrupt handlers, and system calls. This is invaluable for debugging kernel bugs, understanding driver interactions, or analyzing system responsiveness. The Perfetto UI is the primary tool for visualizing and initially analyzing these traces.
How do I add custom instrumentation to my kernel code and see it in a trace? When developing new kernel features or debugging specific modules, you can define new ftrace tracepoints in your kernel code. Perfetto can then be configured to collect these custom events, allowing you to visualize your instrumentation alongside standard kernel events for targeted debugging.
Which parts of the kernel (or userspace) are consuming the most CPU time? If you suspect a CPU performance bottleneck in the kernel or a userspace process interacting heavily with the kernel, Perfetto can capture CPU profiles using perf events. This helps identify functions or kernel paths that are consuming excessive CPU cycles. Perfetto can also visualize profiles captured with the standalone perf tool.
If you‘re developing C/C++ applications on Linux, macOS, or Windows, Perfetto’s Tracing SDK allows you to instrument your code to understand its behavior and identify performance characteristics. On Linux, Perfetto also offers dedicated heap and CPU profiling tools for deeper investigation into resource usage.
Here’s how Perfetto can help:
How can I understand my application's execution flow, debug behavior, or find performance bottlenecks? By integrating the Perfetto Tracing SDK, you can add custom trace points (slices for timing, counters for values, flow events for causality) to your application. This allows you to visualize its internal operations on a timeline, measure the duration of functions or tasks, identify slow sections, and debug complex interactions within your code. These traces can be collected and viewed with the Perfetto UI.
(Linux-specific) How do I reduce my application's CPU usage? If your application is CPU-bound or you want to optimize its CPU consumption on Linux, Perfetto can capture CPU profiles. This helps pinpoint the exact functions consuming the most CPU cycles, guiding your optimization efforts.
(Linux-specific) How can I investigate native memory usage in my C/C++ application? On Linux, Perfetto‘s native heap profiler can track malloc/free (or C++ new/delete) calls, attributing allocations to specific function callstacks. This is crucial for identifying memory leaks, understanding memory churn, or finding opportunities to reduce your application’s memory footprint.
Perfetto underpins the chrome://tracing system for the Chromium browser and its related projects (Angle, Skia, V8). While the Chromium project has its own extensive internal documentation and best practices for recording and analyzing traces, Perfetto provides the foundational tools for this.
If you're looking to capture traces from Chrome, our tutorial provides a straightforward way to get started using the Perfetto UI:
For a general introduction to practical trace analysis in Chrome, this Perf-Planet blog post is also a helpful resource.
Perfetto's powerful UI and Trace Processor are not limited to traces recorded by Perfetto itself. If you have existing traces from other systems or custom timestamped data, you can often leverage Perfetto for visualization and analysis.
Can I open traces from other tools (e.g., Chrome JSON, Android Systrace, Linux perf, Fuchsia, Firefox Profiler) in Perfetto? Yes, the Perfetto UI and Trace Processor support a variety of common trace formats out of the box. This allows you to use Perfetto's advanced visualization and SQL-based analysis capabilities on data you may already have.
I have my own custom logging or timestamped data. How can I view it in Perfetto? If your data isn‘t in a directly supported format, you can convert it into Perfetto’s native protobuf-based format. This allows you to represent virtually any kind of timestamped activity on a timeline and create complex links between them. Once converted, you can use the full power of the Perfetto UI and Trace Processor.
If your specific role or use case wasn‘t directly covered by the categories above, don’t worry! Perfetto is a versatile suite of tools, and its core capabilities might still be highly relevant to your needs. At its heart, Perfetto excels in several key areas:
Recording Rich Timeline Data: Perfetto provides a reasonably high-performance Tracing SDK and integrates deeply with system-level data sources (like ftrace on Linux/Android). This allows you to capture detailed, time-correlated events from your application and/or the system it runs on.
Powerful Timeline Visualization (No Code Required): The Perfetto UI is designed to intuitively explore large, complex traces. You can navigate timelines, zoom into nanosecond-level details, inspect event properties, and correlate activity across different processes and hardware components, all through a graphical interface without writing any code. Features like track filtering, expanding/collapsing process threads, and visualizing event flows help you understand what your system is doing.
In-depth Programmatic Trace Analysis: For going beyond visual inspection, automating analysis, or extracting custom metrics, Perfetto's Trace Processor engine allows you to query traces using SQL. This powerful backend can be accessed programmatically.
For further inspiration on how Perfetto's flexible architecture has been adapted for a wide range of complex diagnostic scenarios, see:
If you're unsure where to start or how Perfetto might apply to your unique situation: