イベント プロトコルを構築する

問題を報告する ソースを表示 ナイトリー · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Build Event Protocol(BEP)を使用すると、サードパーティのプログラムが Bazel の呼び出しに関する分析情報を取得できます。たとえば、BEP を使用して、ビルド結果を表示する IDE プラグインやダッシュボードの情報を収集できます。

このプロトコルは、その上に定義されたセマンティクスを持つ一連のプロトコル バッファ メッセージです。ビルドとテストの結果、ビルドの進行状況、ビルド構成などに関する情報が含まれます。BEP はプログラムで使用することを目的としており、Bazel のコマンドライン出力の解析は過去のものになります。

Build Event Protocol は、ビルドに関する情報をイベントとして表します。ビルドイベントは、ビルドイベント ID、一連の子イベント ID、ペイロードで構成されるプロトコル バッファ メッセージです。

  • ビルドイベント ID: ビルドイベントの種類に応じて、ビルドイベントの詳細を示す不透明な文字列または構造化情報のいずれかになります。ビルドイベント ID はビルド内で一意です。

  • 子: ビルドイベントは、子フィールドにビルドイベント ID を含めることで、他のビルドイベントを通知できます。たとえば、PatternExpanded ビルドイベントは、子が拡張されるターゲットを通知します。このプロトコルでは、最初のイベントを除くすべてのイベントが、前のイベントによって通知されることが保証されます。

  • ペイロード: ペイロードには、そのイベントに固有のプロトコル バッファ メッセージとしてエンコードされた、ビルドイベントに関する構造化情報が含まれています。なお、ペイロードは想定されるタイプではない場合があります。ビルドが途中で中断された場合は、Aborted メッセージになる可能性があります。

イベントグラフを作成する

すべてのビルドイベントは、親子関係を通じて有向非巡回グラフを形成します。最初のビルドイベントを除くすべてのビルドイベントには、1 つ以上の親イベントがあります。なお、子イベントの親イベントがすべて子イベントの前に投稿される必要はありません。ビルドが完了すると(成功または失敗)、通知されたすべてのイベントが投稿されます。Bazel のクラッシュやネットワーク転送の失敗の場合、一部の通知されたビルドイベントが投稿されないことがあります。

イベントグラフの構造は、コマンドのライフサイクルを反映しています。すべての BEP グラフには、次の特徴的な形状があります。

  1. ルートイベントは常に BuildStarted イベントです。他のすべてのイベントはその子孫です。
  2. BuildStarted イベントの直接の子には、コマンドに関するメタデータが含まれています。
  3. ビルドされたファイルやテスト結果など、コマンドによって生成されたデータを含むイベントは、BuildFinished イベントの前に表示されます。
  4. BuildFinished イベントの後に、ビルドに関する概要情報(指標やプロファイリング データなど)を含むイベントが続くことがあります。

Build Event Protocol の使用

バイナリ形式で消費する

BEP をバイナリ形式で使用するには:

  1. オプション --build_event_binary_file=/path/to/file を指定して、Bazel にプロトコル バッファ メッセージをファイルにシリアル化させます。このファイルには、シリアル化されたプロトコル バッファ メッセージが含まれ、各メッセージは長さで区切られます。各メッセージの先頭には、可変長整数としてエンコードされた長さが付加されます。この形式は、プロトコル バッファ ライブラリの parseDelimitedFrom(InputStream) メソッドを使用して読み取ることができます。

  2. 次に、シリアル化されたプロトコル バッファ メッセージから関連情報を抽出するプログラムを作成します。

テキスト形式または JSON 形式で使用

次の Bazel コマンドライン フラグを使用すると、BEP がテキストや JSON などの人間が読める形式で出力されます。

--build_event_text_file
--build_event_json_file

Build Event Service

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://)を付ける必要があります。

Build Event Service フラグ

Bazel には、Build Event Service プロトコルに関連する次のようなフラグがあります。

  • --bes_backend
  • --[no]bes_lifecycle_events
  • --bes_results_url
  • --bes_timeout
  • --bes_instance_name

これらのフラグの説明については、コマンドライン リファレンスをご覧ください。

認証とセキュリティ

Bazel の Build Event Service の実装は、認証と TLS もサポートしています。これらの設定は、次のフラグを使用して制御できます。これらのフラグは、Bazel のリモート実行にも使用されます。つまり、Build Event Service と Remote Execution Endpoints は、同じ認証と TLS インフラストラクチャを共有する必要があります。

  • --[no]google_default_credentials
  • --google_credentials
  • --google_auth_scopes
  • --tls_certificate
  • --[no]tls_enabled

これらのフラグの詳細については、コマンドライン リファレンスをご覧ください。

Build Event Service とリモート キャッシュ

通常、BEP には、Bazel が実行されているマシンに保存されているログファイル(test.log、test.xml など)への参照が多数含まれています。通常、リモート BES サーバーは、これらのファイルが別のマシンにあるため、これらのファイルにアクセスできません。この問題を回避するには、リモート キャッシュで Bazel を使用します。Bazel は、すべての出力ファイルをリモート キャッシュにアップロードします(BEP で参照されているファイルを含む)。これにより、BES サーバーはキャッシュから参照ファイルを取得できます。

詳しくは、GitHub の問題 3689 をご覧ください。