After building features, eliminating bugs and cleaning up your code, you should spend some + time looking at the performance of your application. The speed and smoothness with which your + application draws pixels and performs operations has an significant impact on your users' + experience.
+ +Android applications operate within a shared resource environment, and the performance of + your application can be impacted by how efficiently it interacts with those resources in + the larger system. Applications also operate in a multithreaded environment, competing with other + threaded processes for resources, which can cause performance problems that are hard to diagnose. +
+ +The {@code systrace} tool allows you to collect and review code execution data for your + application and the Android system. You can use this data to diagnose execution problems and + improve the performance of your application.
+ + +{@code systrace} helps you analyze how the execution of your application fits into the larger + Android environment, letting you see system and applications process execution on a common + timeline. The tool allows you to generate highly detailed, interactive reports from devices + running Android 4.1 and higher, such as the report in figure 1.
+ +
++ Figure 1. An example {@code systrace} report on 5 seconds of process execution + for a running application and related Android system processes. +
+ + +In order to create a trace of your application, you must perform a few setup steps. First, you + must have a device running Android 4.1 or higher. Setup the device for + debugging, connect it to your development + system and install your application. Some types of trace information, specifically disk activity + and kernel work queues, require root access to the device, but most {@code systrace} log data + only requires that the device be enabled for developer debugging.
+ + +The {@code systrace} tool can generate a potentially huge amount of data from applications + and system sources. To limit the amount of data the tool collects and make the data more relevant + to your analysis, use the following options:
+ +To use {@code systrace} effectively, you must specify the types of processes you want to trace. + The tool can gather the following types of process information:
+ +To set trace tags for {@code systrace} using the command-line:
+ ++$> python systrace.py --set-tags=gfx,view,wm ++
+$> adb shell stop +$> adb shell start +
To set trace tags for {@code systrace} using the device user interface:
+ ++ Note: The {@code adb} shell does not have to be stopped and restarted when + selecting trace tags using this method. +
+ + +After you have configured the category tags for your trace, you can start collecting + information for analysis.
+ +To run a trace using the current trace tag settings:
+ ++$> python systrace.py --cpu-freq --cpu-load --time=10 -o mytracefile.html ++
After you have generated a trace using {@code systrace}, it lists the location of the output + file and you can open the report using a web browser. + How you use the trace data depends on the performance issues you are investigating. However, + this section provides some general instructions on how to analyze a trace.
+ +The reports generated by {@code systrace} are interactive, allowing you to zoom into and out of + the process execution details. Use the W key to zoom in, the S + key to zoom out, the A key to pan left and the D key to pan + right. Select a task in timeline using your mouse to get more information about the task. + For more information about the using the keyboard navigation shortcuts and navigation, see the + Systrace reference + documentation.
+ +A well-behaved application executes many small operations quickly and with a regular rhythm, + with individual operations completing within few milliseconds, depending on the device + and the processes being performed, as shown in figure 2:
+ +
++ Figure 2. Excerpt from a trace of a smoothly running application with a regular + execution rhythm. +
+ +The trace excerpt in figure 2 shows a well-behaved application with + a regular process rhythm (1). The lower section of figure 2 shows a magnified section of + the trace indicated by the dotted outline, which reveals some irregularity in the process + execution. In particular, one of the wider task bars, indicated by (2), is taking slightly + longer (14 milliseconds) than other, similar tasks on this thread, which are averaging between + 9 and 12 milliseconds to complete. This particular task execution length is likely not noticeable + to a user, unless it impacts another process with specific timing, such as a screen update.
+ +Long running processes show up as thicker than usual execution bars in a trace. These thicker + bars can indicate a problem in your application performance. When they show up in your + trace, zoom in on the process using the + keyboard navigation shortcuts to + identify the task causing the problem, and click on the task to get more information. You should + also look at other processes running at the same time, looking for a thread in one process that is + being blocked by another process.
+ + +The {@code systrace} tool is particularly useful in analyzing application display slowness, + or pauses in animations, because it shows you the execution of your application across multiple + system processes. With display execution, drawing screen frames with a regular rhythm is essential + for good performance. Having a regular rhythm for display ensures that animations and motion are + smooth on screen. If an application drops out of this rhythm, the display can become jerky or slow + from the users perspective.
+ +If you are analyzing an application for this type of problem, examine the + SurfaceFlinger process in the {@code systrace} report where your application is + also executing to look for places where it drops out of its regular rhythm.
+ +
++ Figure 3. Excerpt from a trace of an application showing interruptions in + display processing. +
+ +The trace excerpt in figure 3 shows an section of a trace that indicates an interruption in the + device display. The section of the SurfaceFlinger process in top excerpt, + indicated by (1), shows that display frames are being missed. These + dropped frames are potentially causing the display to stutter or halt. Zooming into this problem + area in the lower trace, shows that a memory operation (image buffer dequeuing and allocation) in + the surfaceflinger secondary thread is taking a long time (2). This delay + causes the application to miss the display update window, indicated by the dotted + line. As the developer of this application, you should investigate other threads in your + application that may also be trying to allocate memory at the same time or otherwise blocking + memory allocation with another request or task.
+ +Regular, rhythmic execution of the SurfaceFlinger process is essential to smooth + display of screen content, particularly for animations and motion. Interruptions in the regular + execution pattern of this thread is not always an indication of a display problem with your + application. Further testing is required to determine if this is actually a performance problem + from a user perspective. Being able to identify display execution patterns like the example above + can help you detect display problems and build a smooth-running, high-performance application. +
+ ++ Note: When using {@code systrace} to analyze display problems, make sure + you activate the tracing tags for Graphics and Views. +
+ +For more information on the command line options and keyboard controls for {@code systrace}, +see the Systrace reference page.
\ No newline at end of file diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd index 447d39cf50739..0f943956a53db 100644 --- a/docs/html/tools/help/index.jd +++ b/docs/html/tools/help/index.jd @@ -55,6 +55,9 @@ outside of Android code.The {@code systrace} tool helps analyze the performance of your application by capturing and + displaying execution times of your applications processes and other Android system processes. The + tool combines data from the Android kernel such as the CPU scheduler, disk activity and + application threads to generate an HTML report that shows an overall picture of an Android + device’s system processes for a given period of time.
+ +The {@code systrace} tool is particularly useful in diagnosing display problems where an + application is slow to draw or stutters while displaying motion or animation. For more information + on how to use {@code systrace}, see Analyzing + Display and Performance with Systrace.
+ + +In order to run {@code systrace}, the {@code adb} tool and +Python must be installed and included in your development +computer's execution path. In order to generate a trace, you must connect a device running Android +4.1 (API Level 16) or higher to your development system using a USB debugging connection.
+ +The syntax for running {@code systrace} is as follows.
+ ++$> python systrace.py [options] ++ +
Here is an example execution run that sets trace tags and generates a trace from a connected +Android device.
+ ++$> cd android-sdk/tools/systrace +$> python systrace.py --set-tags gfx,view,wm +$> adb shell stop +$> adb shell start +$> python systrace.py --disk --time=10 -o mynewtrace.html ++ + + +
The table below lists the command line options for {@code systrace}.
+ +| Option | + +Description | +
|---|---|
-o <FILE> |
+
+ Write the HTML trace report to the specified file. | +
-t N, --time=N |
+
+ Trace activity for N seconds. Default value is 5 seconds. | +
-b N, --buf-size=N |
+
+ Use a trace buffer size of N kilobytes. This option lets you limit the total size of the + data collected during a trace. | +
-d, --disk |
+
+ Trace disk input and output activity. This option requires root access on the device. | +
-f, --cpu-freq |
+
+ Trace CPU frequency changes. Only changes to the CPU frequency are logged, so the initial + frequency of the CPU when tracing starts is not shown. | +
-i, --cpu-idle |
+
+ Trace CPU idle events. | +
-l, --cpu-load |
+
+ Trace CPU load. This value is a percentage determined by the interactive CPU frequency + governor. | +
-s, --no-cpu-sched |
+
+ Prevent tracing of the CPU scheduler. This option allows for longer trace times by reducing + the rate of data flowing into the trace buffer. | +
-w, --workqueue |
+
+ Trace kernel work queues. This option requires root access on the device. | +
--set-tags=<TAGS> |
+
+ Set the enabled trace tags in a comma separated list. The available tags are:
+
Note: When setting trace tags from the command line, you + must stop and restart the framework ({@code $> adb shell stop; adb shell start}) for the + tag tracing changes to take effect. + |
+
--link-assets |
+
+ Link to the original CSS or JS resources instead of embedding them in the HTML trace + report. | +
-h, --help |
+
+ Show the help message. | +
You can set the trace tags for {@code systrace} with your device's user +interface, by navigating to Settings > Developer options > Monitoring > Enable +traces.
+ + +The table below lists the keyboard shortcuts that are available while viewing a {@code systrace} +trace HTML report.
+ +| Key | + +Description | +
|---|---|
| w | + +Zoom into the trace timeline. | +
| s | + +Zoom out of the trace timeline. | +
| a | + +Pan left on the trace timeline. | +
| d | + +Pan right on the trace timeline. | +
| e | + +Center the trace timeline on the current mouse location. | +
| g | + +Show grid at the start of the currently selected task. | +
| Shift+g | + +Show grid at the end of the currently selected task. | +
| Right Arrow | + +Select the next event on the currently selected timeline. | +
| Left Arrow | + +Select the previous event on the currently selected timeline. | +
| Double Click | + +Zoom into the trace timeline. | +
| Shift+Double Click | + +Zoom out of the trace timeline. | +