การตรวจสอบประสิทธิภาพการทํางาน

Health Monitor (HM) เป็นตัวแทน SDV ที่ทำงานในเครื่องเสมือน (VM) แต่ละเครื่องเพื่อติดตามสถานะของชุดบริการ กำหนดประสิทธิภาพการทำงานของ VM และสร้างรายงานประสิทธิภาพการทำงานของ VM เป็นระยะๆ

แพ็กเกจบริการที่ OEM กําหนดต้องรับฟังสัญญาณด้านสุขภาพต่างๆ ที่ HM รายงาน และดําเนินการกู้คืนตามข้อมูล เช่น อินสแตนซ์ SDV ที่มีแพ็กเกจบริการที่ขัดข้องอาจต้องรีสตาร์ทหรืออัปเดต

คุณกำหนดค่าเอเจนต์ HM เพื่อติดตามข้อมูลต่อไปนี้ได้

• สถานะการทำงานของเอนทิตีที่ทำงานเป็นระยะๆ โดยการตรวจสอบ ฮาร์ตบีตการทำงาน คุณกำหนดค่าการตรวจสอบนี้ได้ทั้งสำหรับอินสแตนซ์ของชุดบริการ และตัวแทน OEM ที่กำหนดเอง
  • สถานะการกู้คืนของอินสแตนซ์ชุดบริการ คุณกำหนดค่าชุดบริการ สำหรับการรีสตาร์ทอัตโนมัติเมื่อเกิดข้อขัดข้องได้ HM จะให้สัญญาณ เพื่อตรวจสอบกระบวนการกู้คืนนี้
  • QoS ของการสื่อสาร
• ความพร้อมใช้งานของ SDV และเอเจนต์ที่กำหนดเองของ OEM

แคตตาล็อก VSIDL ฉบับเต็ม รวมถึงคำจำกัดความของ Proto พร้อมให้ใช้งานที่ //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl

คำศัพท์

ข้อกำหนดเหล่านี้ใช้ในหน้านี้

ทำงานกับระบบย่อย HM

หากต้องการใช้ฟีเจอร์ HM การติดตั้งใช้งาน OEM ต้องมีคุณสมบัติดังนี้

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

กำหนดค่าระบบ HM

การกำหนดค่าที่เกี่ยวข้องกับ HM จะอยู่ในประเภทการกำหนดค่าใดประเภทหนึ่งต่อไปนี้

• การกำหนดค่าการตรวจสอบสถานะส่วนกลางต่อ VM
• การกำหนดค่าสถานะของแต่ละชุดบริการ ซึ่งกำหนดพารามิเตอร์สถานะสำหรับ อินสแตนซ์ทั้งหมดของชุดบริการ

การกำหนดค่าสถานะของแต่ละ VM

ในเวลาเรียกใช้ เอเจนต์ HM คาดหวังการกำหนดค่าสถานะของทั้ง VM ซึ่งเป็นไฟล์ Textproto (มีนามสกุล .textproto) ประเภท VMHealth ที่กำหนดไว้ที่ //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto การกำหนดค่าสถานะของ VM ควรอยู่ที่เส้นทางที่ระบุโดยใช้พร็อพเพอร์ตี้ระบบเวลาบูต androidboot.sdv.health_monitor.config_path หรือจะกำหนดค่าแบบไดนามิกในเวลาที่รันก็ได้โดยตั้งค่า persist.sdv.health_monitor.config_pathพร็อพเพอร์ตี้ของระบบเป็นเส้นทางที่กำหนดเอง การตั้งค่า persist.* จะมีความสำคัญเหนือกว่าการตั้งค่า androidboot.* คุณต้อง รีบูตอุปกรณ์เพื่อให้การกำหนดค่าใหม่มีผล

การกำหนดค่าสถานะของ VM ช่วยให้คุณตั้งค่าสิ่งต่อไปนี้ได้

• ความถี่ของรายงานสถานะ VM ผ่าน period_ms การตั้งค่านี้เป็นการ แลกเปลี่ยนระหว่างการส่งสัญญาณที่เร็วขึ้นว่าตรวจพบการละเมิดด้านสุขภาพ และ ประสิทธิภาพของระบบย่อย HM เราขอแนะนำให้กำหนดค่าไว้ที่ 100 มิลลิวินาที

• Agent ที่จะได้รับการตรวจสอบการขัดข้อง (ดูการตรวจสอบการขัดข้องของ Agent)

ตัวอย่างไฟล์การกำหนดค่าอยู่ใน //system/software_defined_vehicle/health_monitor/src/prod_configs/ ตัวอย่างไฟล์การกำหนดค่ามีดังนี้

period_ms: 100
monitored_agent {
  agent_name: "sdv_dt_agent"
  binder_interface_name: "google.sdv.data_tunnel.IAgentService/default"
}
monitored_agent {
  agent_name: "sdv_rpc_agent"
  binder_interface_name: "google.sdv.rpc.IRpcAgent/default"
}

ในตัวอย่างนี้ เอเจนต์ SDV DT และ RPC ได้รับการกำหนดค่าสำหรับการตรวจสอบข้อขัดข้อง และ รายงานสถานะของ VM ได้รับการกำหนดค่าให้เผยแพร่ทุกๆ 100 มิลลิวินาที

การกำหนดค่าแพ็กเกจบริการ

การตรวจสอบความสมบูรณ์ของอินสแตนซ์ชุดบริการเป็นทางเลือก หากต้องการเลือกใช้ ให้จัดเก็บไฟล์การกำหนดค่าด้านสุขภาพใน APEX ของชุดบริการและกำหนดเส้นทางไปยังไฟล์ดังกล่าวในฟิลด์ health_config_path ของ sdv_service_bundle_metadata ใน sdv_service_bundles_manifest.textproto ดูข้อมูลเพิ่มเติมเกี่ยวกับไฟล์ Manifest ของแพ็กเกจบริการได้ที่ข้อมูลเมตาของแพ็กเกจบริการ

ไฟล์การกำหนดค่าด้านสุขภาพคือไฟล์ Textproto ประเภทต่อไปนี้

message ServiceBundleHealthConfiguration {
  // Required: An empty ServiceBundleHealthConfiguration is equivalent to no
   // implicit health monitoring or QoS monitoring configured.
  //
  // Key should contain the instance name that the `InstanceConfiguration` applies to.
  map<string, InstanceConfiguration> instance_config = 1;
}

คุณระบุทั้งการกำหนดค่า Heartbeat การทำงานและการกำหนดค่า QoS สำหรับแต่ละอินสแตนซ์ได้โดยทำดังนี้

// Service bundle *instance* configuration.
message InstanceConfiguration {
  // Optional.
  //
  // Instance health monitoring configuration. Monitors instance
  // general health. Well suited for bundles executing periodic tasks.
  optional HealthConfiguration health_config = 1;

  // Optional.
   //
   // Map defining the QoS monitoring profile of the instance.
   // The key (string) is the topic name of the specific QoS heartbeat
   // publication. Choose a meaningful topic name for
   // expressive HM reporting.
   //
   // Only one publisher should publish on this topic. The HM
   // agent ignores all publishers except the first one registered
   // by the service bundle instance configured for QoS monitoring.
   map<string, QosMonitoringConfiguration> qos_config = 2;
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าต่อฟีเจอร์ได้ที่ การตรวจสอบสัญญาณชีพของความพร้อมใช้งานและการตรวจสอบ QoS

ฟังเอาต์พุตของ HM

คุณสามารถฟัง HM ผ่านรายงานเป็นระยะหรือ RPC API ก็ได้

รายงานสถานะของ VM

การตรวจสอบความสมบูรณ์จะสร้างรายงานความสมบูรณ์ของ VM เป็นระยะๆ ที่มีความถี่สูง ซึ่งให้ข้อมูลที่กระชับเกี่ยวกับสถานะความสมบูรณ์ของเอนทิตีที่ตรวจสอบ

ไวยากรณ์ประเภทของ VmHealth มีคำจำกัดความอยู่ใน //system/software_defined_vehicle/health_monitor/catalog/health_topic.proto

message VmHealth {
  // Required.
  // Describes if all monitored service bundles are healthy and report heartbeats on time.
  bool all_monitored_service_bundles_healthy = 1;

  // Required.
  // Describes if all service bundles which should be running on the VM are alive.
  bool all_service_bundles_alive = 2;

  // Required.
  // Indicates if QoS requirements for all service bundles which should be running
  // on the VM are satisfied.
  bool qos_violations_detected = 3;
}

ชุดบริการ Listener ของ HM ที่ OEM กำหนดควรรอรับVMHealthรายงาน และดำเนินการตามความเหมาะสมโดยขึ้นอยู่กับสถาปัตยกรรมระบบที่สมบูรณ์ การดำเนินการที่เป็นไปได้มีดังนี้

• เรียกใช้กิจวัตรการวินิจฉัยใน VM
• รีสตาร์ท VM
• เรียกใช้แคมเปญการวัดและส่งข้อมูลเพื่อระบุสาเหตุ
• อัปเดตระบบหรือหยุดการอัปเดตหากระบบทำงานผิดปกติ

HM RPC API

รายงานสถานะของ VM เป็นสิ่งพิมพ์ที่ได้รับการเพิ่มประสิทธิภาพสำหรับความถี่และความเร็วในการส่ง โดยให้ข้อมูลในวงกว้างเกี่ยวกับสถานะของระบบ

HM RPC API ช่วยให้ผู้ฟัง HM ได้รับข้อมูลโดยละเอียดเกี่ยวกับแหล่งที่มา ของการละเมิดด้านสุขภาพ อินเทอร์เฟซกำหนดไว้ใน //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto เราได้จำลองอินเทอร์เฟซไว้ที่นี่เพื่อความสะดวก

// RPC Interface of the VM Health Monitor Agent for querying details about the current VM
// health.
//
// An OEM-defined service bundle typically monitors the overall health of the SDV instance by listening to
// high-frequency `VMHealth` publication. If violations are detected, this RPC interface can
// be used to retrieve detailed information about the malfunctioning component.
service HealthMonitorService {
  // Returns the list of running SDV service bundles that were created or started
  // by the orchestrator on this VM.
  rpc ListAllServiceBundles(ListAllServiceBundlesRequest) returns (ListAllServiceBundlesResponse) {}

  // Returns the list of crashed SDV service bundles.
  rpc ListCrashingServiceBundles(ListCrashingServiceBundlesRequest)
      returns (ListCrashingServiceBundlesResponse) {}

  // Returns the list of recovering SDV service bundles.
  rpc ListRecoveringServiceBundles(ListRecoveringServiceBundlesRequest)
      returns (ListRecoveringServiceBundlesResponse) {}

  // Returns the list of monitored SDV service bundles, which registered for reporting
  // aliveness heartbeats but failed to report heartbeats on time.
  rpc ListUnhealthyMonitoredServiceBundles(ListUnhealthyMonitoredServiceBundlesRequest)
      returns (ListUnhealthyMonitoredServiceBundlesResponse) {}

  // Returns a list of QoS monitoring violations detected.
  // Provides a snapshot of the current system state.
  rpc ListQosViolations(ListQosViolationsRequest)
      returns (ListQosViolationsResponse) {}
}

คำอธิบายโดยละเอียดของฟีเจอร์

ส่วนนี้จะอธิบายแง่มุมต่างๆ ของ HM โดยละเอียด

การตรวจสอบการเต้นของหัวใจเพื่อดูว่ายังใช้งานได้อยู่

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

รูปที่ 1 โฟลว์การตรวจสอบการทำงานของ HM

การกำหนดค่า

หากต้องการเปิดใช้ HB การทำงานบนอินสแตนซ์ชุดบริการ ให้เพิ่มอินสแตนซ์ของ HealthConfiguration ลงในฟิลด์ health_config ในการกำหนดค่าชุด

การกำหนดค่าฮาร์ทบีตความพร้อมใช้งานจะกำหนดชุดพารามิเตอร์ที่กำหนดไว้ล่วงหน้า ซึ่งสร้างเกณฑ์สำหรับการประเมินสัญญาณฮาร์ทบีตเป็นระยะของบริการ หากลักษณะการทำงานของ Heartbeat ของบริการเบี่ยงเบนไปจากพารามิเตอร์เหล่านี้ ระบบจะจัดประเภท Heartbeat ว่าล่าช้าและจัดประเภทแพ็กเกจบริการที่เกี่ยวข้องว่า ไม่สมบูรณ์ ซึ่งอาจบ่งบอกถึงสถานะการทำงานที่ไม่เหมาะสม

ระบบจะถือว่าชุดบริการมีประสิทธิภาพดีเมื่อรายงานการเต้นของหัวใจตรงเวลา ตามการกำหนดค่าประสิทธิภาพ ในกรณีที่เกิดข้อขัดข้องหรือโหลดระบบสูง อาจไม่มีการส่งสัญญาณชีพหรือมีการส่งสัญญาณชีพล่าช้า ซึ่งจะทำให้ระบบทำเครื่องหมายชุดบริการว่ามีสถานะไม่ดี ในกรณีนี้ การละเมิดจะปรากฏในVmHealthรายงาน

นักพัฒนาแพ็กเกจบริการควรกำหนดค่าการตรวจสอบสถานะของแพ็กเกจบริการในข้อมูลเมตา APEX ที่เกี่ยวข้อง การกำหนดค่าความสมบูรณ์จะกำหนดเกณฑ์ต่อไปนี้

• ความล่าช้าเริ่มต้นสูงสุดที่อนุญาตระหว่างการเริ่มต้นบริการและการตรวจจับ การเต้นของหัวใจครั้งแรก

• ระยะเวลาที่ชุดบริการ SDV ดำเนินการตามตรรกะทางธุรกิจ ซึ่งสอดคล้องกับระยะเวลาการเผยแพร่การเต้นของหัวใจของบริการ

• จำนวนช่วงเวลาที่ต้องขาดหายก่อนที่ HM จะพิจารณาว่า แพ็กเกจบริการไม่มีประสิทธิภาพ

• เวลาในการดำเนินการคือระยะเวลาที่ชุดบริการ SDV ต้องใช้ในการ ดำเนินการตามตรรกะทางธุรกิจก่อนที่จะเผยแพร่การเต้นของหัวใจของบริการได้

แพ็กเกจบริการจะสร้างการละเมิดด้านสุขภาพหากการเต้นของหัวใจของบริการล่าช้า มี 2 กรณีตามเวลาที่สังเกตอาการด้านสุขภาพ ดังนี้

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

• กรณีที่ 2: ได้รับสัญญาณชีพแล้ว หากเกินเกณฑ์ ระหว่างการเต้นของหัวใจครั้งล่าสุดกับเวลาที่สังเกต ระบบจะถือว่าชุดบริการ ไม่สมบูรณ์ เกณฑ์นี้คำนวณจากผลรวมของ ระยะเวลาการรายงาน (คูณด้วยจำนวนระยะเวลา) และระยะเวลาของ งาน

รูปแบบการกำหนดค่าด้านสุขภาพมีการกำหนดไว้ใน //system/software_defined_vehicle/health_monitor/catalog/health_config.proto

package com.android.sdv.health;

// Service Bundle's configuration for health monitoring.
message HealthConfiguration {
  // Required.
  // Initial delay in milliseconds is the time between the service starts and its first heartbeat.
  optional uint64 initial_delay_ms = 2;

  // Required.
  // Period of reporting a heartbeat in milliseconds which corresponds to the periodicity of
  // executing a business logic by the SDV service. This value should be larger than 0.
  optional uint64 period_ms = 3;

  // Required.
  // The number of periods missing a heartbeat before the Health Monitor should consider the
  // service as unhealthy. This value should be larger than 0.
  optional uint64 num_periods = 4;

  // Required.
  // Duration of the business logic the SDV service bundle executes in milliseconds.
  optional uint64 task_duration_ms = 5;
}

ข้อควรพิจารณาเกี่ยวกับเวลาที่เรียกใช้

ส่วนนี้มีคำแนะนำในการเผยแพร่การเต้นของหัวใจเพื่อตรวจสอบสถานะการทำงานและลงทะเบียนเพื่อรับการตรวจสอบอย่างถูกต้อง

เผยแพร่การเต้นของหัวใจเพื่อแสดงว่ายังใช้งานอยู่

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

ออบเจ็กต์อินสแตนซ์ของแพ็กเกจที่จะตรวจสอบต้องสร้างผู้เผยแพร่ประเภท ServiceHeartbeat ซึ่งมีอยู่ในคลัง libhealth_api

 message ServiceHeartbeat {
   // Required.
   // The timestamp.
   .google.protobuf.Timestamp timestamp = 1;
 }

เลือกหัวข้อการเผยแพร่โดยพลการ เอเจนต์ HM ใช้การค้นหาตามประเภทข้อความ เพื่อตรวจหาการเผยแพร่

เมื่อกำหนดค่าการตรวจสอบความพร้อมใช้งานผ่านการกำหนดค่าสถานภาพที่ลิงก์ไว้ใน ไฟล์ Manifest ของแพ็กเกจบริการที่เกี่ยวข้อง เอเจนต์ HM คาดหวังให้เผยแพร่ HB ทันทีที่อินสแตนซ์ทำตามกิจวัตร on_start เสร็จ เราขอแนะนำให้on_startมีระยะเวลาสั้นๆ เพื่อไม่ให้ระบบบล็อกการเริ่มต้นระบบ ดังนั้นให้เผยแพร่ Heartbeat ในงานแบบอะซิงโครนัสที่เริ่มต้นใน on_start

นักพัฒนาแพ็กเกจสามารถปรับแต่งเวลาที่คาดว่าจะมีการส่ง Heartbeat ครั้งแรกได้โดย ใช้รายการการกำหนดค่า initial_delay_ms

อินสแตนซ์ของ Bundle ควรเผยแพร่ Heartbeat ต่อไปจนกว่าจะหยุด ระบบจะถือว่าอินสแตนซ์หยุดทำงานเมื่อon_stopรูทีนเสร็จสิ้น

กรณีการใช้งานพิเศษ: ลงทะเบียนอย่างชัดเจนเพื่อการตรวจสอบ Heartbeat

ลักษณะการทำงานที่อธิบายไว้ในการตรวจสอบสัญญาณชีพที่บ่งบอกว่ายังทำงานอยู่ ซึ่งคาดว่าสัญญาณชีพ จะอยู่ระหว่าง on_start ถึง on_stop เรียกว่าการตรวจสอบสัญญาณชีพที่บ่งบอกว่ายังทำงานอยู่โดยนัย เราขอแนะนำให้ใช้วิธีนี้เพื่อลดความซับซ้อนของตรรกะทางธุรกิจของกลุ่มผลิตภัณฑ์ และตรวจสอบว่ามีการตรวจสอบกลุ่มผลิตภัณฑ์อยู่เสมอ

อย่างไรก็ตาม อาจมีกรณีการใช้งานบางอย่างที่ระยะเวลาการตรวจสอบเริ่มต้นเป็น ข้อจำกัด ดังนี้

• อินสแตนซ์ของแพ็กเกจบริการมีตรรกะทางธุรกิจที่เกิดขึ้นเป็นระยะๆ ในช่วงเวลา ซึ่งไม่ได้ลิงก์กับเหตุการณ์ start และ stop คุณอาจต้องตรวจสอบความพร้อมใช้งานเฉพาะในช่วงเวลาที่กำหนดเองนี้
• HM จะติดตาม HB อย่างถูกต้องในช่วงที่ระงับและกลับมาทำงานต่อ ดังนั้น อาจต้องมีการตรวจสอบกลุ่มต่อไปหลังon_stop
• อาจไม่ได้ติดตั้งใช้งานเอเจนต์ OEM ที่กำหนดเองเป็นแพ็กเกจบริการ จึงไม่สามารถใช้ประโยชน์จากการตรวจสอบความมีชีวิตโดยนัยได้ อย่างไรก็ตาม อาจยังคง ต้องมีการตรวจสอบความพร้อมใช้งาน

สำหรับกรณีเหล่านี้ HM จะช่วยให้คุณข้ามการลงทะเบียนโดยนัยเพื่อตรวจสอบว่าอุปกรณ์ยังใช้งานได้ อยู่หรือไม่ แล้วลงทะเบียนอย่างชัดเจนแทน หากต้องการใช้การลงทะเบียนที่ชัดเจน อินสแตนซ์ของ Bundle ต้องเลือกไม่ใช้การลงทะเบียนโดยนัยโดยไม่รวมรายการประเภท HealthConfiguration สำหรับอินสแตนซ์นั้นๆ ในไฟล์ Manifest ของ Bundle จากนั้นที่รันไทม์ อินสแตนซ์ของ Bundle ควรใช้ RPC API ที่กำหนดไว้ ใน //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto เพื่อลงทะเบียนและยกเลิกการลงทะเบียนจากการตรวจสอบด้วยตนเอง คาดว่า จะมีการเผยแพร่สัญญาณชีพทันทีที่การเรียก RPC ของการลงทะเบียนสำเร็จ

ดูตัวอย่างการใช้งานได้ที่ //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/

การตรวจสอบ QoS

คุณภาพของการบริการ (QoS) คือการวัดการสื่อสาร HM จะตรวจสอบ ว่าข้อความที่ส่งใช้เวลานานเกินไปหรือไม่ หรือในกรณีของ การสื่อสารเป็นระยะ HM จะตรวจสอบว่าได้รับข้อความตาม ความถี่ที่เลือกหรือไม่

SDV มี Pub/Sub และการสื่อสาร RPC หลายรูปแบบ ตัวหารร่วมคือรูปแบบการสื่อสารทั้งหมดมีผู้ฟังอย่างน้อย 1 คน สำหรับ HM ในการตรวจสอบการสื่อสาร อินสแตนซ์ของชุดบริการการฟังนี้ต้อง เผยแพร่การเต้นของหัวใจ QoS พิเศษทุกครั้งที่ได้รับข้อความที่น่าสนใจ

การกำหนดค่า

หากต้องการเปิดใช้การตรวจสอบ QoS ของการสื่อสาร ให้ระบุเครื่องมือฟังการสื่อสาร ที่จะเผยแพร่การเต้นของหัวใจ QoS ก่อน จากนั้นสําหรับอินสแตนซ์ของแพ็กเกจบริการที่ระบุ ให้เพิ่มหัวข้ออย่างน้อย 1 รายการลงในQosMonitoringConfigurationการแมป ในฟิลด์qos_config ดูข้อมูลเพิ่มเติมได้ที่ การกำหนดค่าแพ็กเกจต่อบริการ

หัวข้อคือสตริงที่กำหนดหัวข้อการเผยแพร่ที่ HM คาดหวัง QoS HB ในรันไทม์ อินสแตนซ์ของชุดการฟังสามารถเข้าร่วมการสื่อสารหลายรายการและรายงาน HB ของ QoS ในหลายหัวข้อได้

หัวข้อควรมีคำอธิบาย เนื่องจากระบบจะรายงานกลับไปยังชุดบริการของเครื่องรับฟัง HM หากตรวจพบการละเมิด QoS ในขณะรันไทม์

ประเภท QosMonitoringConfiguration กำหนดไว้ใน //system/software_defined_vehicle/health_monitor/catalog/health_config.proto ดังนี้

message QosMonitoringConfiguration {
  // Optional - If absent, heartbeat frequency monitoring is disabled for this SB.
  //
  // The maximum allowable interval between consecutive heartbeats (in milliseconds).
  // A QoS frequency violation is triggered if the time elapsed between
  // two heartbeats exceeds this threshold.
  optional uint64 qos_period_threshold_ms = 1;

  // Optional - If absent, heartbeat latency monitoring is disabled for this SB.
  //
  // The maximum allowable interval between data publication and data processing timestamps (in milliseconds).
  // A QoS latency violation is triggered if the time elapsed between
  // data publication and data processing timestamps exceeds this threshold.
  optional uint64 qos_latency_threshold_ms = 2;
}

สำหรับ Use Case เริ่มต้น ให้บังคับใช้การตรวจสอบ QoS ทั้ง 2 ประเภท qos_latency_threshold_ms30 เป็นค่าที่เหมาะสมสำหรับการสื่อสาร Pub/Sub ใน VM ภายใต้ภาระงานของระบบปกติ

ข้อควรพิจารณาเกี่ยวกับเวลาที่เรียกใช้

เช่นเดียวกับการตรวจสอบ HB ของการตรวจจับความมีชีวิตอยู่ ชุดการตรวจสอบการสื่อสารคาดว่าจะเผยแพร่ประเภทของสัญญาณชีพ ในกรณีนี้ ควรเผยแพร่ QoS HB ทุกครั้งที่ได้รับข้อความที่สนใจ ไม่ใช่เมื่อสิ้นสุดการดำเนินการตรรกะทางธุรกิจ

QoS HB มีประเภทเป็น QosHeartbeat ซึ่งกำหนดไว้ใน //system/software_defined_vehicle/health_monitor/catalog/qos_heartbeat.proto

message QosHeartbeat {
  option (.sdv.vsidl.v1.publication) = {
    message_count: 2
    model: SINGLE_PUB
  };
  // Required.
  // Current timestamp at heartbeat transmission. The heartbeat should be sent
  // immediately after the listener receives the related QoS-monitored message.
  .google.protobuf.Timestamp timestamp = 1;

  // Required.
  // Timestamp corresponding to the creation time of the underlying data. This
  // implies that, in addition to the data of interest, the monitored message includes
  // a data creation timestamp field. The listener is responsible for routing this
  // timestamp to the QosHeartbeat upon receiving a QoS-monitored message.
  .google.protobuf.Timestamp data_timestamp = 2;
}

เวลาในการลงทะเบียนและยกเลิกการลงทะเบียนสื่อเผยแพร่ QoS HB มีความสำคัญต่อ การตรวจสอบที่ถูกต้อง HM คาดหวังว่าจะมี HB ของ QoS ระหว่างเหตุการณ์ทั้ง 2 รายการนี้ ชุดการฟังข้อความควรลงทะเบียนการเผยแพร่ HB ของ QoS เมื่อมีการลงทะเบียนการสื่อสารที่ตรวจสอบกับสแต็กการสื่อสาร SDV HM สามารถใช้ Availability API เพื่อดำเนินการนี้ได้ ดูข้อมูลเพิ่มเติมได้ที่พิจารณา ความพร้อมให้บริการ

การตรวจสอบการกู้คืนแพ็กเกจบริการ

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

การขัดข้องของอินสแตนซ์ชุดบริการที่ไม่ได้กำหนดค่าสำหรับการกู้คืนจะทำให้เกิด การละเมิดสถานะในกรณีที่ขัดข้องเป็นครั้งแรก

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

การตรวจสอบการขัดข้องของ Agent

HM ตรวจหาการขัดข้องที่อาจเกิดขึ้นของ Agent SDV โดยใช้กลไก linkToDeath Binder

คุณกำหนดค่าการตรวจสอบข้อขัดข้องได้โดยเป็นส่วนหนึ่งของการกำหนดค่าสถานะของ VM (ดูการกำหนดค่าอินสแตนซ์ (VM) ต่อ SDV) โดยเฉพาะmonitored_agent ฟิลด์ที่ซ้ำกัน ฟิลด์นี้ควรมีรายการของBinderServiceAgentประเภทต่อไปนี้

message BinderServiceAgent {
  // agent_names must be unique across configuration
  // used for HM internal agent identification, and naming entries in HM dumpsys report
  string agent_name = 1;

  // Binder interface name/identifier, e.g: "google.sdv.data_tunnel.IAgentService/default"
  // HM Agent should have appropriate permissions to find the binder interface
  // see also `sdv_crash_monitored_service` selinux attribute
  string binder_interface_name = 2;
}

นอกจากนี้ คุณยังตรวจสอบเอเจนต์ที่กำหนดเองได้ด้วยหากเอเจนต์แสดงอินเทอร์เฟซ Binder หากต้องการตรวจสอบเอเจนต์ที่กำหนดเอง ให้มอบสิทธิ์ HM SELinux เพื่อฟัง อินเทอร์เฟซ Binder ที่เหมาะสม

พร็อพเพอร์ตี้ของระบบ ro.boot.sdv.health_monitor.agent_startup_timeout_sec สามารถ ลบล้างระยะเวลาที่ HM รอให้ตัวแทนลงทะเบียนอินเทอร์เฟซ Binder เมื่อ HM เริ่มทำงาน ระยะหมดเวลาเริ่มต้น 3 วินาทีนั้นเหมาะสมแล้ว เว้นแต่ตัวแทนที่กำหนดเองจะกำหนดไว้

คู่มือนักพัฒนาซอฟต์แวร์สำหรับแพ็กเกจบริการ

ส่วนนี้จะให้คำแนะนำแบบทีละขั้นตอนเกี่ยวกับวิธีใช้ฟีเจอร์ HM จากแพ็กเกจบริการ ซึ่งแตกต่างจากการอธิบายเชิงทฤษฎีในส่วนก่อนหน้า ตัวอย่างข้อมูลอ้างอิงล่าสุดซึ่งเป็นพื้นฐานของคำแนะนำเหล่านี้คือqos_monitoringตัวอย่าง ทำตามตัวอย่าง //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README เพื่อรับประสบการณ์การใช้งานจริง

เพิ่มการตรวจสอบการเต้นของหัวใจเพื่อตรวจสอบสถานะการทำงานลงในชุดบริการ

วิธีนี้เป็นวิธีที่ตรงที่สุดในการเปิดใช้การตรวจสอบสถานะของระบบสำหรับแพ็กเกจบริการ

1. กำหนดอินสแตนซ์ของ ServiceBundleHealthConfiguration สำหรับอินสแตนซ์ของ Bundle ในไฟล์ชื่อ health_configuration.textproto ดังนี้

   # health_bundle_configuration.textproto
   instance_config {
     key: "instance1"
     value: {
       health_config {
         initial_delay_ms: 1000
         period_ms: 500
         num_periods: 2
         task_duration_ms: 200
       }
   
       # qos_config entries irrelevant for this dev guide
       qos_config { ... }
   
     }
   }
   

2. เพิ่มไฟล์การกำหนดค่าลงใน APEX ของชุดบริการ ในAndroid.bp

   
   apex {
       name: "com.android.sdv.sample.oem.health.qos_monitoring",
       // ...
       prebuilts: [
           // ...
           "com.android.sdv.sample.oem.health.qos_monitoring.health_config",
       ],
   }
   
   prebuilt_etc {
       name: "com.android.sdv.sample.oem.health.qos_monitoring.health_config",
       src: "health_configuration.textproto",
       filename: "health.textproto",
       // ...
       // Reduce prebuilt visibility to avoid adding it in another APEX.
       visibility: ["//system/software_defined_vehicle/samples/health/qos_monitoring/apex"],
   }
   
   

3. จัดเก็บการกำหนดค่าด้านสุขภาพใน APEX และตั้งค่า health_config_path ในไฟล์ Manifest ดังนี้

   # sdv_service_bundles_manifest.textproto
   sdv_service_bundle_metadata {
     ...
     health_config_path: "etc/config/health_configuration.textproto"
   }
   

4. ในการกําหนด VSIDL ให้ตรวจสอบว่าแพ็กเกจเผยแพร่ com.android.sdv.health.ServiceHeartbeat:

   sdv_service_bundle {
     name: "SampleBundle"
     publisher {
       message: "com.android.sdv.health.ServiceHeartbeat"
       topic: "arbitrary-topic"
       capacity: 2
     }
   }
   

5. เพิ่มสิทธิ์ SDV ลงในแพ็กเกจเพื่อให้แพ็กเกจได้รับอนุญาตให้ เผยแพร่ HB

     publisher {
       type: "com.android.sdv.health.ServiceHeartbeat"
     }
   

6. เผยแพร่การตรวจสอบสถานะบริการเป็นระยะๆ ในโค้ด โดยเริ่มตั้งแต่ on_start

   // ...
   fn on_start(&mut self) {
     // ...
     runtime.spawn(business_logic(self.context))
   }
   async fn business_logic(context: ContextRef) -> SdvResult<()>{
     // register HB publication
     let mw_comms = SdvComms { context };
     let aliveness_hb_pub = create_publisher::<PublisherDescriptor<ServiceHeartbeat>>(
         &mw_comms,
         PublisherDescriptors::<ServiceHeartbeat>::ARBITRARY_TOPIC,
     )
     .await?;
     loop{
       // do business logic
       // ...
   
       // publish hb
       aliveness_hb_pub.publish(&ServiceHeartbeat {
           timestamp: MessageField(Some(Box::new(now.into()))),
           ..Default::default()
       })?;
     }
   }
   

กรณีการใช้งานพิเศษ: การลงทะเบียนอย่างชัดเจน

สำหรับกรณีการใช้งานพิเศษอื่นๆ ที่ต้องมีการตรวจสอบ HB สำหรับวงจรที่กำหนดเอง (เช่น การตรวจสอบที่เริ่มต้นก่อนหรือสิ้นสุดหลังจากSTARTEDสถานะมาตรฐาน) คุณสามารถใช้วิธีการลงทะเบียนที่ชัดเจนได้ดังนี้

1. ในคำจำกัดความ VSIDL ให้เพิ่ม com.android.sdv.health.HealthMonitorRegistrationService ไคลเอ็นต์:

   sdv_service_bundle {
     # ...
     client {
       service: "com.android.sdv.health.HealthMonitorRegistrationService"
       channel: "com-android-sdv-health-health-monitor-registration-service"
     }
   }
   

2. เพิ่มสิทธิ์ SDV สำหรับใช้ RPC การลงทะเบียน HB การตรวจจับการทำงาน

     # ...
     client {
       service: "com.android.sdv.health.HealthMonitorRegistrationService"
       channel: "com-android-sdv-health-health-monitor-registration-service"
     }
   

3. ลงทะเบียนกับ HM ผ่าน RPC เช่น ใน on_start หรือ new

   let rpc_client = Self::new_client(comms).await?;
   let _ = rpc_client
     .RegisterConfiguration(&RegisterConfigurationRequest {
         config: Some(HealthConfiguration{
           initial_delay_ms: 100,
           period_ms: 200,
           num_periods: 3,
           task_duration_ms: 40,
           special_fields: protobuf::SpecialFields::default(),
         }).into(),
         ..Default::default()
     })
     .await
     .unwrap();
   

4. เผยแพร่ HB

5. ยกเลิกการลงทะเบียนจากการตรวจสอบเมื่อไม่ต้องการใช้แล้ว โดยทำดังนี้

   let _ = rpc_client
     .UnregisterConfiguration(&UnregisterConfigurationRequest { ..Default::default() })
     .await
     .unwrap();
   

เพิ่มการตรวจสอบ QoS ในการสื่อสาร

1. ตรวจสอบว่าอินสแตนซ์ของแพ็กเกจบริการเป็นผู้ติดตามหัวข้อที่ชื่อ fog-light-status ในแคตตาล็อก VSIDL ดังนี้

   subscriber {
     message: "QosMonitoredFogLightStatus"
     topic: "left-fog-light-status"
   }
   

   รูปแบบข้อความมีดังนี้

   package com.android.sdv.sample.oem.health.qos_monitoring;
   import "google/protobuf/timestamp.proto";
   
   message QosMonitoredFogLightStatus {
     // arbitrary fields related to business logic
     int32 status = 1;
   
     // A QoS-monitored message must include a timestamp field
     .google.protobuf.Timestamp timestamp = 2;
   }
   

2. กำหนดอินสแตนซ์ของ ServiceBundleHealthConfiguration สำหรับอินสแตนซ์ของกลุ่ม ในไฟล์ health_configuration.textproto ที่มีการตรวจสอบ QoS ดังนี้

   # health_bundle_configuration.textproto
   instance_config {
     key: "instance1"
     value: {
       # aliveness HB monitoring config irrelevant for this dev guide
       health_config { ... }
       qos_config {
         key: "qos-hb-right-fog-light-status"
         value { qos_period_threshold_ms: 100 qos_latency_threshold_ms: 50 }
       }
     }
   }
   

   หัวข้อที่เลือกในkeyฟิลด์แสดงให้เห็นว่า QoS HB จะ เผยแพร่ในหัวข้อนี้ ซึ่งจะช่วยให้ตรวจสอบหัวข้อที่ชื่อ fog-light-statusได้

3. เพิ่มไฟล์การกำหนดค่าลงใน APEX ของชุดบริการ ในAndroid.bp

   apex {
       name: "com.android.sdv.sample.oem.health.qos_monitoring",
       // ...
       prebuilts: [
           // ...
           "com.android.sdv.sample.oem.health.qos_monitoring.health_config",
       ],
   }
   
   prebuilt_etc {
       name: "com.android.sdv.sample.oem.health.qos_monitoring.health_config",
       src: "health_configuration.textproto",
       filename: "health.textproto",
       // ...
       // Reduce prebuilt visibility to avoid adding it in another APEX.
       visibility: ["//system/software_defined_vehicle/samples/health/qos_monitoring/apex"],
   }
   

4. จัดเก็บการกำหนดค่าด้านสุขภาพใน APEX และตั้งค่า health_config_path ในไฟล์ Manifest ดังนี้

   # sdv_service_bundles_manifest.textproto
   sdv_service_bundle_metadata {
     ...
     health_config_path: "etc/config/health_configuration.textproto"
   }
   

5. ในคำจำกัดความ VSIDL ให้ตรวจสอบว่าแพ็กเกจเป็นผู้เผยแพร่ com.android.sdv.health.QosHeartbeat

   sdv_service_bundle {
     name: "SampleBundle"
     publisher {
       message: "com.android.sdv.health.QosHeartbeat"
       topic: "qos-hb-right-fog-light-status"
       capacity: 2
     }
   }
   

6. เพิ่มสิทธิ์ SDV ลงในแพ็กเกจเพื่อให้แพ็กเกจได้รับอนุญาตให้ เผยแพร่ HB ของ QoS

   publisher { message: "com.android.sdv.health.QosHeartbeat" topic: "qos-hb-right-fog-light-status" }
   

7. ลงทะเบียนการเผยแพร่ QoS HB เมื่อมีการลงทะเบียนการสื่อสารที่ตรวจสอบแล้วเท่านั้น ใช้ Availability API จาก libsdv_mw_clientlib

   // Wait for monitored communication to be available
   let comms = SdvComms{context};
   let registration_stream = create_registration_event_stream(
     &comms,
     SubscriberDescriptors::<QosMonitoredFogLightStatus>::LEFT_FOG_LIGHT_STATUS,
   ).await?;
   let mut registration_stream = Box::pin(registration_stream.filter(|e|e==Availability::Available));
   registration_stream.next().await;
   
   // only when available, create QoS HB publication:
    let qos_hb_pub = create_publisher(
     &comms,
     PublisherDescriptors::<QosHeartbeat>::QOS_HB_LEFT_FOG_LIGHT_STATUS,
   ).await?;
   
   // ...
   

8. เผยแพร่ HB ของ QoS ทุกครั้งที่ได้รับข้อความ

   // ...
   use tap::Pipe;
   
   fn flatten_mw<T: Send>(
       s: impl Stream<Item = SdvResult<Vec<T>>> + Send + Unpin,
   ) -> impl Stream<Item = SdvResult<T>> + Send + Unpin {
     s.flat_map(|v| match v {
         Ok(v) => v.into_iter().map(Ok).pipe(stream::iter).left_stream(),
         Err(err) => Err(err).pipe(future::ready).pipe(stream::once).right_stream(),
     })
   }
   
   {
     // ...
   
     let data_stream = create_observer(
       &comms,
       SubscriberDescriptors::<QosMonitoredFogLightStatus>::LEFT_FOG_LIGHT_STATUS,
       SubscribeOptions::default()
     )
       .pipe(flatten_mw)
       .await?;
   
     while let Some(data) = data_stream.next().await {
       // publish QoS HB. Note how data.timestamp is used to populate the field
        qos_hb_pub.publish(
         &QosHeartbeat {
             timestamp: SystemTime::now(),
             data_timestamp: data.timestamp,
             ..Default::default()
         }
       )
   
       // use data
       // ...
     }
   }
   

9. หากต้องการหยุดการตรวจสอบ QoS ให้ทิ้งออบเจ็กต์ผู้เผยแพร่โฆษณา

   // ...
   drop(qos_hb_pub);
   

แก้ไขข้อบกพร่องในการตรวจสอบสถานะของระบบ

หากต้องการแก้ไขข้อบกพร่องและดูภาพรวมของระบบ ให้ใช้dumpsysเครื่องมือเพื่อตรวจสอบสถานะการตรวจสอบสถานะของ VM

adb shell dumpsys com.google.sdv.ISdvAgent/hm

รายงานจะแสดงรายละเอียดการกำหนดค่าการรายงานสถานะของ VM, การกำหนดค่าแพ็กเกจ และสถานะการตรวจสอบ ตัวอย่างรายงานดังกล่าวมีดังนี้

AGENT NAME: SDV Agent dump - Health Monitor
AGENT FQIN: instance1:com.android.sdv.health.HealthMonitorServiceBundle/instance1
AGENT STATE: Started
----------------
----------------
INTERNAL STATE REPORTERS:

*NAME: VM health report period:
*REPORT:
100----------------
*NAME: Recovery monitor manager
*REPORT:

HEARTBEAT MONITORING:
NO ACTIVE MONITORS

QOS MONITORING:
NO ACTIVE MONITORS
RECOVERY MONITORING:
a. Agent monitoring:
MONITOR 0:
ID: Agent: sdv_vsidl_provider_agent
linked_binder: com.google.sdv.ISdvAgent/vsidl_provider
alive: true

MONITOR 1:
ID: Agent: sdv_someip_broker
linked_binder: com.google.sdv.ISdvAgent/someip_broker
alive: false

b. SB monitoring:
MONITOR 0:
ID: FQIN: instance1:com.android.sdv.test.orchestrator.OrchSampleInitialPowerState/sample-initial-power-state
Recovery State: Normal
Lifecycle State: Started
Health Status: Healthy
MONITOR 1:
ID: FQIN: instance1:com.android.sdv.sample.apex.provider.Provider/sample-provider-v1
Recovery State: Normal
Lifecycle State: Started
Health Status: Healthy
MONITOR 2:
ID: FQIN: instance1:com.sdv.google.display_safety.HarSdvVehicleDataPublisher/instance-1
Recovery State: Normal
Lifecycle State: Started
Health Status: Healthy
----------------
*NAME: Health monitor
*REPORT:
CURR TIMESTAMP(ns): 1775543863756836167
INTERNAL STATE:
background_thread running: true
should_run: true

----------------