Xây dựng giao thức sự kiện

Báo cáo vấn đề Xem nguồn Nightly .

Xây dựng Giao thức sự kiện (BEP) cho phép các chương trình của bên thứ ba thu thập thông tin chi tiết về lệnh gọi Bazel. Ví dụ: bạn có thể sử dụng BEP để thu thập thông tin cho trình bổ trợ IDE hoặc một trang tổng quan cho thấy kết quả về bản dựng.

Giao thức là một tập hợp các thông báo vùng đệm giao thức với một số ngữ nghĩa được xác định ở trên cùng. Thư viện này bao gồm thông tin về kết quả bản dựng và kiểm thử, tiến trình xây dựng, cấu hình bản dựng và nhiều thông tin khác. BEP được sử dụng theo phương thức lập trình và biến việc phân tích cú pháp dòng lệnh của Bazel thành dĩ vãng.

Giao thức sự kiện bản dựng biểu thị thông tin về một bản dựng dưới dạng sự kiện. Sự kiện bản dựng là một thông báo vùng đệm giao thức bao gồm một giá trị nhận dạng sự kiện bản dựng, một bộ giá trị nhận dạng sự kiện con và một tải trọng.

  • Tạo giá trị nhận dạng sự kiện: Tuỳ thuộc vào loại sự kiện của bản dựng, có thể là một chuỗi mờ hoặc thông tin có cấu trúc cung cấp thêm thông tin về sự kiện tạo bản dựng. Giá trị nhận dạng sự kiện bản dựng là giá trị duy nhất trong một bản dựng.

  • Tệp con: Sự kiện bản dựng có thể thông báo các sự kiện bản dựng khác bằng cách đưa giá trị nhận dạng sự kiện bản dựng vào trường con. Ví dụ: sự kiện tạo bản dựng PatternExpanded sẽ thông báo các mục tiêu mà sự kiện này mở rộng dưới dạng phần tử con. Giao thức đảm bảo rằng tất cả các sự kiện (ngoại trừ sự kiện đầu tiên) đều được công bố thông qua một sự kiện trước đó.

  • Tải trọng: Tải trọng chứa thông tin có cấu trúc về một sự kiện bản dựng, được mã hoá dưới dạng thông báo vùng đệm giao thức dành riêng cho sự kiện đó. Lưu ý rằng tải trọng có thể không phải là loại dự kiến nhưng có thể là thông báo Aborted nếu bản dựng bị huỷ sớm.

Tạo biểu đồ sự kiện

Tất cả sự kiện bản dựng tạo thành một biểu đồ không chu trình có hướng thông qua mối quan hệ mẹ và con. Mỗi sự kiện tạo bản dựng (ngoại trừ sự kiện tạo bản dựng ban đầu) đều có một hoặc nhiều sự kiện mẹ. Xin lưu ý rằng không phải sự kiện mẹ nào của một sự kiện con cũng cần được đăng trước sự kiện đó. Khi một bản dựng hoàn tất (thành công hoặc không thành công), tất cả các sự kiện được thông báo sẽ được đăng. Trong trường hợp xảy ra sự cố Bazel hoặc truyền tải mạng không thành công, một số sự kiện bản dựng đã thông báo có thể không bao giờ được đăng.

Cấu trúc của biểu đồ sự kiện phản ánh vòng đời của một lệnh. Mỗi biểu đồ BEP đều có hình dạng đặc trưng như sau:

  1. Sự kiện gốc luôn là sự kiện BuildStarted. Tất cả các sự kiện khác đều là thành phần con của sự kiện đó.
  2. Các phần tử con ngay lập tức của sự kiện BuildStarted (Bắt đầu dựng) chứa siêu dữ liệu về lệnh.
  3. Các sự kiện chứa dữ liệu do lệnh tạo ra, chẳng hạn như các tệp được tạo và kết quả kiểm thử, sẽ xuất hiện trước sự kiện BuildFinished.
  4. Theo sau sự kiện BuildFinished có thể có các sự kiện chứa thông tin tóm tắt về bản dựng (ví dụ: dữ liệu chỉ số hoặc dữ liệu phân tích tài nguyên).

Sử dụng giao thức sự kiện của bản dựng

Sử dụng ở định dạng nhị phân

Cách sử dụng BEP ở định dạng nhị phân:

  1. Yêu cầu Bazel chuyển đổi tuần tự các thông báo vùng đệm giao thức thành một tệp bằng cách chỉ định tuỳ chọn --build_event_binary_file=/path/to/file. Tệp này sẽ chứa các thông điệp vùng đệm giao thức nối tiếp, trong đó mỗi thông điệp được phân tách độ dài. Mỗi thư có tiền tố là độ dài được mã hoá dưới dạng số nguyên có độ dài biến đổi. Bạn có thể đọc định dạng này bằng phương thức parseDelimitedFrom(InputStream) của thư viện vùng đệm giao thức.

  2. Sau đó, viết một chương trình trích xuất thông tin liên quan từ thông báo vùng đệm giao thức tuần tự.

Sử dụng ở định dạng văn bản hoặc JSON

Các cờ dòng lệnh Bazel sau đây sẽ xuất BEP ở các định dạng mà con người có thể đọc được, chẳng hạn như văn bản và JSON:

--build_event_text_file
--build_event_json_file

Xây dựng dịch vụ sự kiện

Giao thức Dịch vụ sự kiện tạo là một dịch vụ gRPC chung để phát hành sự kiện bản dựng. Giao thức Build Event Service (Dịch vụ sự kiện bản dựng) độc lập với BEP và coi các sự kiện BEP là các byte mờ. Bazel triển khai một ứng dụng gRPC của giao thức Dịch vụ sự kiện tạo bản dựng. Giao thức này sẽ xuất bản các sự kiện Giao thức sự kiện tạo. Bạn có thể chỉ định điểm cuối để gửi các sự kiện bằng cách sử dụng cờ --bes_backend=HOST:PORT. Nếu phần phụ trợ của bạn sử dụng gRPC, thì bạn phải thêm tiền tố địa chỉ bằng giao thức thích hợp: grpc:// cho gRPC văn bản thuần tuý và grpcs:// cho gRPC có bật TLS.

Tạo cờ Dịch vụ sự kiện

Bazel có một số cờ liên quan đến giao thức Build Event Service (Dịch vụ sự kiện tạo), trong đó có:

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

Để biết nội dung mô tả về từng cờ trong số này, hãy xem phần Tham chiếu dòng lệnh.

Xác thực và bảo mật

Hoạt động triển khai Dịch vụ sự kiện xây dựng của Bazel cũng hỗ trợ xác thực và TLS. Bạn có thể kiểm soát các chế độ cài đặt này bằng cách sử dụng các cờ bên dưới. Xin lưu ý rằng các cờ này cũng được dùng cho Hoạt động thực thi từ xa của Bazel. Điều này có nghĩa là Dịch vụ sự kiện xây dựng và Điểm cuối thực thi từ xa cần dùng chung cùng một cơ sở hạ tầng xác thực và TLS.

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

Để biết nội dung mô tả về từng cờ trong số này, hãy xem phần Tham chiếu dòng lệnh.

Xây dựng dịch vụ sự kiện và lưu vào bộ nhớ đệm từ xa

BEP thường chứa nhiều tệp tham chiếu đến tệp nhật ký (test.log, test.xml, v.v.) được lưu trữ trên máy mà Bazel đang chạy. Một máy chủ BES từ xa thường không thể truy cập vào các tệp này vì các tệp này đang ở trên các máy khác nhau. Một cách để giải quyết vấn đề này là sử dụng Bazel với tính năng lưu vào bộ nhớ đệm từ xa. Bazel sẽ tải tất cả các tệp đầu ra lên bộ nhớ đệm từ xa (bao gồm cả các tệp được tham chiếu trong BEP) và sau đó, máy chủ BES có thể tìm nạp các tệp được tham chiếu từ bộ nhớ đệm.

Hãy xem Vấn đề GitHub 3689 để biết thêm thông tin chi tiết.