Systrace — What It Is, Android System Tracing Tool

What is Systrace

Systrace is a command-line utility from the Android SDK that captures and merges data from multiple kernel tracing (ftrace) and user-space (atrace) sources into a single HTML report. The tool appeared in Android 4.1 (Jelly Bean) as a replacement for the old traceview utility for system profiling and remained the standard performance diagnostics tool on the Android platform for a long time.

Systrace Architecture

Systrace relies on ftrace — a Linux kernel tracing mechanism available in Android since version 4.1. When Systrace starts, it activates the specified trace categories: sched (task scheduler), freq (CPU frequency), idle (idle states), workq (work queues), binder, gfx, and others. Data is collected in the kernel’s ring buffer and, after stopping, merged into a single trace.html file that can be opened in any browser.

Systrace in the Context of Android Studio

Starting with Android Studio 3.1, Systrace is built into the CPU Profiler. In Trace System Calls mode, the profiler launches Systrace on the connected device and displays the results directly in the Android Studio window. This eliminates the need to work with the command line for basic cases while retaining full functionality — all trace categories, filtering, and interactive timeline. Device performance during tracing decreases insignificantly since ftrace is designed for minimal overhead.

How Systrace Works

Systrace uses two data collection mechanisms: ftrace at the kernel level for system events and atrace in user space for Android-specific tags. ftrace records context switches (sched_switch), CPU frequency changes (cpu_frequency), interrupts (irq_handler_entry), and other events. atrace adds tags from the Android framework — the start and end of frame rendering, SurfaceFlinger calls, and Binder transactions.

Frame Rendering Pipeline in Systrace

The key feature of Systrace is the visualization of each frame’s rendering pipeline: application → BufferQueue → SurfaceFlinger → HWC (composer) → Display. If a delay occurs at any stage, Systrace shows the exact cause: the application didn’t prepare the buffer in time, SurfaceFlinger was waiting for VSync, or HWC couldn’t composite the layers. Frame Lifecycle on the timeline is color-coded by status: green (on time), yellow (delayed), red (dropped). This visualization is the primary tool for optimizing UI performance.

Trace Categories

Systrace supports over 20 trace categories, each including a set of related events. Important categories include: gfx (graphics rendering), input (input processing), view (View system), webview (WebView), power (power consumption), hal (hardware abstraction layer). For game profiling, the gfx category with GPU command detail via AGI (Android GPU Inspector) is useful.

Key Features of Systrace

Systrace provides a unique set of capabilities for Android that are unavailable in other profilers: system timeline, kernel-level metrics, and automatic problem detection.

Interactive Timeline

The Systrace HTML report contains a multi-level timeline where each lane corresponds to one process or thread. You can zoom in and out on the time scale, click on events to view details (duration, initiating process, additional arguments). Color coding helps you quickly navigate: green blocks — process running, blue — waiting, orange — interrupt, white — idle.

Alert Messages

Systrace automatically analyzes the trace and displays Alert messages indicating problem areas. For example: Buffer underrun — SurfaceFlinger didn’t receive the buffer before VSync or Long Binder transaction — 42 ms in thread Binder_1. Each alert contains a link to the corresponding section of the timeline and a recommendation for fixing the issue. This saves hours of manual analysis and is one of the main reasons to use Systrace instead of manual logging.

Trace.beginSection Method

Developers can add custom tags to the Systrace trace using the Trace.beginSection and Trace.endSection API. This allows you to trace the execution of critical code sections directly on the system timeline — for example, marking the start and end of data loading or layout calculation. The tags appear as separate blocks on the application lane and are visible alongside system events.

How to Run Systrace

Running Systrace is possible in two ways: via the Android Studio CPU Profiler (Trace System Calls mode) or via the command line using the systrace.py Python script from the platform-tools folder. Each method has its own use cases.

Running via Android Studio

Connect the device, open the Profiler (View → Tool Windows → Profiler), select your process, go to the CPU tab, select Trace System Calls mode, and click Record. After 5–30 seconds, click Stop — Android Studio will launch Systrace on the device, wait for completion, and load the result. Limitation: recording is only possible while the Profiler is open, which is inconvenient for long scenarios or automation.

Running from the Command Line

For more flexible control, use the systrace.py script. Specify the trace categories, duration, and output file name. Example: capturing gfx, input, and sched data for 10 seconds. Running requires Python 2.7+ and a connected device with USB debugging enabled. On Android 12+, Systrace is replaced by Perfetto — the command remains the same, but the script redirects calls to perfetto.

# Basic systrace run for 10 seconds
$ python systrace.py \
    --time=10 \
    -o trace.html \
    gfx input sched

# Only gfx category for UI analysis
$ python systrace.py \
    --time=5 \
    -t gfx \
    -o ui_trace.html

Setting Up Custom Tags in Code

To make your code appear on the Systrace timeline, wrap the critical section with Trace.beginSection / Trace.endSection. It’s important that beginSection and endSection are strictly paired — otherwise Systrace will show an incorrect timeline. In Kotlin, it’s convenient to use an inline extension to guarantee section closure even in case of an exception.

import android.os.Trace

fun traceSection(name: String, block: () -> Unit) {
    Trace.beginSection(name)
    try {
        block()
    } finally {
        Trace.endSection()
    }
}

// Usage in code
traceSection("load_screen_data") {
    fetchData()
    updateUI()
}

Reading the Systrace HTML Report

The Systrace report is a self-contained HTML file that can be opened in Chrome, Edge, or Firefox. It contains an interactive timeline, a process selection panel, a list of alert messages, and key metrics (frame rate, CPU usage, binder transactions). Understanding the report structure is a key skill for effective profiling.

Timeline and Navigation

The timeline displays time from left to right. Each process and thread is a separate lane. W/S keys zoom in/out, A/D move through time. Select an area with the mouse to zoom in on a section. VSync lines show frame boundaries (every 16.6 ms at 60 FPS). If a full rendering cycle doesn’t fit between two VSync lines — the frame is dropped. Pay attention to the SurfaceFlinger lane: if it’s busy for a long time (orange block), layer composition is slowing down the overall rendering.

Analyzing Alert Messages

The Alerts panel on the left side of the report contains automatically detected problems. Each alert is clickable — clicking moves the timeline to the problematic moment. The most common alerts: Long Sync (long thread synchronization), Scheduling Delay (scheduler delay), Buffer Overrun (SurfaceFlinger buffer overflow). If an alert shows a value of ~100 ms for Scheduling Delay, it directly indicates that the UI thread was waiting for CPU due to background load — heavy computations should be moved to a Worker Thread.

Frame Lifecycle and Jank

To analyze dropped frames, enable the SurfaceFlinger and app.gfx lanes. Each frame is displayed as a rectangle: green (≤16 ms), yellow (16–32 ms), red (>32 ms). If you see a red rectangle on the app lane, click on it — Systrace will show which specific method (or system call) exceeded the limit. According to Google (Android Performance Patterns, 2023), 70% of jank problems are caused by slow onBindViewHolder or frequent GC.

Systrace vs Perfetto: Transitioning to the New Format

Perfetto is the successor to Systrace, introduced by Google in Android 9 (Pie) as an experimental tool and becoming the primary solution starting with Android 12. Perfetto uses a modern protobuf data format, supports long sessions (hours instead of seconds), and has a Web UI for viewing traces. Let’s examine the key differences between the two systems.

Despite the transition to Perfetto, Systrace skills remain relevant: on devices running Android 11 and below, it is used by default, and Perfetto maintains backward compatibility with Systrace categories. In Android Studio CPU Profiler, Perfetto is used for new devices and Systrace for older ones — transparent to the user. For CI/CD, Perfetto is recommended since its format can be automatically processed via Python and SQL.

Systrace Usage Examples

To practically master Systrace, let’s consider two scenarios: finding the cause of dropped frames during scrolling and diagnosing frequent GC that blocks the UI thread.

Finding Jank During RecyclerView Scrolling

Run Systrace with the gfx category for 10 seconds, scroll through the list in the app. In the report, find sections with red frames. Click on the problematic frame and look at the app lane — if there’s an inflateLayout or onBindViewHolder block wider than 16 ms, the problem is in layout inflation or data binding. Solution: optimize the layout (reduce deep ViewGroup, ViewStub), offload image loading to Glide with onAttachedToWindow.

Diagnosing GC Throughput

Systrace with freq and sched categories allows you to see how often GC cycles preempt the UI thread. Find the application lane on the timeline — if you see periodic blocks lasting 20–50 ms named Concurrent GC, the garbage collector is running too frequently. Add the dalvik category for detailed analysis. Solution: convert Bitmap to ByteBuffer, use an object pool (ObjectPool) for frequent allocations, reduce heap fragmentation via ART arguments.

# Run with categories for UI + GC analysis
$ python systrace.py \
    --time=15 \
    -o gc_analysis.html \
    gfx sched dalvik freq

# Capture with 30-second length for reproducible test
$ python systrace.py \
    --time=30 \
    --app=com.example.app \
    -o app_trace.html