How do I start using Perfetto?

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 undestand what parts of the documentation 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":

• Tutorials are guides which explain how to get started using Perfetto tools. They are focused on teaching you the tools themselves and not so much on how the tools can be used to solve real world problems.
• Cookbooks are pages containing small, bite-sized guides (recipes) which give you a quick idea on how to solve a concrete problem with Perfetto. They will have snippets of code you can copy-paste or a sequence of instructions you can follow.
• Case Studies are detailed, opinionated guides which take you step-by-step how you can debug and root-cause a "vertical" problem using Perfetto. They focus more on helping you solve the problem and and less on teaching you Perfetto tools. They may also make signifcant use of non-Perfetto based tools or commands where appropriate.

Based on what technology you are interested in, please choose one of the following sections to go next:

Android App & Platform Developers

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:

1. Why is a specific operation taking longer than expected?
2. What sequence of events led to this bug?
3. How do different processes and system services interact during a particular use case?
4. Is my component behaving correctly under specific system conditions?
5. Why is my app - or the whole system - using so much memory?
6. How can I optimize my component's CPU or resource usage?
7. What is the state of various system components at a critical point in time?

Understanding System Behavior & Debugging Functional Issues

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.

  • Tutorial: Recording and Analyzing System Traces
  • Reference: CPU Scheduling Data Source (Often key for understanding interactions and component state)

• 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.

  • Tutorial: Instrumenting Android code with atrace
  • Reference: ATrace Data Source

• 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.

  • Android bugreport.zip files often contain Perfetto traces. The Perfetto UI can open these directly, automatically extracting and loading the traces.
    • Tutorial: Visualizing Android bugreports
  • You can visualize adb logcat output alongside trace data. Perfetto can also be configured to include logcat directly into new traces.
    • Tutorial: Visualizing adb logcat

Optimizing Performance & Addressing Latency

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:

  • Binder/IPC latency: See how long your component waits for responses from other processes.
  • Lock contention: Identify threads blocked waiting for mutexes.
  • Scheduling delays: Determine if your thread isn't getting scheduled promptly when it becomes runnable.
  • I/O waits: See if operations are blocked on disk or network I/O.
  • UI Jank: Correlate system activity with frame production and presentation, often in conjunction with FrameTimeline data.

  Starting points includes:

  • Tutorial: Recording and Analyzing System Traces
  • Reference: CPU Scheduling Data Source

• 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.

  • Tutorial: Recording and Analyzing System Traces
  • Reference: FrameTimeline Data Source

• 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.

  • Tutorial: Recording performance counters and CPU profiling with Perfetto
  • Tutorial: Visualizing simpleperf files

Diagnosing Memory Issues

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:

• Case Study: Debugging memory usage on Android

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.

  • Tutorial: Recording Memory Profiles (Java/JVM Heap Dumps)
  • Reference: Java Heap Dumps Data Source

• 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).

  • Tutorial: Recording Memory Profiles (Native Heap Profiling)
  • Reference: Native Heap Profiler Data Source

• 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.

  • Tutorial: Recording and Analyzing System Traces
  • Reference: Memory Counters and Events Data Source

Linux Kernel Developer

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:

• ftrace: For capturing detailed, high-frequency kernel events like scheduling changes, syscalls, interrupts, and custom tracepoints. Perfetto acts as an efficient userspace daemon for ftrace. Perfetto supports also recording and visualizing whole funcgraph traces via ftrace, to track each kernel function entry/exit on the timeline.
• /proc and /sys interfaces: For polling lower-frequency kernel statistics, process information (like command lines and parent/child relationships), and system-wide counters (e.g., memory usage, CPU frequency).
• perf events: For CPU profiling by sampling kernel and userspace callstacks based on hardware or software counters.

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.

  • Tutorial: Recording System Traces on Linux (Focus on Linux-specific ftrace configuration)
  • Reference: CPU Scheduling Data Source
  • Reference: System Calls Data Source
  • Reference: Memory Counters and Events (from /proc, /sys, and kmem ftrace)

• 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.

  • Tutorial: Instrumenting the Linux kernel with ftrace
  • Reference: Kernel Tracepoint Documentation (External link to kernel.org)

• 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.

  • Tutorial: Recording performance counters and CPU profiling with Perfetto
  • Guide: Visualizing perf files

C/C++ Developer (non-Android)

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.

  • Tutorial: Recording In-App Traces with Perfetto
  • Reference: Perfetto Tracing SDK Details

• (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.

  • Tutorial: Recording performance counters and CPU profiling with Perfetto

• (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.

  • Tutorial: Recording Memory Profiles (Native Heap Profiling)
  • Reference: Native Heap Profiler Data Source

Chromium Developers

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:

• Tutorial: Recording traces on Chrome

For a general introduction to practical trace analysis in Chrome, this Perf-Planet blog post is also a helpful resource.

Anyone with "trace-like" data to analyse/visualize

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.

  • Guide: Visualizing external trace formats with Perfetto (Lists supported formats and how to open them)

• 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.

  • Guide: Converting arbitrary timestamped data to Perfetto
  • Reference: TrackEvent protobuf definition for synthetic traces

Anyone not listed above

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:

1. 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.

   • Think creatively: Could your problem be understood by instrumenting your C/C++ code to log events on a timeline? Our Recording In-App Traces with Perfetto Tutorial shows how.
   • Are you working with an existing system that produces timestamped data? It might be convertible to a format Perfetto understands. See our guide on converting custom data.

2. 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.

   • Explore diverse data: Perfetto can open various external trace formats directly in the UI.
   • Discover UI features: The Perfetto UI also has features like Debug Tracks that allow for sophisticated data aggregation and custom visualizations driven by simple UI configurations.

3. 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.

   • Automate your insights: If you have recurring analysis tasks or want to extract specific metrics from any trace (Perfetto-native or converted), the Trace Processor is invaluable.

For further inspiration on how Perfetto's flexible architecture has been adapted for a wide range of complex diagnostic scenarios, see:

• Snap's presentation on Client Tracing at Scale.
• How Collabora used Perfetto for profiling virtualized GPU acceleration.

If you're unsure where to start or how Perfetto might apply to your unique situation:

• Browse our documentation: Use the navigation sidebar to explore different sections like "Concepts," "Data Sources," or "Diving Deep."
• Engage with the community: Ask questions on Discord or our public mailing list.