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.
Working with traces is possible only when an application is debuggable. You should use a build variant that includes debuggable true in the build configuration. See the Android documentation for more information about enabling debugging for a build variant.
Using MapboxTracing when the application is not debuggable will throw a runtime exception.
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.