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

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Báo cáo sự cố Xem nguồn

Giao thức sự kiện xây dựng (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 một trình bổ trợ IDE hoặc trang tổng quan hiển thị kết quả về bản dựng.

Giao thức là một tập hợp thông báo bộ đệm giao thức có một số ngữ nghĩa được xác định ở trên. Báo cáo này bao gồm thông tin về các kết quả của bản dựng và thử nghiệm, 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 dự định sẽ được sử dụng theo phương thức lập trình và khiến việc phân tích cú pháp kết quả đầu ra của dòng lệnh của Bazel trở thành một điều trong quá khứ.

Giao thức bản dựng sự kiện thể hiện 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 tạo bản dựng, một tập hợp giá trị nhận dạng sự kiện con và một trọng tải.

  • Mã nhận dạng sự kiện bản dựng: Tuỳ thuộc vào loại sự kiện xây dựng, đó có thể là chuỗi mờ hoặc thông tin có cấu trúc hiển thị thêm về sự kiện xây dựng. Giá trị nhận dạng sự kiện xây dựng là duy nhất trong một bản dựng.

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

  • Phần tải: Trọng tải chứa thông tin có cấu trúc về một sự kiện bản dựng, được mã hóa dưới dạng thông báo vùng đệm giao thức dành riêng cho sự kiện đó. Xin lưu ý rằng trọng tải 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.

Xây dựng biểu đồ sự kiện

Tất cả các sự kiện xây dựng đều 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. Ngoại trừ sự kiện xây dựng ban đầu, mỗi sự kiện xây dựng đều có một hoặc nhiều sự kiện mẹ. Xin lưu ý rằng không phải tất cả các sự kiện mẹ của một sự kiện con đều phải được đăng trước khi sự kiện đó diễn ra. Khi 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ông bố sẽ được đăng. Trong trường hợp Bazel gặp sự cố 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 đượ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 điểm 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à con cháu của sự kiện đó.
  2. Các thành phần con ngay lập tức của sự kiện BuildStarted 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. Sự kiện BuildFinished có thể theo sau là các sự kiện chứa thông tin tóm tắt về bản dựng (ví dụ: chỉ số hoặc dữ liệu hồ sơ).

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

Tiêu thụ ở đị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 chuyển đổi tuần tự, trong đó mỗi thông báo được phân tách theo độ dài. Mỗi thông điệp sẽ được mã hoá bằng độ dài được mã hoá dưới dạng số nguyên có độ dài thay đổ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 chuyển đổi tuần tự.

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

Các cờ hiệu dòng lệnh sau của Bazel sẽ xuất ra 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 sự kiện tạo bản dựng Giao thức là một dịch vụ gRPC chung để xuất bản các sự kiện bản dựng. Giao thức Dịch vụ sự kiện xây dựng độc lập với BEP và coi các sự kiện BEP là các byte không trong suốt. Bazel sẽ triển khai ứng dụng gRPC cho giao thức Xây dựng sự kiện dịch vụ để phát hành các sự kiện Giao thức xây dựng sự kiện. Người dùng có thể chỉ định điểm cuối để gửi các sự kiện đến bằng cờ --bes_backend=HOST:PORT. Nếu phần phụ trợ của bạn sử dụng gRPC, bạn phải thêm tiền tố cho địa chỉ bằng lược đồ thích hợp: grpc:// cho gRPC văn bản thuần tuý và grpcs:// cho gRPC đã bật TLS.

Cờ dịch vụ sự kiện xây dựng

Bazel có một số cờ liên quan đến giao thức Dịch vụ sự kiện bản dựng, bao gồm:

  • --bes_backend
  • --[no]bes_best_effort
  • --[no]bes_lifecycle_events
  • --bes_results_url
  • --bes_timeout
  • --project_id

Để biết nội dung mô tả về từng cờ trong số này, hãy xem Tài liệu tham khảo về dòng lệnh.

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

Phương thức triển khai Dịch vụ bản dựng sự kiện của Bazel cũng hỗ trợ việc 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ác cờ bên dưới. Xin lưu ý rằng các cờ này cũng được dùng cho quá trình 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 phải có chung cơ sở hạ tầng TLS và xác thực.

  • --[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 Tài liệu tham khảo về dòng lệnh.

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

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áy chủ BES từ xa thường không thể truy cập vào các tệp này vì chúng nằm trên các máy khác nhau. Bạn có thể giải quyết vấn đề này bằng cách sử dụng Bazel bằng tính năng lưu từ xa vào bộ nhớ đệm. Bazel sẽ tải tất 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à máy chủ BES sau đó có thể tìm nạp các tệp được tham chiếu từ bộ nhớ đệm.

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