bevy-diagnostics-profiling
/bevy-diagnostics-profiling
Use when profiling Bevy 0.20 with `DiagnosticPath`, `DiagnosticsStore`, `info_span!`, `RenderDiagnosticsPlugin`, or the `RenderDebugOverlay`: custom metrics, CPU/GPU pass timings, queue/task/upload telemetry, stale-result counts, and native, Steam Deck, or WebGPU budgets.
- Author
- ianpurton ↗
- Repository
- disposable-heroes ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when profiling Bevy 0.20 with `DiagnosticPath`, `DiagnosticsStore`, `info_span!`, `RenderDiagnosticsPlugin`, or the `RenderDebugOverlay`: custom metrics, CPU/GPU pass timings, queue/task/upload telemetry, stale-result counts, and native, Steam Deck, or WebGPU budgets.
Original author description
Use when profiling Bevy 0.20 with `DiagnosticPath`, `DiagnosticsStore`, `info_span!`, `RenderDiagnosticsPlugin`, or the `RenderDebugOverlay`: custom metrics, CPU/GPU pass timings, queue/task/upload telemetry, stale-result counts, and native, Steam Deck, or WebGPU budgets.
How it works
- When to use this skill
- Canonical pattern
- Built-in plugins
- Tracing for causality
- Gotchas and platform truth
- Choose the relevant deep dive
- Review checklist
- See also
SKILL.md preview
---
name: bevy-diagnostics-profiling
description: "Use when profiling Bevy 0.20 with `DiagnosticPath`, `DiagnosticsStore`, `info_span!`, `RenderDiagnosticsPlugin`, or the `RenderDebugOverlay`: custom metrics, CPU/GPU pass timings, queue/task/upload telemetry, stale-result counts, and native, Steam Deck, or WebGPU budgets."
license: MIT
compatibility: opencode,claude-code,cursor
metadata:
tier: "2"
area: diagnostics
bevy_version: "0.20"
---
# Bevy 0.20 — diagnostics and profiling
## When to use this skill
- A frame, render pass, worker pipeline, or upload path needs causal evidence.
- A queue/task system needs stable gauges, counters, latency, and high-water marks.
- Performance claims must pass native, Steam Deck, or browser acceptance budgets.
- Render GPU diagnostics are absent or disagree with CPU traces.
Diagnostics answer “what is happening over time?” Tracing answers “where did this
execution spend time?” Render diagnostics expose pass-level renderer measurements.
Use all three, but do not treat any one of them as proof of a bottleneck.
## Canonical pattern
```rust
use bevy::{
diagnostic::{
Diagnostic, DiagnosticPath, Diagnostics, RegisterDiagnostic,
},
prelude::*,
};
const REMESH_QUEUE_DEPTH: DiagnosticPath =
DiagnosticPath::const_new("voxel/remesh_queue_depth");
#[derive(Resource, Default)]
struct RemeshQueue {
valid_jobs: usize,
}
struct VoxelDiagnosticsPlugin;
impl Plugin for VoxelDiagnosticsPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<RemeshQueue>()
.register_diagnostic(
Diagnostic::new(REMESH_QUEUE_DEPTH).with_suffix(" sections"),
)
.add_systems(Update, record_voxel_diagnostics);
}
}
fn record_voxel_diagnostics(
queue: Res<RemeshQueue>,
mut diagnostics: Diagnostics,
) {
diagnostics.add_measurement(&REMESH_QUEUE_DEPTH, || queue.valid_jobs as f64);
}
```
Paths are an API: use namespaced, stable names with explicit units in suffixes or
documentation. Register before recording. `DiagnosticsStore` provides latest and
historical/smoothed values for displays and exporters. Measurements are deferred
telemetry, not a same-system synchronisation mechanism.
## Built-in plugins
- `FrameTimeDiagnosticsPlugin`: FPS, frame time, and frame count.
- `EntityCountDiagnosticsPlugin`: live entity count.
- `SystemInformationDiagnosticsPlugin`: process/system CPU and memory on supported
native targets. It is unavailable/no-op for WASM, iOS, and dynamic-link builds.
- `LogDiagnosticsPlugin`: development output; filter paths and cadence to avoid noise.
- `RenderDiagnosticsPlugin`: CPU/GPU time per recorded render span and pipeline
statistics where the backend supports them.
- `RenderDebugOverlayPlugin` (0.20): on-screen render debug overlay, in
`DefaultPlugins` under the `dev` feature (`bevy_dev_tools` + `render_dev_tools`).
Off until `RenderDebugOverlayKeybindings { enable_keybindings: true, .. }`
is inserted; F1 cycles mode, F2 cycles opacity.
Add `RenderDiagnosticsPlugin` from `bevy::render::diagnostic`. It creates dynamic
paths shaped like `render/<span>/elapsed_cpu` and, when supported,
`render/<span>/elapsed_gpu` plus invocation/primitive statistics.
## Tracing for causality
Enable a backend in an optimised build:
```text
cargo run --release --features bevy/trace_tracy
cargo run --release --features bevy/trace_chrome
```
`trace_tracy_memory` adds allocation tracking with extra overhead. Add coarse spans
around work whose cause matters:
```rust
use bevy::prelude::*;
fn rebuild_visible_sections() {
let _span = info_span!("rebuild_visible_sections").entered();
// measured work
}
```
Avoid high-cardinality span names and per-element spans. Record section/entity IDs as
fields only during targeted captures. Keep a low-overhead diagnostic gauge/counter
for continuous observability and switch on detailed traces for investigation.
## Gotchas and platform truth
- 0.19→0.20: `Render`, `RenderGraph`, and `Core3d` sets order with `chain_weak`.
A diagnostic-recording render system that relied on an earlier set finishing via
a channel or atomic needs an explicit `.after(system)`.
- `tracing` is not a direct dependency: write `bevy::log::tracing::field::Empty`.
- Stale output imports `RenderDebugOverlayPlugin` without the `dev` feature; the
`bevy::dev_tools` module does not exist without `bevy_dev_tools`.
Bevy 0.20 render timestamp queries and pipeline statistics are supported on Vulkan
and DX12. Metal, WebGPU, and WebGL2 expose CPU render timings only through
`RenderDiagnosticsPlugin`. Missing `elapsed_gpu` is an unsupported measurement, not
zero GPU cost. Use vendor/platform GPU profilers where available; RenderDoc is a
graphics debugger, not a performance profiler.
Profile the shipping renderer, resolution, power mode, content, and build profile.
Desktop results do not establish Steam Deck or browser budgets.
## Choose the relevant deep dive
| Problem | Read |
|---|---|
| Metric types, stable paths, diagnostics store, tracing spans | [Diagnostics and tracing](references/diagnostics-and-tracing.md) |
| Render diagnostics, backend limitations, CPU/GPU tool choice | [Render and platform profiling](references/render-and-platform-profiling.md) |
| Acceptance thresholds, replay design, queue/task/upload telemetry | [Budgets and telemetry](references/budgets-and-telemetry.md) |
## Review checklist
- Every number has a type (gauge/counter/histogram), unit, scope, and sampling rule.
- Queue depth excludes obsolete heap entries; latency timestamps use one clock.
- Spans cover queue wait, worker compute, main-thread apply, and render/upload costs.
- Captures are release-like, repeatable, warm, and made on each claimed target.
- Reports include percentiles and worst sustained intervals, not averages alone.
- Unsupported GPU values remain absent and are never converted to zero.
- Instrumentation overhead is measured and disabled/reduced in normal shipping runs.
## See also
- [`bevy-voxel-runtime`](../bevy-voxel-runtime/SKILL.md) — concrete queue, stale-result, and upload metrics.
- [`bevy-rendering`](../bevy-rendering/SKILL.md) — renderer architecture and custom render systems.
- [`bevy-testing`](../bevy-testing/SKILL.md) — deterministic benchmark replays and visual captures.
- [`bevy-migration-0-19-to-0-20`](../bevy-migration-0-19-to-0-20/SKILL.md) — weak ordering and render-world renames.
- [Bevy diagnostics](https://docs.rs/bevy/0.20.1/bevy/diagnostic/index.html)
- [Bevy render diagnostics](https://docs.rs/bevy/0.20.1/bevy/render/diagnostic/index.html)
- [Bevy 0.20 profiling guide](https://github.com/bevyengine/bevy/blob/v0.20.1/docs/profiling.md)
Files in this package (4)
- SKILL.md 7 KB
- references/budgets-and-telemetry.md 3 KB
- references/diagnostics-and-tracing.md 3 KB
- references/render-and-platform-profiling.md 3 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ianpurton/disposable-heroes | 100 | MIT |
| chrisgliddon/bevy-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version cc4281de9c3a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100bevy-platform-web
Ship a Bevy 0.20 app to the browser: wasm32 canvas Window, one of webgl2 or webgpu, and asset paths the page can serve. Use when the same ECS app must run in a browser. Keywords: Bevy, wasm, web, webgl2, webgpu, canvas, Window. - 100bevy-vfx
Use when adding GPU particles via `bevy_hanabi 0.20.0` (`HanabiPlugin`, `EffectAsset`, `ParticleEffect`, `ExprWriter`, `SpawnerSettings`, modifiers like `SetPositionSphereModifier` / `ColorOverLifetimeModifier`), rendering Gaussian splats via `bevy_spark`, picking between hanabi… - 100bevy-vfx
Use when adding GPU particles with `bevy_hanabi 0.19`, rendering Gaussian splats with `bevy_gaussian_splatting 8`, choosing sprite-sheet or vector-shape effects, writing custom WGSL materials, or profiling VFX on native and web targets in Bevy 0.19. - 100bevy-wasm-webgpu
Use when targeting Bevy 0.19 at `wasm32-unknown-unknown`, choosing the `webgl2` or `webgpu` feature, generating browser glue with `wasm-bindgen`, using a `wasm-release` profile, or debugging canvas startup and asset HTTP 404s. - 100bevy-master
Bevy ECS hub for Bevy 0.20+. Use when starting a Bevy game, choosing ECS boundaries, or picking a Bevy skill. Keywords: Bevy, ECS, bevy-master, schedules, plugins. - 100bevy
This skill should be used when working on Bevy game engine projects. It provides specialized knowledge for Bevy's Entity Component System (ECS) architecture, component-driven design patterns, system ordering, UI development, build strategies, and common pitfalls. Use this skill…