症状： CIでInstrumentsの記録設定やtraceの保存方法が定まらず、手動計測と自動処理の結果を比較できません。
最短の進め方： Xcode 27のリリースノートで確認できる2つの指定、--show-recording-options と --recording-options を使い、対象テンプレートの選択肢を調べてから、入力を固定してtraceを保存します。自動収集だけで性能回帰を判定せず、反復測定と分析を分けてください。
対象読者 iOS／macOS開発者：決まったアプリ操作のInstruments記録を自動化したい方。 CIエンジニア：リモートMacのパイプラインで性能記録を保存・追跡したい方。 開発基盤の担当者：記録タスクと性能ゲートの責務を分けたい方。
最終更新：2026年10月30日。 Xcode 27の対応内容はリリースノート、ツールの役割はコマンドラインツールリファレンスを確認しています。オプションの詳細は、実際に使うXcode環境で照合してください。
まず比較できる基準を用意します
最初に決めるのは記録コマンドではなく、毎回同じ条件で実行できるアプリ操作やテストです。たとえば特定画面の表示、固定データの読み込み、同じテストケースの実行など、結果を比較する対象を明確にします。
次に、調べたい問題とInstrumentsのテンプレートを対応させます。CPUの呼び出し経路を調べるのか、別の動作を記録するのかを先に決め、関係のないテンプレートや負荷を混ぜないようにします。
パイプライン上では、以下の三つを別々の段階として扱ってください。
- ビルド： 同じソースから実行対象を用意します。
- ワークロードの実行： 決めた入力と操作で対象アプリを動かします。
- traceの収集： テンプレートと記録設定を使ってInstrumentsのデータを取得します。
実行ユーザーのXcode環境を照合します
リモートMacでは、ログイン時に使っているXcodeとCIジョブが使うXcodeが異なることがあります。ターミナルで確認した値だけに頼らず、実際のジョブと同じユーザー、シェル、環境変数で開発ディレクトリとツールのパスを調べてください。
開発ディレクトリの選択状態はxcode-select -pで確認できます。AppleのCommand Line Toolsの設定説明とインストール手順を参照し、選択先が想定したXcodeか、xcrun経由でxctraceを解決できるかを照合します。Command Line Toolsだけが入っている環境を、Xcode本体のツール一式が使える環境と同一視しないでください。
その後、対象プロジェクトがビルドできること、記録対象のアプリやデバイスにアクセスできることを先に確かめます。ここが未確認のままでは、記録オプションの問題とビルド・起動失敗を切り分けられません。リモートMac上のツールチェーンや接続条件を整える際は、MACGPUの利用環境案内も確認できます。
テンプレートを指定して記録オプションを照会します
xctraceの記録オプションは、どのテンプレートにも共通する固定項目ではありません。まずCIで使うテンプレートを確定し、その環境で--show-recording-optionsを実行して、返された内容を確認します。AppleはXcode 27のリリースノートでこのオプションによるJSON出力と、--recording-optionsから設定ファイルを渡す方法を説明しています。
実行形式は、プロジェクトのテンプレート名や対象に合わせて組み立てます。以下は構造を示す例です。山括弧内は実環境の値に置き換えてください。
xcrun xctrace record \
--template '<テンプレート名>' \
--show-recording-options返されたJSONを確認してから、必要な値を含む設定ファイルを作り、記録時に指定します。
xcrun xctrace record \
--template '<テンプレート名>' \
--recording-options '<記録設定JSONのパス>' \
--output '<traceの出力先>' \
--launch -- '<アプリまたは実行対象>'コマンドの利用範囲や記録・読み込み・書き出しなどの役割は、xctraceのコマンドラインリファレンスで確認できます。項目名や利用可能な設定は現在のテンプレートから得た内容を優先し、未確認の共通JSONを作って複数のテンプレートに流用しないでください。
固定した作業でtraceを収集します
記録ジョブでは、起動するアプリ、入力データ、操作手順、終了条件、出力先を一つの実行単位として管理します。たとえばアプリの起動に失敗した場合、所定の操作が完了しない場合、traceが生成されない場合は、成功扱いにせず、後続の分析工程に進ませないようにします。
CIスクリプトには、少なくとも次の確認を組み込みます。
- ビルドと対象の起動が成功したか。
- ワークロードが予定した入力と手順で実行されたか。
- 失敗時の終了状態がジョブに反映されているか。
- 指定した出力先にtraceが生成されたか。
- 生成物を次の保存工程から参照できるか。
traceを保存し、分析可能な成果物として確かめます
traceは一時ディレクトリに置いたままにせず、ジョブの成果物として回収できる場所に出力します。traceと一緒に、コミット識別子、Xcodeのバージョン、記録対象、テンプレート、ワークロードの識別情報を残せば、後日の比較で条件をたどれます。
ファイルが存在するかだけで合格にしてはいけません。実際に開く、または必要なデータを書き出し、分析工程で読めることを確認します。AppleのCPUプロファイルとコールツリービューの説明では、記録結果の分析や実行間の比較が説明されています。表示・比較できたtraceを、元の実行条件と結び付けて保存してください。
関連する疑問をCI導入前に解消します
記録オプションを調べるときの流れ
テンプレートを指定して、実行中のXcodeに含まれるxctraceから記録オプションを表示します。出力されたJSONを確認してから設定ファイルを用意してください。テンプレートやツールチェーンが違えば選択肢も変わり得るため、別のMacで作成した設定をそのまま採用せず、実際のCIノードで再確認します。
traceの保存で確認する範囲
出力先が成果物の回収対象か、ジョブ終了後も保存されるかを確かめます。traceに加え、コミット、Xcodeのバージョン、対象、ワークロードを記録し、後続処理で開くか書き出して分析可能性を確認します。生成ファイルの有無だけでは、内容が読めることや性能変化の判定までは保証されません。
自動記録を性能ゲートにする条件
自動記録は証跡を集める処理であり、そのまま性能ゲートにはなりません。同一条件での反復実行、ばらつきの評価、比較基準の合意、分析結果の確認がそろうまでは、ゲート判定と分けて運用します。閾値や許容範囲は、プロジェクトの実データからチームが決めてください。
開発ディレクトリを確認する方法
CIと同じユーザー・シェルでxcode-select -pを実行し、選択中の開発ディレクトリを確かめます。続けてxcrunからxctraceを呼び出せるかを検証し、意図したXcodeが選択されていることを確認します。Command Line Toolsの導入状況だけで判断せず、設定と実際に解決されるツールの両方を照合してください。
試験運用の結果で定期実行かゲートかを分けます
導入前に、次のチェックリストをCIの受け入れ判定に使ってください。上から確認し、該当しない項目があれば記載した判断に従います。
- [ ] 同じコミット、入力、対象環境でワークロードを再現できる。未達なら性能比較を保留し、必要時だけ記録します。
- [ ] CIジョブで対象アプリまたはデバイスにアクセスでき、起動と終了を判定できる。未達なら常設を保留し、環境や権限を修正します。
- [ ] traceが成果物として回収され、後続の分析工程で開くか書き出せる。未達なら性能ゲートにせず、出力先と保存工程を修正します。
- [ ] 反復測定で比較条件を確認し、チームが基準と許容範囲を定めている。未達なら定期収集にとどめ、ゲート化を延期します。
- [ ] 物理機器への直接接続や継続的な専有が必要かを確認した。必要なら専用の自社Macを候補にし、短期利用や必要時の計測ならリモートMacも比較します。
短期の計測や検証用ノードが必要なら、MACGPUのリモートMac利用環境を候補にし、まず実際のワークロードで接続方法、権限、traceの受け渡しを確かめてください。常時の高負荷運用や物理機器への直接接続が必須なら、専用の自社Macを含めて比較するのが適切です。