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 Xcode Instruments, ensuring a streamlined workflow for developers.

How to enable tracing

The tracing support in Maps v11 takes advantage of signpost events, which is an important instrument for analyzing performance and detecting bottlenecks. Here is how you can enable tracing:

Tracing.status = .enabled

Or, you can set the MAPBOX_MAPS_SIGNPOSTS_ENABLED environment variable to 1 in your application scheme.

Note that these options will enable all available Maps SDK components for tracing.

Configure tracing components

Signposts in the Maps SDK are currently separated into two components:

Tracing componentDescription
coreRendering engine (responsible for almost every rendering aspect in the MapView and Snapshotter).
platformMaps SDK functionality like gestures, animations, view annotations, etc.
Use windowed recording mode in Xcode Instruments

The tracing may generate a lot of events for each frame so that Instruments might skip some of them in Immediate record mode. Enable Last N seconds mode to preserve full signpost data (see more).

You can limit signposts generation for a single component using the following API:

Tracing.status = .platform

You can also configure tracing components through the environment variable using a comma separated list of components:

Disable tracing through environment variable

Pass 0 or disabled to disable tracing through environment variable.

Tracing.status API takes precedence over environment variable value. All values are case-insensitive.

Record traces and analyze the results

You can record traces using the Xcode Instruments application. The simplest way is to select Build and profile the current scheme in Xcode, and when the Instruments application starts, use the blank template and then add os_signpost instrument from the instrument library.

When the interesting part of the application is profiled, you can analyze the results. Here is an example of the MapView initialization and rendering of the Map content.

Was this page helpful?