mcpField
B
bevy-diagnostics-profiling

bevy-diagnostics-profiling

github.com/chrisgliddon开发2668 次安装9 周前更新
代码仓库

关于 bevy-diagnostics-profiling

面向 Bevy 0.19 开发者的诊断与性能分析技能，介绍如何组合指标、追踪和渲染诊断来定位耗时并评估平台性能。内容涵盖诊断路径、GPU 指标限制和可重复的性能验收。

主要功能

  1. 01注册稳定命名的诊断指标
  2. 02查看指标历史与平滑值
  3. 03使用追踪跨度分析执行耗时
  4. 04记录渲染 CPU 与 GPU 指标
  5. 05说明各图形后端的测量限制
  6. 06制定可重复的性能验收

适用场景

  1. 01调查帧时间或渲染通道耗时
  2. 02跟踪队列深度、延迟和高水位
  3. 03比较目标设备上的性能预算
  4. 04区分不支持的 GPU 测量与零耗时

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/chrisgliddon/bevy-skills --skill bevy-diagnostics-profiling

安装后在 Claude Code 中输入/bevy-diagnostics-profiling确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
budgets-and-telemetry.md
diagnostics-and-tracing.md
render-and-platform-profiling.md

详细介绍

Bevy 0.19 — 诊断与性能分析

何时使用此技能

  • 帧、渲染通道、工作线程流水线或上传路径需要因果证据。
  • 队列/任务系统需要稳定的仪表值、计数器、延迟和高水位。
  • 性能声明必须通过原生平台、Steam Deck 或浏览器的验收预算。
  • 缺少渲染 GPU 诊断数据，或其结果与 CPU 跟踪不一致。

诊断回答“随时间发生了什么？”。跟踪回答“这次执行的耗时花在哪里？”。渲染诊断提供通道级渲染器测量数据。三者都要用，但不要把其中任何一项单独视为瓶颈的证据。

标准模式

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);
}

路径属于 API：使用带命名空间且稳定的名称，并在后缀或文档中明确标注单位。记录数据前先注册。DiagnosticsStore 提供最新值和历史/平滑值，可用于显示和导出。测量数据是延迟遥测，不是同一系统内的同步机制。

内置插件

  • FrameTimeDiagnosticsPlugin：FPS、帧时间和帧数。
  • EntityCountDiagnosticsPlugin：活动实体数量。
  • SystemInformationDiagnosticsPlugin：在支持的原生目标上获取进程/系统 CPU 和内存数据。WASM、iOS 和动态链接构建不支持此插件，或该插件不执行任何操作。
  • LogDiagnosticsPlugin：用于开发环境的输出；过滤路径并设置输出频率，以避免噪声。
  • RenderDiagnosticsPlugin：每个记录的渲染跨度的 CPU/GPU 时间，以及后端支持时的流水线统计数据。

从 bevy::render::diagnostic 添加 RenderDiagnosticsPlugin。它会创建形如 render/<span>/elapsed_cpu 的动态路径，并在支持时创建 render/<span>/elapsed_gpu，以及调用次数/图元统计数据。

用跟踪分析因果关系

在优化构建中启用一个后端：

cargo run --release --features bevy/trace_tracy
cargo run --release --features bevy/trace_chrome

trace_tracy_memory 会添加内存分配跟踪，但会带来额外开销。在关心其成因的工作周围添加粗粒度跨度：

use bevy::prelude::*;

fn rebuild_visible_sections() {
    let _span = info_span!("rebuild_visible_sections").entered();
    // measured work
}

避免使用高基数跨度名称，也不要为每个元素创建跨度。仅在针对性采集期间，将区段/实体 ID 作为字段记录。持续观测时，使用低开销的诊断仪表值/计数器，并在排查问题时启用详细跟踪。

注意事项与平台实际情况

Bevy 0.19 的渲染时间戳查询和流水线统计数据支持 Vulkan 和 DX12。Metal、WebGPU 和 WebGL2 只能通过 RenderDiagnosticsPlugin 提供 CPU 渲染时间。缺少 elapsed_gpu 表示不支持该测量，并不意味着 GPU 开销为零。可用时请使用厂商/平台提供的 GPU 性能分析器；RenderDoc 是图形调试器，不是性能分析器。

应针对正式发布时使用的渲染器、分辨率、电源模式、内容和构建配置进行性能分析。桌面端的结果不能证明 Steam Deck 或浏览器的预算达标。

选择相关深入指南

问题阅读内容
指标类型、稳定路径、诊断存储、跟踪跨度诊断与跟踪
渲染诊断、后端限制、CPU/GPU 工具选择渲染与平台性能分析
验收阈值、回放设计、队列/任务/上传遥测预算与遥测

审查清单

  • 每个数值都明确标注类型（仪表值/计数器/直方图）、单位、范围和采样规则。
  • 队列深度不包含已过时的堆条目；延迟时间戳使用同一时钟。
  • 跨度涵盖队列等待、工作线程计算、主线程应用，以及渲染/上传开销。
  • 性能采集使用接近正式发布的配置，可重复、预热完成，并覆盖每个声明支持的目标平台。
  • 报告包含百分位数和持续时间最长的区间，而不只是平均值。
  • 不支持的 GPU 数值应保持缺失，绝不能转换为零。
  • 测量了插桩开销，并在正常发布运行中禁用或减少插桩。

另请参阅

评论

支持 Markdown