Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Merged by Bors] - docs: Add section about using Tracy for profiling #4534

Closed
wants to merge 10 commits into from
Closed

[Merged by Bors] - docs: Add section about using Tracy for profiling #4534

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c079018
docs: Add section about using Tracy for profiling
superdump Apr 19, 2022
e118139
Clarify the location of the Tracy statistics button in its UI
superdump Jul 4, 2022
18a5c5f
Restructure Tracy capabilities and usage
superdump Jul 4, 2022
aaa2de6
Improve alt-text on Tracy profile timeline image
superdump Jul 4, 2022
1e45271
Merge branch 'main' into docs-profiling-tracy
superdump Jul 4, 2022
f8796e5
Clarify Tracy capture.exe name on Windows
superdump Jul 4, 2022
f7a5d81
Improve Tracy example image alt-text
superdump Jul 4, 2022
9d3c7be
Strip some trailing whitespace
superdump Jul 4, 2022
fb22d0e
Add a section about how to capture wgpu spans when profiling
superdump Jul 4, 2022
38e00cc
profiling.md: Use markdown inline image syntax instead of HTML
superdump Jul 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/profiling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,34 @@ After running your app a `json` file in the "chrome tracing format" will be prod

![image](https://user-images.githubusercontent.com/2694663/141657409-6f4a3ad3-59b6-4378-95ba-66c0dafecd8e.png)

### Backend: trace_tracy

The [Tracy profiling tool](https://github.com/wolfpld/tracy) is:
> A real time, nanosecond resolution, remote telemetry, hybrid frame and sampling profiler for games and other applications.

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

It has a command line capture tool that can be used for capturing with minimal disruption to the execution of graphical applications, saving the profile data to a file. It also has a GUI that can be used to inspect these profile files, or live capture them, though running the live capture on the same machine will be a competing graphical application, which may impact results. As such, @superdump tends to use the command line to for capturing, and the GUI tool for inspecting.
superdump marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please line break your .md paragraphs; it makes for cleaner git changes.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree for text because then I end up re-joining and re-splitting all the lines whenever any words change, which creates a lot of noise. If they are on one line, in GitHub's UI only the changed words are highlighted. Plus none of the other existing paragraphs in this document are split across multiple lines. I won't resist on this point if you want us to consistently split paragraphs onto multiple lines in documentation though as I respect your ownership of docs more than my own opinions on it. :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "capturing" mean?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll clarify this, but it means 'receiving and recording profile data.' The Tracy tool is called 'capture'.

Copy link
Contributor Author

@superdump superdump Jul 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like nicopap's rewording already makes this much clearer so I left it as-is after their change was committed. Let me know if you think it needs further clarification.


In one terminal, run:
`./capture-release -o my_capture.tracy`
superdump marked this conversation as resolved.
Show resolved Hide resolved
This will sit and wait for a tracy-instrumented application to start, and when it does, it will automatically connect and start capturing.

Then run your application, enabling the `trace_tracy` feature:
`cargo run --release --features bevy/trace_tracy`

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:

<img width="1840" alt="Tracy timeline" src="https://user-images.githubusercontent.com/302146/163988636-25c017ab-64bc-4da7-a897-a80098b667ef.png">
superdump marked this conversation as resolved.
Show resolved Hide resolved
superdump marked this conversation as resolved.
Show resolved Hide resolved

There is a button to display statistics of mean time per call (MTPC) for all systems:

<img width="1086" alt="Tracy span MTPC overview" src="https://user-images.githubusercontent.com/302146/163988302-c21102d8-b7eb-476d-a741-a2c28d9bf8c1.png">

Or you can select an individual system and inspect its statistics to see things like the distribution of execution times in a graph, or statistical aggregates such as mean, median, standard deviation, etc. It will look something like this:
superdump marked this conversation as resolved.
Show resolved Hide resolved

<img width="514" alt="Tracy span detailed statistics" src="https://user-images.githubusercontent.com/302146/163988464-86e1a3ee-e97b-49ae-9f7e-4ff2b8b761ad.png">

### Adding your own spans

Add spans to your app like this (these are in `bevy::prelude::*` and `bevy::log::*`, just like the normal logging macros).
Expand Down