Skip to content
Skills Library
Programming · Analysis

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.

Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

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

  1. When to use this skill
  2. Canonical pattern
  3. Built-in plugins
  4. Tracing for causality
  5. Gotchas and platform truth
  6. Choose the relevant deep dive
  7. Review checklist
  8. See also
Original SKILL.md headings · 146 lines, 715 words
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

RepositoryScoreLicence
This page · ianpurton/disposable-heroes100MIT
chrisgliddon/bevy-skills100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.