コンテンツにスキップ
Framedash Docs
日本語 ja English en 简体中文 zh-cn 繁體中文 zh-tw 한국어 ko

自分のPCでUnityの性能を比較する（パイロット）

管理できるPCで再現可能なシナリオを計測し、Framedashで集計結果を比較する任意参加のパイロットです。まず手動で結果を確認します。CI化や自動判定は別の段階です。この非空間的な比較にマップ登録は必要ありません。

前提条件

Section titled “前提条件”
  1. Framedash Unity SDK 0.1.8 を使うUnity 2022.3以降と、CLI 0.1.11 を使うNode.js 20以降。Unity 0.1.7 / CLI 0.1.10以前にはこのAPI・コマンドがありません。
  2. Framedashのプロジェクト、プレイヤー送信用の events:write キー、比較用の別の analytics:read キー。キーは環境変数や非公開ファイルで扱い、コミットしないでください。
  3. COPPAが有効でない組織。COPPAの保護処理は必要な属性を削除するため、比較APIは403を返します。必要な保護設定は維持してください。ローカル計測やHTTP応答の成功は利用資格の証拠になりません。

Unity Package Managerで以下のタグ付きGit URLを指定し、CLIもインストールします。

https://github.com/crane-valley/framedash-unity-sdk.git#v0.1.8
Terminal window
npm install --global @framedash/cli@0.1.11

1. 条件を揃える

Section titled “1. 条件を揃える”

同じベースラインのビルドを2回実行し、その後で候補を実行します。再試行も含め、実行ごとに新しい小文字のUUID v4 を使います。シナリオ、機器構成、画質、解像度、設定、エンジン・OS、SDK版、ウォームアップ・計測フレーム数を揃えます。変更なしの再実行はビルドIDとコミットもベースラインと同じにします。ドライバー、電源・温度管理、VSync・FPS制限なども記録してください。ラベルが同じでも実際の環境が同じとは限りません。

2. シナリオを計測する

Section titled “2. シナリオを計測する”

準備後、プレイヤーのメインスレッドから呼び出します。ビルドID・コミット・設定は実際の値に置き換えてください。ラベルには設定名を使い、機器のシリアル番号や個人情報を入れません。空白だけの値、128 UTF-16コード単位を超える値、ASCII制御文字は使えません。出力された実行IDを保存し、started がfalseなら計測を進めないでください。

var sdk = Framedash.TelemetrySDK.Initialize(
    apiKey: System.Environment.GetEnvironmentVariable("FRAMEDASH_API_KEY"),
    buildId: "build-a");
var options = new Framedash.PerformanceRunOptions
{
    RunId = System.Guid.NewGuid().ToString("D"),
    Scenario = "route-a",
    Hardware = "lab-pc-a",
    Graphics = "high-vsync-off",
    Resolution = "1920x1080",
    Configuration = "release-dx12-driver-profile-a",
    Commit = "commit-sha",
    Branch = "main",
    WarmupFrames = 120,
    TargetFrames = 3600,
};
bool started = sdk.BeginPerformanceRun(options);
UnityEngine.Debug.Log("Performance run: " + options.RunId + ", started=" + started);

Unityのプレイヤーループを動かしてシナリオを実行します。この例では最初の120間隔を除外し、続く3,600間隔を集計します。固定時間の保証ではありません。計測枠を満たす長さのシナリオを選び、プロセスの実行時間は別に制限します。シナリオ完了後、メインスレッドで呼び出します。

bool complete = sdk.EndPerformanceRun();
bool acknowledged = sdk.FlushBlocking(5000);
UnityEngine.Debug.Log("complete=" + complete + ", acknowledged=" + acknowledged);

両方の戻り値を確認し、サーバーの結果も確認します。complete はローカルの完了状態で、記録追加の失敗、バッファ溢れ、欠損、早すぎる終了では成功しません。acknowledged はHTTP応答の確認であり、永続保存の証明ではありません。中断には EndPerformanceRun(completed: false) を使います。クラッシュや計測中のSDK終了は未完了です。run-profile-test 単体ではこの計測は始まりません。

3. 比較を読む

Section titled “3. 比較を読む”

ログからプロジェクトIDと3つの実行IDを設定します。読み取り対象は直近7日です。変更なしの再実行がなければ --repeat は省略できますが、それを計測の安定性の証拠にしないでください。

Terminal window
framedash run-diff --project-id "$FRAMEDASH_PROJECT_ID" \
  --api-key-file analytics-read.key \
  --baseline "$BASELINE_RUN_ID" --candidate "$CANDIDATE_RUN_ID" \
  --repeat "$REPEAT_RUN_ID" --format json

証拠の読み方

Section titled “証拠の読み方”

JSONには条件、時刻、採用・欠損・ウォームアップ数、計測時間、P50/P95/P99の区間、1,000/60・1,000/30・50・100msを厳密に超えた回数と1,000フレームあたりの割合が含まれます。table/csvは分位点の簡易表示です。

計測するのはSDKの Update 間の経過時間で、GPU時間や画面提示間隔ではありません。最初のコールバックは除外します。分位点はヒストグラムのビンの下端・上端で、上端を含みません。差分は候補からベースラインを引いた保守的な範囲で、正なら間隔が長くなっています。これらの範囲や変更なし再実行の差は統計的な信頼区間ではありません。1回の再実行や最低1,000フレームだけでノイズや統計的信頼性は確定しません。

終了コード意味
0比較可能な証拠。候補が遅くても0です。回帰判定ではありません。
2比較不成立。記録不足・未完了・条件違いを確認します。
1コマンド/APIエラー。不正な応答も含みます。

問題が起きた場合

Section titled “問題が起きた場合”
  • 記録がない: 送信キー、プロジェクト、実行ID、直近7日の範囲を確認し、取り込みを有限回の確認で待ちます。flush成功だけでは十分ではありません。
  • 未完了: 終了結果、フレーム数、欠損を確認します。無効値・0以下・32,768ms以上の間隔は欠損として計測枠を消費します。ウォームアップは0〜60,000、計測枠は1,000〜1,000,000です。新しいIDでシナリオ全体をやり直します。
  • 条件違い: ラベルと実際の条件を修正します。比較を通すために違う機器やビルドを同じ名前にしないでください。再実行はベースラインのビルド・コミットが必要です。
  • 競合・記録過多: IDを再利用しないでください。読み取りは重複処理前に実行あたり16件の生レコードで制限します。
  • 403: プロジェクト権限、analytics:read、アカウントの利用条件、COPPAの対象外であることを確認します。保護設定を弱めないでください。

チーム内で結果を確認し、次の調査内容と導入時間を記録して、修正後に再計測します。根本原因の特定やリリース安全性を保証する機能ではありません。既存のCI性能ゲートの動作は維持されます。API概要とUnity SDK設定も参照してください。

AI エージェント向け: llms.txt
稼働状況