bevy-diagnostics-profiling

Bevy 0.19 — 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

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.