Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2025-02-16 14:08:32 +00:00
Code Issues Projects Releases Packages Wiki Activity

Include note of common profiling issue (#9484)

Browse source 
- Includes a note about a common issue seen when profiling with span
based tracing tools
- Adds a table of contents to profile.md


[Rendered](https://github.com/tbillington/bevy/blob/profiling-doc-update/docs/profiling.md).


[Suggested](https://discord.com/channels/691052431525675048/866787577687310356/1141612079460139108)
by Jasmine on discord.

---------

Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
This commit is contained in:
Trent 2023-08-23 00:45:54 +10:00 • committed by GitHub
parent 546f7fc194
commit ebdf5063df
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/profiling.md
View file

@ -1,14 +1,31 @@
# Profiling # Profiling
## Runtime Flame Graph: `tracing` spans ## Table of Contents
- [Runtime](#runtime)
- [Chrome tracing format](#chrome-tracing-format)
- [Tracy profiler](#tracy-profiler)
- [Adding your own spans](#adding-your-own-spans)
- [Perf flame graph](#perf-flame-graph)
- [Compile time](#compile-time)
## Runtime
Bevy has built-in [tracing](https://github.com/tokio-rs/tracing) spans to make it cheap and easy to profile Bevy ECS systems, render logic, engine internals, and user app code. Enable the `trace` cargo feature to enable Bevy's built-in spans. Bevy has built-in [tracing](https://github.com/tokio-rs/tracing) spans to make it cheap and easy to profile Bevy ECS systems, render logic, engine internals, and user app code. Enable the `trace` cargo feature to enable Bevy's built-in spans.
If you also want to include `wgpu` tracing spans when profiling, they are emitted at the `tracing` `info` level so you will need to make sure they are not filtered out by the `LogSettings` resource's `filter` member which defaults to `wgpu=error`. You can do this by setting the `RUST_LOG=info` environment variable when running your application. If you also want to include `wgpu` tracing spans when profiling, they are emitted at the `tracing` `info` level so you will need to make sure they are not filtered out by the `LogSettings` resource's `filter` member which defaults to `wgpu=error`. You can do this by setting the `RUST_LOG=info` environment variable when running your application.
You also need to select a `tracing` backend using the following cargo features: You also need to select a `tracing` backend using one of the following cargo features.
### Backend: trace_chrome **⚠️ Note**: for users of [span](https://docs.rs/tracing/0.1.37/tracing/index.html) based profilers
When your app is bottlenecked by the GPU, you may encounter frames that have multiple prepare-set systems all taking an unusually long time to complete, and all finishing at about the same time.
Improvements are planned to resolve this issue, you can find more details in the doc comment for [`prepare_windows`](../crates/bevy_render/src/view/window/mod.rs).
![prepare_windows span bug](https://github.com/bevyengine/bevy/assets/2771466/15c0819b-0e07-4665-aa1e-579caa24fece)
### Chrome tracing format
`cargo run --release --features bevy/trace_chrome` `cargo run --release --features bevy/trace_chrome`
@ -16,7 +33,7 @@ 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) ![image](https://user-images.githubusercontent.com/2694663/141657409-6f4a3ad3-59b6-4378-95ba-66c0dafecd8e.png)
### Backend: trace_tracy ### Tracy profiler
The [Tracy profiling tool](https://github.com/wolfpld/tracy) is: 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. > A real time, nanosecond resolution, remote telemetry, hybrid frame and sampling profiler for games and other applications.
@ -78,19 +95,19 @@ Search for `info_span!` in this repo for some real-world examples.
For more details, check out the [tracing span docs](https://docs.rs/tracing/*/tracing/span/index.html). For more details, check out the [tracing span docs](https://docs.rs/tracing/*/tracing/span/index.html).
## `perf` Runtime Flame Graph ### `perf` Flame Graph
This approach requires no extra instrumentation and shows finer-grained flame graphs of actual code call trees. This is useful when you want to identify the specific function of a "hot spot". The downside is that it has higher overhead, so your app will run slower than it normally does. This approach requires no extra instrumentation and shows finer-grained flame graphs of actual code call trees. This is useful when you want to identify the specific function of a "hot spot". The downside is that it has higher overhead, so your app will run slower than it normally does.
Install [cargo-flamegraph](https://github.com/flamegraph-rs/flamegraph), [enable debug symbols in your release build](https://github.com/flamegraph-rs/flamegraph#improving-output-when-running-with---release), then run your app using one of the following commands. Note that `cargo-flamegraph` forwards arguments to cargo. You should treat the `cargo-flamegraph` command as a replacement for `cargo run --release`. The commands below include `--example EXAMPLE_NAME` to illustrate, but you can remove those arguments in favor of whatever you use to run your app: Install [cargo-flamegraph](https://github.com/flamegraph-rs/flamegraph), [enable debug symbols in your release build](https://github.com/flamegraph-rs/flamegraph#improving-output-when-running-with---release), then run your app using one of the following commands. Note that `cargo-flamegraph` forwards arguments to cargo. You should treat the `cargo-flamegraph` command as a replacement for `cargo run --release`. The commands below include `--example EXAMPLE_NAME` to illustrate, but you can remove those arguments in favor of whatever you use to run your app:
* Graph-Like Flame Graph: `RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph -c "record -g" --example EXAMPLE_NAME` - Graph-Like Flame Graph: `RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph -c "record -g" --example EXAMPLE_NAME`
* Flat-ish Flame Graph: `RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph --example EXAMPLE_NAME` - Flat-ish Flame Graph: `RUSTFLAGS='-C force-frame-pointers=y' cargo flamegraph --example EXAMPLE_NAME`
After closing your app, an interactive `svg` file will be produced: After closing your app, an interactive `svg` file will be produced:
![image](https://user-images.githubusercontent.com/2694663/141657609-0089675d-fb6a-4dc4-9a59-871e95e31c8a.png) ![image](https://user-images.githubusercontent.com/2694663/141657609-0089675d-fb6a-4dc4-9a59-871e95e31c8a.png)
## Project Compile Times ## Compile time
Append `--timings` to your app's cargo command (ex: `cargo build --timings`). Append `--timings` to your app's cargo command (ex: `cargo build --timings`).
If you want a "full" profile, make sure you run `cargo clean` first (note: this will clear previously generated reports). If you want a "full" profile, make sure you run `cargo clean` first (note: this will clear previously generated reports).