Android Systrace Basics - Introduction to Systrace

Word count: 2.4kReading time: 14 min

 2019/05/28

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
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 mainly produces .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 is not just a different web viewer. It puts short traces, long traces, protobuf files, SQL, metrics, command-line processing, and large-file analysis into one system. 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. The underlying knowledge points are common between Systrace and Perfetto, so don’t worry about which one to use—you can learn from both series.

Perfetto Series Article Index

Systrace Series Article Index

Main Content

Systrace is a performance data sampling and analysis tool introduced in Android 4.1. It helps developers collect execution information from key Android subsystems (such as SurfaceFlinger, SystemServer, Kernel, Input, Display, and other critical framework modules, services, 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 ftrace modules in the kernel must be enabled.
Data Collection: Android defines a Trace class that applications can use to output statistical information to ftrace. 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: Systrace

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, known as TracePoints (essentially Ftrace info). 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 data to provide an overview of system operation over a period of time.

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.

Consequently, Systrace can collect and centrally display all information from both upper and lower layers of Android. For Android developers, Systrace’s greatest value is transforming the internal state of the Android system from a black box to a white box. Its global perspective and visualization make it the preferred choice for analyzing complex performance issues.

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.

From a technical standpoint, Systrace covers major performance categories: Responsiveness, Jank/Dropped Frames, and ANR.
From a user perspective, Systrace can analyze issues including but not limited to:
1. App startup speed (cold, hot, and warm start).
2. Slow UI navigation or janky transitions.
3. Sluggishness in non-navigation actions (toggles, popups, long-presses, selection, etc.).
4. Slow screen on/off, power on/off, unlocking, or face recognition.
5. List scrolling jank.
6. Window animation jank.
7. Content loading jank.
8. System-wide sluggishness.
9. App unresponsiveness (ANR), freezes, or crashes.

When encountering these issues, old systems can still use Systrace HTML and Chrome. 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 Chrome or the legacy UI.

The current flow 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.

A typically captured Systrace file looks like this:

Capturing Systrace / Perfetto with Command-Line Tools

The command-line approach is more flexible and faster. Once configured, you can get results quickly (highly recommended).
The Systrace tool used to live under platform-tools/systrace in the Android SDK. Current platform-tools no longer treats systrace.py as the recommended entry point. If you need to reproduce the old flow, use version 33 or older. For current projects, use perfetto directly:

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 .

If you need app-level custom trace points, add the package name:

1
2
3

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

The following is the old Systrace usage, useful for older systems or historical trace reproduction:

1 2	$ cd android-sdk/platform-tools/systrace $ python systrace.py

Configuring the path and an Alias in your Bash profile can make this very efficient. Traces from User builds contain less information than Eng or Userdebug builds. For system-service, kernel-scheduling, or vendor-policy issues, use a Userdebug device when possible. For normal app issues, User builds can still be a useful first pass through System Tracing or Perfetto, but some system detail will be missing.

After old Systrace capture, a Trace.html file is generated. After Perfetto capture, a .perfetto-trace file is generated. We’ll cover how to analyze trace files in later sections. The following options are the old systrace.py parameters:

-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.

While there are many parameters, you usually don’t need to worry about most of them when using tools—just check the boxes. In the CLI, we typically alias the command. For example:

1
2

alias st-start='python /path-to-sdk/platform-tools/systrace/systrace.py'
alias st-start-gfx-trace='st-start -t 8 am,binder_driver,camera,dalvik,freq,gfx,hal,idle,input,memory,memreclaim,res,sched,sync,view,webview,wm,workq,binder'

This allows you to simply type st-start to begin. Of course, to distinguish and save files, add -o filename.html. You don’t need to understand every parameter immediately; they will become familiar during the analysis process.

Commonly used parameters:

-o: Specifies the output file path and name.
-t: Capture duration (you can press Enter to stop early in newer versions).
-b: Specifies the buffer size (default is usually enough; increase it for longer traces).
-a: Specifies the app package name (required for debugging custom TracePoints).

Viewing Supported TAGs

The default TAGs supported by Systrace can be viewed with the following command. Different manufacturers may have various configurations; you can choose and configure TAGs based on your needs. Selecting fewer TAGs results in smaller Trace files but less content. Large Trace files can impact Chrome’s performance during analysis, so choose wisely.

Using my Android 12 device as an example, it supports the following tags (tag name on the left, description 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)

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!”