リモート実行のためのリモートキャッシュヒットのデバッグ

このページでは、キャッシュヒット率を確認する方法と、リモート実行のコンテキストでキャッシュミスを調査する方法について説明します。

このページでは、リモート実行を正常に利用しているビルドまたはテストがあり、リモートキャッシュを効果的に利用していることを確認することを前提としています。

キャッシュヒット率を確認する

Bazel 実行の標準出力で、プロセスを一覧表示する INFO 行を確認します。これは、おおまかに Bazel アクションに対応しています。この行には、アクションが実行された場所の詳細が記載されています。リモートで実行されたアクションを示す remote ラベル、ローカルサンドボックスで実行されたアクションを示す linux-sandbox、その他の実行戦略を示すその他の値を探します。リモートキャッシュから結果が返されたアクションは remote cache hit と表示されます。

例:

INFO: 11 processes: 6 remote cache hit, 3 internal, 2 remote.

この例では、6 件のリモートキャッシュヒットがあり、2 件のアクションにはキャッシュヒットがないためリモートで実行されました。この 3 つの内部部分は無視できます。通常は、シンボリックリンクの作成などの小さな内部アクションです。この概要にはローカルキャッシュヒットは含まれません。プロセスが 0 個（または想定よりも少ない数）の場合は、bazel clean の後にビルド / テストコマンドを実行します。

キャッシュヒットのトラブルシューティング

想定どおりのキャッシュヒット率が得られない場合は、次の操作を行います。

同じビルド/テストコマンドを再実行するとキャッシュヒットが発生することを確認する

キャッシュに入力する予定のビルドやテストを実行します。特定のスタックで新しいビルドが初めて実行された場合、リモートキャッシュヒットは発生しません。リモート実行の一環として、アクションの結果はキャッシュに保存され、以降の実行で取得されます。
bazel clean を実行します。このコマンドはローカルキャッシュをクリーンアップします。これにより、結果がローカルキャッシュヒットによってマスクされることなく、リモートキャッシュヒットを調査できます。
再調査するビルドとテストを（同じマシンで）実行します。
INFO 行でキャッシュヒット率を確認します。remote cache hit と internal 以外のプロセスが表示されない場合、キャッシュは正しく入力され、アクセスされています。その場合は、次のセクションに進みます。
不一致の原因として考えられるのは、ビルド内の非気密性により、2 回の実行でアクションが異なるアクションキーを受け取ることです。これらのアクションを確認する手順は次のとおりです。

a. 問題のビルドまたはテストを再度実行して、実行ログを取得します。
```
  bazel clean
  bazel --optional-flags build //your:target --execution_log_compact_file=/tmp/exec1.log
```
b. 2 つの実行の実行ログを比較します。2 つのログファイルでアクションが同じであることを確認します。不一致は、実行間で発生した変更についての手がかりとなります。これらの不一致を解消するようにビルドを更新します。

キャッシュの問題を解決し、繰り返し実行ですべてのキャッシュヒットが発生する場合は、次のセクションに進みます。

アクション ID が同じなのにキャッシュヒットがない場合は、構成の何らかの原因でキャッシュが保存されていない可能性があります。このセクションに進んで、一般的な問題を確認します。
実行ログのすべてのアクションで cacheable が true に設定されていることを確認します。特定のアクションの実行ログに cacheable が表示されない場合は、対応するルールの BUILD ファイルの定義に no-cache タグが含まれている可能性があります。実行ログの mnemonic フィールドと target_label フィールドを確認して、アクションの発生元を特定します。
アクションが同一で cacheable であるのにキャッシュヒットがない場合は、コマンドラインに --noremote_accept_cached が含まれている可能性があります。これにより、ビルドのキャッシュルックアップが無効になります。

実際のコマンドラインがわかりにくい場合は、次のように Build Event Protocol の正規のコマンドラインを使用します。

a. ログのテキストバージョンを取得するには、--build_event_text_file=/tmp/bep.txtを Bazel コマンドに追加します。

b. ログのテキストバージョンを開き、command_line_label: "canonical" で structured_command_line メッセージを検索します。展開するとすべてのオプションが表示されます。

c. remote_accept_cached を検索して、false に設定されているかどうかを確認します。

d. remote_accept_cached が false の場合は、コマンドラインまたは bazelrc ファイルで、false に設定されている場所を確認します。

マシン間でのキャッシュ保存を確認する

同じマシンでキャッシュヒットが期待どおりに発生したら、別のマシンで同じビルドまたはテストを実行します。マシン間でキャッシュに保存されていないと思われる場合は、次の操作を行います。

既存のキャッシュにヒットしないように、ビルドに小さな変更を加えます。

最初のマシンでビルドを実行します。

 bazel clean
 bazel ... build ... --execution_log_compact_file=/tmp/exec1.log

2 番目のマシンでビルドを実行し、ステップ 1 の変更が含まれていることを確認します。
```
 bazel clean
 bazel ... build ... --execution_log_compact_file=/tmp/exec2.log
```
2 つの実行の実行ログを比較します。ログが同一でない場合は、ビルド構成に不一致がないか、ホスト環境のプロパティがいずれかのビルドに漏れていないか調べます。

実行ログの比較

実行ログには、ビルド中に実行されたアクションの記録が含まれます。各レコードには、アクションの入力（ファイルだけでなく、コマンドライン引数、環境変数など）と出力の両方を記述します。したがって、ログを調べると、アクションが再実行された理由がわかります。

実行ログは、コンパクト（--execution_log_compact_file）、バイナリ（--execution_log_binary_file）、JSON（--execution_log_json_file）の 3 つの形式のいずれかで生成できます。コンパクト形式では、生成されるファイルのサイズが大幅に小さく、実行時のオーバーヘッドが非常に少ないためおすすめです。以下の手順はどの形式でも有効です。//src/tools/execlog:converter ツールを使用して変換することもできます。

想定どおりにキャッシュヒットを共有していない 2 つのビルドのログを比較する手順は次のとおりです。

各ビルドから実行ログを取得し、/tmp/exec1.log と /tmp/exec2.log として保存します。
Bazel ソースコードをダウンロードして、//src/tools/execlog:parser ツールをビルドします。

git clone https://github.com/bazelbuild/bazel.git cd bazel bazel build //src/tools/execlog:parser
//src/tools/execlog:parser ツールを使用して、ログを人間が読めるテキスト形式に変換します。この形式では、2 番目のログのアクションが最初のログの順序と一致するように並べ替えられ、比較が容易になります。
```
bazel-bin/src/tools/execlog/parser \
  --log_path=/tmp/exec1.log \
  --log_path=/tmp/exec2.log \
  --output_path=/tmp/exec1.log.txt \
  --output_path=/tmp/exec2.log.txt
```
任意のテキスト差分を使用して、/tmp/exec1.log.txt と /tmp/exec2.log.txt を比較します。

リモート実行のためのリモート キャッシュ ヒットのデバッグ

キャッシュ ヒット率を確認する