सेहत की देखभाल करने से जुड़े ऐप्लिकेशन

हेल्थ मॉनिटर (एचएम) एक एसडीवी एजेंट है. यह हर वर्चुअल मशीन (वीएम) पर चलता है. इसका काम, सेवा बंडलों की स्थिति को ट्रैक करना, वीएम की स्थिति का पता लगाना, और समय-समय पर वीएम की स्थिति की रिपोर्ट जनरेट करना है.

ओईएम की ओर से तय किए गए सर्विस बंडल को, एचएम की ओर से रिपोर्ट किए गए अलग-अलग स्वास्थ्य सिग्नल को सुनना होगा. साथ ही, डेटा के आधार पर रिकवरी की कार्रवाइयां करनी होंगी. उदाहरण के लिए, क्रैश हो रहे सर्विस बंडल वाले SDV इंस्टेंस को रीस्टार्ट या अपडेट करने की ज़रूरत पड़ सकती है.

एचएम एजेंट को इन चीज़ों को ट्रैक करने के लिए कॉन्फ़िगर किया जा सकता है:

• समय-समय पर टास्क पूरा करने वाली इकाइयों की मौजूदगी की स्थिति. इसके लिए, मौजूदगी की जानकारी देने वाली पल्स की निगरानी की जाती है. इस मॉनिटरिंग को, सर्विस बंडल के इंस्टेंस और कस्टम ओईएम एजेंट, दोनों के लिए कॉन्फ़िगर किया जा सकता है.
  • सेवा बंडल इंस्टेंस की रिकवरी की स्थिति. SDV 2.0 में, क्रैश होने पर अपने-आप रीस्टार्ट होने के लिए, सर्विस बंडल कॉन्फ़िगर किए जा सकते हैं. एचएम, खाता वापस पाने की इस प्रोसेस को मॉनिटर करने के लिए सिग्नल देता है.
  • कम्यूनिकेशन की क्वालिटी ऑफ़ सर्विस
• एसडीवी और ओईएम के कस्टम एजेंट की उपलब्धता

रेफ़रंस के लिए, प्रोटोकॉल बफ़र की परिभाषाओं के साथ-साथ पूरा VSIDL कैटलॉग //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl पर उपलब्ध है.

शब्दावली

इस पेज पर इन शब्दों का इस्तेमाल किया गया है.

एचएम सबसिस्टम के साथ काम करना

एचएम की सुविधाओं का इस्तेमाल करने के लिए, ओईएम को ये काम करने होंगे:

• एचएम सिस्टम को कॉन्फ़िगर करना में दिए गए निर्देशों के मुताबिक, कॉन्फ़िगरेशन फ़ाइलें देकर हेल्थ मॉनिटरिंग सिस्टम को कॉन्फ़िगर करें.
• एचएम के आउटपुट को सुनने और ज़रूरी कार्रवाई करने के लिए, ओईएम की ओर से तय की गई एचएम लिसनर सेवा के बंडल का इस्तेमाल करें.
• ऐसे सर्विस बंडल डेवलप करें जो कॉन्फ़िगरेशन के हिसाब से, सिग्नल पब्लिश करते हों. इस पब्लिकेशन से, एचएम को अपनी सेहत का आकलन करने में मदद मिलती है. ज़्यादा जानकारी के लिए, सेवा बंडल की डेवलपर गाइड देखें.

एचएम सिस्टम को कॉन्फ़िगर करना

एचएम से जुड़ा कोई भी कॉन्फ़िगरेशन, इनमें से किसी एक कॉन्फ़िगरेशन टाइप में मौजूद होता है:

• हर वीएम के लिए ग्लोबल हेल्थ कॉन्फ़िगरेशन
• हर सेवा बंडल के लिए हेल्थ कॉन्फ़िगरेशन. इससे बंडल के सभी इंस्टेंस के लिए हेल्थ पैरामीटर तय किए जाते हैं

हर वीएम के लिए हेल्थ कॉन्फ़िगरेशन

रन टाइम पर, एचएम एजेंट को पूरे वीएम के लिए हेल्थ कॉन्फ़िगरेशन की ज़रूरत होती है. यह VMHealth टाइप की textproto फ़ाइल होती है. इसका .textproto एक्सटेंशन होता है. इसे //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto पर तय किया जाता है. वीएम हेल्थ कॉन्फ़िगरेशन, बूट टाइम सिस्टम प्रॉपर्टी 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 में सेव करें. साथ ही, sdv_service_bundles_manifest.textproto में sdv_service_bundle_metadata के health_config_path फ़ील्ड में इसका पाथ तय करें. सेवा बंडल के मेनिफ़ेस्ट के बारे में ज़्यादा जानने के लिए, सेवा बंडल का मेटाडेटा देखें.

सेहत से जुड़ी कॉन्फ़िगरेशन फ़ाइल, इस तरह की 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;
}

हर इंस्टेंस के लिए, अलाइवनेस हार्टबीट कॉन्फ़िगरेशन और 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 के आउटपुट को सुनना

एचएम को समय-समय पर मिलने वाली रिपोर्ट या आरपीसी एपीआई के ज़रिए सुना जा सकता है.

वीएम की सेहत की रिपोर्ट

परफ़ॉर्मेंस की निगरानी करने की सुविधा, वीएम की परफ़ॉर्मेंस की रिपोर्ट को बार-बार जनरेट करती है. इससे निगरानी की जा रही इकाइयों की परफ़ॉर्मेंस के बारे में कम शब्दों में जानकारी मिलती है.

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

वीएम की हेल्थ रिपोर्ट, पब्लिश करने की फ़्रीक्वेंसी और ट्रांसमिशन की स्पीड के लिए ऑप्टिमाइज़ की गई होती है. इससे सिस्टम की हेल्थ के स्टेटस के बारे में ज़्यादा जानकारी मिलती है.

एचएम आरपीसी एपीआई की मदद से, एचएम लिसनर को स्वास्थ्य से जुड़े उल्लंघनों के सोर्स के बारे में ज़्यादा जानकारी मिलती है. इंटरफ़ेस को //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) {}
}

सुविधाओं के बारे में पूरी जानकारी

इस सेक्शन में, एचएम के अलग-अलग पहलुओं के बारे में ज़्यादा जानकारी दी गई है.

Aliveness heartbeats monitoring

जब किसी सेवा बंडल इंस्टेंस के लिए, ऐक्टिवनेस मॉनिटरिंग कॉन्फ़िगर की जाती है, तो एचएम को उम्मीद होती है कि इंस्टेंस समय-समय पर हार्टबीट पब्लिश करेगा. इससे यह साबित होगा कि कारोबार का लॉजिक सही तरीके से काम कर रहा है. यह मॉनिटरिंग, सेवा के बंडल के उन इंस्टेंस के लिए सबसे सही है जो समय-समय पर टास्क पूरे करते हैं. इसके अलावा, एसिंक्रोनस रनटाइम का इस्तेमाल करने वाले बंडल, अलाइवनेस मॉनिटरिंग का इस्तेमाल करके यह साबित कर सकते हैं कि थ्रेड पूल खत्म नहीं हुआ है.

पहली इमेज. HM aliveness monitoring flow.

कॉन्फ़िगरेशन

किसी सेवा बंडल इंस्टेंस पर अलाइवनेस एचबी चालू करने के लिए, बंडल कॉन्फ़िगरेशन में health_config फ़ील्ड में HealthConfiguration का इंस्टेंस जोड़ें.

अलिवनेस हार्टबीट कॉन्फ़िगरेशन, पैरामीटर का एक ऐसा सेट होता है जो पहले से तय होता है. यह सेट, किसी सेवा के पीरियोडिक हार्टबीट सिग्नल का आकलन करने के लिए शर्तें तय करता है. अगर सेवा की हार्टबीट की विशेषताएं इन पैरामीटर से अलग होती हैं, तो हार्टबीट को देरी से होने वाली हार्टबीट के तौर पर क्लासिफ़ाई किया जाता है. साथ ही, इससे जुड़े सेवा बंडल को खराब माना जाता है. इससे पता चल सकता है कि सेवा ठीक से काम नहीं कर रही है.

किसी सेवा बंडल को तब सही माना जाता है, जब वह अपने हेल्थ कॉन्फ़िगरेशन के हिसाब से समय पर हार्टबीट रिपोर्ट करता है. क्रैश होने या सिस्टम पर ज़्यादा लोड होने की वजह से, हार्टबीट मिस हो सकती है या उसमें देरी हो सकती है. इससे सर्विस बंडल को अस्वस्थ के तौर पर मार्क किया जा सकता है. इस मामले में, VmHealth रिपोर्ट में उल्लंघन दिखता है.

सेवा बंडल के डेवलपर को, सेवा बंडल के हेल्थ कॉन्फ़िगरेशन को उससे जुड़े APEX मेटाडेटा में तय करना चाहिए. स्वास्थ्य कॉन्फ़िगरेशन में इन शर्तों के बारे में बताया गया है:

• सेवा शुरू होने और पहले हार्टबीट का पता चलने के बीच ज़्यादा से ज़्यादा शुरुआती देरी.

• वह अवधि जिसके दौरान एसडीवी सेवा बंडल, कारोबारी नियमों को लागू करता है. यह अवधि, सेवा के हार्टबीट को पब्लिश करने की अवधि से मेल खाती है.

• एचएम के लिए, सेवा बंडल को खराब मानने से पहले, कितने समय तक सेवा नहीं दी गई.

• एक्ज़ीक्यूशन का समय, एसडीवी सेवा बंडल को अपने कारोबार के लॉजिक को पूरा करने में लगने वाला समय होता है. इसके बाद ही, वह सेवा की पल्स पब्लिश कर सकता है.

अगर सेवा की हार्टबीट में देरी होती है, तो सेवा बंडल से सेहत से जुड़े उल्लंघन की जानकारी जनरेट होती है. सेहत की निगरानी के समय के आधार पर, दो तरह के मामले होते हैं:

• पहला मामला: शुरुआती हार्टबीट नहीं मिली. अगर सेवा बंडल के शुरू होने और जांच के समय के बीच, तय की गई शुरुआती देरी से ज़्यादा समय बीत चुका है, तो सेवा बंडल को खराब माना जाता है.

• दूसरा मामला: हार्टबीट पहले ही मिल चुकी हैं. अगर आखिरी हार्टबीट और ऑब्ज़र्वेशन के समय के बीच थ्रेशोल्ड पार हो गया है, तो सेवा बंडल को खराब माना जाता है. इस थ्रेशोल्ड का हिसाब लगाने के लिए, रिपोर्टिंग अवधि को अवधियों की संख्या से गुणा किया जाता है. इसके बाद, इसमें टास्क की अवधि को जोड़ा जाता है.

सेहत से जुड़े कॉन्फ़िगरेशन का फ़ॉर्मैट //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;
 }

पब्लिकेशन का विषय अपनी पसंद के हिसाब से चुनें. एचएम एजेंट, मैसेज टाइप के हिसाब से पब्लिकेशन का पता लगाने के लिए, डिस्कवरी का इस्तेमाल करता है.

जब सेवा बंडल के मेनिफ़ेस्ट में लिंक किए गए हेल्थ कॉन्फ़िगरेशन के ज़रिए, डिवाइस के चालू होने की स्थिति की निगरानी की जाती है, तो एचएम एजेंट को उम्मीद होती है कि इंस्टेंस के on_start रूटीन पूरा करने के तुरंत बाद एचबी पब्लिश किए जाएंगे. हमारा सुझाव है कि on_start को छोटा रखें, ताकि सिस्टम के स्टार्टअप को ब्लॉक होने से बचाया जा सके. इसलिए, on_start में शुरू किए गए एसिंक्रोनस टास्क में हार्टबीट पब्लिश करें.

बंडल डेवलपर, initial_delay_ms कॉन्फ़िगरेशन एंट्री का इस्तेमाल करके, पहले हार्टबीट का समय अपने हिसाब से तय कर सकते हैं.

बंडल इंस्टेंस को तब तक हार्टबीट पब्लिश करते रहना चाहिए, जब तक इसे बंद न कर दिया जाए. किसी इंस्टेंस को तब बंद माना जाता है, जब उसका on_stop रूटीन पूरा हो जाता है.

इस्तेमाल का खास उदाहरण: हार्टबीट मॉनिटरिंग के लिए साफ़ तौर पर रजिस्टर करना

लाइवनेस हार्टबीट मॉनिटरिंग में बताए गए व्यवहार को इंप्लिसिट लाइवनेस मॉनिटरिंग कहा जाता है. इसमें हार्टबीट on_start और on_stop के बीच होने चाहिए. इस सुविधा का इस्तेमाल करने का यह सबसे सही तरीका है: इससे बंडल के बिज़नेस लॉजिक को आसान बनाया जा सकता है. साथ ही, यह पक्का किया जा सकता है कि बंडल की हमेशा निगरानी की जाए.

हालांकि, कुछ ऐसे मामले हो सकते हैं जिनमें डिफ़ॉल्ट मॉनिटरिंग की अवधि एक सीमा हो सकती है:

• किसी सेवा बंडल इंस्टेंस में ऐसा कारोबारी नियम होता है जो समय-समय पर होता है. यह start और stop इवेंट से लिंक नहीं होता. ऐसा हो सकता है कि इस कस्टम अवधि में ही, लाइवनेस मॉनिटरिंग की ज़रूरत हो.
• एचएम, निलंबित और फिर से शुरू किए जाने की अवधि के दौरान, एचबी को सटीक तरीके से ट्रैक करता है. इसलिए, के बाद भी बंडल की निगरानी जारी रखी जा सकती है.on_stop
• ऐसा हो सकता है कि कस्टम ओईएम एजेंट, सेवा बंडलों के तौर पर लागू न किए गए हों. इसलिए, वे लाइवनेस मॉनिटरिंग की सुविधा का फ़ायदा नहीं ले सकते. हालांकि, इसके बावजूद, उन्हें चालू रखने के लिए निगरानी करने की ज़रूरत पड़ सकती है.

इन मामलों में, एचएम आपको एक्सप्लिसिट रजिस्ट्रेशन के लिए, ज़िंदा होने की पुष्टि करने के लिए इंप्लिसिट रजिस्ट्रेशन को बायपास करने की सुविधा देता है. साफ़ तौर पर रजिस्ट्रेशन करने की सुविधा का इस्तेमाल करने के लिए, बंडल इंस्टेंस को इंप्लिसिट रजिस्ट्रेशन से ऑप्ट आउट करना होगा. इसके लिए, बंडल के मेनिफ़ेस्ट में उस इंस्टेंस के लिए HealthConfiguration टाइप की एंट्री शामिल न करें. इसके बाद, रन टाइम पर बंडल इंस्टेंस को //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto में तय किए गए RPC API का इस्तेमाल करना चाहिए, ताकि मैन्युअल तरीके से मॉनिटरिंग के लिए रजिस्टर और डीरजिस्टर किया जा सके. रजिस्ट्रेशन आरपीसी कॉल के पूरा होने के तुरंत बाद, पब्लिश किए गए हार्टबीट मिलने चाहिए.

लागू करने के उदाहरण के लिए, //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/ देखें.

QoS मॉनिटरिंग

सेवा की क्वालिटी (QoS), कम्यूनिकेशन को मेज़र करने का एक तरीका है. एचएम यह मॉनिटर करता है कि भेजे गए मैसेज को पहुंचने में ज़्यादा समय तो नहीं लग रहा है. इसके अलावा, अगर समय-समय पर कम्यूनिकेशन किया जाता है, तो एचएम यह भी मॉनिटर करता है कि मैसेज, चुनी गई फ़्रीक्वेंसी के हिसाब से नहीं मिल रहे हैं.

SDV, Pub/Sub और RPC कम्यूनिकेशन के कई वर्शन उपलब्ध कराता है. इन सभी कम्यूनिकेशन स्कीम में एक बात सामान्य है कि इनमें कम से कम एक लिसनर होता है. एचएम को कम्यूनिकेशन की निगरानी करने के लिए, इस लिसनिंग सेवा बंडल इंस्टेंस को खास क्यूओएस हार्टबीट पब्लिश करने चाहिए. ऐसा तब करना चाहिए, जब इसे कोई काम का मैसेज मिले.

कॉन्फ़िगरेशन

किसी कम्यूनिकेशन की क्वालिटी ऑफ़ सर्विस (क्यूओएस) मॉनिटरिंग को चालू करने के लिए, सबसे पहले उस कम्यूनिकेशन लिसनर की पहचान करें जो क्यूओएस हार्टबीट पब्लिश करेगा. इसके बाद, पहचाने गए सेवा बंडल इंस्टेंस के लिए, QosMonitoringConfiguration फ़ील्ड में QosMonitoringConfiguration मैपिंग में एक या उससे ज़्यादा विषय जोड़ें.qos_config ज़्यादा जानकारी के लिए, हर सेवा के लिए बंडल कॉन्फ़िगरेशन देखें.

विषय एक स्ट्रिंग है. इससे पब्लिकेशन के उस विषय के बारे में पता चलता है जिसके लिए, एचएम को रन टाइम पर QoS HB की ज़रूरत होती है. लिसनिंग बंडल का कोई इंस्टेंस, कई कम्यूनिकेशन में हिस्सा ले सकता है. साथ ही, कई विषयों पर QoS HB रिपोर्ट कर सकता है.

विषयों के बारे में पूरी जानकारी दी जानी चाहिए, क्योंकि अगर रन टाइम के दौरान सेवा की क्वालिटी (क्यूओएस) से जुड़े उल्लंघन का पता चलता है, तो इसकी सूचना एचएम लिसनर सर्विस बंडल को दी जाती है.

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 मॉनिटरिंग लागू करें. सिस्टम पर सामान्य लोड होने पर, वीएम में Pub/Sub कम्यूनिकेशन के लिए 30 का qos_latency_threshold_ms सही होता है.

रनटाइम से जुड़ी बातें

लाइवनेस एचबी मॉनिटरिंग की तरह ही, कम्यूनिकेशन लिसनिंग बंडल को भी एक तरह का हार्टबीट पब्लिश करना होता है. इस मामले में, दिलचस्पी के हिसाब से मैसेज मिलने पर, 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 पब्लिकेशन को रजिस्टर और डीरजिस्टर करने का समय, सटीक मॉनिटरिंग के लिए ज़रूरी है. एचएम को इन दोनों इवेंट के बीच QoS HB की उम्मीद है. जब मॉनिटर किए जा रहे कम्यूनिकेशन को SDV कम्यूनिकेशन स्टैक के साथ रजिस्टर किया जाता है, तब मैसेज सुनने वाले बंडल को QoS HB पब्लिकेशन रजिस्टर करना चाहिए. इसके लिए, एचएम उपलब्धता एपीआई का इस्तेमाल कर सकता है. ज़्यादा जानकारी के लिए, सेवा की उपलब्धता का पता लगाना लेख पढ़ें.

सेवा के बंडल की रिकवरी की निगरानी

सर्विस बंडल इंस्टेंस को वापस लाने की सुविधा, ऑर्केस्ट्रेशन एजेंट की कॉन्फ़िगरेशन फ़ाइलों के हिस्से के तौर पर कॉन्फ़िगर की जाती है. इस विषय के बारे में पूरी जानकारी के लिए, सेवा बंडल लेख पढ़ें. एचएम सबसिस्टम, रिकवरी प्रोसेस को पैसिव तरीके से मॉनिटर करता है. बंडल इंस्टेंस को वापस लाने में गड़बड़ी का पता चलने पर, VMHealth रिपोर्ट में उल्लंघन जोड़ा जाता है. एचएम की निगरानी से जुड़ी अन्य सुविधाओं के उलट, रिकवरी की निगरानी करना ज़रूरी है. इसे कॉन्फ़िगर नहीं किया जा सकता.

अगर सेवा बंडल के ऐसे इंस्टेंस क्रैश होते हैं जिन्हें ठीक करने के लिए कॉन्फ़िगर नहीं किया गया है, तो पहली बार क्रैश होने पर उनकी स्थिति खराब होने की सूचना जनरेट होती है.

Service bundle instance recovery को, heartbeat aliveness monitoring के साथ इंटिग्रेट करने के लिए डिज़ाइन किया गया है. जब एचएम सिस्टम को पता चलता है कि बंडल ठीक हो रहा है, तो वह दिल की धड़कनों का आकलन करते समय ज़्यादा नरमी बरतता है. इस छूट का मतलब है कि अगर सेवा बंडल क्रैश हो जाते हैं, तो उन्हें निगरानी हटाने या रजिस्ट्रेशन करने से जुड़ी कोई अतिरिक्त कार्रवाई करने की ज़रूरत नहीं है.

एजेंट के क्रैश को मॉनिटर करना

एचएम, बाइंडर linkToDeathमैकेनिज़्म का इस्तेमाल करके, एसडीवी एजेंट के संभावित क्रैश का पता लगाता है.

क्रैश मॉनिटरिंग को वीएम की सेहत से जुड़े कॉन्फ़िगरेशन के हिस्से के तौर पर कॉन्फ़िगर किया जा सकता है. इसके लिए, हर एसडीवी इंस्टेंस (वीएम) का कॉन्फ़िगरेशन देखें. खास तौर पर, monitored_agent repeated फ़ील्ड देखें. इस फ़ील्ड में 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;
}

अगर एजेंट, बाइंडर इंटरफ़ेस को दिखाता है, तो कस्टम एजेंटों की भी निगरानी की जा सकती है. कस्टम एजेंट को मॉनिटर करने के लिए, एचएम को SELinux की अनुमतियां दें, ताकि वह सही बाइंडर इंटरफ़ेस को सुन सके.

सिस्टम प्रॉपर्टी ro.boot.sdv.health_monitor.agent_startup_timeout_sec, इस बात को बदल सकती है कि एचएम को एजेंट के बाइंडर इंटरफ़ेस रजिस्टर करने के लिए कितनी देर तक इंतज़ार करना चाहिए. ऐसा तब होता है, जब एचएम शुरू हो जाता है. अगर कस्टम एजेंट के लिए ज़रूरी न हो, तो तीन सेकंड का डिफ़ॉल्ट समय सही होता है.

सेवा बंडल के लिए डेवलपर गाइड

इस सेक्शन में, सेवा बंडलों में शामिल एचएम की सुविधाओं को इस्तेमाल करने के बारे में सिलसिलेवार तरीके से बताया गया है. यह पिछले सेक्शन में दी गई जानकारी से अलग है. इन गाइड में इस्तेमाल किया गया रेफ़रंस सैंपल, qos_monitoring सैंपल है. बेहतर अनुभव के लिए, सैंपल के //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README को फ़ॉलो करें.

किसी सेवा बंडल में, ज़िंदा होने की पुष्टि करने के लिए हार्टबीट मॉनिटरिंग की सुविधा जोड़ना

किसी सेवा के बंडल के लिए, परफ़ॉर्मेंस पर नज़र रखने की सुविधा चालू करने का सबसे आसान तरीका यह है:

1. health_configuration.textproto नाम की फ़ाइल में, बंडल इंस्टेंस के लिए ServiceBundleHealthConfiguration का इंस्टेंस तय करें:

   # 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. बंडल में एसडीवी की अनुमतियां जोड़ें, ताकि बंडल को एचबी पब्लिश करने की अनुमति मिल सके:

     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. aliveness HB registration RPC का इस्तेमाल करने के लिए, SDV की अनुमति जोड़ें:

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

3. आरपीसी के ज़रिए एचएम के साथ रजिस्टर करें. उदाहरण के लिए, 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();
   

बातचीत में QoS मॉनिटरिंग की सुविधा जोड़ना

1. पुष्टि करें कि सर्विस बंडल इंस्टेंस, VSIDL कैटलॉग में fog-light-status नाम के विषय का सदस्य है:

     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. health_configuration.textproto फ़ाइल में बंडल इंस्टेंस के लिए ServiceBundleHealthConfiguration का इंस्टेंस तय करें. इसमें क्यूओएस मॉनिटरिंग शामिल है:

   # 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 सेट करें:

   # 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. बंडल में एसडीवी की अनुमतियां जोड़ें, ताकि बंडल को क्वालिटी ऑफ़ सर्विस (क्यूओएस) एचबी पब्लिश करने की अनुमति मिल सके:

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

7. QoS 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. मैसेज मिलने पर हर बार QoS HB पब्लिश करें:

   // ...
   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 टूल का इस्तेमाल करके वीएम की सेहत की निगरानी करने की स्थिति पर नज़र रखें:

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

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