Skip to content

Commit 0294fa8

Browse files
authored
Mitigate Tracy dep version woes (#20109)
# Objective Turns out, Tracy dep (in)compatibilities can be a headache. Here was my experience following the [Profiling Tracy documentation](https://github.com/bevyengine/bevy/blob/1525dff7ada14714b35c8908381d534a7833faa3/docs/profiling.md#tracy-profiler): I ran into this error when I attempted to connect to my bevy client: <img width="473" height="154" alt="Screenshot 2025-07-13 at 14 39 27" src="https://github.com/user-attachments/assets/97634b37-253c-40ab-86ca-6eba02985638" /> Attempting to find where the version incompatibility stemmed, I found these tracy dep versions and a link to the compatibility table in the source: https://github.com/bevyengine/bevy/blob/1525dff7ada14714b35c8908381d534a7833faa3/crates/bevy_log/Cargo.toml#L32-L35 This led me to believe I needed Tracy `0.11.1`, to match the `tracy-client` version `0.18.0`. This was confusing because `0.11.1` is the version I already had installed (by running `brew install tracy`), and latest Tracy version currently available on `brew`. It turned out that Cargo was eagerly pulling `tracy-client` `0.18.2` instead of `0.18.0`, making the Tracy version I needed actually `0.12.2`. At the time of writing, `0.12.2` is not published on `brew`. ## Solution I've pinned the Tracy deps, and mentioned in the comment which Tracy version Bevy is compatible with. I've also added some notes to [Profiling Tracy documentation](https://github.com/bevyengine/bevy/blob/1525dff7ada14714b35c8908381d534a7833faa3/docs/profiling.md#tracy-profiler) to explain - How to determine which Tracy version to install - That MacOS users may need to compile from source if the required Tracy version is not available on `brew`. ## Testing - Did you test these changes? If so, how? I ran Tracy locally. - Are there any parts that need more testing? I don't think so. - How can other people (reviewers) test your changes? Is there anything specific they need to know? Follow instructions to run Tracy - If relevant, what platforms did you test these changes on, and are there any important ones you can't test? Tested MacOS. I think change should be OS agnostic.
1 parent e13e259 commit 0294fa8

File tree

1 file changed

+11
-5
lines changed

1 file changed

+11
-5
lines changed

docs/profiling.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,9 +67,14 @@ The [Tracy profiling tool](https://github.com/wolfpld/tracy) is:
6767
6868
There are binaries available for Windows, and installation / build instructions for other operating systems can be found in the [Tracy documentation PDF](https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf).
6969

70+
To determine which Tracy version to install
71+
72+
1. Run `cargo tree --features bevy/trace_tracy | grep tracy` in your Bevy workspace root to see which tracy dep versions are used
73+
2. Cross reference the tracy dep versions with the [Version Support Table](https://github.com/nagisa/rust_tracy_client?tab=readme-ov-file#version-support-table)
74+
7075
It has a command line capture tool that can record the execution of graphical applications, saving it as a profile file. Tracy has a GUI to inspect these profile files. The GUI app also supports live capture, showing you in real time the trace of your app. The version of tracy must be matched to the version of tracing-tracy used in bevy. A compatibility table can be found on [crates.io](https://crates.io/crates/tracing-tracy) and the version used can be found [here](https://github.com/bevyengine/bevy/blob/latest/crates/bevy_log/Cargo.toml).
7176

72-
On macOS, Tracy can be installed through Homebrew by running `brew install tracy`, and the GUI client can be launched by running `tracy`.
77+
On macOS, Tracy can be installed through Homebrew by running `brew install tracy`, and the GUI client can be launched by running `tracy`. Note that `brew` does not always have the latest version of Tracy available, in which cases you may be required to build from source.
7378

7479
In one terminal, run:
7580
`./capture-release -o my_capture.tracy`
@@ -154,20 +159,20 @@ Follow the steps below to start GPU debugging on macOS. There is no need to crea
154159

155160
1. In the menu bar click on Debug > Debug Executable…
156161

157-
![Xcode's menu bar open to Debug > Debug Executable...](https://github.com/user-attachments/assets/efdc5037-0957-4227-b29d-9a789ba17a0a)
162+
![Xcode's menu bar open to Debug > Debug Executable...](https://github.com/user-attachments/assets/efdc5037-0957-4227-b29d-9a789ba17a0a)
158163

159164
2. Select your executable from your project’s target folder.
160165
3. The Scheme Editor will open. If your assets are not located next to your executable, you can go to the Arguments tab and set `BEVY_ASSET_ROOT` to the absolute path for your project (the parent of your assets folder). The rest of the defaults should be fine.
161166

162-
![Xcode's Schema Editor opened to an environment variable configuration](https://github.com/user-attachments/assets/29cafb05-0c49-4777-8d41-8643812e8f6a)
167+
![Xcode's Schema Editor opened to an environment variable configuration](https://github.com/user-attachments/assets/29cafb05-0c49-4777-8d41-8643812e8f6a)
163168

164169
4. Click the play button in the top left and this should start your bevy app.
165170

166-
![A cursor hovering over the play button in XCode](https://github.com/user-attachments/assets/859580e2-779b-4db8-8ea6-73cf4ef696c9)
171+
![A cursor hovering over the play button in XCode](https://github.com/user-attachments/assets/859580e2-779b-4db8-8ea6-73cf4ef696c9)
167172

168173
5. Go back to Xcode and click on the Metal icon in the bottom drawer and then Capture in the following the popup menu.
169174

170-
![A cursor hovering over the Capture button in the Metal debugging popup menu](https://github.com/user-attachments/assets/c0ce1591-0a53-499b-bd1b-4d89538ea248)
175+
![A cursor hovering over the Capture button in the Metal debugging popup menu](https://github.com/user-attachments/assets/c0ce1591-0a53-499b-bd1b-4d89538ea248)
171176

172177
6. Start debugging and profiling!
173178

@@ -183,6 +188,7 @@ When you compile with Bevy's `trace_tracy` feature, GPU spans will show up in a
183188

184189
> [!NOTE]
185190
> Due to dynamic clock speeds, GPU timings will have large frame-to-frame variance, unless you use an external tool to lock your GPU clocks to base speeds. When measuring GPU performance via Tracy, only look at the MTPC column of Tracy's statistics panel, or the span distribution/median, and not at any individual frame data.
191+
186192
<!-- markdownlint-disable MD028 -->
187193

188194
> [!NOTE]

0 commit comments

Comments
 (0)