Skip to main content

Tracing

The Tracing API offers a detailed overview of the operations performed by the Maps SDK. The tracing information includes style loading, tile parsing, and rendering events. Notably, the Tracing API is efficiently integrated with Android system tracing tools, ensuring a streamlined workflow for developers.

How to enable tracing​

Mapbox Maps SDK for Android allows enabling additional Mapbox traces that could be of help troubleshooting performance issues.

It is recommended to use the release build variant of your app with profileable enabled. See the Android documentation for more information on how to build such variant.

Configure tracing components​

There are 2 types of traces that could be enabled:

  • Native rendering engine traces could be enabled with MapboxTracing.enableCore(). Those traces include native render calls, style loading, requesting tiles and more.
  • Android platform traces could be enabled with MapboxTracing.enablePlatform(). Those traces include Android render thread calls such as preparing / destroying surface.

It is also possible to enable all the traces with MapboxTracing.enableAll(). Tracing could be disabled with MapboxTracing.disableAll().

Record traces and analyze the results​

There are several ways of capturing traces for Android which are described in the official documentation.

Recording traces using Perfetto UI​

The Perfetto Record settings can be edited when recording a new trace from ui.perfetto.dev. We recommend enabling the following options in Perfetto and combine them with MapboxTracing.enableAll() enabled in application code:

In the GPU section, enable GPU frequency, GPU memory and GPU work period:

In the CPU section, enable Coarse CPU usage counter, Scheduling details and CPU frequency and idle states (with default Poll interval). Make sure the “Syscalls” is not enabled, otherwise the trace gets bloated with these records and becomes unreadable.

Android apps & services

Make sure the “Atrace userspace annotations” and “Record events from all Android apps and services” are enabled ("Record events from all Android apps and services" is also required to record the Mapbox trace annotations).

Note that this UI auto-generates the corresponding command line instructions for each section.

The HTML file produced by this command can be opened in the https://ui.perfetto.dev viewer.

Recording traces using Android studio​

You can start profiling your application by clicking the Profile button directly from the Android Studio UI. See the Android documentation for more information about running an application to profile it.

When the profiling session starts, click on the CPU track and select System Trace to capture system traces for your application. When you have recorded what you need, press the Stop button, wait Android Studio to parse your traces and hit Export system trace recording to save trace recording locally.

After we exported trace recording you could use Perfetto to view investigate recorded traces.

Other ways to record traces​

There are several other ways how to record traces.

Directly from the device (supported on Google Pixel devices)​

Devices running Android 9 (API level 28) or higher include a system-level app called System Tracing. The app lets you record traces directly from a test device itself, without needing to plug in the device and connect to it over adb.

To use system tracing app, you can follow the official instructions and record the trace directly from the System Tracing tile in your device's Quick Settings panel, as shown below:

Using command line utility (/Library/Android/sdk/platform-tools/systrace)​

The systrace command invokes the Systrace tool, which allows you to collect and inspect timing information across all processes running on your device at the system level. For detailed instructions, follow the official guide.

python systrace.py -a "com.mapbox.maps.testapp" -o trace.html -b 20000

Analyze recorder system trace​

After we exported trace recording we could use Perfetto to investigate the Mapbox traces.

  1. Open Perfetto and drag-and-drop your local trace recording file there.
  2. When it is loaded - navigate to your application package and expand it.
  3. You can find the Mapbox native render engine traces added by MapboxTracing.enableCore() at the bottom of your app process in separate groups. Those traces start with mbx:.
  1. Mapbox platform specific traces will be located inside other Android threads and not in dedicated groups, so you could use global search by mbx: to locate them.
Was this page helpful?