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

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

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

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

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

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

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

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

--build_event_text_file
--build_event_json_file

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

บริการ สร้างเหตุการณ์ โปรโตคอลเป็นบริการ 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 Service ซึ่งรวมถึง

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

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

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

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

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

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

สร้างบริการกิจกรรมและการแคชระยะไกล

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

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