نظارت بر سلامت

مانیتور سلامت (HM) یک عامل SDV است که روی هر ماشین مجازی (VM) اجرا می‌شود تا وضعیت بسته‌های سرویس را ردیابی کند، سلامت ماشین مجازی را تعیین کند و به صورت دوره‌ای یک گزارش سلامت ماشین مجازی تولید کند.

بسته‌های خدماتی تعریف‌شده توسط تولیدکننده اصلی (OEM) باید به سیگنال‌های مختلف سلامت گزارش‌شده توسط HM گوش دهند و بر اساس داده‌ها، اقدامات بازیابی را انجام دهند. به عنوان مثال، یک نمونه SDV با بسته‌های خدماتی از کار افتاده ممکن است نیاز به راه‌اندازی مجدد یا به‌روزرسانی داشته باشد.

شما می‌توانید عامل HM را برای ردیابی موارد زیر پیکربندی کنید:

• وضعیت زنده بودن موجودیت‌هایی که وظایف دوره‌ای را انجام می‌دهند، با نظارت بر ضربان قلب زنده بودن. این نظارت را می‌توان هم برای نمونه‌های بسته خدماتی و هم برای عوامل OEM سفارشی پیکربندی کرد.
  • وضعیت بازیابی نمونه‌های بسته سرویس. در SDV 2.0، می‌توانید بسته‌های سرویس را برای راه‌اندازی مجدد خودکار هنگام خرابی پیکربندی کنید. HM سیگنال‌هایی را برای نظارت بر این فرآیند بازیابی ارائه می‌دهد.
  • کیفیت خدمات ارتباطی
• زنده بودن نمایندگان سفارشی SDV و OEM

برای مرجع، کاتالوگ کامل VSIDL، شامل تعاریف اولیه، در //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl موجود است.

اصطلاحات

این اصطلاحات در این صفحه استفاده شده‌اند.

کار با زیرسیستم HM

برای استفاده از ویژگی‌های HM، یک پیاده‌سازی OEM باید:

• سیستم نظارت بر سلامت را با ارائه فایل‌های پیکربندی، همانطور که در بخش «پیکربندی سیستم HM» شرح داده شده است، پیکربندی کنید.
• از یک بسته سرویس HM Listener تعریف‌شده توسط OEM برای گوش دادن به خروجی HM و انجام اقدامات مناسب استفاده کنید.
• بسته‌های خدماتی را توسعه دهید که به طور فعال سیگنال‌ها را مطابق با پیکربندی سلامت خود منتشر کنند. این نشریه به HM اجازه می‌دهد وضعیت سلامت خود را ارزیابی کند. برای اطلاعات بیشتر، به راهنماهای توسعه بسته خدماتی مراجعه کنید.

پیکربندی سیستم HM

هر پیکربندی مرتبط با HM در یکی از این انواع پیکربندی قرار دارد:

• یک پیکربندی سراسری، به ازای هر VM Health
• پیکربندی سلامت بسته‌ی سرویس به ازای هر سرویس، که پارامترهای سلامت را برای تمام نمونه‌های بسته تعریف می‌کند.

پیکربندی سلامت ماشین مجازی (Per VM Health Configuration)

در زمان اجرا، عامل HM انتظار یک پیکربندی سلامت در سطح ماشین مجازی را دارد: این یک فایل textproto (با پسوند .textproto) از نوع VMHealth است که در //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.* اولویت دارد. برای اعمال پیکربندی جدید، باید دستگاه را مجدداً راه‌اندازی کنید.

پیکربندی سلامت ماشین مجازی به شما امکان می‌دهد موارد زیر را تنظیم کنید:

• Periodicity of the VM health report through period_ms . Setting it is a tradeoff between faster signalling that health violations are detected, and HM subsystem performance. We recommend a value of 100 ms.

• کدام عامل‌ها باید تحت نظارت خرابی قرار گیرند (به بخش نظارت بر خرابی عامل مراجعه کنید).

نمونه‌هایی از فایل‌های پیکربندی در //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 برای نظارت بر خرابی پیکربندی شده‌اند و گزارش سلامت ماشین مجازی طوری پیکربندی شده است که هر ۱۰۰ میلی‌ثانیه منتشر شود.

پیکربندی بسته نرم‌افزاری بر اساس سرویس

نظارت بر سلامت نمونه‌های بسته سرویس اختیاری است. برای شرکت در آن، فایل پیکربندی سلامت را در 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;
}

برای هر نمونه، می‌توانید پیکربندی ضربان قلب زنده بودن و پیکربندی 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;
}

برای اطلاعات بیشتر در مورد پیکربندی هر ویژگی، به نظارت بر ضربان قلب Aliveness و نظارت بر QoS مراجعه کنید.

به خروجی HM گوش دهید

شما می‌توانید از طریق گزارش‌های دوره‌ای یا یک API RPC به 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;
}

یک بسته سرویس شنونده HM تعریف‌شده توسط OEM باید به گزارش‌های VMHealth گوش دهد و بسته به معماری کامل سیستم، اقدامات مناسب را انجام دهد. اقدامات بالقوه شامل موارد زیر است:

• اجرای روال‌های تشخیصی روی ماشین مجازی.
• ماشین مجازی را مجدداً راه‌اندازی کنید.
• برای تعیین علت، یک کمپین تله‌متری اجرا کنید.
• سیستم را به‌روزرسانی کنید یا اگر سیستم دچار نقص است، به‌روزرسانی را متوقف کنید.

رابط برنامه‌نویسی کاربردی HM RPC

گزارش سلامت ماشین مجازی، نشریه‌ای است که برای فرکانس و سرعت انتقال بهینه شده و اطلاعات گسترده‌ای در مورد وضعیت سلامت سیستم ارائه می‌دهد.

رابط برنامه‌نویسی کاربردی 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) {}
}

شرح مفصلی از ویژگی‌ها

این بخش جنبه‌های مختلف HM را با جزئیات بیشتری شرح می‌دهد.

نظارت بر ضربان قلب با قابلیت Aliveness

وقتی نظارت بر زنده بودن برای یک نمونه بسته سرویس پیکربندی می‌شود، HM انتظار دارد که نمونه ضربان قلب‌های دوره‌ای را منتشر کند تا ثابت کند که منطق کسب‌وکار به درستی کار می‌کند. این نظارت برای نمونه‌های بسته سرویس که وظایف دوره‌ای انجام می‌دهند، مناسب‌تر است. علاوه بر این، بسته‌هایی که از زمان‌های اجرای ناهمزمان استفاده می‌کنند می‌توانند از نظارت بر زنده بودن برای اثبات اینکه مخزن نخ‌ها (thread pool) پر نشده است، استفاده کنند.

شکل ۱. جریان نظارت بر زنده بودن HM.

پیکربندی

برای فعال کردن aliveness HB روی یک نمونه بسته سرویس، یک نمونه از HealthConfiguration را به فیلد health_config در پیکربندی بسته اضافه کنید.

An aliveness heartbeat configuration defines a predetermined set of parameters that establish the criteria for assessing a service's periodic heartbeat signal. If the characteristics of the service heartbeat deviate from these parameters, the heartbeat is classified as delayed and the corresponding service bundle as unhealthy, which might indicate a non-optimal operational state.

یک بسته خدماتی زمانی سالم در نظر گرفته می‌شود که ضربان قلب را به موقع و مطابق با پیکربندی سلامت خود گزارش دهد. در صورت خرابی یا بار زیاد سیستم، ممکن است ضربان قلب از دست برود یا با تأخیر ارسال شود و باعث شود بسته خدماتی به عنوان ناسالم علامت‌گذاری شود. در این حالت، تخلفی در گزارش VmHealth ظاهر می‌شود.

توسعه‌دهندگان بسته‌های خدماتی باید پیکربندی سلامت یک بسته خدماتی را در متادیتای APEX مربوطه تعریف کنند. پیکربندی سلامت این معیارها را تعریف می‌کند:

• حداکثر تأخیر اولیه مجاز بین شروع سرویس و اولین تشخیص ضربان قلب.

• دوره‌ای که طی آن بسته سرویس SDV منطق کسب‌وکار را اجرا می‌کند، که مربوط به تناوب انتشار ضربان قلب سرویس است.

• تعداد دوره‌هایی که باید از دست بروند تا HM بسته خدماتی را ناسالم تشخیص دهد.

• زمان اجرا، مدت زمانی است که یک بسته سرویس SDV برای انجام منطق تجاری خود نیاز دارد تا بتواند ضربان قلب سرویس را منتشر کند.

اگر ضربان قلب سرویس با تأخیر مواجه شود، بسته سرویس نقض سلامت ایجاد می‌کند. بر اساس زمان مشاهده سلامت، دو حالت وجود دارد:

• مورد ۱: ضربان قلب اولیه دریافت نشده است. اگر بیش از تأخیر اولیه مجاز بین شروع بسته سرویس و زمان مشاهده سپری شده باشد، بسته سرویس ناسالم در نظر گرفته می‌شود.

• مورد ۲: ضربان قلب قبلاً دریافت شده بود. اگر آستانه‌ای بین آخرین ضربان قلب و زمان مشاهده سپری شده باشد، بسته خدماتی ناسالم در نظر گرفته می‌شود. این آستانه به صورت مجموع دوره گزارش (ضرب در تعداد دوره‌ها) و مدت زمان انجام وظیفه محاسبه می‌شود.

قالب پیکربندی سلامت در //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 آن به پایان رسیده باشد.

مورد استفاده خاص: ثبت صریح برای نظارت بر ضربان قلب

رفتاری که در نظارت بر ضربان قلب Aliveness شرح داده شده است، که در آن ضربان قلب بین on_start و on_stop انتظار می‌رود، نظارت ضمنی بر زنده بودن نامیده می‌شود. این روش توصیه شده برای استفاده از این ویژگی است: منطق تجاری بسته را ساده می‌کند و تضمین می‌کند که بسته همیشه تحت نظارت باشد.

با این حال، برخی موارد استفاده ممکن است وجود داشته باشد که دوره نظارت پیش‌فرض یک محدودیت باشد:

• یک نمونه بسته سرویس شامل منطق تجاری است که به صورت دوره‌ای در یک بازه زمانی که به رویدادهای start و stop مرتبط نیست، اجرا می‌شود. نظارت بر زنده بودن سرویس ممکن است فقط در این دوره سفارشی مورد نیاز باشد.
• HM به طور دقیق HBها را در دوره‌های تعلیق و از سرگیری ردیابی می‌کند. بنابراین، ممکن است بسته بخواهد پس از on_stop همچنان تحت نظارت باشد.
• ممکن است عامل‌های سفارشی OEM به عنوان بسته‌های خدماتی پیاده‌سازی نشوند. بنابراین، آنها نمی‌توانند از نظارت ضمنی بر زنده بودن بهره‌مند شوند. با این حال، ممکن است هنوز به نظارت بر زنده بودن نیاز داشته باشند.

در این موارد، HM به شما امکان می‌دهد تا از ثبت ضمنی برای نظارت بر زنده بودن سیستم (liveness monitoring) به نفع ثبت صریح (explicit registration) عبور کنید. برای استفاده از ثبت صریح، یک نمونه بسته (bundle instance) باید با عدم درج ورودی از نوع HealthConfiguration برای نمونه خاص در مانیفست بسته، از ثبت ضمنی انصراف دهد. سپس، در زمان اجرا، نمونه بسته باید از API RPC تعریف شده در //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto برای ثبت و لغو ثبت دستی از نظارت استفاده کند. ضربان قلب‌های منتشر شده به محض موفقیت فراخوانی RPC ثبت، انتظار می‌رود.

برای یک نمونه پیاده‌سازی، به //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/ مراجعه کنید.

نظارت بر کیفیت سرویس (QoS)

کیفیت سرویس (QoS) معیاری برای سنجش ارتباطات است. HM بررسی می‌کند که آیا پیام ارسالی زمان زیادی را در حال ارسال صرف می‌کند یا خیر، یا در صورت ارتباط دوره‌ای، آیا پیام‌ها با فرکانس انتخاب شده دریافت نمی‌شوند.

SDV چندین نوع ارتباط Pub/Sub و RPC را ارائه می‌دهد. وجه مشترک همه آنها این است که همه طرح‌های ارتباطی حداقل یک شنونده دارند. برای اینکه HM بتواند ارتباط را رصد کند، این نمونه بسته سرویس شنود باید هر زمان که پیام مورد نظر را دریافت می‌کند، ضربان قلب‌های QoS ویژه‌ای را منتشر کند.

پیکربندی

برای فعال کردن نظارت QoS بر یک ارتباط، ابتدا شنونده ارتباطی که ضربان قلب QoS را منتشر خواهد کرد، شناسایی کنید. سپس، برای نمونه بسته سرویس شناسایی شده، یک یا چند موضوع را به نگاشت‌های QosMonitoringConfiguration در فیلد qos_config اضافه کنید. برای اطلاعات بیشتر، به پیکربندی بسته سرویس به ازای هر سرویس مراجعه کنید.

موضوع ، رشته‌ای است که موضوع انتشار را تعریف می‌کند، جایی که HM در زمان اجرا انتظار QoS HBs را دارد. یک نمونه بسته گوش‌دادنی می‌تواند در چندین ارتباط شرکت کند و QoS HBs را در چندین موضوع گزارش دهد.

موضوعات باید توصیفی باشند، زیرا در صورت تشخیص نقض 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 را اعمال کنید. مقدار qos_latency_threshold_ms برابر با 30 برای ارتباطات Pub/Sub درون ماشین مجازی تحت بارهای عادی سیستم معقول است.

ملاحظات زمان اجرا

مشابه نظارت بر HB زنده بودن، انتظار می‌رود بسته شنود ارتباطی نوعی ضربان قلب منتشر کند. در این حالت، یک HB QoS باید هر زمان که پیام‌های مورد نظر دریافت می‌شوند، منتشر شود، برخلاف پایان اجرای منطق کسب‌وکار.

یک QoS HB از نوع QosHeartbeat است که در //system/software_defined_vehicle/health_monitor/catalog/qos_heartbeat.proto تعریف شده است:

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

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

زمان ثبت و لغو ثبت انتشار QoS HB برای نظارت دقیق بسیار مهم است. HM انتظار دارد QoS HBها بین این دو رویداد ثبت شوند. بسته شنود پیام باید انتشار QoS HB را زمانی ثبت کند که ارتباط تحت نظارت در پشته ارتباطی SDV ثبت شده باشد. HM می‌تواند از API دسترسی‌پذیری برای انجام این کار استفاده کند. برای اطلاعات بیشتر، به بخش تعیین دسترسی‌پذیری سرویس مراجعه کنید.

نظارت بر بازیابی بسته خدماتی

بازیابی نمونه‌های بسته‌ی سرویس به عنوان بخشی از فایل‌های پیکربندی عامل هماهنگ‌سازی پیکربندی می‌شود. برای بررسی کامل موضوع، به بسته‌های سرویس مراجعه کنید. زیرسیستم HM به صورت غیرفعال فرآیند بازیابی را مشاهده می‌کند. هنگامی که عدم موفقیت در بازیابی یک نمونه‌ی بسته شناسایی شود، یک تخلف به گزارش VMHealth اضافه می‌شود. برخلاف سایر قابلیت‌های نظارت HM، نظارت بر بازیابی اجباری و غیرقابل پیکربندی است.

خرابی‌های نمونه‌های بسته‌ی خدماتی که برای بازیابی پیکربندی نشده‌اند، در اولین خرابی خود، نقض سلامت ایجاد می‌کنند.

بازیابی نمونه بسته سرویس به گونه‌ای طراحی شده است که با نظارت بر زنده بودن ضربان قلب ادغام شود. سیستم HM هنگام ارزیابی ضربان قلب، زمانی که تشخیص می‌دهد بسته در حال بازیابی است، سهل‌گیرتر عمل می‌کند. در عمل، این سهل‌گیری به این معنی است که بسته‌های سرویس در صورت خرابی، نیازی به انجام هیچ مرحله اضافی برای لغو ثبت یا ثبت نظارت ندارند.

نظارت بر خرابی عامل

HM با استفاده از مکانیسم binder linkToDeath ، خرابی‌های احتمالی عامل‌های SDV را تشخیص می‌دهد.

شما می‌توانید مانیتورینگ خرابی را به عنوان بخشی از پیکربندی سلامت ماشین مجازی (به پیکربندی Per-SDV instance (VM) مراجعه کنید)، به ویژه فیلد مکرر monitored_agent پیکربندی کنید. این فیلد باید حاوی ورودی‌هایی از نوع BinderServiceAgent باشد:

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

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

اگر عامل، رابط اتصال‌دهنده (binder interface) را در معرض دید قرار دهد، می‌توان عامل‌های سفارشی را نیز رصد کرد. برای رصد یک عامل سفارشی، مجوزهای HM SELinux را برای گوش دادن به رابط اتصال‌دهنده مناسب اعطا کنید.

ویژگی سیستمی ro.boot.sdv.health_monitor.agent_startup_timeout_sec می‌تواند مدت زمانی را که HM پس از شروع HM منتظر می‌ماند تا عامل‌ها رابط‌های اتصال‌دهنده خود را ثبت کنند، لغو کند. مگر اینکه عامل‌های سفارشی الزامی داشته باشند، پیش‌فرض سه ثانیه مناسب است.

راهنماهای توسعه بسته خدمات

این بخش، برخلاف روش‌های نظری بخش‌های قبلی، راهنماهای گام به گام در مورد نحوه استفاده از ویژگی‌های HM از بسته‌های خدماتی ارائه می‌دهد. نمونه مرجع به‌روز که این راهنماها بر اساس آن نوشته شده‌اند، نمونه qos_monitoring است. برای یک تجربه عملی، فایل //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README نمونه را دنبال کنید.

مانیتورینگ ضربان قلب aliveness را به بسته خدماتی اضافه کنید

این روش مستقیم‌ترین راه برای فعال کردن نظارت بر سلامت برای یک بسته خدماتی است:

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()
       })?;
     }
   }
   

مورد استفاده خاص: ثبت صریح

برای موارد استفاده خاص‌تر، جایی که بسته نرم‌افزاری برای چرخه‌های عمر سفارشی به نظارت 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 ، در HM ثبت نام کنید:

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

4. HB ها را منتشر کنید.

5. وقتی دیگر نیازی به آن ندارید، از نظارت خارج شوید:

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

افزودن نظارت QoS به ارتباطات

1. تأیید کنید که نمونه بسته سرویس، مشترک موضوعی با نام fog-light-status در کاتالوگ VSIDL است:

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

   قالب پیام به شرح زیر است:

   package com.android.sdv.sample.oem.health.qos_monitoring;
   import "google/protobuf/timestamp.proto";
   
   message QosMonitoredFogLightStatus {
     // arbitrary fields related to business logic
     int32 status = 1;
   
     // In SDV1.0, a qos monitored message should include a timestamp field
     .google.protobuf.Timestamp timestamp = 2;
   }
   

2. یک نمونه از ServiceBundleHealthConfiguration برای نمونه‌های بسته نرم‌افزاری در فایل health_configuration.textproto که شامل نظارت QoS است، تعریف کنید:

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

   موضوع انتخاب شده در فیلد key نشان می‌دهد که HBهای QoS در این موضوع منتشر خواهند شد و امکان نظارت بر موضوعی به نام 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های QoS باشد:

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

7. انتشار QoS HB را فقط زمانی ثبت کنید که ارتباط تحت نظارت ثبت شده باشد. از API مربوط به دسترسی از libsdv_mw_clientlib استفاده کنید:

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

8. هر بار که پیامی دریافت می‌شود، HBهای QoS را منتشر کنید:

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

9. برای متوقف کردن نظارت QoS، شیء publisher را حذف کنید:

   // ...
   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

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