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

2025-4-17 Update

Google has discontinued maintenance for the Systrace tool. If you are new to this, it is recommended to use Perfetto to capture traces. For detailed usage, refer to the Perfetto Series on this blog.
The latest version of platform-tools has removed the Systrace tool. Google recommends using Perfetto to capture traces. If you need the Systrace tool, please download an older version of platform-tools.
Choosing between Systrace and Perfetto: My personal recommendation is that you can use both; use whichever feels most comfortable. However, Google eventually plans to replace Systrace with Perfetto, so you might consider switching your default trace viewing tool to Perfetto UI.
Advantages of Perfetto:
1. The most significant improvement of Perfetto over Systrace is its support for long-duration data capture. This is thanks to a background service that encodes collected data into Protobuf format and saves it to disk. In terms of data sources, the core principle is consistent with Systrace—both rely on the Linux kernel’s Ftrace mechanism to record key events in both user and kernel space (ATRACE, CPU scheduling). Perfetto supports all features provided by Systrace, which is why Systrace will eventually be replaced.
2. Perfetto’s supported data types, acquisition methods, and analysis techniques are unprecedentedly comprehensive. It supports trace types via ATRACE, metric types through customizable node reading, and log types on UserDebug versions by acquiring logd data.
3. You can manually trigger capture and termination through the Perfetto.dev website or command-line tools, trigger long-duration captures via Developer Options in Settings, or even dynamically enable capture using the Perfetto Trigger API provided in the framework. This covers nearly all scenarios encountered in projects.
4. On the data analysis side, Perfetto provides a web-based visualization tool similar to Systrace but with a entirely different underlying implementation. The biggest benefit is support for rendering extremely large files—something Systrace cannot do (it may crash or become extremely laggy with files over 300M). This visualization site allows you to see various post-processed data, execute SQL queries, and even view logcat content. Perfetto Trace files can be converted into SQLite-based database files, allowing you to run pre-written SQL files or write queries on the fly. You can even import data into data science stacks like Jupyter and share your analytical insights with colleagues.
5. For example, if you want to calculate the total CPU consumption of the SurfaceFlinger thread or identify which threads are running on the large cores, you can collaborate with domain experts to translate their experience into SQL commands. If that’s not enough, Perfetto also provides a Python API to export data into DataFrame format, enabling almost any custom data analysis effect you desire.
6. You can find introductions to and comparisons of various tools in the article Techniques, Philosophy, and Tools for Android Performance Optimization.

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: Android provides systrace.py (a Python script located in Android SDK directory/platform-tools/systrace that calls atrace internally) to configure data collection (such as tags, output filename, etc.), collect ftrace statistics, and generate a resulting HTML file for user viewing. Essentially, Systrace is a wrapper around the Linux Kernel’s ftrace. Applications need to utilize the Trace class provided by Android to use Systrace.

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, you can capture a Systrace using various methods, open the parsed file in Chrome, and begin analysis.

Simple Usage of Systrace

Before using Systrace, understand how to use it on various platforms. Given the widespread use of Eclipse and Android Studio, I’ll quote the official usage methods, although the process is the same regardless of the tool:

Prepare the UI you want to trace on the phone.
Click to start capturing (or execute the command in the CLI).
Perform operations on the phone (don’t take too long).
Once the preset time is up, a Trace.html file will be generated. Open this file in Chrome for analysis.

A typically captured Systrace file looks like this:

Capturing Systrace 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 is located in platform-tools within the Android-SDK directory (Note: The latest platform-tools versions have removed the systrace tool. You need to download version 33 or older, available here: https://androidsdkmanager.azurewebsites.net/Platformtools). Below is the basic usage:

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. Also, traces from User builds contain less information than Eng or Userdebug builds. It’s recommended to use a Userdebug device for debugging to ensure both performance and detailed output.

After capturing, a Trace.html file is generated, which must be opened in Chrome. We’ll cover how to analyze the file in later sections. Regardless of the tool used, you can select parameters before capturing. Here’s what they mean:

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