Merge pull request #11938 from m4gr3d/update_perfetto_documentation

Update the perfetto profiler documentation

engine_details/development/profiling/index.rst

@@ -89,6 +89,12 @@ Godot currently supports three tracing profilers:
 - :ref:`Perfetto <doc_profiler_perfetto>`
 - :ref:`Instruments <doc_profiler_instruments>` (Apple only)
 
+.. note::
+
+    Perfetto is the default tracing system for Android, so pre-built export templates
+    with Perfetto built-in and enabled are provided from 
+    the `GitHub Releases page <https://github.com/godotengine/godot-builds/releases>`__.
+
 In order to use either of them, you'll need to build the engine from source.
 If you've never done this before, please read
 :ref:`these docs <doc_compiling_index>` for the platform you want to profile on.

engine_details/development/profiling/perfetto.rst

@@ -8,22 +8,59 @@ Perfetto
 `Perfetto <https://perfetto.dev>`__ is the default tracing system for Android. In fact, its system tracing
 service has been built into the platform since Android 9.
 
-Build Godot with Perfetto support
+Using official Perfetto templates
 ---------------------------------
 
-First, clone the latest version of the Perfetto source code ("53.0" at the
-time of writing) using Git:
+Starting with Godot 4.7, Perfetto export templates are provided for every stable Godot release and can be 
+downloaded from the `GitHub Releases page <https://github.com/godotengine/godot/releases/>`_.
+
+Using the Gradle build template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Navigate to the release page and download the ``Godot_v<godot_version>_android_source.perfetto.zip`` 
+  release artifact where ``godot_version`` corresponds to the version of the engine being used.
+- In the **Project > Export** dialog, **Advanced Options** and **Use Gradle Build** must be enabled.
+- Point **Android Source Template** to the downloaded export template.
+
+.. image:: img/cpp_profiler_perfetto_gradle_build_config.webp
+
+Follow the instructions in the :ref:`Configuration section <doc_profiler_perfetto_configuration>` to 
+learn how to configure and create a trace.
+
+Using non-gradle build templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Navigate to the release page and download the following release artifacts 
+  where ``godot_version`` corresponds to the version of the engine being used:
+
+  - ``Godot_v<godot_version>_android_debug.perfetto.apk`` (for debug builds)
+  - ``Godot_v<godot_version>_android_release.perfetto.apk`` (for release builds)
+
+- In the **Project > Export** dialog:
+
+  - **Advanced Options** must be enabled
+  - **Use Gradle Build** must be disabled
+
+- Point **Custom Template** to the downloaded export templates.
+
+.. image:: img/cpp_profiler_perfetto_non_gradle_build_config.webp
+
+Follow the instructions in the :ref:`Configuration section <doc_profiler_perfetto_configuration>` to 
+learn how to configure and create a trace.
+
+Custom Godot builds with Perfetto support
+-----------------------------------------
+
+From the ``godot`` root directory, run the following python script to install 
+the latest version of the Perfetto SDK under ``thirdparty/perfetto``:
 
 .. code-block:: shell
 
-    git clone -b v53.0 --single-branch https://github.com/google/perfetto.git
-
-This will create a ``perfetto`` directory - you can place this anywhere.
+    python misc/scripts/install_perfetto.py
 
 Next, build the Android debug or release templates for your architecture using
 ``scons`` (per :ref:`Compiling for Android <doc_compiling_for_android>`), but
-adding the ``profiler=perfetto profiler_path=path/to/perfetto`` arguments with
-the real path to the ``perfetto`` directory.
+adding the ``profiler=perfetto`` argument.
 
 .. note::
 
@@ -37,15 +74,16 @@ For example, to build the release templates for arm64:
 
 .. code-block:: shell
 
-    scons platform=android target=template_release arch=arm64 generate_android_binaries=yes profiler=perfetto profiler_path=path/to/perfetto
+    scons platform=android target=template_release arch=arm64 generate_android_binaries=yes profiler=perfetto
+
+.. _doc_profiler_perfetto_configuration:
 
 Configuration
 -------------
 
 Perfetto requires a configuration file to tell it which events to track.
 
-Create a file called ``godot.config`` inside of the ``perfetto`` directory
-with this content:
+Create a file called ``godot.config`` with this content:
 
 .. code-block:: text
 
@@ -71,6 +109,18 @@ with this content:
         }
     }
 
+.. note::
+
+    Godot records two categories of track events:
+
+    - **godot**: Used to record Godot engine events. This is used for performance analysis. 
+      Event tracing overhead should not significantly impact performance. 
+      This should be the typical tracing mode for most developers.
+    - **godot_scripting**: Used to record Godot scripting events. 
+      This is a slow category as it profiles the entire game scripting logic. 
+      This is used for code understanding / debugging / finding what caused a frame hitch. 
+      Performance is much slower, but it helps to find that one problematic function call that was otherwise hidden.
+
 Record a trace
 --------------
 
@@ -78,13 +128,12 @@ Finally, launch your game on an Android device using the export templates you
 built earlier.
 
 When you're ready to record a trace (for example, when you've hit the part of
-your game that is exhibiting performance issues), you can use this script that
-comes with the Perfetto source code:
+your game that is exhibiting performance issues), you can 
+use `this script from the Perfetto GitHub repository <https://github.com/google/perfetto/blob/main/tools/record_android_trace>`_.
 
 .. code-block:: shell
 
-    cd perfetto
-    ./tools/record_android_trace -c godot.config
+    ./record_android_trace -c /path/to/godot.config
 
 This will record for 10 seconds (per the configuration), or until you press
 :kbd:`Ctrl + C`.
@@ -95,7 +144,7 @@ Examining the trace
 As soon as that script exits, it will launch the Perfetto UI in a web browser.
 
 To see the Godot events, expand the row for your application by clicking on its
-Android "Unique Name" (Perfetto will also include some events from system
+Android *Unique Name* / *Package Name* / *App ID* (Perfetto will also include some events from system
 services in the trace).
 
 .. image:: img/cpp_profiler_perfetto.webp