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

engine_details/development/debugging/profiling/tracing_profilers.rst

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!

engine_details/development/debugging/profiling/tracing_profilers.rst

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 · 2025-12-09T16:03:05Z

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

Let's save this bit for a follow-up. I'd really like to get the simplest "getting started" steps merged in this PR, and then it can be built upon

AdriaandeJongh · 2025-12-09T16:10:20Z

Let's save this bit for a follow-up. I'd really like to get the simplest "getting started" steps merged in this PR, and then it can be built upon.

I tend to agree with this approach, but it’s very easy to add now, and without it, it will lead to issue reports. it makes the GDScript tracy implementation seem broken.

AdriaandeJongh

aside from the missing mention of enable the checkboxes in the player settings to get correct line numbers in tracy, the guide is great!

akien-mga · 2025-12-09T17:20:25Z

engine_details/development/debugging/profiling/tracing_profilers.rst

+First, clone the latest version of the Tracy source code ("0.13.0" at the
+time of writing) using Git:
+
+.. code-block:: shell
+
+    git clone -b v0.13.0 --single-branch https://github.com/wolfpld/tracy.git


Tracy has relatively frequent releases so this will get out of date quickly, and we don't want to have to update it regularly (which would add churn and also invalidate translations), so I'd suggest looking for an alternative that doesn't hardcode a version number.

You can use https://github.com/wolfpld/tracy/releases/latest to link to the latest tag, but that's not usable for the git clone command.

akien-mga

Let's merge so we can link to this in the beta 1 blog post.

akien-mga · 2025-12-09T17:21:07Z

Thanks!

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

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

engine_details/development/debugging/profiling/tracing_profilers.rst Show resolved Hide resolved

engine_details/development/debugging/profiling/tracing_profilers.rst Show resolved Hide resolved

engine_details/development/debugging/profiling/tracing_profilers.rst Show resolved Hide resolved

AdriaandeJongh suggested changes Dec 8, 2025

View reviewed changes

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

Ivorforce reviewed Dec 8, 2025

View reviewed changes

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

Add documentation on how to use Tracy and Perfetto

1f1c0ee

dsnopek force-pushed the tracing-profiler branch from ed378b8 to 1f1c0ee Compare December 9, 2025 16:16

dsnopek requested a review from AdriaandeJongh December 9, 2025 16:18

AdriaandeJongh approved these changes Dec 9, 2025

View reviewed changes

akien-mga reviewed Dec 9, 2025

View reviewed changes

akien-mga approved these changes Dec 9, 2025

View reviewed changes

akien-mga merged commit b6f12fc into godotengine:master Dec 9, 2025
1 check passed

Ivorforce mentioned this pull request Dec 9, 2025

Reorganize profilers into dedicated subpages. #11523

Open

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

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

Choose a reason for hiding this 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