How to Customize Android Systrace with ftrace and Catapult for Deep Kernel Insights

Principle and Basic Process

Systrace is an Android performance‑debugging tool built on the Linux ftrace subsystem. It records both user‑space events (UI layout, rendering, binder calls) and kernel‑space events (CPU scheduling, I/O, interrupts). The data are merged into a single HTML trace file that can be opened with Chrome’s chrome://tracing viewer.

Specify trace categories and parameters to atrace. The tool writes the selected events to the ftrace buffer and produces an intermediate file atrace_raw.

Systrace augments the raw data with process‑task information (PID ↔︎ process name) and wraps the result with HTML templates ( prefix.html, systrace_trace_viewer.html, suffix.html) to generate a single trace file.

Chrome parses the generated HTML, categorises the events, aggregates them on a timeline and renders coloured blocks for visual analysis.

Implementation Details

All events are written to the unified trace marker node /sys/kernel/debug/tracing/trace_marker. User‑space code writes timestamped strings to this file; ftrace records the write time, enabling entry/exit timing for functions.

When a user selects a category (e.g., Input, Graphics), atrace activates the corresponding ATRACE_TAG_* flag and records the events to the same marker file.

Kernel‑space events require enabling specific tracepoint nodes. For example, to capture scheduling activity:

events/sched/sched_switch/enable
events/sched/sched_wakeup/enable

Enabling these nodes causes the kernel to emit sched_switch and sched_wakeup events into the ftrace buffer, which atrace later reads.

Adding a Custom Trace Category

Add a new category definition in frameworks/native/cmds/atrace/atrace.cpp (e.g., kernel_runqueue).

Create a corresponding kernel tracepoint (e.g., sched_rq_running) and expose its enable node under events/…/enable.

Rebuild the Android source tree so that the new category appears in the atrace command line options.

Select the new category when running atrace; the resulting trace.html will contain the custom events, but the default Chrome parser will not recognise them.

Extending the Catapult Parser for Custom Events

The open‑source Catapult project provides the JavaScript‑based tracing UI used by Chrome. Its source is hosted at: https://chromium.googlesource.com/catapult Custom parsers live in tracing/tracing/extras/importer/linux_perf. Existing examples include sched_parser.html (process scheduling) and power_parser.html (CPU frequency).

To visualise sched_rq_running events:

Create a new parser file, e.g., sched_rq_running_parser.html, and register a handler that interprets the custom event format.

Run tracing/tracing_build/generate_about_tracing_contents.py to regenerate about_tracing.html and tracing.js. Ensure the generated script name matches the one referenced in about_tracing.html.

Open the regenerated about_tracing.html (instead of chrome://tracing) and load the custom sched_rq_running.html trace. The new UI will render the custom kernel information.