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

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Giao thức Sự kiện bản dựng (BEP) cho phép các chương trình của bên thứ ba hiểu rõ hơn về một 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 một trang tổng quan hiển thị kết quả bản dựng.

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

Giao thức sự kiện bản dựng trình bày thông tin về một bản dựng dưới dạng các 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 tập hợp các giá trị nhận dạng sự kiện con và một tải trọng.

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

  • Phần tử con: Một 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 của các sự kiện đó vào trường phần tử con của sự kiện đó. Ví dụ: sự kiện bản dựng PatternExpanded thông báo các mục tiêu mà sự kiện này mở rộng thành 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 một sự kiện trước đó thông báo.

  • 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 đó. Xin 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ỷ bỏ sớm.

Biểu đồ sự kiện bản dựng

Tất cả các sự kiện bản dựng tạo thành một biểu đồ có hướng không có chu kỳ thông qua mối quan hệ mẹ và con. Mọi sự kiện bản dựng, ngoại trừ sự kiện 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 tất cả các sự kiện mẹ của một sự kiện con đều phải đượ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 Bazel gặp sự cố hoặc quá trình truyền tải mạng không thành công, một số sự kiện bản dựng được 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 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à sự kiện hậu duệ của sự kiện này.
  2. Các phần tử con trực tiếp 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 xây dựng và kết quả kiểm thử, xuất hiện trước BuildFinished sự kiện.
  4. Sự kiện BuildFinished có thể được theo sau bởi 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 lập hồ sơ).

Sử dụng Giao thức sự kiện 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 tuần tự hoá 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 báo vùng đệm giao thức được tuần tự hoá, trong đó mỗi thông báo được phân tách theo độ dài. Mỗi thông báo được thêm tiền tố bằng độ dài của thông báo đó đượ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 của thư viện vùng đệm giao thức. parseDelimitedFrom(InputStream)

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

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

Dịch vụ sự kiện bản dựng

Giao thức Dịch vụ Sự kiện Bản dựng 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 bản dựng độc lập với BEP và coi các sự kiện BEP là byte mờ đục. Bazel đi kèm với một bản triển khai ứng dụng gRPC của giao thức dịch vụ sự kiện bản dựng xuất bản các sự kiện Giao thức sự kiện bản dựng. Bạn có thể chỉ định điểm cuối để gửi các sự kiện đế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, bạn phải thêm tiền tố địa chỉ bằng lược đồ thích hợp: grpc:// cho gRPC văn bản thuần và grpcs:// cho gRPC có bật TLS.

Cờ dịch vụ sự kiện bản 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ờ 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

Bản triển khai Dịch vụ sự kiện bản 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ác cờ bên dưới. Xin lưu ý rằng các cờ này cũng được dùng cho tính năng Thực thi từ xa của Bazel. Điều này ngụ ý rằng Dịch vụ sự kiện bản dựng và Điểm cuối thực thi từ xa cần dùng chung 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ờ này, hãy xem Tài liệu tham khảo về dòng lệnh.

Dịch vụ sự kiện bản dựng và bộ nhớ đệm từ xa

BEP thường chứa nhiều tham chiếu đến các tệp nhật ký (test.log, test.xml, v.v.) được lưu trữ trên máy chạy Bazel. 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. Một cách để giải quyết vấn đề này là sử dụng Bazel với 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.

Xem vấn đề 3689 trên GitHub để biết thêm thông tin.