مراقبة الحالة الصحية

أداة مراقبة السلامة (HM) هي وكيل SDV يعمل على كل جهاز افتراضي (VM) لتتبُّع حالة حِزم الخدمات وتحديد سلامة الجهاز الافتراضي وإنشاء تقرير دوري عن سلامة الجهاز الافتراضي.

يجب أن تستمع حِزم الخدمات التي يحدّدها المصنّع الأصلي للجهاز إلى إشارات السلامة المختلفة التي يرسلها HM، وأن تنفّذ إجراءات الاسترداد استنادًا إلى البيانات. على سبيل المثال، قد تحتاج إلى إعادة تشغيل أو تعديل مثيل SDV يتضمّن حِزم خدمات معطّلة.

يمكنك ضبط برنامج HM لتتبُّع ما يلي:

• حالة نشاط الكيانات التي تنفّذ مهامًا دورية، وذلك من خلال رصد الإشارات الدورية التي تشير إلى النشاط. يمكن ضبط عملية المراقبة هذه لكلّ من حِزم الخدمات وعملاء OEM المخصّصين.
  • حالة الاسترداد لمثيلات حِزم الخدمات يمكنك ضبط حِزم الخدمات لإعادة التشغيل تلقائيًا عند حدوث عطل. يقدّم HM إشارات لمراقبة عملية الاسترداد هذه.
  • جودة الخدمة (QoS) في التواصل
• حالة توفّر وكلاء SDV وOEM المخصّصين

للحصول على مرجع، تتوفّر قائمة VSIDL الكاملة، بما في ذلك تعريفات البروتوكول، على //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl.

المصطلحات

تُستخدَم هذه المصطلحات في هذه الصفحة.

العمل مع النظام الفرعي HM

لاستخدام ميزات "الخرائط على الأجهزة"، يجب أن يستوفي تنفيذ الشركة المصنّعة للمعدّات الأصلية ما يلي:

• اضبط نظام مراقبة السلامة من خلال توفير ملفات الإعداد كما هو موضّح بالتفصيل في ضبط نظام مراقبة السلامة.
• استخدِم حزمة خدمة HM Listener التي يحدّدها المصنّع الأصلي للجهاز للاستماع إلى ناتج HM واتّخاذ الإجراء المناسب.
• تطوير حِزم خدمات تنشر الإشارات بشكل نشط، وفقًا لإعدادات الصحة. يتيح هذا المنشور لمقدّم الرعاية الصحية تقييم حالته الصحية. لمزيد من المعلومات، يُرجى الاطّلاع على أدلة المطوّرين لحِزم الخدمات.

ضبط نظام إدارة المنزل

تتوفّر أي إعدادات ذات صلة بإدارة الأجهزة الجوّالة في أحد أنواع الإعدادات التالية:

• إعدادات عامة لكل جهاز افتراضي خاصة بالسلامة
• إعدادات حالة الحزمة لكل خدمة، وتحدّد مَعلمات الحالة لجميع مثيلات الحزمة

إعدادات السلامة لكل جهاز افتراضي

في وقت التشغيل، يتوقّع وكيل HM إعدادات سلامة على مستوى الجهاز الافتراضي: هذا الملف هو ملف textproto (مع امتداد .textproto) من النوع VMHealth محدّد في //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto. يجب أن يكون إعداد VM Health متاحًا في المسار المحدّد باستخدام سمة نظام وقت التشغيل androidboot.sdv.health_monitor.config_path. بدلاً من ذلك، يمكنك ضبط هذا الإعداد ديناميكيًا في وقت التشغيل من خلال ضبط سمة النظام persist.sdv.health_monitor.config_path على مسار مخصّص. تكون لإعداد persist.* الأولوية على إعداد androidboot.*. يجب إعادة تشغيل الجهاز لتفعيل الإعدادات الجديدة.

يتيح لك إعداد حالة الجهاز الافتراضي ضبط ما يلي:

• معدّل تكرار تقرير حالة الجهاز الظاهري من خلال period_ms ويُعدّ ضبط هذا الخيار حلاً وسطًا بين سرعة الإبلاغ عن رصد انتهاكات الصحة وأداء النظام الفرعي لإدارة الصحة. ننصح باستخدام القيمة 100 مللي ثانية.

• الوكلاء الذين سيتم رصد الأعطال فيهم (راجِع رصد الأعطال في الوكلاء).

تتوفّر أمثلة على ملفات الإعداد في //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 لمراقبة الأعطال، وتم ضبط تقرير سلامة الجهاز الافتراضي ليتم نشره كل 100 مللي ثانية.

حسب إعداد حزمة الخدمة

تُعدّ مراقبة سلامة مثيلات حِزم الخدمات إجراءً اختياريًا. للموافقة على استخدام هذه الميزة، عليك تخزين ملف إعدادات الصحة في حزمة APEX الخاصة بحزمة الخدمات وتحديد مسار له في الحقل health_config_path من sdv_service_bundle_metadata في sdv_service_bundles_manifest.textproto. لمزيد من المعلومات حول بيانات خدمة الحزمة الوصفية، يُرجى الاطّلاع على بيانات خدمة الحزمة الوصفية.

ملف إعدادات الصحة هو ملف 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;
}

يمكنك تحديد إعدادات نبضات القلب الخاصة بالنشاط وإعدادات جودة الخدمة لكل مثيل:

// 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;
}

لمزيد من المعلومات حول عملية الضبط لكل ميزة، يُرجى الاطّلاع على رصد إشارات دورية للبقاء على قيد الحياة ورصد جودة الخدمة.

الاستماع إلى مخرجات "النماذج المتناغمة"

يمكنك الاستماع إلى HM من خلال التقارير الدورية أو واجهة برمجة تطبيقات RPC.

تقرير حالة الجهاز الافتراضي

تُنشئ ميزة "مراقبة السلامة" تقريرًا دوريًا عالي التكرار عن سلامة الجهاز الافتراضي، وتوفّر معلومات موجزة عن حالة السلامة للعناصر التي تتم مراقبتها.

يتم تحديد بنية النوع 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;
}

يجب أن تستمع حزمة خدمة مستمع إدارة الصحة (HM) التي تحدّدها الشركة المصنّعة للمعدات الأصلية إلى تقارير VMHealth وتتّخذ الإجراء المناسب استنادًا إلى بنية النظام الكاملة. تشمل الإجراءات المحتملة ما يلي:

• نفِّذ إجراءات التشخيص على الجهاز الظاهري.
• أعِد تشغيل الجهاز الافتراضي.
• يمكنك تنفيذ حملة قياس عن بُعد لتحديد السبب.
• تحديث النظام أو إيقاف التحديث إذا كان النظام لا يعمل بشكل سليم

HM RPC API

تقرير سلامة الجهاز الظاهري هو منشور محسّن من حيث معدّل التكرار وسرعة النقل، ويقدّم معلومات شاملة حول حالة سلامة النظام.

تتيح واجهة برمجة التطبيقات 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 أن ينشر المثيل إشارات نبض دورية لإثبات أنّ منطق النشاط يعمل بشكل صحيح. تكون هذه المراقبة الأنسب لحالات حِزم الخدمات التي تنفّذ مهامًا دورية. بالإضافة إلى ذلك، يمكن أن تستخدم الحِزم التي تستخدم أوقات تشغيل غير متزامنة ميزة مراقبة النشاط لإثبات أنّ مجموعة سلاسل التنفيذ لم يتم استنفادها.

الشكل 1: مسار مراقبة نشاط "إدارة الصحة"

الإعداد

لتفعيل نبضات القلب الخاصة بالنشاط على مثيل حزمة خدمة، أضِف مثيلاً من HealthConfiguration إلى الحقل health_config في إعدادات الحزمة.

يحدّد إعداد نبضات القلب الخاصة بالنشاط مجموعة محدّدة مسبقًا من المَعلمات التي تحدّد معايير تقييم إشارة نبضات القلب الدورية للخدمة. إذا انحرفت خصائص نبض الخدمة عن هذه المَعلمات، يتم تصنيف النبض على أنّه متأخّر ويتم تصنيف حزمة الخدمة المقابلة على أنّها غير سليمة، ما قد يشير إلى حالة تشغيل غير مثالية.

تُعدّ حزمة الخدمات سليمة عندما ترسل إشارات نبض في الوقت المحدّد وفقًا لإعدادات السلامة. في حال حدوث عُطل أو ارتفاع في عبء النظام، قد لا يتم إرسال إشارة نبض القلب أو قد تتأخر، ما يؤدي إلى تصنيف حزمة الخدمة على أنّها غير سليمة. في هذه الحالة، ستظهر مخالفة في التقرير VmHealth.

على مطوّري حِزم الخدمات تحديد إعدادات السلامة لحزمة الخدمات في البيانات الوصفية الخاصة بحزمة APEX. يحدّد إعداد الصحة المعايير التالية:

• الحد الأقصى للمهلة الأولية المسموح بها بين بدء الخدمة ورصد أول إشارة نبض.

• الفترة التي تنفّذ خلالها حزمة خدمات SDV منطق النشاط التجاري، والتي تتوافق مع معدّل تكرار نشر إشارة نبض الخدمة.

• عدد الفترات التي يجب عدم توفّرها قبل أن تعتبر "مراقبة الصحة" حزمة الخدمة غير سليمة.

• وقت التنفيذ هو مقدار الوقت الذي يحتاج إليه حِزم خدمات SDV لتنفيذ منطق أعمالها قبل أن تتمكّن من نشر إشارة نبض الخدمة.

تُنشئ حزمة الخدمة مخالفة صحية إذا تأخّر نبض الخدمة. هناك حالتان استنادًا إلى وقت المراقبة الصحية:

• الحالة 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 عملية البحث حسب نوع الرسالة لرصد المنشور.

عند ضبط إعدادات مراقبة حالة النشاط من خلال إعدادات الصحة المرتبطة ببيان حزمة الخدمة المعنيّة، يتوقّع وكيل HM نشر حزم HB فور انتهاء مثيل من روتين on_start. ننصحك بإبقاء on_start قصيرًا لتجنُّب حظر بدء تشغيل النظام، لذا يمكنك نشر إشارات نبض القلب في مهمة غير متزامنة تبدأ في on_start.

يمكن لمطوّري الحِزم تخصيص الوقت المتوقّع لظهور أول إشارة نبض باستخدام إدخال الإعداد initial_delay_ms.

يجب أن يستمر مثيل الحزمة في نشر إشارات نبض القلب إلى أن يتم إيقافه. يُعدّ الجهاز الظاهري متوقفًا عند انتهاء روتينه on_stop.

حالة استخدام خاصة: التسجيل بشكل صريح في خدمة مراقبة نبض القلب

يُطلق على السلوك الموضّح في مراقبة إشارات نبض البقاء على قيد الحياة، حيث يُتوقّع أن تتراوح إشارات نبض البقاء على قيد الحياة بين on_start وon_stop، اسم مراقبة البقاء على قيد الحياة الضمنية. هذه هي الطريقة المقترَحة لاستخدام الميزة، فهي تبسّط منطق الأعمال الخاص بالحزمة وتضمن مراقبتها دائمًا.

ومع ذلك، قد توجد بعض حالات الاستخدام التي تكون فيها فترة المراقبة التلقائية قيدًا:

• يحتوي مثيل حزمة الخدمة على منطق نشاط تجاري دوري في فاصل زمني غير مرتبط بالحدثين start وstop. قد تكون مراقبة حالة النشاط مطلوبة فقط خلال هذه الفترة المخصّصة.
• يتتبّع HM بدقة عمليات HB خلال فترات التعليق والاستئناف. لذلك، قد يطلب الحِزم مواصلة مراقبتها بعد on_stop.
• قد لا يتم تنفيذ وكلاء مصنّعي المعدات الأصلية المخصّصين كحِزم خدمات. وبالتالي، لا يمكن الاستفادة من ميزة المراقبة الضمنية لحالة النشاط. ومع ذلك، قد تظلّ تتطلّب مراقبة حالة النشاط.

في هذه الحالات، تتيح لك وحدة إدارة الأجهزة تجاوز التسجيل الضمني في خدمة مراقبة حالة الجهاز لصالح التسجيل الصريح. لاستخدام التسجيل الصريح، يجب أن يوقف مثيل الحزمة التسجيل الضمني من خلال عدم تضمين إدخال من النوع HealthConfiguration للمثيل المحدّد في بيان الحزمة. بعد ذلك، يجب أن يستخدم مثيل الحزمة في وقت التشغيل واجهة 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) هي مقياس للاتصال. يراقب HM ما إذا كانت الرسالة المرسَلة تستغرق وقتًا طويلاً جدًا في النقل، أو في حالة الاتصال الدوري، ما إذا كانت الرسائل لا يتم تلقّيها بالوتيرة المحدّدة.

توفّر SDV العديد من أشكال الاتصال عبر Pub/Sub وRPC. القاسم المشترك هو أنّ جميع مخططات الاتصال تحتوي على مستمع واحد على الأقل. ولكي يتمكّن HM من مراقبة عملية التواصل، يجب أن ينشر مثيل حزمة خدمة الاستماع هذه إشارات نبض خاصة بجودة الخدمة كلما تلقّى رسالة مهمة.

الإعداد

لتفعيل مراقبة جودة الخدمة (QoS) لإحدى عمليات الاتصال، عليك أولاً تحديد أداة معالجة الاتصال التي ستنشر إشارة نبض جودة الخدمة. بعد ذلك، أضِف موضوعًا واحدًا أو أكثر إلى عمليات الربط QosMonitoringConfiguration لمثيل حزمة الخدمة المحدّدة في الحقل qos_config. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد حِزم الخدمات.

الموضوع هو سلسلة تحدّد موضوع المنشور الذي تتوقّع فيه وحدة معالجة الطلبات من نوع HM عرض وحدات HB ذات جودة الخدمة في وقت التشغيل. يمكن أن يشارك مثيل حزمة الاستماع في عدة عمليات تواصل ويمكنه إعداد تقارير عن نبضات القلب المتعلقة بجودة الخدمة حول مواضيع متعددة.

يجب أن تكون المواضيع وصفية، لأنّه يتم إرسالها مرة أخرى إلى حزمة خدمة مستمع HM في حال تم رصد انتهاكات لجودة الخدمة في وقت التشغيل.

يتم تحديد النوع 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;
}

بالنسبة إلى حالات الاستخدام التلقائية، يجب فرض كلا النوعين من مراقبة جودة الخدمة. يُعدّ معدّل نقل بيانات يبلغ qos_latency_threshold_ms لكل ثانية من 30 مناسبًا للتواصل بين الخدمات في الجهاز الافتراضي باستخدام Pub/Sub في ظل أحمال النظام العادية.

اعتبارات وقت التشغيل

على غرار رصد نبض القلب الخاص بالنشاط، من المتوقّع أن تنشر حزمة الاستماع إلى التواصل نوعًا من الإشارات الدورية. في هذه الحالة، يجب نشر إشارة نبض جودة الخدمة كلما تم تلقّي رسائل مهمة، بدلاً من نشرها في نهاية تنفيذ منطق العمل.

يكون نبض القلب الخاص بجودة الخدمة من النوع 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 أمرًا بالغ الأهمية لضمان دقة المراقبة. يتوقّع "مدير الموارد" تلقّي حزم بيانات QoS بين هذين الحدثين. يجب أن تسجّل حزمة الاستماع إلى الرسائل عملية نشر نبضات القلب الخاصة بجودة الخدمة عند تسجيل الاتصال الذي تتم مراقبته باستخدام حزمة برامج الاتصال SDV. يمكن لمدير الفندق استخدام واجهة برمجة التطبيقات الخاصة بمعلومات التوفّر لإجراء ذلك. لمزيد من المعلومات، راجِع مقالة تحديد مدى توفّر الخدمة.

مراقبة استرداد حِزم الخدمات

يتم ضبط استرداد مثيلات حِزم الخدمات كجزء من ملفات إعداد عامل التنسيق. للحصول على معالجة كاملة للموضوع، يُرجى الاطّلاع على حِزم الخدمات. يراقب النظام الفرعي "إدارة الصحة" عملية الاسترداد بشكل غير نشط. عند رصد تعذُّر استرداد مثيل حزمة، تتم إضافة انتهاك إلى التقرير VMHealth. على عكس بقية إمكانات مراقبة صحة الجهاز، فإنّ مراقبة عملية الاسترداد إلزامية ولا يمكن ضبطها.

تؤدي الأعطال في مثيلات حِزم الخدمات التي لم يتم ضبطها على الاسترداد إلى حدوث انتهاك للصحة عند حدوث العطل الأول.

تم تصميم عملية استرداد مثيل حزمة الخدمة لكي تتكامل مع عملية مراقبة حالة النشاط باستخدام إشارات نبض القلب. يكون نظام HM أكثر تساهلاً عند تقييم نبضات القلب عندما يرصد أنّ الحزمة في طور التعافي. من الناحية العملية، يعني هذا التساهل أنّه ليس على حِزم الخدمات اتّخاذ أي خطوات إضافية لإلغاء التسجيل أو التسجيل في خدمة المراقبة في حال تعذُّرها.

مراقبة أعطال الوكيل

يرصد "مراقب الصحة" الأعطال المحتملة لوكلاء SDV باستخدام آلية binder linkToDeath.

يمكنك ضبط إعدادات مراقبة الأعطال كجزء من إعدادات سلامة الجهاز الافتراضي (راجِع إعدادات كل مثيل من "بيئة تطوير البرامج الآمنة" (الجهاز الافتراضي))، وتحديدًا الحقل المتكرّر 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;
}

يمكن أيضًا مراقبة الوكلاء المخصّصين إذا كان الوكيل يعرض واجهة رابطة. لمراقبة وكيل مخصّص، عليك منح أذونات HM SELinux للاستماع إلى واجهة الرابط المناسبة.

يمكن للخاصية ro.boot.sdv.health_monitor.agent_startup_timeout_sec للنظام أن تتجاوز المدة التي ينتظرها HM لتسجيل واجهات الرابط الخاصة بالوكلاء بعد بدء تشغيل HM. ما لم يطلب وكلاء مخصّصون ذلك، يكون الإعداد التلقائي لثلاث ثوانٍ مناسبًا.

أدلة المطوّرين لحِزم الخدمات

يقدّم هذا القسم أدلة مفصّلة حول كيفية استخدام ميزات "المنزل الذكي" من حِزم الخدمات، وذلك على عكس المعالجة النظرية في الأقسام السابقة. إنّ النموذج المرجعي الحديث الذي تستند إليه هذه الأدلة هو النموذج qos_monitoring. اتّبِع الخطوات الواردة في العيّنة //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README للحصول على تجربة عملية.

إضافة ميزة مراقبة نبض القلب إلى حزمة خدمة

هذه الطريقة هي الأسهل لتفعيل مراقبة سلامة الجهاز لمجموعة من الخدمات:

1. حدِّد مثيلاً من ServiceBundleHealthConfiguration لحِزم المثيلات في ملف باسم 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 في ملف البيان:

   # 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 إلى الحزمة كي يكون بإمكانها نشر حزم أساسية:

     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. سجِّل لدى "هيئة تنظيم الإعلام" من خلال 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. نشر "الكتب الرائجة"

5. إلغاء التسجيل في ميزة الرصد عند الاستغناء عنها:

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

إضافة ميزة مراقبة جودة الخدمة إلى التواصل

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 يتضمّن مراقبة جودة الخدمة:

   # 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 أنّ رسائل نبض القلب المتعلقة بجودة الخدمة سيتم نشرها حول هذا الموضوع، ما يتيح مراقبة موضوع يُسمى 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 في ملف البيان:

   # 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 الخاصة بجودة الخدمة:

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

7. يجب تسجيل نشر رسالة نبض QoS فقط عند تسجيل الاتصال الذي تتم مراقبته. استخدِم واجهة برمجة التطبيقات الخاصة بالتوفّر من 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. نشر رسائل نبضات القلب الخاصة بجودة الخدمة في كل مرة يتم فيها تلقّي رسالة:

   // ...
   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. لإيقاف تتبُّع جودة الخدمة، أزِل عنصر الناشر:

   // ...
   drop(qos_hb_pub);
   

تصحيح أخطاء مراقبة السلامة

لأغراض تصحيح الأخطاء والنظرة العامة على النظام، استخدِم الأداة dumpsys لمراقبة حالة مراقبة سلامة الجهاز الافتراضي:

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

يقدّم التقرير تفاصيل حول إعداد تقارير سلامة الجهاز الظاهري وإعداد الحِزمة وحالة المراقبة. في ما يلي نموذج لهذا التقرير:

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

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