Protokol Peristiwa Build

Laporkan masalah Lihat sumber

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 buffering protokol dengan beberapa semantik yang ditentukan di atasnya. Halaman ini berisi informasi tentang hasil build dan pengujian, progres build, konfigurasi build, dan banyak lagi. BEP dimaksudkan untuk digunakan secara terprogram dan membuat penguraian command line Bazel tidak lagi diperlukan.

Protokol Peristiwa Build menampilkan informasi tentang build sebagai peristiwa. Peristiwa build adalah pesan buffering protokol 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 peristiwa build lebih lanjut. ID peristiwa build bersifat unik dalam build.

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

  • Payload: Payload berisi informasi terstruktur tentang peristiwa build, yang dienkode sebagai pesan buffering protokol khusus untuk peristiwa tersebut. Perlu diperhatikan 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 untuk peristiwa build awal memiliki satu atau beberapa peristiwa induk. Perhatikan bahwa tidak semua acara induk dari acara turunan harus diposting sebelumnya. Setelah build selesai (berhasil atau gagal), semua peristiwa yang diumumkan akan diposting. Jika terjadi error Bazel atau transportasi jaringan yang gagal, 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 lain adalah turunannya.
  2. Turunan langsung 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 dengan peristiwa yang berisi informasi ringkasan tentang build (misalnya, data metrik atau pembuatan profil).

Memakai Protokol Peristiwa Build

Memakai dalam format biner

Untuk menggunakan BEP dalam format biner:

  1. Minta Bazel untuk membuat serialisasi pesan buffering protokol ke file dengan menentukan opsi --build_event_binary_file=/path/to/file. File ini akan berisi pesan buffering protokol yang diserialisasi dengan setiap pesan 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.

Memakai 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

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 dikirimkan dengan implementasi klien gRPC dari protokol Layanan Peristiwa Build yang memublikasikan peristiwa Build Event Protocol. Kita dapat menentukan endpoint untuk mengirim peristiwa untuk menggunakan flag --bes_backend=HOST:PORT. Jika backend Anda menggunakan gRPC, Anda harus mengawali alamat dengan skema yang sesuai: grpc:// untuk teks biasa gRPC dan grpcs:// untuk gRPC dengan TLS diaktifkan.

Tanda Layanan Peristiwa Build

Bazel memiliki beberapa flag yang terkait dengan protokol Build Event Service, termasuk:

  • --bes_backend
  • --[no]bes_best_effort
  • --[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 autentikasi dan TLS. Setelan ini dapat dikontrol menggunakan tanda di bawah. Perlu diperhatikan bahwa flag ini juga digunakan untuk Eksekusi Jarak Jauh Bazel. Ini menyiratkan bahwa Layanan Peristiwa Build dan Endpoint Eksekusi Jarak Jauh harus memiliki autentikasi dan infrastruktur 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 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 komputer yang berbeda. Cara untuk mengatasi masalah ini adalah dengan menggunakan Bazel dengan 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 direferensikan dari cache.

Lihat Masalah GitHub 3689 untuk detail selengkapnya.