bevy-debugging-profiling

用途

当运行中的应用需要打印日志，或记录帧时间、实体数量、进程 CPU 与内存占用时，可加载本技能。它面向 Bevy 0.20+，围绕日志与诊断两类能力展开。

主要能力

日志（LogPlugin）

LogPlugin 是 DefaultPlugins 的一部分。可通过 DefaultPlugins.set(LogPlugin { level, filter, .. }) 覆盖其配置。示例使用 Level::DEBUG 以及类似 wgpu=error,bevy_render=info,bevy_ecs=trace 的过滤字符串。同一过滤字符串也可用作 RUST_LOG。若要接入自己的收集器，可在 DefaultPlugins 上禁用该插件。

诊断核心

DiagnosticsPlugin 添加核心资源。DiagnosticsStore 保存采集结果。Diagnostic 是由 DiagnosticPath 寻址的 DiagnosticMeasurement 值组成的时间线。RegisterDiagnostic 为 App 添加 register_diagnostic 方法。

内置插件

FrameTimeDiagnosticsPlugin：添加帧时间、fps 和帧计数。
EntityCountDiagnosticsPlugin：添加实体数量。
SystemInformationDiagnosticsPlugin：添加 cpu_usage 和 mem_usage 百分比。
LogDiagnosticsPlugin：将诊断信息打印到控制台。
FrameCount / FrameCountPlugin：统计自启动以来的帧数。

顺序方面，log-diagnostics 示例在 DefaultPlugins 之后添加这些插件，因为它们使用 time 插件生成时间戳。

调度

内置插件自行进行测量。当 HUD 需要最新样本时，读取 DiagnosticsStore。只有需要测量自己定义的值时，才注册 Diagnostic。

使用方式

配置日志

use bevy::log::{Level, LogPlugin};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(LogPlugin {
            filter: "wgpu=error,bevy_render=info,bevy_ecs=trace".into(),
            level: Level::DEBUG,
            ..default()
        }))
        .run();
}

添加诊断插件

use bevy::diagnostic::{
    EntityCountDiagnosticsPlugin, FrameTimeDiagnosticsPlugin, LogDiagnosticsPlugin,
    SystemInformationDiagnosticsPlugin,
};

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            FrameTimeDiagnosticsPlugin::default(),
            EntityCountDiagnosticsPlugin {
                max_history_length: 60,
            },
            SystemInformationDiagnosticsPlugin,
            LogDiagnosticsPlugin::default(),
        ))
        .run();
}

在 HUD 中读取帧时间

use bevy::diagnostic::{DiagnosticsStore, FrameTimeDiagnosticsPlugin};

fn read_frame_time(store: Res<DiagnosticsStore>) {
    let Some(frame) = store.get(&FrameTimeDiagnosticsPlugin::FRAME_TIME) else {
        return;
    };
    let Some(ms) = frame.smoothed() else {
        return;
    };
    info!("frame {ms:.2} ms");
}

注册自定义诊断

自定义计数器由一个 DiagnosticPath 加 register_diagnostic 构成。一个系统写入测量值，其他任何地方都不应修改该路径。

use bevy::diagnostic::{Diagnostic, DiagnosticPath, Diagnostics, RegisterDiagnostic};

const LIVE_ENEMIES: DiagnosticPath = DiagnosticPath::const_new("game/live_enemies");

#[derive(Component)]
struct Enemy;

fn install(app: &mut App) {
    app.register_diagnostic(Diagnostic::new(LIVE_ENEMIES).with_max_history_length(60));
}

fn measure_enemies(mut diagnostics: Diagnostics, enemies: Query<(), With<Enemy>>) {
    let count = enemies.iter().count() as f64;
    diagnostics.add_measurement(&LIVE_ENEMIES, || count);
}

适用场景

运行中的应用需要输出日志，并调整日志级别或过滤规则。
需要采集帧时间、FPS、帧数、实体数量、进程 CPU 与内存占用等运行指标。
需要将诊断信息打印到控制台。
需要在 HUD 中读取最新诊断样本。
需要注册并测量自定义的数值。

限制

逐系统火焰图和 Tracy 不在本技能范围内。
本技能不将诊断信息转发到渲染应用。
不涉及物理、导航、网络或 XR crate。
不涉及第三方性能分析 crate。
不包含本文件未打开的外部性能分析器设置。
自定义测量使用 Diagnostic、DiagnosticPath 和 register_diagnostic，如上述示例。

技能介绍

用途