bevy_diagnostic

A small framework for tracking time-windowed measurements: FPS, frame time, entity count, asset count, and any custom metric you add. The data store other crates plug into.

Purpose

bevy_diagnostic provides:

• DiagnosticsStore — keyed map of DiagnosticPath → ring buffer of recent samples.
• Diagnostic — a single named measurement with rolling history.
• Standard plugins that populate diagnostics out of the box: FrameTimeDiagnosticsPlugin, EntityCountDiagnosticsPlugin, SystemInformationDiagnosticsPlugin, LogDiagnosticsPlugin.
• The FrameCount resource and the FrameCountPlugin.

It does not render diagnostics — that's bevy_dev_tools. Other consumers include the BRP which can stream diagnostics to a remote inspector.

Directory layout

crates/bevy_diagnostic/src/
├── lib.rs
├── diagnostic.rs                  # Diagnostic, DiagnosticsStore, DiagnosticPath
├── frame_count_diagnostics_plugin.rs
├── frame_time_diagnostics_plugin.rs
├── entity_count_diagnostics_plugin.rs
├── log_diagnostics_plugin.rs
└── system_information_diagnostics_plugin.rs

Key abstractions

Type	File	Description
Diagnostic	crates/bevy_diagnostic/src/diagnostic.rs	One named measurement with a history.
DiagnosticPath	crates/bevy_diagnostic/src/diagnostic.rs	Slash-delimited path used as the key.
DiagnosticsStore	crates/bevy_diagnostic/src/diagnostic.rs	Resource: insert/lookup diagnostics.
FrameCount	crates/bevy_diagnostic/src/frame_count_diagnostics_plugin.rs	Monotonic frame counter resource.
FrameTimeDiagnosticsPlugin	crates/bevy_diagnostic/src/frame_time_diagnostics_plugin.rs	Records frame time, FPS.
LogDiagnosticsPlugin	crates/bevy_diagnostic/src/log_diagnostics_plugin.rs	Periodically logs all diagnostics.

How it works

A plugin registers a Diagnostic (path + display name + max history length) and a system that writes Diagnostic::add_measurement(...) each frame. The DiagnosticsStore keeps the latest N samples and computes a rolling average.

Consumers — the FPS overlay, log diagnostics plugin, BRP — read DiagnosticsStore and format the values.

fn show_fps(diagnostics: Res<DiagnosticsStore>) {
    if let Some(fps) = diagnostics.get(&FrameTimeDiagnosticsPlugin::FPS) {
        if let Some(value) = fps.smoothed() {
            println!("{:.1} FPS", value);
        }
    }
}

Integration points

• Depends on: bevy_app, bevy_ecs, bevy_log, bevy_time.
• Depended on by: bevy_dev_tools, bevy_remote (for diagnostic streaming), bevy_app (uses FrameCountPlugin).

Entry points for modification

• New built-in diagnostic: new file under crates/bevy_diagnostic/src/<name>_diagnostics_plugin.rs. Follow the existing patterns — register the path, add a system, write samples each tick.
• Adjust history size: Diagnostic::with_max_history_length.

See also

• bevy_dev_tools — visualization.
• bevy_log — LogDiagnosticsPlugin outputs through tracing.