Record traces

To start recording a trace, choose a recording configuration from either of the dropdown menus above or below the CPU Profiler and click Record.

Figure 1. The CPU Profiler displays the status, duration, and type of recording being made.

Interact with your app, and then click Stop when you're done. The profiler automatically displays its tracing information in the trace pane, as shown in Figure 2.

Figure 2. The CPU Profiler after recording a method trace.

1. Selected range: Determines the portion of the recorded time to inspect in the trace pane. When you first record a trace, the CPU Profiler automatically selects the entire length of your recording in the CPU timeline. To inspect trace data for only a portion of the recorded time range, drag the edges of the highlighted region.
2. Interaction section: Displays user interaction and app lifecycle events along a timeline.
3. Threads section: Displays thread state activity (such as running, sleeping, etc.) and Call Chart (or trace event chart in System Trace) for every thread along a timeline.
   • Use mouse and keyboard shortcuts to navigate the timeline.
   • Double-click the thread name or press Enter while a thread is selected to expand or collapse a thread.
   • Select a thread to see additional information in the Analysis pane. Hold Shift or Ctrl (Command on Mac) to select multiple threads.
   • Select a method call (or trace event in System Trace) to see additional information in the Analysis pane.
4. Analysis pane: Displays trace data for the time range and thread or method call you have selected. In this pane, you can select how to view each stack trace (using the analysis tabs) and how to measure execution time (using the time reference dropdown menu).
5. Analysis pane tabs: Choose how to display trace details. For details about each option, see Inspect traces.
6. Time reference menu: Select one of the following to determine how timing information for each call is measured (only supported in Sample/Trace Java Methods):
   • Wall clock time: Timing information represents actual elapsed time.
   • Thread time: Timing information represents actual elapsed time minus any portion of that time when the thread is not consuming CPU resources. For any given call, its thread time is always less than or equal to its wall clock time. Using thread time gives you a better understanding of how much of a thread’s actual CPU usage is consumed by a given method or function.
7. Filter: Filters trace data by function, method, class, or package name. For example, if you want to quickly identify trace data related to a specific call, type the name in the search field. In the Flame chart tab, call stacks that include a call, package, or class that matches the search query are emphasized. In the Top down and Bottom up tabs, those call stacks are prioritized over other trace results. You can also enable the following options by checking the appropriate box next to the search field:
   • Regex: To include regular expressions in your search, use this option.
   • Match case: If your search is case-sensitive, use this option.

Choose a recording configuration

Before you begin recording trace information, choose the appropriate recording configuration for the profiling information that you want to capture:

• Sample Java Methods: Captures your app’s call stack at frequent intervals during your app’s Java-based code execution. The profiler compares sets of captured data to derive timing and resource usage information about your app’s Java-based code execution.

  An inherent issue of sampled-based tracing is that if your app enters a method after a capture of the call stack and exits the method before the next capture, that method call is not logged by the profiler. If you are interested in tracing methods with such short lifecycles, you should use instrumented tracing.

• Trace Java Methods: Instruments your app at runtime to record a timestamp at the beginning and end of each method call. Timestamps are collected and compared to generate method tracing data, including timing information and CPU usage.

  Note that the overhead associated with instrumenting each method impacts runtime performance and may influence profiling data; this is even more noticeable for methods with relatively short lifecycles. Additionally, if your app executes a large number of methods in a short time, the profiler may quickly exceed its file size limit and may not be able to record any further tracing data.

• Sample C/C++ Functions: Captures sampled traces of your app’s native threads. To use this configuration, you must deploy your app to a device running Android 8.0 (API level 26) or higher.

  Internally, this configuration uses simpleperf to trace your app's native code. If you want to specify additional options for simpleperf, such as sampling specific device CPUs or specifying sampling durations at a high accuracy, you can use simpleperf from the command line.

• Trace System Calls: Captures fine-grained details that allow you to inspect how your app interacts with system resources. You can inspect exact timings and durations of your thread states, visualize where your CPU bottlenecks are across all cores, and add custom trace events to analyze. Such information can be crucial when you are troubleshooting performance issues. To use this configuration, you must deploy your app to a device running Android 7.0 (API level 24) or higher.

  While using this trace configuration, you can visually mark important code routines in the profiler timeline by instrumenting your code. To instrument C/C++ code, use the native tracing API provided by trace.h. To instrument Java code, use the Trace class. For more information, see Instrument your app code.

  This trace configuration is built on systrace. You can use the systrace command-line utility to specify options beyond those provided in the CPU Profiler. The additional system-level data provided by systrace can help you to inspect native system processes and troubleshoot dropped or delayed frames.

  On devices running Android 9 (API level 28) or higher, you can use a system app called System Tracing to record system traces on a device.

Create, edit, or view a recording configuration

You create, edit, and view recording configurations in the CPU Recording Configurations dialog, which you open by selecting Edit configurations from the recording configurations dropdown menu at the top of the CPU Profiler.

To view the settings of an existing recording configuration, select it in the left pane of the CPU Recording Configurations dialog.

To create a new recording configuration, do the following:

1. Click Add at the top-left of the dialog. This creates a new configuration with some default settings.
2. Name your configuration.
3. Select a Trace Technology.
4. For sampled recording configurations, specify the Sampling interval in microseconds (μs). This value represents the time between each sample of your app’s call stack. The shorter the interval you specify, the faster you reach the file size limit for the recorded data.
5. Specify the File size limit, in megabytes (MB), for the recorded data that’s written to the connected device. When you stop recording, Android Studio parses this data and displays it in the profiler window. So, if you increase the limit and record a large amount of data, Android Studio takes much longer to parse the file and may become unresponsive.

   Note: If you use a connected device running Android 8.0 (API level 26) or higher, there is no limit on the file size of the trace data, and this value is ignored. However, you still need to be careful about how much data the device collects after each recording—Android Studio may have difficulty parsing large trace files. For example, if you’re recording either a sampled trace with a short sampling interval or an instrumented trace while your app calls many methods in a short time, you’ll generate large trace files quickly.

6. To accept the changes and continue making changes to other configurations, click Apply. To accept all applied changes and close the dialog, click OK.

Record CPU activity with the Debug API

You can use the Debug API to give your app the ability to start and stop the recording of CPU activity in the CPU Profiler.

The CPU Profiler begins recording when your app calls startMethodTracing(String tracePath), and the CPU Profiler stops recording when your app calls stopMethodTracing(). While recording CPU activity that’s triggered using this API, the CPU profiler shows Debug API as the active CPU recording configuration.

To control the recording of CPU activity with the Debug API, deploy your instrumented app to a device running Android 8.0 (API level 26) or higher. API-initiated recording is supported in profileable apps, however Android Studio profilers require a debuggable app to display the recording status in the UI.

For more information, see Generate trace logs by instrumenting your app.

Record CPU activity during app startup

To begin recording CPU activity automatically during app startup, do the following:

1. Select Run > Edit Configurations.
2. In the Profiling tab, check the box next to Start recording a method trace on startup.
3. Select a CPU recording configuration from the menu.
4. Click Apply.
5. Deploy your app to a device running Android 8.0 (API level 26) or higher by selecting Run > Profile.