Recording system traces with Perfetto

In this guide, you'll learn how to:

  • Record a system-wide trace on Android and Linux.
  • Visualize the trace in the Perfetto UI.
  • Programmatically analyze the trace using PerfettoSQL.

A powerful use of Perfetto is to collect tracing information from many different processes and data sources on a single machine and combine them all into a single trace. This allows debugging a wide range of performance and functional problems including complex ones. Examples include problems which might span multiple processes, between an app and the OS or even interactions between hardware and the OS. Such traces are known as system traces or commonly abbreviated to just systraces.

NOTE: Recording system traces with Perfetto is only supported out of the box on Android and Linux. While trace recording daemons work on Windows and macOS, there is no integration with system-level data sources meaning traces are unlikely to be useful.

Recording your first system trace

This section walks you through the process of recording your first system-wide trace. There are multiple paths depending on whether you want to record on Android with a GUI, on Android using the command line or on Linux (with the command line only).

Viewing your first trace

We can now explore the captured trace visually by using the web-based trace visualizer: the Perfetto UI.

NOTE: The Perfetto UI runs fully locally, in-browser using JavaScript + WebAssembly. The trace file is not uploaded anywhere by default, unless you explicitly click on the ‘Share’ link.

NOTE: The ‘Share’ link is available only to Googlers.

The recording instructions above should all have caused the trace to automatically open in the browser. However, if they did not work for any reasons (most likely if you are running the commands over SSH), you can also open the traces manually:

  1. Navigate to ui.perfetto.dev in a browser.
  2. Click the Open trace file on the left-hand menu, and load the captured traces or simply drag and drop your trace into the Perfetto UI.

Perfetto UI open trace

Perfetto UI with a trace loaded

  • Explore the trace by zooming/panning using WASD, and mouse for expanding process tracks (rows) into their constituent thread tracks. Press “?” for further navigation controls.
  • Please also take a look at our Perfetto UI documentation page

Querying your first trace

As well as visualizing traces on a timeline, Perfetto has support for querying traces using SQL. The easiest way to do this is using the query engine available directly in the UI.

  1. In the Perfetto UI, click on the “Query (SQL)” tab in the left-hand menu.

    Perfetto UI Query SQL

  2. This will open a two-part window. You can write your PerfettoSQL query in the top section and view the results in the bottom section.

    Perfetto UI SQL Window

  3. You can now execute queries. For example, to see all the processes captured in the trace, run the following query (you can use Ctrl/Cmd + Enter as a shortcut):

For example, to query the CPU scheduling information we recorded you can use:

INCLUDE PERFETTO MODULE sched.with_context;

SELECT *
FROM sched_with_thread_process
LIMIT 100;

For the CPU frequency information, you can do:

INCLUDE PERFETTO MODULE linux.cpu.frequency;

SELECT *
FROM cpu_frequency_counters
LIMIT 100;

For Android traces, to query the atrace slices, you can do:

INCLUDE PERFETTO MODULE slices.with_context;

SELECT *
FROM thread_or_process_slice
LIMIT 100;

And atrace counters are available by doing:

SELECT *
FROM counter
LIMIT 100;

Next steps

Now that you've recorded and analyzed your first system trace, you can explore more topics:

More data sources

A system trace can include data from many different parts of the system. Learn more about some of the most common data sources:

For Android developers, it's also common to include:

  • ATrace: Events from Android apps and services.
  • Logcat: Logcat messages.

More about trace recording

More about trace analysis

To get the most out of the Perfetto UI, check out the detailed Perfetto UI documentation.

To learn more about programmatic analysis, see: