bevy-diagnostics-profiling

Bevy 0.19 — 診断とプロファイリング

このスキルを使う場面

• フレーム、レンダーパス、ワーカーパイプライン、またはアップロード経路について、因果関係を示す証拠が必要な場合。
• キュー／タスクシステムに、安定したゲージ、カウンター、レイテンシ、高水位点が必要な場合。
• パフォーマンスに関する主張が、ネイティブ、Steam Deck、またはブラウザーの受け入れ基準を満たす必要がある場合。
• レンダーの GPU 診断が存在しないか、CPU トレースと一致しない場合。

診断は「時間の経過とともに何が起きているか」に答えます。トレーシングは「この実行ではどこに時間がかかったか」に答えます。レンダー診断は、パスレベルのレンダラー計測値を明らかにします。3つすべてを使いますが、どれか1つだけをボトルネックの証明とみなしてはいけません。

基本パターン

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 値は欠損のままとし、ゼロに変換しない。
• 計測のオーバーヘッドを測定し、通常の出荷時の実行では無効化または縮小している。

関連項目

• bevy-voxel-runtime — キュー、古い結果、アップロードの具体的なメトリクス。
• bevy-rendering — レンダラーのアーキテクチャとカスタムレンダーシステム。
• bevy-testing — 決定論的なベンチマークの再生とビジュアルキャプチャ。
• Bevy の診断機能
• Bevy のレンダリング診断機能
• Bevy 0.19 のプロファイリングガイド