สร้างโปรโตคอลเหตุการณ์

Build Event Protocol (BEP) ช่วยให้โปรแกรมของบุคคลที่สามได้รับข้อมูลเชิงลึกเกี่ยวกับการเรียกใช้ Bazel ตัวอย่างเช่น คุณอาจใช้ BEP เพื่อรวบรวมข้อมูลสำหรับปลั๊กอิน IDE หรือแดชบอร์ดที่แสดงผลการบิลด์

โปรโตคอลคือชุดข้อความ protocol buffer ที่มี ความหมายบางอย่างที่กำหนดไว้ด้านบน ซึ่งรวมถึงข้อมูลเกี่ยวกับผลลัพธ์ของการบิลด์และการทดสอบ ความคืบหน้าของการบิลด์ การกำหนดค่าบิลด์ และอื่นๆ อีกมากมาย BEP มีไว้เพื่อใช้แบบเป็นโปรแกรมและทำให้การแยกวิเคราะห์เอาต์พุตบรรทัดคำสั่งของ Bazel เป็นเรื่องในอดีต

Build Event Protocol แสดงข้อมูลเกี่ยวกับการสร้างเป็นเหตุการณ์ เหตุการณ์บิลด์คือข้อความบัฟเฟอร์โปรโตคอลที่ประกอบด้วยตัวระบุเหตุการณ์บิลด์ ชุดตัวระบุเหตุการณ์ย่อย และเพย์โหลด

• สร้างตัวระบุเหตุการณ์: เหตุการณ์บิลด์อาจเป็นสตริง ที่ไม่โปร่งใส หรือข้อมูล ที่มีโครงสร้าง ซึ่งเผยให้เห็นรายละเอียดเพิ่มเติมเกี่ยวกับเหตุการณ์บิลด์ ทั้งนี้ขึ้นอยู่กับประเภทของเหตุการณ์บิลด์ ตัวระบุเหตุการณ์บิลด์จะไม่ซ้ำกันภายใน บิลด์

• เหตุการณ์ย่อย: เหตุการณ์บิลด์อาจประกาศเหตุการณ์บิลด์อื่นๆ โดยการใส่ตัวระบุเหตุการณ์บิลด์ในฟิลด์เหตุการณ์ย่อย เช่น เหตุการณ์บิลด์ PatternExpanded จะประกาศเป้าหมายที่ขยายเป็นองค์ประกอบย่อย โปรโตคอลรับประกันว่าเหตุการณ์ทั้งหมด ยกเว้นเหตุการณ์แรก จะได้รับการประกาศโดยเหตุการณ์ก่อนหน้า

• เพย์โหลด: เพย์โหลดมีข้อมูลที่มีโครงสร้างเกี่ยวกับเหตุการณ์บิลด์ ซึ่งเข้ารหัสเป็นข้อความบัฟเฟอร์โปรโตคอลที่เฉพาะเจาะจงสำหรับเหตุการณ์นั้น โปรดทราบว่า เพย์โหลดอาจไม่ใช่ประเภทที่คาดไว้ แต่อาจเป็นAbortedข้อความ หากการสร้างถูกยกเลิกก่อนเวลา

สร้างกราฟเหตุการณ์

เหตุการณ์การสร้างทั้งหมดจะสร้างกราฟแบบมีทิศทางและไม่มีวัฏจักรผ่านความสัมพันธ์หลักและย่อย เหตุการณ์บิลด์ทุกเหตุการณ์ ยกเว้นเหตุการณ์บิลด์เริ่มต้น จะมีเหตุการณ์ระดับบนอย่างน้อย 1 เหตุการณ์ โปรดทราบว่ากิจกรรมหลักของกิจกรรมย่อยไม่จำเป็นต้องโพสต์ก่อนกิจกรรมย่อยเสมอไป เมื่อการสร้างเสร็จสมบูรณ์ (สำเร็จหรือไม่สำเร็จ) ระบบจะโพสต์เหตุการณ์ที่ประกาศทั้งหมด ในกรณีที่ Bazel ขัดข้องหรือการรับส่งข้อมูลเครือข่ายล้มเหลว ระบบอาจไม่โพสต์เหตุการณ์การสร้างที่ประกาศไว้บางรายการ

โครงสร้างของกราฟเหตุการณ์จะแสดงวงจรของคำสั่ง กราฟ BEP ทุกกราฟมีรูปร่างลักษณะต่อไปนี้

1. เหตุการณ์รูทจะเป็นเหตุการณ์ BuildStarted เสมอ ส่วนเหตุการณ์อื่นๆ ทั้งหมดคือเหตุการณ์ที่สืบทอดมาจากเหตุการณ์นี้
2. บุตรหลานโดยตรงของเหตุการณ์ BuildStarted มีข้อมูลเมตาเกี่ยวกับคำสั่ง
3. เหตุการณ์ที่มีข้อมูลที่สร้างขึ้นโดยคำสั่ง เช่น ไฟล์ที่สร้างขึ้นและผลการทดสอบ จะปรากฏก่อนเหตุการณ์ BuildFinished
4. เหตุการณ์ BuildFinished อาจตามด้วยเหตุการณ์ที่มีข้อมูลสรุปเกี่ยวกับการบิลด์ (เช่น ข้อมูลเมตริก หรือการสร้างโปรไฟล์)

การใช้โปรโตคอล Build Event

ใช้ในรูปแบบไบนารี

หากต้องการใช้ BEP ในรูปแบบไบนารี ให้ทำดังนี้

1. ให้ Bazel จัดลำดับข้อความบัฟเฟอร์โปรโตคอลเป็นไฟล์โดยการระบุตัวเลือก --build_event_binary_file=/path/to/file ไฟล์จะมีข้อความบัฟเฟอร์โปรโตคอลที่ซีเรียลไลซ์ โดยแต่ละข้อความจะมีการจำกัดความยาว ข้อความแต่ละรายการจะมีคำนำหน้าเป็นความยาวของข้อความที่เข้ารหัสเป็นจำนวนเต็มที่มีความยาวผันแปร อ่านรูปแบบนี้ได้โดยใช้เมธอด parseDelimitedFrom(InputStream) ของไลบรารีบัฟเฟอร์โปรโตคอล

2. จากนั้นเขียนโปรแกรมที่ดึงข้อมูลที่เกี่ยวข้องจากข้อความบัฟเฟอร์โปรโตคอลที่ซีเรียลไลซ์

ใช้ในรูปแบบข้อความหรือ JSON

แฟล็กบรรทัดคำสั่ง Bazel ต่อไปนี้จะแสดงผล BEP ในรูปแบบที่มนุษย์อ่านได้ เช่น ข้อความและ JSON

--build_event_text_file
--build_event_json_file

บริการ Build Event

โปรโตคอลบริการ Build Event เป็นบริการ gRPC ทั่วไปสำหรับการเผยแพร่เหตุการณ์การสร้าง โปรโตคอลบริการ Build Event ไม่ขึ้นอยู่กับ BEP และถือว่าเหตุการณ์ BEP เป็นไบต์ที่ทึบแสง Bazel มาพร้อมกับการติดตั้งใช้งานไคลเอ็นต์ gRPC ของโปรโตคอล Build Event Service ที่ เผยแพร่เหตุการณ์โปรโตคอล Build Event ผู้ใช้สามารถระบุปลายทางที่จะส่งเหตุการณ์ได้โดยใช้แฟล็ก --bes_backend=HOST:PORT หากแบ็กเอนด์ใช้ gRPC คุณต้องนำหน้าที่อยู่ด้วยรูปแบบที่เหมาะสม: grpc:// สำหรับ gRPC แบบข้อความธรรมดา และ grpcs:// สำหรับ gRPC ที่เปิดใช้ TLS

แฟล็กบริการ Build Event

Bazel มีแฟล็กหลายรายการที่เกี่ยวข้องกับโปรโตคอลบริการเหตุการณ์บิลด์ ซึ่งรวมถึง

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

ดูคำอธิบายของแต่ละแฟล็กได้ที่ข้อมูลอ้างอิงของบรรทัดคำสั่ง

การตรวจสอบสิทธิ์และความปลอดภัย

การติดตั้งใช้งาน Build Event Service ของ Bazel ยังรองรับการตรวจสอบสิทธิ์และ TLS ด้วย คุณควบคุมการตั้งค่าเหล่านี้ได้โดยใช้ฟีเจอร์ค่าสถานะด้านล่าง โปรดทราบว่าแฟล็กเหล่านี้ยังใช้สำหรับการดำเนินการจากระยะไกลของ Bazel ด้วย ซึ่งหมายความว่า Build Event Service และปลายทางการดำเนินการจากระยะไกลต้องใช้โครงสร้างพื้นฐานการตรวจสอบสิทธิ์และ TLS เดียวกัน

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

ดูคำอธิบายของแต่ละแฟล็กได้ที่ข้อมูลอ้างอิงของบรรทัดคำสั่ง

บริการ Build Event และการแคชระยะไกล

โดยปกติแล้ว BEP จะมีการอ้างอิงไฟล์บันทึกจำนวนมาก (test.log, test.xml, etc. ) ที่จัดเก็บไว้ในเครื่องที่ Bazel ทำงานอยู่ โดยปกติแล้วเซิร์ฟเวอร์ BES ระยะไกล จะเข้าถึงไฟล์เหล่านี้ไม่ได้เนื่องจากอยู่ในเครื่องที่แตกต่างกัน วิธีแก้ปัญหานี้คือการใช้ Bazel กับการแคชระยะไกล Bazel จะอัปโหลดไฟล์เอาต์พุตทั้งหมดไปยังแคชระยะไกล (รวมถึงไฟล์ที่อ้างอิงใน BEP) จากนั้นเซิร์ฟเวอร์ BES จะดึงไฟล์ที่อ้างอิงจากแคชได้

ดูรายละเอียดเพิ่มเติมได้ที่ปัญหา GitHub 3689