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

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

  • รายการย่อย: กิจกรรมบิลด์อาจประกาศกิจกรรมบิลด์อื่นๆ โดยใส่ตัวระบุกิจกรรมบิลด์ในช่องรายการย่อย เช่น เหตุการณ์ 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

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

แฟล็กบริการเหตุการณ์ของบิลด์

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

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

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

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

การใช้งานบริการเหตุการณ์การสร้างของ Bazel ยังรองรับการตรวจสอบสิทธิ์และ TLS ด้วย คุณควบคุมการตั้งค่าเหล่านี้ได้โดยใช้แฟล็กด้านล่าง โปรดทราบว่า 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