android profiler systemtrace start

Start trace recording segment.

Usage

android profiler systemtrace start [-h] [--activity=PARAM] [--device=PARAM] [--disable=PARAM] [--duration=PARAM] [--enable=PARAM] [--keep-session] [--launch] [--output=PARAM] [--package=PARAM] [--preset=PARAM] [--session=PARAM] [--wait]

Options

  • --activity=PARAM - Activity to launch with --launch; defaults to the launcher activity. Only when 'start' creates the session (not allowed after 'prepare').
  • --device=PARAM - Device serial or AVD name.
  • --disable=PARAM - Trace options not to record: a group (cpu, gpu, vulkan, compose) or an individual option (cpu.freq, cpu.sched, cpu.syscalls, cpu.slices, gpu.freq, gpu.memory, gpu.work-period, gpu.frame-lifecycle, gpu.counters, vulkan.cpu-timing, vulkan.debug-names, vulkan.screenshots, compose.composition, compose.recomposition); repeatable or comma-separated. Individual options take precedence over groups, e.g. --enable cpu --disable cpu.syscalls. Only when 'start' creates the session (not allowed after 'prepare').
  • --duration=PARAM - Duration in seconds (auto-stops trace and restores device if --keep-session is false).
  • --enable=PARAM - Trace options to record on top of the preset: a group (cpu, gpu, vulkan, compose) or an individual option (cpu.freq, cpu.sched, cpu.syscalls, cpu.slices, gpu.freq, gpu.memory, gpu.work-period, gpu.frame-lifecycle, gpu.counters, vulkan.cpu-timing, vulkan.debug-names, vulkan.screenshots, compose.composition, compose.recomposition); repeatable or comma-separated. Individual options take precedence over groups, e.g. --enable cpu --disable cpu.syscalls. Only when 'start' creates the session (not allowed after 'prepare').
  • -h,--help - Shows the help message for the specified command.
  • --keep-session - Keep the session alive after the recording ends (requires --duration or --wait); for manual recordings pass --keep-session to 'stop'.
  • --launch - Launch target application after trace buffer settles.
  • -o,--output=PARAM - Directory or file path to save output trace.
  • --package=PARAM - Package name of the app to trace; omit for a system-wide trace. Only when 'start' creates the session (not allowed after 'prepare').
  • --preset=PARAM - Recording configuration template to start from (default, graphics); omit for default. Adjust it with --enable and --disable. Only when 'start' creates the session (not allowed after 'prepare').
  • --session=PARAM - Session ID for background daemon.
  • --wait - Block until the recording ends.

android options:

  • --sdk=PARAM - Path to the Android SDK.
  • -v,--verbose - Enable verbose output for troubleshooting.
  • -V,--version - Print version information and exit.

Description

android profiler systemtrace start starts recording a system trace. If no session is active, it starts one first; otherwise, it records in the active session, such as one started by android profiler systemtrace prepare.

Pass --package to trace an app, or omit it for a system-wide trace. The trace is saved to the file or directory passed in -o, --output, or to the current directory if it's omitted.

Choose what to record (--preset, --enable, and --disable)

A preset is the set of trace options to start from:

  • default: CPU scheduling, thread slices, CPU frequency and idle states, and the frame lifecycle. Used if --preset is omitted.
  • graphics: Everything in default, plus GPU frequency, GPU memory, GPU work periods, GPU counters, and Vulkan CPU timing. Requires --package.

Pass --enable and --disable to add or remove trace options, either a group (such as cpu) or an individual option (such as cpu.syscalls). Individual options take precedence over groups. The vulkan and compose options require --package.

These options set up the session, so you can only pass them when start starts the session.

Jetpack Compose (compose.composition and compose.recomposition)

The compose options record what Jetpack Compose does in the app. They require androidx.compose.runtime:runtime-tracing 1.13 or newer in the app:

  • compose.composition: Records a slice for each composable function that runs.
  • compose.recomposition: Also records the state reads and writes that cause composable functions to recompose, which shows why they recompose. It includes compose.composition, and has a high overhead, so use it to debug recompositions, not to measure performance.

The app records these traces itself, so the trace is saved as a ZIP archive that contains the system trace and the Compose traces. Open it in the Android Studio profiler, which shows them as a single trace.

Launch the app (--launch and --activity)

Pass --launch to launch the app after the recording starts, which captures the app startup. By default, the launcher activity of the app is launched; pass --activity to launch a different one.

End the recording (--duration and --wait)

By default, start returns as soon as the recording starts, and the recording continues until you run android profiler systemtrace stop. You can also end it as follows:

  • --duration: Stops the recording after the given number of seconds and saves the trace.
  • --wait: Blocks until the recording ends. Press Ctrl+C to stop the recording early and save the trace.

When the recording ends, the session ends and the device is restored. To record again in the same session, pass --keep-session together with --duration or --wait, or pass --keep-session to stop.

Examples

Trace the startup of an app until you stop the recording:

android profiler systemtrace start --package=com.example.app --launch --output=startup.perfetto-trace

Record a 10-second system-wide trace, and wait for the trace to be saved:

android profiler systemtrace start --duration=10 --wait --output=system.perfetto-trace

Record the graphics preset for an app, with system calls and without GPU counters:

android profiler systemtrace start --package=com.example.app --preset=graphics --enable=cpu.syscalls --disable=gpu.counters

Record why the composable functions of an app recompose during its startup:

android profiler systemtrace start --package=com.example.app --launch --enable=compose.recomposition --output=recomposition.perfetto