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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--build_event_text_file
--build_event_json_file

บริการ Build Event

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

Flag บริการ Build Event

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

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

ดูคำอธิบายของ Flag แต่ละรายการเหล่านี้ได้ที่ข้อมูลอ้างอิงเกี่ยวกับบรรทัดคำสั่ง

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

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

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

ดูคำอธิบายของ Flag แต่ละรายการเหล่านี้ได้ที่ข้อมูลอ้างอิงเกี่ยวกับบรรทัดคำสั่ง

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

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

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