Protokol Peristiwa Build

Laporkan masalah Lihat sumber Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Build Event Protocol (BEP) memungkinkan program pihak ketiga mendapatkan insight tentang pemanggilan Bazel. Misalnya, Anda dapat menggunakan BEP untuk mengumpulkan informasi untuk plugin IDE atau dasbor yang menampilkan hasil build.

Protokol ini adalah sekumpulan pesan buffer protokol dengan beberapa semantik yang ditentukan di atasnya. Tab ini mencakup informasi tentang hasil build dan pengujian, progres build, konfigurasi build, dan banyak lagi. BEP dimaksudkan untuk digunakan secara terprogram dan membuat parsing output command line Bazel menjadi tidak diperlukan lagi.

Build Event Protocol menampilkan informasi tentang build sebagai peristiwa. Peristiwa build adalah pesan buffer protokol yang terdiri dari ID peristiwa build, serangkaian ID peristiwa turunan, dan payload.

  • ID Peristiwa Build: Bergantung pada jenis peristiwa build, ID ini mungkin berupa string buram atau informasi terstruktur yang mengungkapkan lebih banyak tentang peristiwa build. ID peristiwa build bersifat unik dalam build.

  • Turunan: Peristiwa build dapat mengumumkan peristiwa build lainnya, dengan menyertakan ID peristiwa build-nya di kolom turunan. Misalnya, peristiwa build PatternExpanded mengumumkan target yang diperluasnya sebagai turunan. Protokol ini menjamin bahwa semua peristiwa, kecuali peristiwa pertama, diumumkan oleh peristiwa sebelumnya.

  • Payload: Payload berisi informasi terstruktur tentang peristiwa build, yang dienkode sebagai pesan buffer protokol khusus untuk peristiwa tersebut. Perhatikan bahwa payload mungkin bukan jenis yang diharapkan, tetapi bisa berupa pesan Aborted jika build dibatalkan sebelum waktunya.

Membangun grafik peristiwa

Semua peristiwa build membentuk grafik asiklik berarah melalui hubungan induk dan turunannya. Setiap peristiwa build, kecuali peristiwa build awal, memiliki satu atau beberapa peristiwa induk. Perhatikan bahwa tidak semua acara induk dari acara anak harus diposting sebelum acara anak. Setelah build selesai (berhasil atau gagal), semua peristiwa yang diumumkan akan diposting. Jika terjadi error Bazel atau kegagalan transmisi jaringan, beberapa peristiwa build yang diumumkan mungkin tidak pernah diposting.

Struktur grafik peristiwa mencerminkan siklus proses perintah. Setiap grafik BEP memiliki bentuk karakteristik berikut:

  1. Peristiwa root selalu merupakan peristiwa BuildStarted. Semua peristiwa lainnya adalah turunannya.
  2. Turunan langsung dari peristiwa BuildStarted berisi metadata tentang perintah.
  3. Peristiwa yang berisi data yang dihasilkan oleh perintah, seperti file yang dibuat dan hasil pengujian, muncul sebelum peristiwa BuildFinished.
  4. Peristiwa BuildFinished dapat diikuti oleh peristiwa yang berisi informasi ringkasan tentang build (misalnya, data metrik atau pembuatan profil).

Menggunakan Build Event Protocol

Menggunakan dalam format biner

Untuk menggunakan BEP dalam format biner:

  1. Minta Bazel melakukan serialisasi pesan protocol buffer ke file dengan menentukan opsi --build_event_binary_file=/path/to/file. File akan berisi pesan buffer protokol yang diserialkan dengan setiap pesan dibatasi panjangnya. Setiap pesan diawali dengan panjangnya yang dienkode sebagai bilangan bulat panjang variabel. Format ini dapat dibaca menggunakan metode parseDelimitedFrom(InputStream) library protocol buffer.

  2. Kemudian, tulis program yang mengekstrak informasi yang relevan dari pesan buffer protokol yang diserialisasi.

Menggunakan dalam format teks atau JSON

Flag command line Bazel berikut akan menampilkan BEP dalam format yang dapat dibaca manusia, seperti teks dan JSON:

--build_event_text_file
--build_event_json_file

Build Event Service

Protokol Build Event Service adalah layanan gRPC generik untuk memublikasikan peristiwa build. Protokol Layanan Peristiwa Build tidak bergantung pada BEP dan memperlakukan peristiwa BEP sebagai byte buram. Bazel dilengkapi dengan penerapan klien gRPC dari protokol Build Event Service yang memublikasikan peristiwa Build Event Protocol. Anda dapat menentukan endpoint untuk mengirim peristiwa menggunakan tanda --bes_backend=HOST:PORT. Jika backend Anda menggunakan gRPC, Anda harus menambahkan awalan skema yang sesuai ke alamat: grpc:// untuk gRPC teks biasa dan grpcs:// untuk gRPC dengan TLS diaktifkan.

Membangun flag Layanan Peristiwa

Bazel memiliki beberapa tanda terkait protokol Layanan Peristiwa Build, termasuk:

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

Untuk mengetahui deskripsi setiap flag ini, lihat Referensi Command Line.

Autentikasi dan keamanan

Implementasi Layanan Peristiwa Build Bazel juga mendukung autentikasi dan TLS. Setelan ini dapat dikontrol menggunakan tanda di bawah. Perhatikan bahwa tanda ini juga digunakan untuk Eksekusi Jarak Jauh Bazel. Hal ini menunjukkan bahwa Build Event Service dan Remote Execution Endpoints harus menggunakan infrastruktur TLS dan autentikasi yang sama.

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

Untuk mengetahui deskripsi setiap flag ini, lihat Referensi Command Line.

Layanan Peristiwa Build dan caching jarak jauh

BEP biasanya berisi banyak referensi ke file log (test.log, test.xml, dll. ) yang disimpan di mesin tempat Bazel berjalan. Server BES jarak jauh biasanya tidak dapat mengakses file ini karena berada di mesin yang berbeda. Salah satu cara untuk mengatasi masalah ini adalah dengan menggunakan Bazel dengan penyimpanan cache jarak jauh. Bazel akan mengupload semua file output ke cache jarak jauh (termasuk file yang dirujuk dalam BEP) dan server BES kemudian dapat mengambil file yang dirujuk dari cache.

Lihat masalah GitHub 3689 untuk mengetahui detail selengkapnya.