Advanced System Tracing on Android

This guide dives deeper into recording system traces on Android, building on the concepts introduced in the System Tracing guide.

Before you continue, you should be familiar with the basics of recording a system trace using either the Perfetto UI or the record_android_trace script.

This guide covers the lower-level details that these tools abstract away, including:

Enabling the Perfetto tracing services on older Android versions.
Using the on-device /system/bin/perfetto binary directly.
Writing and using a full trace config for advanced customization.
Using exclusive mode for tracing sessions to prevent interference from other traces.

Prerequisites: Enabling Tracing Services

Perfetto's tracing daemons (traced) are built into Android, but they are only enabled by default on Android 11 (R) and newer.

If you are using Android 9 (P) or Android 10 (Q), you must first enable the tracing services by running the following command:

# Needed only on Android 9 (P) and 10 (Q) on non-Pixel phones.
adb shell setprop persist.traced.enable 1

NOTE: If you are using a version of Android older than 9 (P), the on-device tools will not work. You must use the record_android_trace script.

Recording using the on-device /system/bin/perfetto command

The record_android_trace script is a wrapper around the on-device /system/bin/perfetto binary. For most use cases, the script is recommended, but you can also invoke the binary directly for more control.

# Example of invoking the on-device binary directly.
adb shell perfetto \
  # The path to the output file on device.
  # Time to record the trace.
  -o /data/misc/perfetto-traces/trace_file.perfetto-trace \
  # Time to record the trace.
  -t 20s \
  # The atrace categories to record.
  sched freq idle am wm gfx view binder_driver hal dalvik input res memory

However, there are several caveats to be aware of when using adb shell perfetto directly:

Stopping the trace: Ctrl+C does not work reliably with adb shell perfetto. It is only propagated correctly when using an interactive PTY-based session (i.e., running adb shell first, then perfetto inside the shell). For long-running traces, it is safer to use the --background flag and kill the process by its PID. See the Tracing in the Background guide for more.
Passing trace configs: On non-rooted devices before Android 12, SELinux rules prevent the perfetto process from reading config files from world-writable locations like /data/local/tmp. The recommended workaround is to pipe the config via standard input: cat config.pbtx | adb shell perfetto -c -. Since Android 12, you can place configs in /data/misc/perfetto-configs and pass the path directly.
Pulling trace files: On devices before Android 10, adb pull may not be able to access the trace file directly due to permissions. The workaround is to use adb shell cat: adb shell cat /data/misc/perfetto-traces/trace > trace.pftrace.

Using a Full Trace Config

For full control over the tracing process, you can provide a complete trace config file instead of using command-line flags. This allows you to enable multiple data sources and fine-tune their settings.

See the Trace Configuration page for a detailed guide on writing trace configs.

WARNING: The below command does not work on Android P because the --txt option was introduced in Q. The binary protobuf format should be used instead; the details of this can be found on the Trace configuration page.

If you are running on a Mac or Linux host, or are using a bash-based terminal on Windows, you can use the following:

cat<<EOF>config.pbtx
duration_ms: 10000

buffers: {
    size_kb: 8960
    fill_policy: DISCARD
}
buffers: {
    size_kb: 1280
    fill_policy: DISCARD
}
data_sources: {
    config {
        name: "linux.ftrace"
        ftrace_config {
            ftrace_events: "sched/sched_switch"
            ftrace_events: "power/suspend_resume"
            ftrace_events: "sched/sched_process_exit"
            ftrace_events: "sched/sched_process_free"
            ftrace_events: "task/task_newtask"
            ftrace_events: "task/task_rename"
            ftrace_events: "ftrace/print"
            atrace_categories: "gfx"
            atrace_categories: "view"
            atrace_categories: "webview"
            atrace_categories: "camera"
            atrace_categories: "dalvik"
            atrace_categories: "power"
        }
    }
}
data_sources: {
    config {
        name: "linux.process_stats"
        target_buffer: 1
        process_stats_config {
            scan_all_processes_on_start: true
        }
    }
}
EOF

./record_android_trace -c config.pbtx -o trace_file.perfetto-trace

Or alternatively, when using directly the on-device command:

cat config.pbtx | adb shell perfetto -c - --txt -o /data/misc/perfetto-traces/trace.perfetto-trace

Alternatively, first push the trace config file and then invoke perfetto:

adb push config.pbtx /data/local/tmp/config.pbtx
adb shell 'cat /data/local/tmp/config.pbtx | perfetto --txt -c - -o /data/misc/perfetto-traces/trace.perfetto-trace'

NOTE: because of strict SELinux rules, on non-rooted builds of Android, passing directly the file path as -c /data/local/tmp/config will fail, hence the -c - + stdin piping above. From Android 12 (S), /data/misc/perfetto-configs/ can be used instead.

Pull the file using adb pull /data/misc/perfetto-traces/trace ~/trace.perfetto-trace and open it in the Perfetto UI.

NOTE: On devices before Android 10, adb cannot directly pull /data/misc/perfetto-traces. Use adb shell cat /data/misc/perfetto-traces/trace > trace.perfetto-trace to work around.

The full reference for the perfetto cmdline interface can be found here.

Exclusive Tracing Sessions

Perfetto is designed to support multiple concurrent tracing sessions from different sources (e.g., adb, on-device apps, automated testing). While this works for most data sources, some advanced features cannot be reliably multiplexed, and sensitive performance measurements require minimizing interference from other traces. In these situations, Perfetto requires a guarantee that no other tracing session is active.

To address this, Perfetto offers an "exclusive" mode. When a session is started in exclusive mode, it ensures no other sessions are running, providing a clean tracing environment. This is controlled by the exclusive_prio field in the TraceConfig.

When to use exclusive mode

You should use an exclusive session in the following scenarios:

For sensitive performance measurements where you need to minimize interference from other concurrent tracing activities.
When using data sources with high overhead, such as function_graph in ftrace, to ensure their behavior is not affected by other sessions.
When configuring parameters that apply globally and are not multiplexed, like the ftrace buffer size (buffer_size_kb), which is only configured by the first active session.

Behavior

An exclusive session has the following behavior:

Priority System: The exclusive_prio is an unsigned integer where a higher number indicates a higher priority. A session is only considered "exclusive" if its priority is greater than 0.
Preemption: If a new exclusive session is requested with a priority strictly higher than any other active session, it will be started, and all other existing sessions (both exclusive and non-exclusive) will be aborted. Consumers of aborted sessions will receive an error message (e.g., Aborted due to user requested higher-priority (#priority) exclusive session.).
Blocking: While an exclusive session is active, any attempt to start a new non-exclusive session, or an exclusive session with a lower or equal priority, will be rejected.
Privileged Access: On Android, requesting an exclusive session is a privileged operation and can only be done by root or shell users.

How to enable

To start an exclusive session, add the exclusive_prio field to your trace config file.

This feature is available from Perfetto v52 and on Android from 25Q3+.

duration_ms: 10000

buffers: {
    size_kb: 8192
}

# Request an exclusive session with priority 10.
# This will abort any running sessions (provided they have a lower priority) and
# block new sessions with a lower or equal priority.
exclusive_prio: 10

data_sources: {
    config {
        name: "linux.ftrace"
        ftrace_config {
            # Advanced features like funcgraph can now be used more reliably.
            function_graph: true
            ftrace_events: "sched/sched_switch"
        }
    }
}