Protokol Peristiwa Build

Nightly · 9.1 · 9.0 · 8.7 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

The 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 kumpulan pesan protocol buffer dengan beberapa semantik yang ditentukan di atasnya. Protokol ini mencakup informasi tentang hasil build dan pengujian, progres build, konfigurasi build, dan banyak lagi. BEP dimaksudkan untuk digunakan secara terprogram dan membuat penguraian output command line Bazel menjadi hal yang tidak relevan.

Build Event Protocol merepresentasikan informasi tentang build sebagai peristiwa. Peristiwa build adalah pesan protocol buffer yang terdiri dari ID peristiwa build, kumpulan 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 di kolom turunannya. Misalnya, peristiwa build PatternExpanded mengumumkan target yang diperluasnya sebagai turunan. Protokol menjamin bahwa semua peristiwa, kecuali peristiwa pertama, diumumkan oleh peristiwa sebelumnya.

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

Grafik peristiwa build

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

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

  1. Peristiwa root selalu merupakan BuildStarted peristiwa. 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 untuk melakukan serialisasi pesan protocol buffer ke file dengan menentukan opsi --build_event_binary_file=/path/to/file. File akan berisi pesan protocol buffer yang diserialisasi 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 protocol buffer 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

Layanan Peristiwa Build

gRPC Protokol Build Event Service bersifat independen dari BEP dan memperlakukan peristiwa BEP sebagai byte buram. Bazel dilengkapi dengan implementasi klien gRPC dari protokol Build Event Service yang memublikasikan peristiwa Build Event Protocol. Anda dapat menentukan endpoint untuk mengirim peristiwa menggunakan flag --bes_backend=HOST:PORT. Jika backend Anda menggunakan gRPC, Anda harus menambahkan awalan alamat dengan skema yang sesuai: grpc:// untuk gRPC teks biasa dan grpcs:// untuk gRPC dengan TLS diaktifkan.

Flag Layanan Peristiwa Build

Bazel memiliki beberapa flag yang terkait dengan protokol Build Event Service, 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 Build Event Service Bazel juga mendukung autentikasi dan TLS. Setelan ini dapat dikontrol menggunakan flag di bawah. Perhatikan bahwa flag ini juga digunakan untuk Eksekusi Jarak Jauh Bazel. Hal ini menunjukkan bahwa Build Event Service dan Endpoint Eksekusi Jarak Jauh harus menggunakan infrastruktur autentikasi dan TLS 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 cache 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 menggunakan Bazel dengan cache jarak jauh. Bazel akan mengupload semua file output ke cache jarak jauh (termasuk file yang direferensikan di BEP), lalu server BES dapat mengambil file yang direferensikan dari cache.

Lihat masalah GitHub 3689 untuk mengetahui detail selengkapnya.