Skip to content

Commit 7fe312c

Browse files
pengdevgithub-actions[bot]
authored andcommitted
Update Android maps developing.md to point to docs site. (#4550)
GitOrigin-RevId: 786191ad767300b22dc67aaaaeb7aaba672726ef
1 parent 4f01fbf commit 7fe312c

File tree

1 file changed

+1
-87
lines changed

1 file changed

+1
-87
lines changed

DEVELOPING.md

Lines changed: 1 addition & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -457,90 +457,4 @@ And then update the Mapbox Maps SDK's version name to the snapshot version in yo
457457

458458
## Working with traces
459459

460-
Mapbox Maps SDK for Android allows enabling additional Mapbox traces that could be of help troubleshooting performance issues.
461-
Working with traces is possible only when app is debuggable:
462-
463-
```xml
464-
<application>
465-
...
466-
android:debuggable="true"
467-
...
468-
</application>
469-
```
470-
471-
If the app is not debuggable and `MapboxTracing` will be used - runtime exception will be thrown.
472-
473-
### Enabling Mapbox traces
474-
475-
There are 2 types of traces that could be enabled:
476-
- Native rendering engine traces could be enabled with `MapboxTracing.enableCore()`. Those traces include native render calls, style loading, requesting tiles and more.
477-
- Android platform traces could be enabled with `MapboxTracing.enablePlatform()`. Those traces include Android render thread calls such as preparing / destroying surface.
478-
479-
It is also possible to enable all the traces with `MapboxTracing.enableAll()`. Tracing could be disabled with `MapboxTracing.disableAll()`.
480-
481-
### Recording traces using Perfetto UI
482-
483-
The Perfetto Record settings can be edited when recording a new trace from [ui.perfetto.dev](https://ui.perfetto.dev/#!/record).
484-
We recommend to enable the following options in Perfetto and combine them with `MapboxTracing.enableAll()` enabled in application code:
485-
486-
In **GPU** section. Enable `GPU frequency`, `GPU memory` and `GPU work period`:
487-
488-
<img src="https://github.com/user-attachments/assets/7cc524c6-5253-4c33-a399-11a95d8f4315" width="400" height="300" alt="image">
489-
490-
491-
In **CPU** section.
492-
Enable `Coarse CPU usage counter`, `Scheduling details` and `CPU frequency and idle states` (with default `Poll interval`).
493-
Please make sure the “Syscalls” **is not** selected, otherwise the trace gets bloated with these records and becomes unreadable.
494-
495-
<img src="https://github.com/user-attachments/assets/2d6a29b1-3087-4501-998f-077db5038bce" width="400" height="300" alt="image">
496-
497-
498-
**Android apps & svcs**
499-
500-
Please make sure the “Atrace userspace annotations” is selected and “Record events from all Android apps and services” is enabled (it is also required to record the Mapbox trace annotations).
501-
502-
<img src="https://github.com/user-attachments/assets/f4978e0d-3165-4aa1-80e0-b747e7eda791" width="400" height="300" alt="image">
503-
504-
Please note that this UI auto-generates the corresponding command line instructions - “Cmdline instructions” section
505-
506-
<img src="https://github.com/user-attachments/assets/f55532df-fdff-4ba2-ac87-823deebfb1c0" width="400" height="300" alt="image">
507-
508-
Produced html file can be opened in https://ui.perfetto.dev viewer.
509-
510-
511-
### Recording traces using Android studio
512-
513-
There are several ways of capturing traces for Android which are described in [official documentation](https://developer.android.com/topic/performance/tracing). As a reference we will describe the steps of recording traces using Android Studio Profiler:
514-
515-
1. Run your app in profile mode e.g. by clicking following icon in Android Studio.
516-
<img width="512" alt="image" src="https://github.com/mapbox/mapbox-maps-android/assets/15800566/67c0a0d9-73e3-48da-9691-0aa581790bfe">
517-
518-
2. When app is run, click on CPU in Profiler window and select `System Trace` radio-button. When you are ready to actually record the traces, hit the `Record` button.
519-
<img width="512" alt="image" src="https://github.com/mapbox/mapbox-maps-android/assets/15800566/0dad3aac-d467-44f9-b3d6-2371ee896c28">
520-
521-
3. When you are done with recording, press `Stop` button, wait Android Studio to parse your traces and hit `Export system trace recording` to save trace recording locally.
522-
<img width="512" alt="image" src="https://github.com/mapbox/mapbox-maps-android/assets/15800566/0a2ee849-e6bb-49b8-9d70-08f90f92d44b">
523-
524-
### Reading Mapbox traces using Perfetto
525-
526-
After we exported trace recording we could use [Perfetto](https://ui.perfetto.dev/) to investigate the Mapbox traces.
527-
528-
1. Open [Perfetto](https://ui.perfetto.dev/) and drag-and-drop your local trace recording file there.
529-
2. When it is loaded - navigate to your application package and un-squash it.
530-
3. Mapbox native render engine traces added by `MapboxTracing.enableCore()` could be found at the bottom of your app process in separate groups. Those traces start with `mbx:`.
531-
<img width="1024" alt="image" src="https://github.com/mapbox/mapbox-maps-android/assets/15800566/957ff955-7cc0-4828-bb90-68f2458b63d9">
532-
533-
4. 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.
534-
<img width="1024" alt="image" src="https://github.com/mapbox/mapbox-maps-android/assets/15800566/a80759ea-4ec1-4dbb-8285-c46534c15e73">
535-
536-
### Other ways to record traces
537-
538-
There are several other ways how to record traces.
539-
540-
#### Directly from the device (supported on Google Pixel devices)
541-
542-
<img src="https://github.com/mapbox/mapbox-maps-android-internal/assets/1001009/f81f3217-55a6-4d07-a6c1-b40842cc1d83" width="60%">
543-
544-
#### Using command line utility (/Library/Android/sdk/platform-tools/systrace)
545-
546-
`python systrace.py -a "com.mapbox.maps.testapp" -o trace.html -b 20000`
460+
If you're experiencing performance problems, enabling and analyzing traces is a crucial step for diagnosis. For step-by-step instructions on how to enable tracing and interpret the collected data, please consult the [tracing guide](https://docs.mapbox.com/android/maps/guides/debugging-and-profiling/tracing/).

0 commit comments

Comments
 (0)