|
6 | 6 | - [Overview](#overview) |
7 | 7 | - [Adding your own spans](#adding-your-own-spans) |
8 | 8 | - [Tracy profiler](#tracy-profiler) |
| 9 | + - [Tracy Quickstart](#tracy-quickstart) |
| 10 | + - [Commandline capture](#commandline-capture-less-overhead) |
| 11 | + - [Using the Tracy UI](#using-the-tracy-ui) |
9 | 12 | - [Chrome tracing format](#chrome-tracing-format) |
10 | 13 | - [Perf flame graph](#perf-flame-graph) |
11 | 14 | - [GPU runtime](#gpu-runtime) |
@@ -65,30 +68,44 @@ The [Tracy profiling tool](https://github.com/wolfpld/tracy) is: |
65 | 68 |
|
66 | 69 | > A real time, nanosecond resolution, remote telemetry, hybrid frame and sampling profiler for games and other applications. |
67 | 70 |
|
68 | | -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). |
| 71 | +#### Tracy Quickstart |
| 72 | + |
| 73 | +1. Install the [correct Tracy version](#finding-the-correct-tracy-version) (0.12.2 for Bevy 0.17) |
| 74 | + - [Windows binaries (official)](https://github.com/wolfpld/tracy/releases) |
| 75 | + - [Macos and Linux binaries (third-party builds)](https://github.com/tracy-builds/tracy-builds/releases) |
| 76 | + - [Packages](https://repology.org/project/tracy/versions) |
| 77 | +2. Start the Tracy UI (called `tracy-profiler` in prebuilt binaries) |
| 78 | +3. In the Tracy UI, click `connect` to wait for a connection. |
| 79 | + - Starting the Tracy UI first and letting it wait for connection ensures it doesn't have to catch up |
| 80 | +4. Run your bevy app with `--features bevy/trace_tracy --release` |
| 81 | + - `--release` as theres little point to profiling unoptimized code |
| 82 | + - You can capture memory usage as well with `--features bevy/trace_tracy_memory`, at the cost of increased overhead. |
| 83 | + |
| 84 | +#### Finding the correct Tracy version |
69 | 85 |
|
70 | 86 | To determine which Tracy version to install |
71 | 87 |
|
72 | 88 | 1. Run `cargo tree --features bevy/trace_tracy | grep tracy` in your Bevy workspace root to see which tracy dep versions are used |
73 | 89 | 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 | 90 |
|
75 | | -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. |
| 91 | +#### Commandline capture (less overhead) |
76 | 92 |
|
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. |
| 93 | +Tracy has a command line capture tool that can record the execution of graphical applications, saving it as a profile file. This reduces potential inaccuracies, as running the live capture on the same machine will be a competing graphical application. Pre-recording the profile data through the CLI tool, while other applications are closed, is recommended for more accurate traces. |
78 | 94 |
|
79 | | -In one terminal, run: |
80 | | -`./capture-release -o my_capture.tracy` |
81 | | -This will sit and wait for a tracy-instrumented application to start, and when it does, it will automatically connect and start capturing. |
| 95 | +> [!NOTE] |
| 96 | +> The name and location of the Tracy command line tool will vary depending on how you installed it - the default executable name for the prebuilt binaries is `tracy-capture`. |
82 | 97 |
|
83 | | -The name and location of the Tracy command line tool will vary depending on how you installed it - the default executable names are `capture-release` on Linux, `tracy` on macOS and `capture.exe` on Windows. In one terminal, run this tool: `./capture-release -o my_capture.tracy`. This will sit and wait for a tracy-instrumented application to start, and when it does, it will automatically connect and start capturing. |
| 98 | +In a terminal, run: |
| 99 | +`./tracy-capture -o my_capture.tracy` |
| 100 | +This will sit and wait for a tracy-instrumented application to start, and when it does, it will automatically connect and start capturing. |
84 | 101 |
|
85 | 102 | Then run your application, enabling the `trace_tracy` feature: `cargo run --release --features bevy/trace_tracy`. If you also want to track memory allocations, at the cost of increased runtime overhead, then enable the `trace_tracy_memory` feature instead: `cargo run --release --features bevy/trace_tracy_memory`. |
86 | 103 |
|
87 | | -After running your app, you can open the captured profile file (`my_capture.tracy` in the example above) in the Tracy GUI application to see a timeline of the executed spans. |
| 104 | +After running your app, you can open the captured profile file (`my_capture.tracy` in the example above) in the Tracy GUI application to see a timeline of the executed spans, or open multiple files to compare them. |
88 | 105 |
|
89 | | -Alternatively, directly run the tracy GUI and then run your application, for live capture. However, beware that running the live capture on the same machine will be a competing graphical application, which may impact results. Pre-recording the profile data through the CLI tool is recommended for more accurate traces. |
| 106 | +#### Using the Tracy UI |
90 | 107 |
|
91 | | -In any case, you'll see your trace in the GUI window: |
| 108 | +You'll see your trace in the GUI window: |
92 | 109 |
|
93 | 110 |  |
94 | 111 |
|
|
0 commit comments