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

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

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

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

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

للحصول على مرجع، تتوفّر قائمة 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. لمزيد من المعلومات حول بيانات خدمة bundle، يُرجى الاطّلاع على البيانات الوصفية لحِزم الخدمات.

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

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

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

HM RPC API

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

تتيح واجهة برمجة التطبيقات HM RPC للمستمع 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) {}
}

وصف مفصّل للميزات

يصف هذا القسم جوانب مختلفة من "النموذج الهرمي" بتفصيل أكبر.

مراقبة إشارات نبض القلب

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

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

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

الإعداد

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

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

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

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

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

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

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

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

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

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

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

يمكن للخاصية ro.boot.sdv.health_monitor.agent_startup_timeout_sec في النظام أن تتجاوز المدة التي ينتظرها HM لتسجيل واجهات Binder الخاصة بالوكلاء بعد بدء تشغيل 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 إلى الحزمة كي يكون بإمكانها نشر عناوين 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()
       })?;
     }
   }
   

حالة استخدام خاصة: التسجيل الصريح

بالنسبة إلى المزيد من حالات الاستخدام الخاصة التي تحتاج فيها الحزمة إلى مراقبة نبض التطبيق لدورات حياة مخصّصة (على سبيل المثال، بدء المراقبة في وقت أبكر أو انتهائها في وقت لاحق من حالة 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 لتسجيل نبض القلب الخاص بالبقاء على قيد الحياة:

     # ...
     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. نشر "الكتب الرائجة"

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;
   
     // In SDV1.0, a qos monitored message should 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 أنّ حزم QoS HBs سيتم نشرها حول هذا الموضوع، ما يتيح مراقبة موضوع يُعرف باسم 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. يجب تسجيل نشر HB الخاص بجودة الخدمة فقط عند تسجيل الاتصال الذي تتم مراقبته. استخدِم واجهة برمجة التطبيقات الخاصة بالتوفّر من 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

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