Trace an Android application
Overview Before you begin Configure your device Capture a trace Related information
Overview
This tutorial describes how to use Arm Graphics Analyzer to capture a graphics trace of a debuggable application running on an Android device with a Mali GPU.
Choose Next to browse through the steps as you work through them, or choose Single Page to view all the steps on one page.
Before you begin
On your host machine:
- Download and install the Arm Mobile Studio package appropriate to your host platform (Windows, Linux, or macOS).
- Install Android Debug Bridge (ADB). ADB is available with the Android SDK platform tools.
- Edit your
PATH
environment variable to add the path to the Android SDK platform tools directory.
You can also set the path to Android Debug Bridge in Graphics Analyzer. Select Edit > Preferences and select Browse in the Path to ADB field to locate theadb
executable.
Configure your device
- Ensure Developer Mode is enabled, then enable USB Debugging using Settings > Developer options.
- Connect the device to your host machine. To test the connection, run the
adb devices
command in a terminal window on the host, which should return the ID of your device.adb devices List of devices attached ce12345abcdf1a1234 device
If
adb devices
does not work, check that you have installed Android Debug Bridge correctly, see Before you begin. - The device must be able to use TCP/IP on port 5002 to communicate with the host. Make sure that this port is not in use.
- The application you want to trace must be debuggable. For example, in Unity applications, select the Development Build checkbox in the Build Settings when you build your application.
Prepare your application
If you're using Unity or Unreal Engine to build your application, follow the instructions here instead:
To enable Graphics Analyzer to perform a trace on devices running Android 9 or earlier, you need to add the Arm interceptor library to your application. Graphics Analyzer uses this library to collect information about the graphics API calls made by your application.
Note: This step is only necessary for devices running Android 9 or earlier. For Android 10 devices Graphics Analyzer can use GLES layers or Vulkan validation layers to collect information from the device. You can ignore this step and go straight to Capture a trace.
- Specify the location of the interceptor library,
libAGA.so
, in the module’sbuild.gradle
file by adding the following line to the SourceSetmain
:
jniLibs.srcDirs += ['<install_dir>/graphics_analyzer/target/android/arm/unrooted/']
For example:sourceSets {
main {
manifest.srcFile 'AndroidManifest.xml'
resources.srcDirs = ['res']
res.srcDirs = ['res']
assets.srcDirs = ['assets']
java.srcDirs = ['src']
jniLibs.srcDirs += ['/Applications/Arm_Mobile_Studio_2020.0/graphics_analyzer/target/android/arm/unrooted/']
}
}Note: Specify theunrooted
directory, not the subdirectory that contains the library. - Ensure that the
abiFilters
property in the module’sbuild.gradle
file is set to a value that the interceptor supports; eitherarmeabi-v7a
,arm64-v8a
, or both. For example:
android {
compileSdkVersion 28
buildToolsVersion "28.0.3"
defaultConfig {
minSdkVersion 9
targetSdkVersion 28
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
} - Enable the interceptor by adding a Java component to the application to be traced to enable it to load the interceptor library. The details of this step depend on the type of application.
For applications that use C or C++ only:- Create a new
Activity
class that extendsandroid.app.NativeActivity
. - Reference this new
Activity
in yourAndroidManifest.xml
as theandroid:name
attribute of theactivity
element. - Ensure that the
android:hasCode
attribute of the application element is set to true, otherwise the Java file will not be included in the APK.
static
{
try
{
System.loadLibrary("GA");
}
catch (UnsatisfiedLinkError e)
{ // Feel free to remove this log message.
Log.e("[GA]", "GA not loaded: " + e.getMessage());
Log.d("[GA]", Log.getStackTraceString(e));
}
}Note: For more information about this step, see the Target installation section of the Graphics Analyzer User Guide. - Create a new
- Recompile the application and install it on the target device.
Prepare your Unity application
If your application is built using Unity, follow these steps to prepare your application for tracing:
- Check your SDK and NDK versions
- Add the interceptor library to your project (Android 9 or earlier)
- Player and build settings
Check your SDK and NDK versions
Check that you are using the Unity recommended Android SDK and Android NDK versions in the Unity editor.
- On Windows and Linux, select Edit > Preferences > External Tools.
- On macOS, select Unity > Preferences > External Tools.
If the checkboxes are selected, they are installed. Otherwise, you can add them as modules. See https://docs.unity3d.com/Manual/android-sdksetup.html for more information.
Add the interceptor library to your project
To enable Graphics Analyzer to trace your application on devices running Android 9 or earlier, you need to add the Arm interceptor library to your Unity project. The interceptor library intercepts and collects information about the OpenGL ES and EGL function calls made by the application. Unity detects the presence of the interceptor library and automatically loads it when you build the application. Follow these steps to add the library and set Unity’s player and build settings to use it.
The library libMGD.so
is provided in your Arm Mobile Studio package:
<install_directory>/graphics_analyzer/target/android/arm/unrooted/
Two versions of the library are provided:
- For 64-bit applications, use the library file located in the
arm64-v8a
directory. - For 32-bit applications, use the library file located in the
armeabi-v7a
directory.Note: You can package one or both interceptor libraries depending on the requirements of your application.
- Copy the required interceptor library,
libMGD.so
, into the Unity project directoryAssets/Plugins/Android/
, creating this directory if it does not already exist.
If you are packaging both interceptor libraries:- Create two directories in the
Assets/Plugins/
directory. For example,armv7
andarmv8
. - Create a directory called Android in each of these directories.
- Copy each
libMGD.so
file into the appropriateAndroid
directory.
- Create two directories in the
- Select the library in Unity and set the following attributes in the Inspector:
- Under Select platforms for plugin, select Android
- Under Platform settings, set the CPU architecture to ARM64 for 64-bit applications, or ARMv7 for 32-bit applications.
- Click Apply.
Player and build settings
Set the following in Unity to build a debuggable application that Graphics Analyzer can trace.
- Select File > Build Settings, then select Player Settings.
- Under Identification, set Target API Level to the required Android version.
Note: By default, Target API Level is set to the latest version of the Android SDK tools that you have installed. If you change to a lower API level, ensure that you have the SDK tools for that version installed, and be aware that if you want to build for a higher API version later, you will need to change this setting accordingly.
- Under Configuration, set the following options to build a 64-bit application:
- Set the scripting backend in Unity to work with 64-bit targets. SetScripting Backend to IL2CPP. For more information about IL2CPP, refer to the Unity documentation.
- Under Target Architectures, select ARM64.
To build a 32-bit application:- Leave the scripting backend at its default setting, Mono.
- Under Target Architectures, select ARM7.
- Close the Player Settings. In the Build Settings, select the Development Build checkbox. This option ensures that your application is marked as debuggable in the Android application manifest.
- Select Build and Run to build your APK and install it on your device in one step. Alternatively, select Build to build the APK and then install it on your device using Android Debug Bridge:
adb install -r YourApplication.apk
Prepare your Unreal Engine application
Note: This step is only necessary for devices running Android 9 or earlier. For Android 10 devices Graphics Analyzer can use GLES layers or Vulkan validation layers to collect information from the device. You can ignore this step and go straight to Capture a trace.
To enable Graphics Analyzer to trace your application, you need to enable Graphics Analyzer in your Unreal Engine project:
- Open your Unreal Engine project.
- Open the Project Settings window.
- Under Platforms, select Android.
- On the right-hand side, under Graphics Debugger, select Mali Graphics Debugger from the Android Graphics Debugger drop-down list.
Note: Mali Graphics Debugger is the old name for Graphics Analyzer. - In the Mali Graphics Debugger Path field, enter the path to the Graphics Analyzer folder in the Arm Mobile Studio installation directory:
<install_directory>/graphics_analyzer
Capture a trace
Connect to your device and start the capture in Graphics Analyzer.
- Launch Graphics Analyzer:
- On Windows, open the Windows Start menu, navigate to the Arm Mobile Studio folder, and select the Graphics Analyzer shortcut.
- On macOS, use Spotlight to search for Graphics Analyzer or go to the
<install_directory>/graphics_analyzer/gui
folder, and double-click theGraphics Analyzer.app
file. - On Linux, navigate to the location where you extracted the package, go to the
graphics_analyzer/gui
directory, and run theaga
file.cd <install_directory>/graphics_analyzer/gui
./aga
- Select Open the Device Manager from the Debug menu.
- Select your connected device from the list of Android devices.
- Select the application you want to debug
- Select Trace Activity.
Graphics Analyzer connects to your device and installs the layer driver and daemon application that it uses to communicate with it. - Optionally, select Trace Config and select which API assets are captured. Only enable the asset types you need. The more asset types you enable, the slower the application will run, the more memory is required, and the generated trace file will be larger.
- Perform your test scenario on the device. Graphics Analyzer displays the trace data as it receives it from the device.
- When you get to a problem area, use the pause, step and play buttons to locate a frame that you want to analyze more closely:
- Click the camera icon
to capture the frame buffer output at the current frame.
- Optionally, capture extra frame data by enabling the following modes:
- Overdraw
- Shader map
- Fragment count
to collect the data.
- Overdraw
- To stop tracing, click
.
All the frames are listed in the Trace Outline view. The frames where you've captured extra data are shown with an icon, to identify the type of frame capture you performed. - To filter the frames to just those where you've captured extra data, use the Show Only Frames With Features Enabled option
- Expand a frame to see the renderpasses and draw calls within it.
- Select frames, renderpasses and draw calls to explore their data. Refer to the Graphics Analyzer user guide information about the different data views.
- Save or export the trace file, using options under the File menu.