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

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

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

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

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

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

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

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

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

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

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

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

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

วิธีใช้ BEP ในรูปแบบไบนารี

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

2. จากนั้นเขียนโปรแกรมที่ดึงข้อมูลที่เกี่ยวข้องจาก ข้อความ Protocol Buffer ที่แปลงเป็นอนุกรมแล้ว

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

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

--build_event_text_file
--build_event_json_file

บริการ Build Event

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

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

Bazel มีแฟล็กหลายรายการที่เกี่ยวข้องกับโปรโตคอล Build Event Service ซึ่งรวมถึง

• --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