Android Systrace Basics - Introduction to Systrace

Word count: 3.2kReading time: 20 min

 2019/05/28

Technical update — 2026-10-13: First published in 2019, this article retains Systrace HTML and script workflows as historical references. Modern capture examples start from Android 11 / API 30+, with separate version requirements for app tracing APIs, permissions and data sources. Device-side atrace, host-side systrace.py and perfetto are different tools; their options are not interchangeable.

This is the first article in the Systrace series, primarily providing a brief introduction to Systrace, its basic usage, how to interpret Systrace traces, and how to analyze phenomena in Systrace in conjunction with other tools.

The purpose of this series is to view the overall operation of the Android system from a different perspective using Systrace, while also providing an alternative angle for learning the Framework. Perhaps you’ve read many articles about the Framework but can never remember the code, or you’re unclear about the execution flow. Maybe from Systrace’s graphical perspective, you can gain a deeper understanding.

Perfetto Series Article Index
Systrace Series Article Index
Main Content
Simple Usage of Systrace
Capturing Systrace with Command-Line Tools
Viewing Supported TAGs
What to Inspect First
About Me && Blog

Perfetto Series Article Index

How the Systrace workflow changed after Perfetto

When this article first described Systrace, the main workflow was systrace.py calling atrace, collecting ftrace and ATrace data, generating HTML, and opening it in Chrome. Today, split that flow into two layers:

The underlying mechanisms are still useful: android.os.Trace, native ATrace macros, ATrace in system services, Linux ftrace, and CPU scheduling events remain core data sources for Android performance analysis.
The tool workflow changed: current platform-tools no longer treats systrace.py as the main entry point. On Android 10 (API 29) and later, System Tracing saves .perfetto-trace files, and the default analysis tools are Perfetto UI and trace_processor.
There are three common capture paths now: use the System Tracing Quick Settings tile for interactive issues; use adb shell perfetto ... --out /data/misc/perfetto-traces/xxx.perfetto-trace for reproducible issues; use a Perfetto config or the record_android_trace script when the configuration needs to be stable and repeatable.
The Systrace concepts in this article map to Perfetto 1: Introduction, Perfetto 2: Capturing traces, and Perfetto 3: Perfetto View.

Perfetto combines protobuf traces, SQL, metrics, command-line processing and large-file analysis, supporting both short scenarios and long recordings. The old Systrace HTML flow is still good for quick visual inspection; the current Perfetto flow is better when the analysis needs search, filtering, SQL, metrics, or automation.

I will continue to update the Perfetto series, and all future illustrations will use Perfetto. Use both series as references, but prefer Perfetto for new work and check the OS version behind old functions, threads and captured data.

Systrace Series Article Index

Main Content

Systrace is a system event tracing and analysis tool introduced in the Android 4.1 era. It primarily records enabled events and instrumentation, rather than automatically sampling every method’s call stack. It helps developers collect execution information from key Android subsystems (such as SurfaceFlinger, SystemServer, kernel scheduling, input, display and the View system), allowing for a more intuitive analysis of system bottlenecks and performance improvements.

Systrace’s capabilities include tracking system I/O operations, kernel workqueues, CPU load, and the health of various Android subsystems. On the Android platform, it’s composed of three main parts:

Kernel Space: Systrace leverages the ftrace feature in the Linux Kernel. Therefore, to use Systrace, the relevant kernel tracing features, events and access permissions must be available; this is not simply a matter of installing an extra module.
Data Collection: The public synchronous android.os.Trace API is available from Android 4.3 / API 18 and lets applications mark custom code sections. Additionally, the atrace program in Android reads statistical info from ftrace and passes it to data analysis tools.
Data Analysis Tools: In the old flow, Android provided systrace.py (a Python script once located under Android SDK directory/platform-tools/systrace) to configure collection and generate HTML. In the current flow, perfetto records data into .perfetto-trace, while Perfetto UI and trace_processor open, query, and analyze it. Essentially, Systrace is a wrapper around Linux Kernel ftrace; Perfetto continues to support ATrace/ftrace while integrating more data sources, file formats, and analysis capabilities. Applications can still use Android’s Trace class to emit custom trace points.

Official documentation and usage for Systrace can be found here: system tracing and on-device capture

Design Philosophy of Systrace

Key flows in the system (such as Touch operations, Power button presses, scrolling), system mechanisms (input dispatching, View rendering, IPC, process management), and hardware/software status (CPU frequency, CPU scheduling, disk info, memory info) have Log-like info inserted, referred to here as TracePoints. Application/Framework ATrace markers and native kernel ftrace events come from different layers. These TracePoints demonstrate the execution time of core operations and the values of specific variables. The Android system then collects these TracePoints scattered across various processes and writes them into a file. After exporting this file, Systrace parses the enabled, permitted and successfully recorded events for that time range. It cannot fill in uninstrumented logic, disabled data sources or lost events.

Historical ATrace and kernel event excerpt

Important modules in Android have TracePoints inserted by default, categorized by TraceTag:

Framework Java-level TracePoints use the android.os.Trace class.
Framework Native-level TracePoints use ATrace macros.
App developers can define custom traces using the android.os.Trace class.

Placing process and kernel events on a shared timeline helps follow an operation across threads, waits and wakeups. This provides a view across layers, not all information about Android. Recording also has overhead; enabling every category or densely instrumenting a hot loop is not automatically useful.

Practical Applications

Because it contains a wealth of system info, parsed Systrace files are naturally suited for analyzing performance issues in both Android Apps and the system itself. App developers, system developers, and Kernel developers can all use Systrace for performance analysis.

Systrace can assist with responsiveness, jank/dropped frames and ANR investigations. Relevant user scenarios include:

App startup speed (cold, hot, and warm start).
Slow UI navigation or janky transitions.
Sluggishness in non-navigation actions (toggles, popups, long-presses, selection, etc.).
Slow screen on/off, power on/off, unlocking, or face recognition.
List scrolling jank.
Window animation jank.
Content loading jank.
System-wide sluggishness.
App unresponsiveness or freezes; traces may help reconstruct the lead-up to a crash, but logs or tombstones are still needed to diagnose it.

ANR analysis also requires ANR records, thread stacks and system logs. Boot issues generally need a dedicated boot trace configuration; an ordinary interactive recording cannot cover a tracing service that has not started.

When encountering these issues, older systems can use compatible Systrace tools to generate HTML. On Android 10 and later, prefer System Tracing or perfetto to capture a .perfetto-trace file and analyze it in Perfetto UI. The methods in this series, such as reading threads, wakeups, CPU scheduling, and Binder waits, still apply; the entry point has moved from Chrome HTML to Perfetto tracks, search, the selection panel, and SQL.

Simple Usage of Systrace

Before using Systrace, understand how the usage changed across Android versions. Older articles mention Eclipse, Android Studio Device Monitor, and systrace.py; today, the recommended flow is System Tracing or Perfetto. The capture rhythm is similar, but the output file and analysis tool are different.

The old flow was:

Prepare the UI you want to trace on the phone.
Click to start capture, or run systrace.py from the command line.
Perform operations on the phone, keeping the reproduction short.
When the configured duration ends, open Trace.html in a viewer that supports that format. Directly opening old HTML in a current Chrome version may have compatibility problems.

The current flow, assuming Android 11+, is:

Start recording from the System Tracing developer option, or run adb shell perfetto.
Reproduce jank, slow response, slow launch, or another target issue.
Export the .perfetto-trace file.
Open it in Perfetto UI, then use search, SQL, metrics, or trace_processor_shell when visual inspection is not enough.

This historical Systrace UI example shows com.android.janktown PID 13409, SurfaceFlinger PID 118, CPU tracks, the main thread and RenderThread. It is neither a fresh capture from the current device nor the Perfetto UI:

Legacy Systrace timeline UI

Capturing Systrace / Perfetto with Command-Line Tools

I recommend the command line: set it up once, and capturing the same kind of scenario becomes convenient. It also makes the configuration easy to keep and reuse. The old systrace.py shipped with the SDK, but current Platform-Tools notes say it has been superseded. “Download version 33 or older” is not a reliable general installation instruction. Historical scripts are available in Catapult; match Python and dependencies to the chosen revision.

The following examples assume Android 11 / API 30+, an authorized ADB connection and device support for the selected categories. Perfetto platform services exist from Android 9 and are enabled by default from Android 11. For Android 9/10 setup and path restrictions, consult the official Android recording guide.

adb shell perfetto -t 10s -b 64mb \
  sched freq idle am wm gfx view binder_driver \
  --out /data/misc/perfetto-traces/trace_file.perfetto-trace

adb pull /data/misc/perfetto-traces/trace_file.perfetto-trace .

This is Perfetto’s simple mode, primarily configuring ftrace/ATrace. It does not automatically enable FrameTimeline, heapprofd or every other data source. The chosen -b 64mb ring buffer is an example, not a guarantee of preserving all ten seconds under high load. Use a full configuration for additional sources or long recordings; see the Perfetto CLI.

To capture app instrumentation, replace com.example.app with the actual app and check the instrumentation requirements below:

adb shell perfetto -t 10s -b 64mb -a com.example.app \
  sched freq idle am wm gfx view binder_driver \
  --out /data/misc/perfetto-traces/app_trace.perfetto-trace

adb pull /data/misc/perfetto-traces/app_trace.perfetto-trace .

The following is a historical Systrace invocation. The path, Python interpreter and dependencies must match the script revision. Separate categories with spaces and specify an output filename:

1 2	$ cd android-sdk/platform-tools/systrace $ python systrace.py -t 8 -o historical.html sched gfx view

Production user builds can provide substantial system tracing data. Visibility depends on Android/OEM version, categories, permissions and app configuration. Userdebug/eng may expose more debugging capabilities, but do not guarantee the same performance as production builds. Validate performance conclusions in the target production environment after investigating the mechanism.

Adding App Instrumentation

Trace.beginSection() / endSection() are available from API 18. Calls must be paired, properly nested and made on the same thread. This fragment belongs inside a synchronous app method; bindArticle() represents the actual work being measured:

android.os.Trace.beginSection("bindArticle");
try {
    bindArticle();
} finally {
    android.os.Trace.endSection();
}

Do not span synchronous begin/end calls across threads or asynchronous work that may resume on another thread. From API 29, beginAsyncSection() / endAsyncSection() pair events using the same name and cookie. See the Trace API.

-a selects the app; it does not add instrumentation or bypass permissions. On Android 10/11, release apps can allow shell profiling with <profileable android:shell="true" /> inside <application>, avoiding debuggable solely for timing measurements. Android 12 changed this gate: AOSP android-12.0.0_r1 allows app Trace when the app is debuggable or isProfileable(). The <profileable> android:enabled default is true, so the older shell restriction should not be generalized to all later releases. Check other profilers’ permissions separately. Profileable documentation

Keep the Three Command Interfaces Separate

The retained option list below belongs to device-side atrace, not systrace.py. It was checked against AOSP android-12.0.0_r1 atrace. Atrace writes raw tracing data; an .html filename does not turn it into an HTML report. Check the actual device with adb shell atrace --help.

-a appname      enable app-level tracing for a comma separated list of cmdlines; * is a wildcard matching any process
-b N            use a trace buffer size of N KB
-c              trace into a circular buffer
-f filename     use the categories written in a file as space-separated
                  values in a line
-k fname,...    trace the listed kernel functions
-n              ignore signals
-s N            sleep for N seconds before tracing [default 0]
-t N            trace for N seconds [default 5]
-z              compress the trace dump
--async_start   start circular trace and return immediately
--async_dump    dump the current contents of circular trace buffer
--async_stop    stop tracing and dump the current contents of circular
                  trace buffer
--stream        stream trace to stdout as it enters the trace buffer
                  Note: this can take significant CPU time, and is best
                  used for measuring things that are not affected by
                  CPU performance, like pagecache usage.
--list_categories
                list the available tracing categories
-o filename      write the trace to the specified file instead
                  of stdout.

For an interactive Bash/zsh session, the old script aliases can be written as follows. Replace the sample path and python with your actual environment. Use ordinary quotes, no spaces around =, and spaces between categories:

1
2
3

alias st-start='python /path/to/legacy-systrace/systrace.py'
alias st-start-gfx-trace='st-start -t 8 sched gfx view'
st-start-gfx-trace -o historical.html

You do not need to memorize every option at once. Start with a simple capture; the options will become familiar as you use them. First make sure which tool you are using, then compare its common options here:

Option	Device-side atrace, Android 12 revision above	Perfetto simple mode
`-o`	Raw data output file on the device	Perfetto trace output file on the device
`-t`	Seconds; help lists a five-second default	Explicit durations such as `10s`
`-b`	KB	Explicit `64mb` in the example, not KB
`-a`	Comma-separated process command lines, with wildcard support	Selects app ATrace instrumentation

For old systrace.py, use that script’s own --help. Do not carry atrace’s -s (delay before starting) over to Perfetto, where simple-mode -s means maximum file size. A full ring buffer overwrites older events. Check data loss, shorten the capture window or adjust the full configuration instead of assuming the default buffer is sufficient.

Viewing Supported TAGs

The device’s currently available atrace categories can be listed with the following command. Different manufacturers may have various configurations; you can choose and configure TAGs based on your needs. Selecting fewer TAGs generally produces smaller Trace files but less content. Large Trace files can impact Chrome’s performance during analysis, so choose wisely.

Below is the output from the Android 12 phone I had on hand. The article does not record its vendor or build, so this is not a standard list for every Android 12 or current device. The HAL entries and repeated names belong to that device output. Names are on the left, descriptions on the right:

$ adb shell atrace --list_categories
         gfx - Graphics
       input - Input
        view - View System
      webview - WebView
           wm - Window Manager
           am - Activity Manager
           sm - Sync Manager
        audio - Audio
        video - Video
       camera - Camera
          hal - Hardware Modules
          res - Resource Loading
       dalvik - Dalvik VM
           rs - RenderScript
       bionic - Bionic C Library
        power - Power Management
           pm - Package Manager
           ss - System Server
     database - Database
      network - Network
          adb - ADB
     vibrator - Vibrator
         aidl - AIDL calls
        nnapi - NNAPI
          rro - Runtime Resource Overlay
          pdx - PDX services
        sched - CPU Scheduling
          irq - IRQ Events
          i2c - I2C Events
         freq - CPU Frequency
         idle - CPU Idle
         disk - Disk I/O
         sync - Synchronization
        workq - Kernel Workqueues
   memreclaim - Kernel Memory Reclaim
   regulators - Voltage and Current Regulators
   binder_driver - Binder Kernel driver
   binder_lock - Binder global lock trace
    pagecache - Page cache
       memory - Memory
      thermal - Thermal event
         freq - CPU Frequency and System Clock (HAL)
          gfx - Graphics (HAL)
          ion - ION Allocation (HAL)
       memory - Memory (HAL)
        sched - CPU Scheduling and Trustzone (HAL)
   thermal_tj - Tj power limits and frequency (HAL)

What to Inspect First

Verify the reproduction window, target process and PID, enabled sources and evidence of data loss. A successfully created file does not prove that it fully records the problem window.
Follow the operation through the main thread, RenderThread, Binder peers and CPU scheduling. Running means executing; Runnable means waiting for CPU. Follow wakeups, locks or Binder evidence to explain sleeping/waiting threads rather than assigning a root cause from one color.
A synchronous slice can include waiting; its duration is not pure CPU time. Correlate threads and frames. Android 12 / API 31+ also supports FrameTimeline, which must be enabled separately and is not captured by the simple commands above.
Cross-check with ANR stacks, crash logs or a specialized profiler. After a change, repeat the scenario on the same device/build under comparable load. Missing tracks or events remain unknown, rather than zero time.

About Me && Blog

Below is my personal intro and related links. I look forward to exchanging ideas with fellow professionals. “When three walk together, one can always be my teacher!”