Tracing in Background

This document describes how to run Perfetto in the background, allowing you to disconnect from the device and collect the trace file later.

Use Case

Let's say you want to start recording a long-running trace on an Android device or a Linux server, then terminate your adb/ssh shell and come back later to stop the tracing session and collect the trace file. This page shows you how to do this while ensuring the trace remains intact.

To run tracing in the background, use the --background-wait argument with the perfetto command. This will daemonize Perfetto (i.e., run it as a background process) and print its process ID (PID).

NOTE: It's recommended to use --background-wait rather than --background, as the former waits for all data sources to be started before exiting. This ensures that no data is lost at the beginning of the trace.

Usage

Start recording a trace using tracebox or perfetto.

This will print the pid of the background perfetto process to stdout.

When you are ready to stop tracing, you need to send a SIGINT or SIGTERM signal to the background Perfetto process. However, simply killing the process creates a race condition: the kill command returns immediately, but Perfetto may still be writing the final parts of the trace file to disk.

If you collect the file too soon, it may be incomplete. To prevent this, you must wait for the close_write event on the trace file, which confirms that Perfetto has finished writing and closed the file. You can achieve this using platform-specific inotify tools.