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](1525dff7ad/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:1525dff7ad/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](1525dff7ad/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.
This commit is contained in:
liamaharon
GitHub
parent
e13e259436
commit
0294fa89db
@ -67,9 +67,14 @@ The [Tracy profiling tool](https://github.com/wolfpld/tracy) is:
|
||||
|
||||
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).
|
||||
|
||||
To determine which Tracy version to install
|
||||
|
||||
1. Run `cargo tree --features bevy/trace_tracy | grep tracy` in your Bevy workspace root to see which tracy dep versions are used
|
||||
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)
|
||||
|
||||
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).
|
||||
|
||||
On macOS, Tracy can be installed through Homebrew by running `brew install tracy`, and the GUI client can be launched by running `tracy`.
|
||||
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.
|
||||
|
||||
In one terminal, run:
|
||||
`./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
|
||||
|
||||
1. In the menu bar click on Debug > Debug Executable…
|
||||
|
||||
|
||||
|
||||
|
||||
2. Select your executable from your project’s target folder.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
4. Click the play button in the top left and this should start your bevy app.
|
||||
|
||||
|
||||
|
||||
|
||||
5. Go back to Xcode and click on the Metal icon in the bottom drawer and then Capture in the following the popup menu.
|
||||
|
||||
|
||||
|
||||
|
||||
6. Start debugging and profiling!
|
||||
|
||||
@ -183,6 +188,7 @@ When you compile with Bevy's `trace_tracy` feature, GPU spans will show up in a
|
||||
|
||||
> [!NOTE]
|
||||
> 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.
|
||||
|
||||
<!-- markdownlint-disable MD028 -->
|
||||
|
||||
> [!NOTE]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user