How to Locally Capture a System Trace on Android Pie
Tracing is an invaluable tool that enables developers to understand the impact that various changes have on a system and can provide clues to identify the root cause of problems.
systrace is one such powerful tracing tool that collects timing information from processes running on an Android device. systrace was used extensively by the Android performance team at Google to optimize performance on the Google Pixel phones. I have used systrace to inspect the impact of kernel scheduler changes on task placements on CPUs, for example, and to identify possible causes of janks. systrace can capture a wide variety of data, including CPU scheduling, CPU frequency, disk I/O, graphics, Binder activity, and much more. The information is combined into a report that can be analyzed in Google Chrome.
Before Android Pie, the only way to capture traces with systrace was to hook up an Android device to a computer and run systrace from there—usually from a terminal. However, not everyone has constant access to a computer, or the knowledge and confidence to run systrace.
With the release of Android Pie, this inconvenience was addressed with the introduction of the Traceur package, which is a tool that captures raw trace data directly on an Android phone. Traceur is available as the “System Tracing” option in the Developer Options of the Settings app, and the raw trace data captured on the device by Traceur can at a later time be converted by systrace to an HTML report for analysis.
The new “System Tracing” option allows users to easily capture and share traces with developers, without needing to actually know how to run systrace on a computer. Developers benefit from the ability to capture traces without a computer and analyze later at their convenience. The complete raw trace data collected by “System Tracing” is also significantly smaller in size than the HTML report generated by systrace, which therefore makes the raw trace data more suitable for storing and sharing with others.
Guide: Collecting System and Analyzing System Traces
Firstly, ensure that you have a device running Android Pie and a computer with Python 2 installed. The following instructions were performed on a OnePlus 6 running the latest OxygenOS Android Pie beta.
- Enable Developer Options in the Settings app, and then access the “System Tracing” option within the “Debugging” section of Developer Options.
- Upon opening System Tracing, you will be presented a toggle to enable System Tracing, and the ability to customize the tracing categories and buffer size of the traces. For this demonstration, the default categories are used, which is sufficient for most cases. A “Show quick settings tile” toggle allows tracing to be started/stopped via Quick Settings. I have enabled this for this guide.
- To begin capturing a trace, tap on the recently added “Record trace” quick settings tile.
- When you are done tracing a test case, you may stop the tracing from the notification shade.
- Great! You have successfully captured a raw trace. A notification will prompt you to share the raw trace file. You should be able to save it to your device, upload it to online storage, email it to someone, etc. Alternatively, you can use ADB to directly pull the trace from your device to your computer (
adb pull /data/local/traces/). Go ahead and save the trace file to your computer.
- The raw trace file has the made-up .ctrace format. It cannot be interpreted in its raw form. We can use systrace to generate a more useful and understandable interactive HTML report from our raw trace file.
- We will use the latest version of systrace from the catapult project repo. In a terminal application, clone the repo (ensure git is installed):
git clone https://github.com/catapult-project/catapult.git
- To generate the HTML report from our raw trace file using systrace, enter the following commands:
python2 catapult/systrace/bin/systrace --from-file=<path to raw trace file>
- To view the HTML report, launch the Google Chrome browser and access the “chrome://tracing” URL. Do not open the HTML report directly in Google Chrome because it will appear blank.
- Click on the “Load” and open the HTML report file from the pop-up dialogue. Voila! Your trace report is now available for inspection.
Now that you are able to capture a trace and generate a systrace report, it is important to understand how to read and interpret the data presented in the report. For a start, I recommend reading “Understanding Systrace”, and watching “Android Performance: An Overview (Google I/O ‘17)” and “Systrace for Games” to see systrace in action.
This is a guest post that was originally written by Josh Choo, also known as XDA Recognized Developer joshuous. The post was lightly edited for formatting.