Protokol Peristiwa Build

Laporkan masalah Lihat sumber Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 adalah kumpulan pesan buffer protokol dengan beberapa semantik yang ditentukan di atasnya. Laporan 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 sudah ketinggalan zaman.

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

  • ID Peristiwa Build: Bergantung pada jenis peristiwa build, ID ini dapat berupa string buram atau informasi terstruktur yang mengungkapkan lebih lanjut 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 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 buffering protokol khusus untuk peristiwa tersebut. Perhatikan bahwa payload mungkin bukan jenis yang diharapkan, tetapi dapat berupa pesan Aborted jika build dibatalkan sebelum waktunya.

Membuat grafik peristiwa

Semua peristiwa build membentuk directed acyclic graph melalui hubungan induk dan turunan. Setiap peristiwa build kecuali untuk peristiwa build awal memiliki satu atau beberapa peristiwa induk. Perhatikan bahwa tidak semua peristiwa induk dari peristiwa turunan harus diposting sebelumnya. 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 berupa 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 ini, seperti file yang dibuat dan hasil pengujian, akan 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 buffering protokol ke file dengan menentukan opsi --build_event_binary_file=/path/to/file. File akan berisi pesan buffering protokol yang diserialisasi dengan setiap pesan yang dibatasi panjang. Setiap pesan diawali dengan panjangnya yang dienkode sebagai bilangan bulat dengan panjang variabel. Format ini dapat dibaca menggunakan metode parseDelimitedFrom(InputStream) library buffering protokol.

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

Gunakan dalam format teks atau JSON

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

--build_event_text_file
--build_event_json_file

Layanan Peristiwa Build

Build Event Service Protocol adalah layanan gRPC umum 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 flag --bes_backend=HOST:PORT. Jika backend menggunakan gRPC, Anda harus memberikan awalan pada alamat dengan skema yang sesuai: grpc:// untuk gRPC teks biasa dan grpcs:// untuk gRPC dengan TLS yang 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 deskripsi setiap flag ini, lihat Referensi Command Line.

Autentikasi dan keamanan

Implementasi Build Event Service Bazel juga mendukung otentikasi dan TLS. Setelan ini dapat dikontrol menggunakan flag di bawah. Perhatikan bahwa flag ini juga digunakan untuk Eksekusi Jarak Jauh Bazel. Artinya, Layanan Peristiwa Build dan Endpoint Eksekusi Jarak Jauh harus berbagi infrastruktur autentikasi dan TLS yang sama.

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

Untuk deskripsi setiap flag ini, lihat Referensi Command Line.

Layanan Peristiwa Build dan penyimpanan dalam cache jarak jauh

BEP biasanya berisi banyak referensi ke file log (test.log, test.xml, dll.) yang disimpan di komputer tempat Bazel berjalan. Server BES jarak jauh biasanya tidak dapat mengakses file ini karena berada di mesin yang berbeda. Cara untuk mengatasi masalah ini adalah menggunakan Bazel dengan caching 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 direferensikan dari cache.

Lihat masalah GitHub 3689 untuk mengetahui detail selengkapnya.