Sağlık durumu izleme

Durum izleyici (HM), hizmet paketlerinin durumunu izlemek, sanal makinenin durumunu belirlemek ve düzenli olarak sanal makine durumu raporu oluşturmak için her sanal makinede (VM) çalışan bir SDV aracısıdır.

OEM tarafından tanımlanan hizmet paketleri, HM tarafından bildirilen çeşitli sağlık sinyallerini dinlemeli ve verilere göre kurtarma işlemleri gerçekleştirmelidir. Örneğin, kilitlenen hizmet paketlerine sahip bir SDV örneğinin yeniden başlatılması veya güncellenmesi gerekebilir.

HM aracını aşağıdakileri izleyecek şekilde yapılandırabilirsiniz:

  • Canlılık sinyalleri izlenerek düzenli görevler gerçekleştiren öğelerin canlılık durumu. Bu izleme hem hizmet paketi örnekleri hem de özel OEM aracıları için yapılandırılabilir.
    • Hizmet paketi örneklerinin kurtarma durumu. Hizmet paketlerini, kilitlenme durumunda otomatik olarak yeniden başlatılacak şekilde yapılandırabilirsiniz. HM, bu toparlanma sürecini izlemek için sinyaller sağlar.
    • İletişim HK'sı
  • SDV ve OEM özel temsilcilerinin etkinliği

Referans olarak, proto tanımları da dahil olmak üzere VSIDL kataloğunun tamamını //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl adresinde bulabilirsiniz.

Terminoloji

Bu terimler bu sayfada kullanılmaktadır.

aliveness heartbeat (HB)
Hizmet paketinin etkin olduğunu belirtmek için hizmet paketi tarafından oluşturulan mesaj. İletide, iletinin ne zaman oluşturulduğunu gösteren bir zaman damgası bulunur. Daha fazla bilgi için Etkinlik sinyali yayınlama başlıklı makaleyi inceleyin.

hizmet kalitesi (HK) sinyali
SDV, çeşitli Pub/Sub ve uzak prosedür çağrısı (RPC) iletişim modellerini destekler. İletişimi dinleyen bir hizmet paketi örneği, HK aracısının HK ihlallerini algılamasına olanak tanıyan HK sinyalleri yayınlayabilir. Daha fazla bilgi için Hizmet kalitesi izleme başlıklı makaleyi inceleyin.

hizmet paketi kurtarma izleme
SDV hizmet paketi örnekleri, kilitlenmeleri durumunda yeniden başlatılacak şekilde yapılandırılabilir. Bir örnek başarıyla kurtarılabilir veya kurtarma işlemi başarısız olabilir. HM, hizmet paketi örneğinin kurtarma durumunu izler ve kurtarma hatalarını sanal makine durumu raporunun bir parçası olarak bildirir. Daha fazla bilgi için Hizmet paketi kurtarma izleme başlıklı makaleyi inceleyin.

aracı kilitlenme izleme
Hizmet paketi örneklerinin aksine, SDV aracıları sistemin doğru çalışması için kritik öneme sahiptir. Kurtarma için yapılandırılamazlar ve bu nedenle asla kilitlenmemelidirler. HM, SDV aracılarını izler ve kilitlenmeleri VM durum raporunun bir parçası olarak bildirir. Özel OEM aracıları izlenebilir. Daha fazla bilgi için Aracı kilitlenme izleme başlıklı makaleyi inceleyin.

Sanal makine durum raporu
Sanal makinenin durumunu belirtmek için HM tarafından oluşturulan bir mesaj. Daha fazla bilgi için Sanal makine sağlık raporu başlıklı makaleyi inceleyin.

HM alt sistemiyle çalışma

HM özelliklerini kullanmak için OEM uygulamasının şunları yapması gerekir:

  • HM sistemini yapılandırma bölümünde ayrıntılı olarak açıklandığı şekilde yapılandırma dosyaları sağlayarak durum izleme sistemini yapılandırın.
  • HM çıkışını dinlemek ve uygun işlemi yapmak için OEM tarafından tanımlanan bir HM Listener hizmet paketi kullanın.
  • Durum yapılandırmalarına göre sinyalleri etkin bir şekilde yayınlayan hizmet paketleri geliştirin. Bu yayın, HM'nin sağlık durumunu değerlendirmesine olanak tanır. Daha fazla bilgi için Hizmet paketi geliştirici kılavuzları'na bakın.

HM sistemini yapılandırma

HM ile ilgili tüm yapılandırmalar şu yapılandırma türlerinden birinde bulunur:

  • Genel, sanal makine başına sağlık durumu yapılandırması
  • Paketin tüm örnekleri için durum parametrelerini tanımlayan, hizmet paketi başına durum yapılandırması

Sanal makine başına sağlık yapılandırması

Çalışma zamanında HM aracısı, VM genelinde bir durum yapılandırması bekler: Bu, VMHealth türünde bir textproto dosyasıdır (.textproto uzantılı) ve //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto konumunda tanımlanır. Sanal makine durumu yapılandırması, androidboot.sdv.health_monitor.config_path önyükleme zamanı sistem özelliği kullanılarak belirtilen yolda bulunmalıdır. Alternatif olarak, persist.sdv.health_monitor.config_path sistem özelliğini özel bir yola ayarlayarak bunu çalışma zamanında dinamik olarak yapılandırabilirsiniz. persist.* ayarı, androidboot.* ayarına göre önceliklidir. Yeni yapılandırmanın geçerli olması için cihazı yeniden başlatmanız gerekir.

Sanal makine durumu yapılandırması, aşağıdakileri ayarlamanıza olanak tanır:

  • period_ms aracılığıyla sanal makine durumu raporunun sıklığı. Bu ayarı belirlemek, durum ihlallerinin daha hızlı sinyallenmesi ile HM alt sisteminin performansı arasında bir denge kurmayı gerektirir. 100 ms değerini kullanmanızı öneririz.

  • Hangi aracıların kilitlenme açısından izleneceği (bkz. Aracı kilitlenme izleme).

Yapılandırma dosyası örnekleri //system/software_defined_vehicle/health_monitor/src/prod_configs/ içinde yer alır. Örnek yapılandırma dosyası:

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"
}

Bu örnekte, SDV DT ve RPC aracıları kilitlenme izleme için yapılandırılmış ve sanal makine durumu raporunun 100 ms'de bir yayınlanması için yapılandırılmıştır.

Hizmet paketi başına yapılandırma

Hizmet paketi örneklerinin durumunu izlemek isteğe bağlıdır. Bu özelliği etkinleştirmek için sağlık yapılandırma dosyasını hizmet paketinizin APEX'inde saklayın ve sdv_service_bundles_manifest.textproto içindeki sdv_service_bundle_metadata alanında health_config_path için bir yol tanımlayın. Hizmet paketi manifestleri hakkında daha fazla bilgi için Hizmet paketi meta verileri başlıklı makaleyi inceleyin.

Sağlık yapılandırma dosyası, aşağıdaki türde bir textproto dosyasıdır:

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

Her örnek için hem canlılık sinyali yapılandırmasını hem de hizmet kalitesi (QoS) yapılandırmasını belirtebilirsiniz:

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

Özellik başına yapılandırma hakkında daha fazla bilgi için Aliveness heartbeats monitoring (Canlılık sinyali izleme) ve QoS monitoring (Hizmet kalitesi izleme) başlıklı makaleleri inceleyin.

HM çıkışını dinleme

HM'yi periyodik raporlar veya bir RPC API aracılığıyla dinleyebilirsiniz.

Sanal makine durum raporu

Durum izleme, izlenen öğelerin durumuna ilişkin kısa bilgiler sağlayan yüksek frekanslı periyodik bir sanal makine durumu raporu oluşturur.

VmHealth türünün söz dizimi //system/software_defined_vehicle/health_monitor/catalog/health_topic.proto içinde tanımlanır:

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

OEM tarafından tanımlanan bir HM işleyici hizmet paketi, VMHealth raporlarını dinlemeli ve sistem mimarisinin tamamına bağlı olarak uygun işlemi yapmalıdır. Olası işlemler şunlardır:

  • Sanal makinede teşhis rutinlerini çalıştırın.
  • Sanal makineyi yeniden başlatın.
  • Nedeni belirlemek için bir telemetri kampanyası yayınlayın.
  • Sistemi güncelleyin veya sistem arızalıysa güncellemeyi durdurun.

HM RPC API

Sanal makine durumu raporu, sıklık ve iletim hızı için optimize edilmiş bir yayındır. Sistemin durum durumu hakkında geniş kapsamlı bilgiler sağlar.

HM RPC API'si, HM dinleyicisinin sağlık ihlallerinin kaynağı hakkında ayrıntılı bilgi edinmesine olanak tanır. Arayüz, //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto içinde tanımlanır. Arayüz, kolaylık sağlaması için burada yeniden üretilmiştir:

// 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) {}
}

Özelliklerin ayrıntılı açıklaması

Bu bölümde, HM'nin çeşitli yönleri daha ayrıntılı olarak açıklanmaktadır.

Canlılık sinyali izleme

Bir hizmet paketi örneği için canlılık izleme yapılandırıldığında HM, iş mantığının doğru çalıştığını kanıtlamak için örneğin düzenli olarak sinyal yayınlamasını bekler. Bu izleme, düzenli görevler gerçekleştiren hizmet paketi örnekleri için en uygun seçenektir. Ayrıca, eşzamansız çalışma zamanlarını kullanan paketler, iş parçacığı havuzunun tükenmediğini kanıtlamak için canlılık izlemeyi kullanabilir.

HM aliveness monitoring flow

Şekil 1. HM aliveness monitoring flow.

Yapılandırma

Bir hizmet paketi örneğinde canlılık HB'sini etkinleştirmek için paket yapılandırmasındaki health_config alanına HealthConfiguration örneği ekleyin.

Etkinlik sinyali yapılandırması, bir hizmetin düzenli etkinlik sinyalini değerlendirme ölçütlerini belirleyen önceden belirlenmiş bir parametreler grubunu tanımlar. Hizmet sinyalinin özellikleri bu parametrelerden saparsa sinyal gecikmiş olarak, ilgili hizmet paketi ise sağlıksız olarak sınıflandırılır. Bu durum, optimal olmayan bir çalışma durumuna işaret edebilir.

Bir hizmet paketi, durum yapılandırmasına göre zamanında sinyal gönderdiğinde sağlıklı kabul edilir. Çökme veya yüksek sistem yükü durumunda, kalp atışı eksik olabilir ya da gecikebilir. Bu da hizmet paketinin sağlıksız olarak işaretlenmesine neden olur. Bu durumda, VmHealth raporunda bir ihlal gösterilir.

Hizmet paketi geliştiricileri, hizmet paketinin sağlık yapılandırmasını ilgili APEX meta verilerinde tanımlamalıdır. Sağlık yapılandırması şu ölçütleri tanımlar:

  • Hizmetin başlatılması ile ilk sinyal algılanması arasında izin verilen maksimum başlangıç gecikmesi.

  • SDV hizmet paketinin, hizmet sinyali yayınlama sıklığına karşılık gelen işletme mantığını yürüttüğü dönem.

  • HM'nin hizmet paketini sağlıksız olarak kabul etmeden önce kaçırılacak dönem sayısı.

  • Yürütme süresi, bir SDV hizmet paketinin hizmet sinyali yayınlayabilmesi için iş mantığını yürütmesi gereken süredir.

Hizmet paketi, hizmet sinyali gecikirse durum ihlali oluşturur. Sağlık gözleminin zamanına bağlı olarak iki durum vardır:

  • 1. durum: İlk kalp atışı alınmadı. Hizmet paketi başlangıcı ile gözlem zamanı arasında izin verilen ilk gecikmeden daha uzun bir süre geçmişse hizmet paketi sağlıksız kabul edilir.

  • 2. durum: Kalp atışları zaten alınmıştır. Son sinyal ile gözlem zamanı arasında bir eşik geçmişse hizmet paketi sağlıksız kabul edilir. Bu eşik, raporlama döneminin (dönem sayısıyla çarpılır) ve görevin süresinin toplamı olarak hesaplanır.

Sağlık yapılandırması biçimi //system/software_defined_vehicle/health_monitor/catalog/health_config.proto içinde tanımlanır:

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

Çalışma zamanı ile ilgili dikkat edilmesi gerekenler

Bu bölümde, canlılık sinyallerinin yayınlanması ve izleme için doğru şekilde kaydolma hakkında rehberlik sağlanır.

Canlılık sinyallerini yayınlama

Bir hizmet paketi örneği, zaman damgası içeren bir hizmet sinyali mesajı oluşturur. Genellikle ana iş mantığı yürütüldükten hemen sonra mesajı düzenli olarak oluşturun. Hizmet sinyali, hizmet paketinin etkin olduğunu gösterir.

İzlenecek paket örneği nesnesinin, libhealth_api kitaplığında bulunan ServiceHeartbeat türünde bir yayıncı oluşturması gerekir:

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

Yayın konusunu rastgele seçme HM aracısı, yayını algılamak için mesaj türüne göre keşif özelliğini kullanır.

İlgili hizmet paketi manifestinde bağlantısı verilen durum yapılandırması aracılığıyla canlılık izlemeyi yapılandırırken HM aracısı, HBs'nin örnek on_start rutinini tamamlar tamamlamaz yayınlanmasını bekler. Sistemin başlatılmasının engellenmesini önlemek için on_start kısa tutmanızı öneririz. Bu nedenle, on_start içinde başlatılan eşzamansız bir görevde kalp atışlarını yayınlayın.

Paket geliştiriciler, initial_delay_ms yapılandırma girişini kullanarak ilk kalp atışının beklendiği zamanı özelleştirebilir.

Paket örneği, durdurulana kadar düzenli olarak sinyal yayınlamaya devam etmelidir. Bir örneğin on_stop rutini tamamlandığında durdurulduğu kabul edilir.

Özel kullanım alanı: Kalp atışı izlemeye açıkça kaydolma

Aliveness heartbeats monitoring (Aliveness sinyallerinin izlenmesi) bölümünde açıklanan davranış, yani on_start ile on_stop arasında sinyal beklenmesi implicit aliveness monitoring (örtülü aliveness izleme) olarak adlandırılır. Bu özellik için önerilen kullanım şekli şudur: Paketin iş mantığını basitleştirir ve paketin her zaman izlenmesini sağlar.

Ancak, varsayılan izleme döneminin kısıtlama olduğu bazı kullanım alanları olabilir:

  • Bir hizmet paketi örneği, start ve stop etkinlikleriyle bağlantılı olmayan bir zaman aralığında periyodik olarak çalışan iş mantığı içerir. Canlılık izleme yalnızca bu özel dönemde gerekebilir.
  • HM, askıya alma ve devam ettirme dönemlerinde HB'leri doğru şekilde izler. Bu nedenle, paket on_stop sonrasında izlenmeye devam etmek isteyebilir.
  • Özel OEM aracıları, hizmet paketleri olarak uygulanmayabilir. Bu nedenle, bu cihazlar örtülü canlılık izlemeden yararlanamaz. Ancak bu cihazlar yine de canlılık izleme gerektirebilir.

Bu durumlarda HM, açık kaydı tercih ederek canlılık izlemeye yönelik örtülü kaydı atlamanıza olanak tanır. Açık kaydı kullanmak için bir paket örneğinin, paketin manifestinde söz konusu örnek için HealthConfiguration türünde bir giriş içermeyerek örtülü kaydı devre dışı bırakması gerekir. Ardından, çalışma zamanında paket örneği, //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto içinde tanımlanan RPC API'yi kullanarak izlemeye manuel olarak kaydolmalı ve izlemeden kaydını silmelidir. Kayıt RPC çağrısı başarılı olur olmaz yayınlanan kalp atışları beklenir.

Örnek uygulama için //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/ bölümüne bakın.

Hizmet kalitesi izleme

Hizmet Kalitesi (HK), iletişimin ölçümüdür. HM, gönderilen iletinin çok fazla süre boyunca iletimde kalıp kalmadığını veya aralıklı iletişim durumunda iletilerin seçilen sıklıkta alınıp alınmadığını izler.

SDV, Pub/Sub ve RPC iletişimi için çeşitli seçenekler sunar. Tüm iletişim şemalarının ortak özelliği en az bir dinleyici içermeleridir. HM'nin iletişimi izlemesi için bu dinleme hizmeti paketi örneği, ilgilenilen bir mesaj aldığında özel QoS sinyalleri yayınlamalıdır.

Yapılandırma

Bir iletişimin QoS izlemesini etkinleştirmek için önce QoS sinyalini yayınlayacak iletişim dinleyicisini belirleyin. Ardından, tanımlanan hizmet paketi örneği için QosMonitoringConfiguration eşlemelerine qos_config alanında bir veya daha fazla konu ekleyin. Daha fazla bilgi için Hizmet başına paket yapılandırması başlıklı makaleyi inceleyin.

Konu, HM'nin çalışma zamanında QoS HB'leri beklediği yayın konusunu tanımlayan bir dizedir. Bir dinleme paketi örneği birden fazla iletişime katılabilir ve birden fazla konuda QoS HBs raporlayabilir.

Çalışma zamanında hizmet kalitesi ihlalleri algılanırsa konular, HM dinleyici hizmet paketine geri bildirildiğinden açıklayıcı olmalıdır.

QosMonitoringConfiguration türü, //system/software_defined_vehicle/health_monitor/catalog/health_config.proto içinde tanımlanır:

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

Varsayılan kullanım alanları için her iki HK izleme türünü de zorunlu kılın. Normal sistem yükleri altında sanal makine içi Pub/Sub iletişimi için 30 değerinin qos_latency_threshold_ms olması makuldür.

Çalışma zamanıyla ilgili dikkat edilmesi gereken noktalar

Canlılık HB izlemeye benzer şekilde, iletişim dinleme paketi bir tür kalp atışı yayınlamalıdır. Bu durumda, ilgilenilen mesajlar alındığında iş mantığı yürütülmesinin sonunda değil, QoS HB yayınlanmalıdır.

Bir HK HK'sı, QosHeartbeat türündedir ve //system/software_defined_vehicle/health_monitor/catalog/qos_heartbeat.proto içinde tanımlanır:

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 yayınının kaydedildiği ve kaydının silindiği zaman, doğru izleme için kritik öneme sahiptir. HM, bu iki etkinlik arasında QoS HBs bekler. Mesaj dinleme paketi, izlenen iletişim SDV iletişim yığınına kaydedildiğinde QoS HB yayınını kaydetmelidir. HM, bu işlemi yapmak için stok durumu API'sini kullanabilir. Daha fazla bilgi için Hizmetin kullanılabilirliğini belirleme başlıklı makaleyi inceleyin.

Hizmet paketi kurtarma izleme

Hizmet paketi örneklerinin kurtarılması, düzenleme aracısı yapılandırma dosyalarının bir parçası olarak yapılandırılır. Konuyla ilgili ayrıntılı bilgi için Hizmet paketleri başlıklı makaleyi inceleyin. HM alt sistemi, kurtarma sürecini pasif olarak gözlemler. Bir paket örneğinin kurtarılamadığı tespit edildiğinde VMHealth raporuna bir ihlal eklenir. Diğer HM izleme özelliklerinin aksine, kurtarma izleme zorunludur ve yapılandırılamaz.

Kurtarma için yapılandırılmamış hizmet paketi örneklerinin kilitlenmesi, ilk kilitlenmelerinde sağlık ihlali oluşturur.

Hizmet paketi örneği kurtarma, kalp atışı canlılık izlemeyle entegre olacak şekilde tasarlanmıştır. HM sistemi, paketin kurtarıldığını algıladığında kalp atışlarını değerlendirirken daha hoşgörülüdür. Uygulamada bu esneklik, hizmet paketlerinin kilitlenmeleri durumunda ek izleme, kayıttan çıkarma veya kayıt adımları atmasına gerek olmadığı anlamına gelir.

Aracı kilitlenme izleme

HM, bağlayıcı linkToDeath mekanizmasını kullanarak SDV aracı kilitlenmesi olasılığını tespit eder.

Kilitlenme izlemeyi VM durumu yapılandırmasının bir parçası olarak yapılandırabilirsiniz (bkz. SDV başına örnek (VM) yapılandırması), özellikle monitored_agent tekrarlanan alanı. Bu alan, BinderServiceAgent türünde girişler içermelidir:

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

Temsilci bir bağlayıcı arayüzü gösteriyorsa özel temsilciler de izlenebilir. Özel bir aracıyı izlemek için HM SELinux'a uygun bağlayıcı arayüzünü dinleme izni verin.

ro.boot.sdv.health_monitor.agent_startup_timeout_sec sistem özelliği, HM başlatıldıktan sonra HM'nin aracıların bağlayıcı arayüzlerini kaydetmesini bekleyeceği süreyi geçersiz kılabilir. Özel aracılar tarafından gerekli kılınmadığı sürece üç saniyelik varsayılan süre uygundur.

Hizmet paketi geliştirici kılavuzları

Bu bölümde, önceki bölümlerdeki teorik yaklaşımların aksine, hizmet paketlerindeki HM özelliklerinin nasıl kullanılacağıyla ilgili adım adım kılavuzlar sunulmaktadır. Bu kılavuzların temel alındığı güncel referans örneği, qos_monitoring örneğidir. Pratik bir deneyim için örneğin //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README bölümünü inceleyin.

Hizmet paketine canlılık sinyali izleme ekleme

Bu yöntem, bir hizmet paketinde cihaz sağlığı izlemeyi etkinleştirmenin en doğrudan yoludur:

  1. health_configuration.textproto adlı bir dosyada paket örnekleri için ServiceBundleHealthConfiguration örneği tanımlayın:

    # 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. Yapılandırma dosyasını hizmet paketi APEX'e ekleyin. Android.bp içinde:

    
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. Sağlık yapılandırmasını APEX'te saklayın ve manifest dosyasında health_config_path öğesini ayarlayın:

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

  4. VSIDL tanımında, paketin yayınladığından emin olun com.android.sdv.health.ServiceHeartbeat:

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

  5. Pakete SDV izinleri ekleyerek paketin HB yayınlamasına yetki verin:

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

  6. on_start'dan itibaren kodda düzenli olarak hizmet sinyalleri yayınlayın:

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

Özel kullanım alanı: Açık kayıt

Paketin özel yaşam döngüleri için HB izlemesi gerektirdiği (ör. izlemenin standart STARTED durumundan daha erken başlaması veya daha geç sona ermesi) diğer özel kullanım alanlarında açık kayıt yöntemini kullanabilirsiniz:

  1. VSIDL tanımına bir com.android.sdv.health.HealthMonitorRegistrationService istemcisi ekleyin:

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

  2. Aliveness HB registration RPC'yi kullanmak için SDV izni ekleyin:

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

  3. Örneğin, on_start veya new'de RPC aracılığıyla HM'ye kaydolun:

    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. HBS'leri yayınlayın.

  5. Artık gerekmediğinde izlemeyi devre dışı bırakma:

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

İletişime HK izleme ekleme

  1. Hizmet paketi örneğinin, VSIDL kataloğunda fog-light-status adlı bir konuya abone olduğunu doğrulayın:

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

    Mesaj biçimi aşağıdaki gibidir:

    package com.android.sdv.sample.oem.health.qos_monitoring;
import "google/protobuf/timestamp.proto";

message QosMonitoredFogLightStatus {
  // arbitrary fields related to business logic
  int32 status = 1;

  // A QoS-monitored message must include a timestamp field
  .google.protobuf.Timestamp timestamp = 2;
}

  2. Kalite hizmeti izleme içeren bir health_configuration.textproto dosyasındaki paket örnekleri için bir ServiceBundleHealthConfiguration örneği tanımlayın:

    # 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 alanında seçilen konu, QoS HB'lerinin bu konuda yayınlanacağını gösterir. Bu sayede fog-light-status adlı bir konu izlenebilir.

  3. Yapılandırma dosyasını hizmet paketi APEX'e ekleyin. Android.bp içinde:

    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. Sağlık yapılandırmasını APEX'te saklayın ve manifestte health_config_path değerini ayarlayın:

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

  5. VSIDL tanımınızda paketin com.android.sdv.health.QosHeartbeat yayıncısı olduğundan emin olun:

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

  6. Paketin, QoS HBs yayınlamaya yetkili olması için pakete SDV izinleri ekleyin:

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

  7. Kalite Hizmeti HB yayını yalnızca izlenen iletişim kaydedildiğinde kaydedilir. libsdv_mw_clientlib adresindeki stok durumu API'sini kullanın:

    // 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. Her ileti alındığında QoS HB'leri yayınlayın:

    // ...
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. HK izlemeyi durdurmak için yayıncı nesnesini bırakın:

    // ...
drop(qos_hb_pub);

Sağlık durumu izlemede hata ayıklama

Hata ayıklama ve sisteme genel bakış amacıyla, sanal makinenin durum izleme durumunu izlemek için dumpsys aracını kullanın:

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

Rapor, sanal makine durumu raporlama yapılandırmasını, paket yapılandırmasını ve izleme durumunu ayrıntılı olarak açıklar. Aşağıda bu tür bir rapora ilişkin örnek verilmiştir:

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

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