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