All content in this course uses:

Profile CPU performance in Android builds with Android Studio

While the Unity Profiler is the best choice for initial, coarse-grained performance profiling, developers on mobile projects may require greater granularity than the Unity Profiler can provide. In this tutorial, you will learn how to profile using Android Studio’s CPU profiling tools in order to track down CPU performance issues at runtime. 

While the Unity Profiler is the best choice for initial, coarse-grained performance profiling, developers on mobile projects may require greater granularity than the Unity Profiler can provide. For example, user code being executed in MonoBehaviour.Update callbacks is not instrumented and therefore will not be marked up. Users can therefore not easily determine bottlenecks in C# code using the Unity Profiler.

Bottlenecks are different in all Unity projects, and profiling is the key to determining and fixing performance issues. If you’re seeing performance issues in your Android application that is built with Unity, follow this tutorial and try Android Studio for yourself.

Android Studio’s CPU profiling tools are very useful for tracking down CPU performance issues at runtime. The two main CPU profiling recording methods explored in this tutorial are System Trace Recording and Callstack Sample Recording. These two methods are complementary to one another and serve different purposes.

System Trace Recording displays instrumentation data to the user, similarly to the Unity Profiler. It can additionally be used to better understand thread execution per CPU core.

Callstack Sample Recording displays sampling data to the user. This recording method shows detailed call stacks that have been sampled across threads during execution.

Please refer to Android Studio’s documentation on 

 for more details. For a summary of profiling-related topics, such as instrumentation and sampling, see Wikipedia’s article on 

Overview

This tutorial assumes that you already have a completed mobile project in Unity that you are ready to profile. In addition, this tutorial assumes that you are working with the following software and hardware:

Android device with Android 8 (API 26) or newer with 64-bit architecture

  If needed, download and install Android Studio. You can use Android Studio’s documentation on how to

  Open your Unity project and ensure that it’s in a state that is ready to be published and profiled.

Before you begin

Several settings must be set correctly in your Unity project in order to successfully profile an Android build in Android Studio.

Reviewing your Player Settings will ensure that your build uses the IL2CPP scripting backend. Builds that use IL2CPP can be profiled in Android Studio.

  Open the Project Settings window by navigating to

. (ARMv7 can also be used by Android Studio, but it is less reliable when used with Android devices that have ARMv7 architecture).

Prepare an Android build of your project

Reviewing Build Settings will ensure that your build is connectable and profileable in Android Studio with as little overhead as possible. To format your settings: 

With Build Settings properly configured, select 

. Once completed, you will have an Android Package file (APK) and a symbols.zip archive on disk.

Build Settings

A Unity Player built with Development Build enabled will result in the debuggable flag being enabled in the AndroidManifest.xml. This AndroidManifest.xml is then used during the Unity build process for Android. When this debuggable flag is enabled for an APK, Android Studio’s profiling tools can be used to profile the application at runtime. To learn more about Android debugging capabilities, consult Android’s 

Android Studio allows users to profile pre-built debuggable APKs without having to export an Android Studio project from Unity. This feature is very useful, as it does not disrupt the Unity project’s build process.

To create an Android Studio project from your APK:

  Navigate to where you saved the build files from the previous step.

 that was created alongside the Android APK.

  Open Android Studio. When presented with the project launcher, select the 

You will be presented with the following screen:

 from the folder where you extracted the 

If symbols have been resolved correctly, you will be presented with the following screen:

: If you see an error stating that the SDK Platform was not installed, select the popup that appears and reads “Install missing platform and fix project”. Once updated, move on to the next step.

At this point you are ready to profile CPU usage using Android Studio. Please refer to Android Studio’s documentation on how to 

Set up the Android Studio project

Android Studio allows you to attach its profiler to a running debuggable application. Android Studio also allows the profiler to automatically attach to an application launched via the 

: Before connecting the Android Studio profiler, ensure that no other processes are making use of Android Debug Bridge (adb). To learn more about adb, consult the 

Attaching to a running debuggable application

To attach to a running debuggable application:

to open Android Studio’s profiler window.

  Connect your device to your computer and then run the application on your device.

  Ensure your device is unlocked. Select 

) on the left sidebar in Android Studio, select your connected device, followed by the bundle identifier of your running application.

If you are properly connected to your running application, Android Studio will display the different profiling modules available to you and a graph representing an overview of data being streamed to Android Studio in realtime.

Android Studio’s Profile button in the toolbar will install and launch your APK on a connected device. Android Studio will then automatically connect the profiler to the launched application. If your prebuilt APK has already been installed on the connected device, installation will be skipped.

Connecting the profiler

Android Studio offers two recording methods that are very helpful to determine CPU performance bottlenecks in Unity Android builds:

: Uses sampling to capture call stacks being executed by your application’s java and native threads. This mode is especially useful when used to determine the cause of unoptimized user code that is not fully instrumented.

: Uses instrumentation to capture the time spent in code that has been instrumented. When running a development build, Android Studio will show all the same markers that are visible in the Unity Profiler. Additionally, a system trace recording can also show which threads were run on a given CPU core at a given time. To learn more, consult Android Studio's 

  Select the CPU profiling module displaying the realtime CPU activity graph. You will then be presented with several recording methods.

 depending on the type of data you wish to analyze. 

. When recording is in process, the CPU chart will begin to highlight the area being recorded. 

  When sufficient data has been collected, select 

, Android Studio may seem to be idling as it is parsing your recording. The time spent parsing the recording is linearly proportional to the amount of data that was captured.

When a Callstack Sample Recording ends, you will be presented with this screen:

When a System Trace Recording ends, you will be presented with this screen:

Refer to the Android Studio’s documentation on 

 for more details around Android Studio’s tracing capabilities and a detailed explanation of Android Studio’s profiler UI.

 has an in-depth explanation of the different views that can be used to inspect traces captured with the Android Studio’s CPU profiler.

Capturing data

In this tutorial you have learned how to prepare an Android build in Unity that can be used to record CPU usage data using Android Studio’s CPU profiler module. The two CPU recording modes covered, Callstack Sample Recording and System Trace Recording, allow you to capture different types of data that can help you find performance bottlenecks in your application.

Conclusion

Internal Training Resources

Please refer to Android Studio’s documentation on The Android Profiler for more details. For a summary of profiling-related topics, such as instrumentation and sampling, see Wikipedia’s article on Profiling.

1.  If needed, download and install Android Studio. You can use Android Studio’s documentation on how to Install Android Studio for help with this.

2.  Open your Unity project and ensure that it’s in a state that is ready to be published and profiled.

1.  Open the Project Settings window by navigating to Edit > Project Settings.

2.  Open the Scripting Backend dropdown and select IL2CPP.

3.  Open the C++ Compiler Configuration dropdown and select Release.

4.  Under Target Architectures, enable ARM64. (ARMv7 can also be used by Android Studio, but it is less reliable when used with Android devices that have ARMv7 architecture).

1.  Select File > Build Settings to open the Build Settings window.

2.  Under Platform, select Android and select Switch Platform at the lower-right of the window.

3.  Under Android Settings, disable Export Project.

With Build Settings properly configured, select Build. Once completed, you will have an Android Package file (APK) and a symbols.zip archive on disk.

A Unity Player built with Development Build enabled will result in the debuggable flag being enabled in the AndroidManifest.xml. This AndroidManifest.xml is then used during the Unity build process for Android. When this debuggable flag is enabled for an APK, Android Studio’s profiling tools can be used to profile the application at runtime. To learn more about Android debugging capabilities, consult Android’s Debug your app documentation.

1.  Navigate to where you saved the build files from the previous step.

2.  Unzip the symbols.zip that was created alongside the Android APK.

3.  Open Android Studio. When presented with the project launcher, select the More menu (⋮) and then select Profile or Debug APK.

5.  Add symbols for libil2cpp.so. Select Select library to add debug symbols and select libil2cpp.so.

7.  Select libil2cpp.dbg.so from the folder where you extracted the symbols.zip archive.

Note: If you see an error stating that the SDK Platform was not installed, select the popup that appears and reads “Install missing platform and fix project”. Once updated, move on to the next step.

At this point you are ready to profile CPU usage using Android Studio. Please refer to Android Studio’s documentation on how to Profile pre-built APKs for additional details. 

Android Studio’s welcome page after having clicked on the additional options button (three vertical dots) and having selected the Profile or Debug APK option.

Android Studio showing the project that was created by selecting the APK.

Android Studio with the Select library to add debug symbols and libil2cpp.so highlighted

Android Studio’s Debug Symbols view with the Add button highlighted.

Android Studio’s Debug Symbols selection view with the libil2cpp.dbg.so library selected.

Android Studio’s Debug Symbols view showing debug symbols resolved.

Android Studio allows you to attach its profiler to a running debuggable application. Android Studio also allows the profiler to automatically attach to an application launched via the Profile button.

Note: Before connecting the Android Studio profiler, ensure that no other processes are making use of Android Debug Bridge (adb). To learn more about adb, consult the Android Debug Bridge (adb) documentation.

1.  Select View > Tool Windows > Profiler to open Android Studio’s profiler window.

2.  Connect your device to your computer and then run the application on your device.

3.  Ensure your device is unlocked. Select Add (+) on the left sidebar in Android Studio, select your connected device, followed by the bundle identifier of your running application.

To begin the profiling process, select Profile.

Android Studio with the View > Tool Windows > Profiler menu highlighted and selected.

Android Studio’s Profiler panel with the + > [device name] > [APK bundle ID] menu highlighted and selected.

Android Studio’s Profiler panel connected to device with different module data (CPU, Memory, Energy) being streamed in.

Callstack Sample Recording: Uses sampling to capture call stacks being executed by your application’s java and native threads. This mode is especially useful when used to determine the cause of unoptimized user code that is not fully instrumented.

System Trace Recording: Uses instrumentation to capture the time spent in code that has been instrumented. When running a development build, Android Studio will show all the same markers that are visible in the Unity Profiler. Additionally, a system trace recording can also show which threads were run on a given CPU core at a given time. To learn more, consult Android Studio's Overview of system tracing.

1.  Select the CPU profiling module displaying the realtime CPU activity graph. You will then be presented with several recording methods.

2.  Select Callstack Sample Recording or System Trace Recording depending on the type of data you wish to analyze. 

3.  Select Record. When recording is in process, the CPU chart will begin to highlight the area being recorded. 

4.  When sufficient data has been collected, select Stop.

Note: When selecting Stop, Android Studio may seem to be idling as it is parsing your recording. The time spent parsing the recording is linearly proportional to the amount of data that was captured.

Refer to the Android Studio’s documentation on Record traces for more details around Android Studio’s tracing capabilities and a detailed explanation of Android Studio’s profiler UI.

Android Studio’s documentation on Inspect traces has an in-depth explanation of the different views that can be used to inspect traces captured with the Android Studio’s CPU profiler.

Android Studio’s Profiler panel connected to device with the CPU module highlighted.

Android Studio’s Profiler panel connected to device, the CPU module selected, with the Callstack Sample Recording toggle selected, and the Record button highlighted.

Android Studio’s Profiler panel connected to device, the CPU module selected, with the Callstack Sample Recording trace being captured, and the Stop button highlighted.

Android Studio’s Profiler panel showing a Callstack Sample Recording trace.

Android Studio’s Profiler panel showing a System Trace Recording trace.

Unity Version undefined