Add documentation on how to use Tracy and Perfetto #11484

dsnopek · 2025-11-21T16:47:35Z

This takes the existing using_cpp_profilers.rst and moves it to be about "Sampling profilers" (sampling_profilers.rst), so that a new page can be added about "Tracing profilers" (like Perfetto and Tracy!) and makes the old URL into an index that explains the difference and links to both pages.

~~This is marked as DRAFT for the moment, because it only covers Perfetto - I actually haven't had a chance try Tracy yet :-)~~

engine_details/development/debugging/profiling/tracing_profilers.rst

engine_details/development/debugging/profiling/sampling_profilers.rst

dsnopek · 2025-11-21T21:30:06Z

I've filled in the docs for Tracy now too, so taking this out of draft!

Given that I've only just tried Tracy for the first time, I'm very curious to hear if I'm using it correctly or not :-)

Ivorforce

Looks really good!

engine_details/development/debugging/using_cpp_profilers.rst

engine_details/development/debugging/profiling/tracing_profilers.rst

engine_details/development/debugging/profiling/sampling_profilers.rst

dsnopek · 2025-11-24T21:54:59Z

@Ivorforce @AThousandShips Thanks for the review! I think I've integrated all your feedback in my latest push :-)

Ivorforce

Looks great!

m4gr3d · 2025-11-25T02:12:11Z

engine_details/development/debugging/using_cpp_profilers.rst

@@ -1,3 +1,3 @@
 .. _doc_using_cpp_profilers:

 Using C++ profilers


Should C++ be dropped from the page title and page path since both sampling and tracing profilers can be used for more than C++ applications and the Godot codebase contains other languages besides C++.

I believe the "C++" is in there to distinguish it from Godot's profiler?

I think the section is explicit enough that we could drop C++. For example, in the same section we have a using sanitizers page.

I think sanitizers is a little different, though: there isn't a "Godot sanitizer" and "C++ sanitizers", whereas we do have a "Godot profiler" and "C++ profilers"

However, if we do rename it, I assume we'd want to keep the path the same so we don't have to deal with redirects?

However, if we do rename it, I assume we'd want to keep the path the same so we don't have to deal with redirects?

yeah, keep things simpler.

Given that the page title isn't from this PR (it's pre-existing), I don't think we need to resolve this here. The title can be addressed in another PR

m4gr3d · 2025-11-25T02:19:36Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+To learn more, see the
+`Tracy manual <https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf>`_.
+
+Perfetto for Android


Worth including that it supports Win/Mac/Linux as well.

I don't think the way Godot has integrated it (at least so far) really supports Windows and Mac. It's setup to use the "system" backend, which requires connecting with Perfetto's system daemon which I think is only Linux and Android. If we added support for the "in process" backend we could add docs for how to use that later? The steps for using it would be somewhat different

m4gr3d · 2025-11-25T02:21:30Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+
+This will create a ``perfetto`` directory - you can place this anywhere.
+
+Next, build the Android debug or release templates for your architecture using


Are debug symbols not required for Perfetto?

Nope! Debug symbols are not required for Perfetto, or Tracy either, if you just use its tracing stuff and not its sampling features

AThousandShips

Looks great!

engine_details/development/debugging/profiling/sampling_profilers.rst

Ryan-000 · 2025-12-03T17:51:41Z

When I previously used a Tracy integration, GDExtensions could not reload. (At least on Linux, I'm not sure about Windows).

If this is still true, it may be worth mentioning.

Ivorforce · 2025-12-03T18:31:07Z

Did you use the Tracy Gdextension?

Ryan-000 · 2025-12-03T21:00:55Z

Did you use the Tracy Gdextension?

Yes https://github.com/Ryan-000/godot_tracy

Ivorforce · 2025-12-03T21:04:53Z

Aha, that should explain it.
The tracy GDExtension is, well, a GDExtension. It's possible that the hot reload didn't work well with how tracy's / the extension's assumptions.
Godot's integration is in core, and does not use the GDExtension system. As such, I don't think it will affect whether GDExtensions can reload or not. But thanks for reporting, we'll keep an eye on it!

Ryan-000 · 2025-12-03T21:33:41Z

Oh my bad, I misinterpreted your question. I actually had it compiled as a custom module, not as GDExtension.

AdriaandeJongh

Followed the guide but didn't get tracy to work unfortunately. As I am now stuck, and with little knowledge of what went wrong where, perhaps a bit of info on common mistakes or troubleshooting would be in order? It would help if I'd know what actually went wrong so I could make a more specific suggestion...

AdriaandeJongh · 2025-12-08T09:49:57Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+Record a trace
+~~~~~~~~~~~~~~
+
+Launch the Tracy server - you'll see something like this:


This 'just launch the server!' is a bit too casual for users like me. I went down a rabbit hole just to discover that the previous cmake compile steps place a binary at tracy/profiler/build/tracy-profiler which is the thing you'll want to launch. Might be good to add that here somehow.

AdriaandeJongh · 2025-12-08T09:51:05Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+
+The full details can be found in the
+`Tracy manual <https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf>`_,
+but here is the TL;DR:


The TL;DR should IMO also contain that you need to install CMake. The easiest way to do that is using a Homebrew command, eg. brew install cmake.

AdriaandeJongh · 2025-12-08T09:57:40Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+that is exhibiting performance issues), wait before pressing the button.
+
+Now, export your game using the release templates you built above, and run it.
+As soon as both are running, and you have pressed the "Connect" button in


I did all the steps precisely as explained, and yet tracy gets stuck in 'Waiting for connection' after pressing the connect button. Perhaps some basic info on troubleshooting is in order here.

Perhaps a bit of a checklist:

make sure you compiled the export templates with the right scons arguments

make sure you export your game using the custom export template

... ?

or maybe this is too convoluted, idk.

AdriaandeJongh

I got it to work! There was an important scons argument missing from this guide. Other than that I think the guide is pretty good! Thanks a lot @dsnopek!

AdriaandeJongh · 2025-12-08T10:32:31Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+Next, build the release templates for your platform using ``scons``, but adding
+the ``profiler_path=path/to/tracy`` argument with the real path to the ``tracy``
+directory, as well as ``debug_symbols=yes`` to allow Tracy's sampling features
+to work.


There is another required argument that is missing from this guide: profiler=tracy. Might also have to be set for the other profilers (I don't know) but for this one I confirmed it to be the reason I wasn't able to get tracy to work.

Yea, this argument was only added recently. Other profilers also need it (profiler=perfetto, as well as profiler=instruments, although I think instruments should be documented in a follow-up PR by Stuart).

Ivorforce · 2025-12-08T10:35:36Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+If you press "Connect" now, you can profile the launch of Godot. However,
+if you want to profile something specific (for example, a part of your game
+that is exhibiting performance issues), wait before pressing the button.


I just learned from a comment on the PR (+ the manual) that by default, tracy just stashes the profiler results until a server connection is made. So starting the server later (instead of immediately) just leads to RAM issues.
For now, I'd say we can change the formulation to ask users to profile immediately to avoid issues. In the future, we may want to add support for TRACY_ON_DEMAND (which makes profiling slower but supports launching the server later without RAM bloat).

Maybe something like this?

Suggested change

If you press "Connect" now, you can profile the launch of Godot. However,

if you want to profile something specific (for example, a part of your game

that is exhibiting performance issues), wait before pressing the button.

Press "connect". This will ensure tracy makes a connection immediately when the game launches. If you forget to press "connect", tracy will store system events in RAM, which can quickly blow up your memory usage (see ``TRACY_ON_DEMAND`` documentation).

AdriaandeJongh · 2025-12-08T11:58:06Z

To make line numbers show up correctly for tracy, these two checkboxes in the player settings need to be checked:

This should be in the docs, too.

dsnopek requested a review from Ivorforce November 21, 2025 16:47

dsnopek added enhancement area:engine details Issues and PRs related to the Engine Details section of the documentation labels Nov 21, 2025

dsnopek marked this pull request as draft November 21, 2025 16:47

dsnopek force-pushed the tracing-profiler branch from 44dee1c to 2b21a42 Compare November 21, 2025 16:52

AThousandShips reviewed Nov 21, 2025

View reviewed changes

dsnopek force-pushed the tracing-profiler branch 3 times, most recently from 00cf4f1 to 74c46a5 Compare November 21, 2025 21:28

dsnopek changed the title ~~[DRAFT] Add documentation on how to use Tracy and Perfetto~~ Add documentation on how to use Tracy and Perfetto Nov 21, 2025

dsnopek marked this pull request as ready for review November 21, 2025 21:28

dsnopek force-pushed the tracing-profiler branch 2 times, most recently from aa775c7 to e5bd5a8 Compare November 21, 2025 22:40

Ivorforce reviewed Nov 23, 2025

View reviewed changes

AThousandShips reviewed Nov 24, 2025

View reviewed changes

dsnopek force-pushed the tracing-profiler branch 2 times, most recently from 6bbb449 to 3b017d0 Compare November 24, 2025 21:51

dsnopek requested review from AThousandShips and Ivorforce November 24, 2025 21:55

Ivorforce approved these changes Nov 24, 2025

View reviewed changes

m4gr3d reviewed Nov 25, 2025

View reviewed changes

AThousandShips approved these changes Nov 25, 2025

View reviewed changes

engine_details/development/debugging/profiling/sampling_profilers.rst Outdated Show resolved Hide resolved

dsnopek force-pushed the tracing-profiler branch from 3b017d0 to 85dcccc Compare November 25, 2025 10:40

dsnopek mentioned this pull request Nov 25, 2025

Add instructions for profiling with Superluminal #11496

Open

mhilbrunner approved these changes Nov 28, 2025

View reviewed changes

dsnopek force-pushed the tracing-profiler branch from 85dcccc to 5a3f3b8 Compare November 28, 2025 10:28

Add documentation on how to use Tracy and Perfetto

ed378b8

dsnopek force-pushed the tracing-profiler branch from 5a3f3b8 to ed378b8 Compare November 28, 2025 10:29

Ivorforce mentioned this pull request Nov 28, 2025

Add support for profiling GDScript with tracy. godotengine/godot#113279

Merged

AdriaandeJongh reviewed Dec 8, 2025

View reviewed changes

AdriaandeJongh suggested changes Dec 8, 2025

View reviewed changes

Ivorforce reviewed Dec 8, 2025

View reviewed changes

		@@ -1,3 +1,3 @@
		.. _doc_using_cpp_profilers:

		Using C++ profilers


		This will create a ``perfetto`` directory - you can place this anywhere.

		Next, build the Android debug or release templates for your architecture using

Uh oh!

Add documentation on how to use Tracy and Perfetto #11484

Are you sure you want to change the base?

Add documentation on how to use Tracy and Perfetto #11484

Conversation

dsnopek commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dsnopek commented Nov 21, 2025

Uh oh!

Ivorforce left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dsnopek commented Nov 24, 2025

Uh oh!

Ivorforce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsnopek Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsnopek Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AThousandShips left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ryan-000 commented Dec 3, 2025

Uh oh!

Ivorforce commented Dec 3, 2025

Uh oh!

Ryan-000 commented Dec 3, 2025

Uh oh!

Ivorforce commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ryan-000 commented Dec 3, 2025

Uh oh!

AdriaandeJongh left a comment

dsnopek commented Nov 21, 2025 •

edited

Loading

dsnopek Nov 25, 2025 •

edited

Loading

dsnopek Nov 25, 2025 •

edited

Loading

Ivorforce commented Dec 3, 2025 •

edited

Loading

AdriaandeJongh Dec 8, 2025 •

edited

Loading

AdriaandeJongh Dec 8, 2025 •

edited

Loading

Ivorforce Dec 8, 2025 •

edited

Loading