Build Event Protocol(BEP)を使用すると、サードパーティ プログラムが Bazel の呼び出しに関する分析情報を取得できます。たとえば、BEP を使用して、ビルド結果を表示する IDE プラグインやダッシュボードの情報を収集できます。
プロトコルは、プロトコル バッファ メッセージのセットであり、その上にいくつかのセマンティクスが定義されています。ビルドとテスト結果、ビルドの進行状況、ビルド構成などに関する情報が含まれています。BEP はプログラムで使用することを想定しており、Bazel のコマンドライン出力を解析する必要がなくなります。
ビルドイベント プロトコルは、ビルドに関する情報をイベントとして表します。ビルドイベントは、ビルドイベント識別子、一連の子イベント識別子、ペイロードで構成されるプロトコル バッファ メッセージです。
ビルドイベント ID: ビルドイベントの種類に応じて、ビルドイベントの詳細を示す不透明な文字列や構造化情報の場合があります。ビルドイベント ID はビルド内で一意です。
子: ビルドイベントは、子フィールドにビルドイベント識別子を含めることで、他のビルドイベントを通知できます。 たとえば、
PatternExpanded
ビルドイベントは、子として展開するターゲットを通知します。このプロトコルにより、最初のイベントを除くすべてのイベントが、前のイベントによって通知されます。ペイロード: ペイロードにはビルドイベントに関する構造化された情報が含まれ、イベントに固有のプロトコル バッファ メッセージとしてエンコードされます。ペイロードは期待されるタイプでなくても、ビルドが途中で中止された場合、
Aborted
メッセージになる場合があります。
イベントグラフを作成する
すべてのビルドイベントは、親と子の関係によって有向非巡回グラフを形成します。初期ビルドイベントを除くすべてのビルドイベントには、1 つ以上の親イベントがあります。子イベントの親イベントがすべて、その前に必ずしも投稿されるとは限りません。ビルドが完了(成功または失敗)すると、通知されたすべてのイベントが投稿されます。Bazel がクラッシュした場合やネットワーク トランスポートが失敗した場合、通知されたビルドイベントの一部が送信されないことがあります。
イベントグラフの構造は、コマンドのライフサイクルを反映しています。すべての BEP グラフには次のような特徴があります。
- ルートイベントは常に
BuildStarted
イベントです。他のすべてのイベントは、その子孫です。 - BuildStarted イベントの直接の子には、コマンドに関するメタデータが含まれます。
- このコマンドによって生成されたデータ(ビルドされたファイルやテスト結果など)を含むイベントは、
BuildFinished
イベントの前に表示されます。 BuildFinished
イベントの後には、ビルドに関する概要情報(指標やプロファイリング データなど)を含むイベントが続く場合があります。
ビルドイベント プロトコルを使用する
バイナリ形式で使用する
BEP をバイナリ形式で使用するには:
オプション
--build_event_binary_file=/path/to/file
を指定して、Bazel でプロトコル バッファ メッセージをファイルにシリアル化します。このファイルには、シリアル化されたプロトコル バッファ メッセージが含まれ、各メッセージは長さで区切られます。各メッセージには、可変長の整数としてエンコードされた長さが接頭辞として付加されます。この形式は、プロトコル バッファ ライブラリのparseDelimitedFrom(InputStream)
メソッドを使用して読み取ることができます。次に、シリアル化されたプロトコル バッファ メッセージから関連情報を抽出するプログラムを作成します。
テキスト形式または JSON 形式で使用する
次の Bazel コマンドライン フラグは、テキストや JSON などの人が読める形式で BEP を出力します。
--build_event_text_file
--build_event_json_file
ビルドイベント サービス
ビルドイベント サービス プロトコルは、ビルドイベントを公開するための汎用の gRPC サービスです。ビルドイベント サービス プロトコルは BEP から独立しており、BEP イベントを不透明なバイトとして扱います。Bazel には、Build Event Protocol イベントを公開する Build Event Service プロトコルの gRPC クライアント実装が付属しています。--bes_backend=HOST:PORT
フラグを使用して、イベントを送信するエンドポイントを指定できます。バックエンドで gRPC を使用する場合は、アドレスに適切なスキームを付ける必要があります(平文の gRPC の場合は grpc://
、TLS を有効にした gRPC の場合は grpcs://
)。
ビルドイベント サービスフラグ
Bazel には、次のようなビルド イベント サービス プロトコルに関連するフラグがあります。
--bes_backend
--[no]bes_best_effort
--[no]bes_lifecycle_events
--bes_results_url
--bes_timeout
--bes_instance_name
これらの各フラグの詳細については、コマンドライン リファレンスをご覧ください。
認証とセキュリティ
Bazel の Build Event Service の実装では、認証と TLS もサポートされています。これらの設定は、以下のフラグで制御できます。これらのフラグは Bazel のリモート実行でも使用されます。これは、ビルドイベント サービスとリモート実行エンドポイントが同じ認証と TLS インフラストラクチャを共有する必要があることを意味します。
--[no]google_default_credentials
--google_credentials
--google_auth_scopes
--tls_certificate
--[no]tls_enabled
これらの各フラグの詳細については、コマンドライン リファレンスをご覧ください。
イベント サービスとリモート キャッシュの構築
BEP には通常、Bazel が実行されているマシンに保存されているログファイル(test.log、test.xml など)への多くの参照が含まれています。これらのファイルは別のマシン上にあるため、リモート BES サーバーは通常、アクセスできません。この問題を回避するには、Bazel とリモート キャッシュを使用します。Bazel は、すべての出力ファイル(BEP で参照されているファイルを含む)をリモート キャッシュにアップロードし、BES サーバーはキャッシュから参照ファイルを取得できます。
詳しくは、GitHub の問題 3689 をご覧ください。