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

รายงานปัญหา ดูแหล่งที่มา

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

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

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

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

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

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

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

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

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

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

การใช้โปรโตคอลเหตุการณ์บิลด์

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

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

แฟล็กบริการเหตุการณ์

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

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

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

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

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

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

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

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

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

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