Skip to content

Commit 318b987

Browse files
authored
Improve Tracy profiling docs (quickstart, split into sections) (#21565)
# Objective The Tracy profiling docs were confusing and overwhelming to some for a number of reasons: - only mentioning that you can capture through the UI in a single sentence quite a bit down - interspersed installation, version-matching and usage instructions - lack of clear steps - lack of separation between topics ## Solution I've added a Quickstart which guides people through using the Tracy UI to capture, including some more installation instructions for various platforms (unofficial macos/linux binary builds, link to repology packages list). Additionally, I've created the following sub-titles (sub-headers?) - `Finding the correct tracy version` - `Commandline capture (less overhead)`, which is where most of the previous instructions ended up - `Using the Tracy UI`, for the basic usage guide with screenshots Rendered version: https://github.com/laundmo/bevy/blob/improve-tracy-profiling-docs/docs/profiling.md#tracy-profiler
1 parent a4404a5 commit 318b987

File tree

1 file changed

+27
-10
lines changed

1 file changed

+27
-10
lines changed

docs/profiling.md

Lines changed: 27 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
- [Overview](#overview)
77
- [Adding your own spans](#adding-your-own-spans)
88
- [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)
912
- [Chrome tracing format](#chrome-tracing-format)
1013
- [Perf flame graph](#perf-flame-graph)
1114
- [GPU runtime](#gpu-runtime)
@@ -65,30 +68,44 @@ The [Tracy profiling tool](https://github.com/wolfpld/tracy) is:
6568

6669
> A real time, nanosecond resolution, remote telemetry, hybrid frame and sampling profiler for games and other applications.
6770
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
6985

7086
To determine which Tracy version to install
7187

7288
1. Run `cargo tree --features bevy/trace_tracy | grep tracy` in your Bevy workspace root to see which tracy dep versions are used
7389
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)
7490

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)
7692

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

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`.
8297
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.
84101

85102
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`.
86103

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

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
90107

91-
In any case, you'll see your trace in the GUI window:
108+
You'll see your trace in the GUI window:
92109

93110
![Tracy timeline demonstrating the performance breakdown of a Bevy app](https://user-images.githubusercontent.com/302146/163988636-25c017ab-64bc-4da7-a897-a80098b667ef.png)
94111

0 commit comments

Comments
 (0)