Skip to main content


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 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.

Recording traces using Perfetto Web UI

You can use Perfetto to record traces and view results directly in the browser.

Analyze recorder system trace

Was this page helpful?