Protokol Peristiwa Build

7/0.9/2.5. Lihat sumber Nightly {/3/}

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. Panduan ini mencakup 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 lama lagi.

Build Event Protocol mewakili 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 tersebut mungkin berupa string buram atau informasi terstruktur yang mengungkapkan lebih banyak tentang peristiwa build. ID peristiwa build bersifat unik dalam sebuah build.

  • Children: Peristiwa build dapat mengumumkan peristiwa build lainnya, dengan menyertakan ID peristiwa build-nya di kolom turunan. Misalnya, peristiwa build PatternExpanded mengumumkan target yang diperluas sebagai turunan. Protokol menjamin bahwa semua peristiwa, kecuali untuk peristiwa pertama, akan 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 dapat berupa pesan Aborted jika build dibatalkan sebelum waktunya.

Buat grafik peristiwa

Semua peristiwa build membentuk grafik asiklik terarah melalui hubungan induk dan turunan mereka. 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 transportasi 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 berupa peristiwa BuildStarted. Semua peristiwa lainnya adalah turunannya.
  2. Turunan langsung peristiwa BuildStarted berisi metadata tentang perintah tersebut.
  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).

Memakai Build Event Protocol

Memakai 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 tersebut akan berisi pesan buffering protokol yang diserialisasi dengan setiap pesan dibatasi panjangnya. 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 Build Event Service tidak bergantung pada 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 tanda --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 Build Event Service

Bazel memiliki beberapa tanda 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 autentikasi dan TLS. Setelan ini dapat dikontrol menggunakan tanda di bawah. Perlu diketahui bahwa penanda 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.

Membangun Event Service 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 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 GitHub masalah 3689 untuk detail selengkapnya.