Pemantauan kesehatan

Health Monitor (HM) adalah agen SDV yang berjalan di setiap virtual machine (VM) untuk melacak status paket layanan, menentukan kondisi VM, dan membuat laporan kondisi VM secara berkala.

Paket layanan yang ditentukan OEM harus memantau berbagai sinyal kesehatan yang dilaporkan oleh HM, dan berdasarkan data tersebut, melakukan tindakan pemulihan. Misalnya, instance SDV dengan paket layanan yang error mungkin perlu dimulai ulang atau diupdate.

Anda dapat mengonfigurasi agen HM untuk melacak hal berikut:

• Status keaktifan entitas yang melakukan tugas berkala, dengan memantau detak jantung keaktifan. Pemantauan ini dapat dikonfigurasi untuk instance paket layanan dan agen OEM kustom.
  • Status pemulihan instance paket layanan. Di SDV 2.0, Anda dapat mengonfigurasi paket layanan untuk memulai ulang secara otomatis saat terjadi error. HM memberikan sinyal untuk memantau proses pemulihan ini.
  • QoS Komunikasi
• Status aktif agen kustom SDV dan OEM

Sebagai referensi, katalog VSIDL lengkap, termasuk definisi proto, tersedia di //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl.

Terminologi

Istilah ini digunakan di halaman ini.

Bekerja dengan subsistem HM

Untuk menggunakan fitur HM, penerapan OEM harus:

• Konfigurasi sistem pemantauan kondisi dengan memberikan file konfigurasi seperti yang dijelaskan dalam Mengonfigurasi sistem HM.
• Gunakan paket layanan HM Listener yang ditentukan OEM untuk memproses output HM dan melakukan tindakan yang sesuai.
• Mengembangkan paket layanan yang secara aktif memublikasikan sinyal, sesuai dengan konfigurasi kesehatannya. Publikasi ini memungkinkan HM menilai kondisi kesehatannya. Untuk mengetahui informasi selengkapnya, lihat Panduan developer paket layanan.

Mengonfigurasi sistem HM

Konfigurasi terkait HM apa pun berada di salah satu jenis konfigurasi berikut:

• Konfigurasi Health global per VM
• Konfigurasi kesehatan paket per layanan, yang menentukan parameter kesehatan untuk semua instance paket

Konfigurasi kesehatan per VM

Saat runtime, agen HM mengharapkan konfigurasi kesehatan di seluruh VM: ini adalah file textproto (dengan ekstensi .textproto) berjenis VMHealth yang ditentukan di //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto. Konfigurasi VM Health harus berada di jalur yang ditentukan menggunakan properti sistem waktu boot androidboot.sdv.health_monitor.config_path. Atau, Anda dapat mengonfigurasi ini secara dinamis saat runtime dengan menetapkan properti sistem persist.sdv.health_monitor.config_path ke jalur kustom. Setelan persist.* lebih diutamakan daripada setelan androidboot.*. Anda harus me-reboot perangkat agar konfigurasi baru diterapkan.

Konfigurasi kondisi VM memungkinkan Anda menetapkan hal berikut:

• Periodisitas laporan kesehatan VM melalui period_ms. Menyetelnya adalah trade-off antara pensinyalan yang lebih cepat bahwa pelanggaran kesehatan terdeteksi, dan performa subsistem HM. Sebaiknya tetapkan nilai 100 md.

• Agen mana yang akan dipantau errornya (lihat Pemantauan error agen).

Contoh file konfigurasi ada di //system/software_defined_vehicle/health_monitor/src/prod_configs/. Berikut adalah contoh file konfigurasi:

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

Dalam contoh ini, agen SDV DT dan RPC dikonfigurasi untuk pemantauan error, dan laporan kesehatan VM dikonfigurasi untuk dipublikasikan setiap 100 md.

Konfigurasi per paket layanan

Pemantauan kondisi instance paket layanan bersifat opsional. Untuk ikut serta, simpan file konfigurasi kesehatan di APEX paket layanan Anda dan tentukan jalur ke file tersebut di kolom health_config_path dari sdv_service_bundle_metadata di sdv_service_bundles_manifest.textproto. Untuk mengetahui informasi selengkapnya tentang manifes paket layanan, lihat Metadata paket layanan.

File konfigurasi kesehatan adalah file textproto dari jenis berikut:

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

Untuk setiap instance, Anda dapat menentukan konfigurasi detak jantung keaktifan dan konfigurasi 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;
}

Untuk mengetahui informasi selengkapnya tentang konfigurasi per fitur, lihat Pemantauan detak jantung keaktifan dan Pemantauan QoS.

Mendengarkan output HM

Anda dapat mendengarkan HM melalui laporan berkala atau RPC API.

Laporan kesehatan VM

Pemantauan kondisi menghasilkan laporan kondisi VM berkala dengan frekuensi tinggi, yang memberikan informasi ringkas tentang status kondisi entitas yang dipantau.

Sintaksis jenis VmHealth ditentukan dalam //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;
}

Paket layanan pemroses HM yang ditentukan OEM harus memproses laporan VMHealth dan mengambil tindakan yang sesuai, bergantung pada arsitektur sistem yang lengkap. Tindakan yang dapat dilakukan meliputi:

• Jalankan rutin diagnostik di VM.
• Mulai ulang VM.
• Jalankan kampanye telemetri untuk menentukan penyebabnya.
• Update sistem atau hentikan update jika sistem tidak berfungsi dengan baik.

HM RPC API

Laporan kondisi VM adalah publikasi yang dioptimalkan untuk frekuensi dan kecepatan transmisi, yang memberikan informasi luas tentang status kondisi sistem.

HM RPC API memungkinkan pendengar HM mendapatkan informasi mendetail tentang sumber pelanggaran kesehatan. Antarmuka ditentukan dalam //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto. Antarmuka direproduksi di sini untuk memudahkan:

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

Deskripsi mendetail tentang fitur

Bagian ini menjelaskan berbagai aspek HM secara lebih mendetail.

Pemantauan detak jantung keaktifan

Saat pemantauan keaktifan dikonfigurasi untuk instance paket layanan, HM mengharapkan instance memublikasikan detak jantung berkala untuk membuktikan bahwa logika bisnis beroperasi dengan benar. Pemantauan ini paling cocok untuk instance paket layanan yang melakukan tugas berkala. Selain itu, paket yang menggunakan runtime asinkron dapat menggunakan pemantauan keaktifan untuk membuktikan bahwa kumpulan thread tidak habis.

Gambar 1. Alur pemantauan keaktifan HM.

Konfigurasi

Untuk mengaktifkan HB keaktifan pada instance paket layanan, tambahkan instance HealthConfiguration ke kolom health_config dalam konfigurasi paket.

Konfigurasi detak jantung keaktifan menentukan serangkaian parameter yang telah ditentukan sebelumnya yang menetapkan kriteria untuk menilai sinyal detak jantung berkala layanan. Jika karakteristik detak jantung layanan menyimpang dari parameter ini, detak jantung diklasifikasikan sebagai tertunda dan paket layanan yang sesuai sebagai tidak sehat, yang mungkin menunjukkan status operasional yang tidak optimal.

Paket layanan dianggap responsif jika melaporkan detak jantung tepat waktu sesuai dengan konfigurasi kesehatannya. Jika terjadi error atau beban sistem yang tinggi, detak jantung mungkin hilang atau tertunda, sehingga menyebabkan paket layanan ditandai sebagai tidak sehat. Dalam hal ini, pelanggaran akan muncul dalam laporan VmHealth.

Developer paket layanan harus menentukan konfigurasi kondisi layanan dari paket layanan dalam metadata APEX yang sesuai. Konfigurasi kesehatan menentukan kriteria berikut:

• Penundaan awal maksimum yang diizinkan antara mulai layanan dan deteksi detak jantung pertama.

• Periode saat paket layanan SDV menjalankan logika bisnis, yang sesuai dengan periodisitas memublikasikan detak jantung layanan.

• Jumlah periode yang harus dilewatkan sebelum HM menganggap paket layanan tidak responsif.

• Waktu eksekusi adalah jumlah waktu yang diperlukan paket layanan SDV untuk melakukan logika bisnisnya sebelum dapat memublikasikan detak jantung layanan.

Paket layanan akan menghasilkan pelanggaran kondisi jika detak jantung layanan tertunda. Ada dua kasus berdasarkan waktu pengamatan kesehatan:

• Kasus 1: Detak jantung awal tidak diterima. Jika lebih dari penundaan awal yang diizinkan telah berlalu antara dimulainya paket layanan dan waktu pengamatan, paket layanan dianggap tidak sehat.

• Kasus 2: Detak jantung sudah diterima. Jika batas waktu telah berlalu antara detak jantung terakhir dan waktu pengamatan, paket layanan dianggap tidak responsif. Nilai minimum ini dihitung sebagai jumlah periode pelaporan (dikalikan dengan jumlah periode) dan durasi tugas.

Format konfigurasi kesehatan ditentukan dalam //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;
}

Pertimbangan waktu proses

Bagian ini memberikan panduan untuk memublikasikan detak jantung keaktifan dan mendaftar dengan benar untuk pemantauan.

Memublikasikan detak jantung keaktifan

Instance paket layanan menghasilkan pesan detak jantung layanan yang menyertakan stempel waktu. Buat pesan secara rutin, biasanya langsung setelah logika bisnis utama dieksekusi. Detak jantung layanan menunjukkan bahwa paket layanan aktif.

Objek instance paket yang akan dipantau perlu membuat penerbit jenis ServiceHeartbeat, yang tersedia di library libhealth_api:

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

Memilih topik publikasi secara acak. Agen HM menggunakan penemuan berdasarkan jenis pesan untuk mendeteksi publikasi.

Saat mengonfigurasi pemantauan keaktifan melalui konfigurasi health yang ditautkan dalam manifest paket layanan yang sesuai, agen HM mengharapkan HB dipublikasikan segera setelah instance menyelesaikan rutin on_start-nya. Sebaiknya on_start tetap singkat untuk menghindari pemblokiran startup sistem, jadi publikasikan detak jantung dalam tugas asinkron yang dimulai di on_start.

Developer paket dapat menyesuaikan waktu saat detak jantung pertama diharapkan terjadi dengan menggunakan entri konfigurasi initial_delay_ms.

Instance paket harus terus memublikasikan detak jantung hingga dihentikan. Instance dianggap dihentikan saat rutin on_stop-nya telah selesai.

Kasus penggunaan khusus: Mendaftar secara eksplisit ke pemantauan detak jantung

Perilaku yang dijelaskan dalam Pemantauan detak jantung keaktifan, dengan detak jantung diharapkan terjadi antara on_start dan on_stop, disebut pemantauan keaktifan implisit. Cara yang direkomendasikan untuk menggunakan fitur ini adalah: menyederhanakan logika bisnis bundle dan memastikan bundle selalu dipantau.

Namun, mungkin ada beberapa kasus penggunaan yang membatasi periode pemantauan default:

• Instance paket layanan berisi logika bisnis yang bersifat periodik dalam interval waktu yang tidak terkait dengan peristiwa start dan stop. Pemantauan keaktifan mungkin hanya diperlukan dalam periode kustom ini.
• HM secara akurat melacak HB di seluruh periode penangguhan dan kelanjutan. Oleh karena itu, paket mungkin ingin terus dipantau setelah on_stop.
• Agen OEM kustom mungkin tidak diimplementasikan sebagai paket layanan. Oleh karena itu, mereka tidak dapat memanfaatkan pemantauan keaktifan implisit. Namun, mereka mungkin masih memerlukan pemantauan keaktifan.

Untuk kasus ini, HM memungkinkan Anda melewati pendaftaran implisit ke pemantauan keaktifan untuk mendukung pendaftaran eksplisit. Untuk menggunakan pendaftaran eksplisit, instance paket harus memilih tidak ikut pendaftaran implisit dengan tidak menyertakan entri jenis HealthConfiguration untuk instance tertentu dalam manifes paket. Kemudian, saat runtime, instance bundle harus menggunakan RPC API yang ditentukan di //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto untuk mendaftar dan membatalkan pendaftaran dari pemantauan secara manual. Detak jantung yang dipublikasikan diharapkan segera setelah panggilan RPC pendaftaran berhasil.

Untuk contoh implementasi, lihat //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/.

Pemantauan QoS

Kualitas Layanan (QoS) adalah ukuran komunikasi. HM memantau apakah pesan yang dikirim menghabiskan terlalu banyak waktu dalam perjalanan, atau dalam kasus komunikasi berkala, apakah pesan tidak diterima dengan frekuensi yang dipilih.

SDV menyediakan beberapa jenis komunikasi Pub/Sub dan RPC. Penyebut umumnya adalah semua skema komunikasi berisi setidaknya satu pendengar. Agar HM dapat memantau komunikasi, instance paket layanan pendengar ini harus memublikasikan detak jantung QoS khusus setiap kali menerima pesan yang menarik.

Konfigurasi

Untuk mengaktifkan pemantauan QoS komunikasi, identifikasi terlebih dahulu pendengar komunikasi yang akan memublikasikan detak jantung QoS. Kemudian, untuk instance paket layanan yang diidentifikasi, tambahkan satu atau beberapa topik ke pemetaan QosMonitoringConfiguration di kolom qos_config. Untuk mengetahui informasi selengkapnya, lihat Konfigurasi paket per layanan.

topic adalah string yang menentukan topik publikasi tempat HM mengharapkan HB QoS saat runtime. Instance paket mendengarkan dapat berpartisipasi dalam beberapa komunikasi dan dapat melaporkan HB QoS pada beberapa topik.

Topik harus deskriptif, karena dilaporkan kembali ke paket layanan pendengar HM jika pelanggaran QoS terdeteksi saat runtime.

Jenis QosMonitoringConfiguration ditentukan di //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;
}

Untuk kasus penggunaan default, terapkan kedua jenis pemantauan QoS. qos_latency_threshold_ms dari 30 cukup wajar untuk komunikasi Pub/Sub dalam VM di bawah beban sistem normal.

Pertimbangan waktu proses

Mirip dengan pemantauan HB keaktifan, paket pemantauan komunikasi diharapkan memublikasikan jenis detak jantung. Dalam hal ini, HB QoS harus dipublikasikan setiap kali pesan yang relevan diterima, bukan di akhir eksekusi logika bisnis.

HB QoS berjenis QosHeartbeat, yang ditentukan dalam //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;
}

Waktu pendaftaran dan pembatalan pendaftaran publikasi HB QoS sangat penting untuk pemantauan yang akurat. HM mengharapkan HB QoS di antara kedua peristiwa ini. Paket pemantauan pesan harus mendaftarkan publikasi HB QoS saat komunikasi yang dipantau didaftarkan dengan stack komunikasi SDV. HM dapat menggunakan API ketersediaan untuk melakukannya. Untuk mengetahui informasi selengkapnya, lihat Menentukan ketersediaan layanan.

Pemantauan pemulihan paket layanan

Pemulihan instance paket layanan dikonfigurasi sebagai bagian dari file konfigurasi agen orkestrasi. Untuk pembahasan lengkap tentang topik ini, lihat Paket layanan. Subsistem HM secara pasif mengamati proses pemulihan. Jika kegagalan memulihkan instance paket terdeteksi, pelanggaran akan ditambahkan ke laporan VMHealth. Berbeda dengan kemampuan pemantauan HM lainnya, pemantauan pemulihan bersifat wajib dan tidak dapat dikonfigurasi.

Error pada instance paket layanan yang tidak dikonfigurasi untuk pemulihan akan menghasilkan pelanggaran kondisi sistem pada error pertamanya.

Pemulihan instance paket layanan dirancang untuk terintegrasi dengan pemantauan keaktifan detak jantung. Sistem HM lebih toleran saat menilai detak jantung saat mendeteksi bahwa paket sedang dipulihkan. Dalam praktiknya, kelonggaran ini berarti bahwa paket layanan tidak perlu melakukan langkah-langkah tambahan untuk memantau pembatalan pendaftaran atau pendaftaran jika terjadi error.

Pemantauan error agen

HM mendeteksi potensi error agen SDV menggunakan mekanisme linkToDeath binder.

Anda dapat mengonfigurasi pemantauan error sebagai bagian dari konfigurasi respons VM (lihat Konfigurasi per instance SDV (VM)), khususnya kolom berulang monitored_agent. Kolom ini harus berisi entri jenis 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;
}

Agen kustom juga dapat dipantau jika agen mengekspos antarmuka binder. Untuk memantau agen kustom, berikan izin SELinux HM untuk memproses antarmuka binder yang sesuai.

Properti sistem ro.boot.sdv.health_monitor.agent_startup_timeout_sec dapat menggantikan durasi HM menunggu agen mendaftarkan antarmuka binder mereka setelah HM dimulai. Kecuali jika diperlukan oleh agen kustom, nilai default tiga detik sudah sesuai.

Panduan developer paket layanan

Bagian ini memberikan panduan langkah demi langkah tentang cara menggunakan fitur HM dari paket layanan, berbeda dengan pembahasan teoretis di bagian sebelumnya. Contoh referensi terbaru, yang menjadi dasar panduan ini, adalah contoh qos_monitoring. Ikuti contoh //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README untuk mendapatkan pengalaman praktis.

Menambahkan pemantauan detak jantung keaktifan ke paket layanan

Metode ini adalah cara paling langsung untuk mengaktifkan pemantauan kondisi untuk paket layanan:

1. Tentukan instance ServiceBundleHealthConfiguration untuk instance paket dalam file bernama 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. Tambahkan file konfigurasi ke APEX bundle layanan. Di 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. Simpan konfigurasi kesehatan di APEX dan tetapkan health_config_path dalam manifes:

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

4. Dalam definisi VSIDL, pastikan paket memublikasikan com.android.sdv.health.ServiceHeartbeat:

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

5. Tambahkan izin SDV ke paket agar paket diizinkan untuk memublikasikan HB:

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

6. Publikasikan detak jantung layanan secara berkala dalam kode, dimulai di 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()
       })?;
     }
   }
   

Kasus penggunaan khusus: Pendaftaran eksplisit

Untuk kasus penggunaan khusus lainnya, saat paket memerlukan pemantauan HB untuk siklus proses kustom (misalnya, pemantauan dimulai lebih awal atau berakhir lebih lambat daripada status STARTED standar), Anda dapat menggunakan metode pendaftaran eksplisit:

1. Dalam definisi VSIDL, tambahkan klien 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. Tambahkan izin SDV untuk menggunakan RPC pendaftaran HB keaktifan:

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

3. Mendaftar ke HM melalui RPC, misalnya, di on_start atau 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. Publikasikan HB.

5. Membatalkan pendaftaran dari pemantauan jika tidak lagi diperlukan:

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

Menambahkan pemantauan QoS ke komunikasi

1. Pastikan instance paket layanan adalah pelanggan topik bernama fog-light-status di katalog VSIDL:

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

   Format pesannya adalah sebagai berikut:

   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. Tentukan instance ServiceBundleHealthConfiguration untuk instance paket dalam file health_configuration.textproto yang mencakup pemantauan 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 }
       }
     }
   }
   

   Topik yang dipilih di kolom key menunjukkan bahwa HB QoS akan dipublikasikan di topik ini, sehingga memungkinkan pemantauan topik yang disebut fog-light-status.

3. Tambahkan file konfigurasi ke APEX bundle layanan. Di 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. Simpan konfigurasi kesehatan di APEX dan tetapkan health_config_path dalam manifes:

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

5. Dalam definisi VSIDL, pastikan paket adalah penayang 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. Tambahkan izin SDV ke paket agar paket diizinkan untuk memublikasikan HB QoS:

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

7. Mendaftarkan publikasi HB QoS hanya saat komunikasi yang dipantau didaftarkan. Gunakan API ketersediaan dari 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. Memublikasikan HB QoS setiap kali pesan diterima:

   // ...
   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. Untuk menghentikan pemantauan QoS, hapus objek penerbit:

   // ...
   drop(qos_hb_pub);
   

Men-debug pemantauan kondisi

Untuk tujuan debug dan ringkasan sistem, gunakan alat dumpsys untuk memantau status pemantauan kondisi VM:

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

Laporan ini menjelaskan konfigurasi pelaporan kondisi VM, konfigurasi paket, dan status pemantauan. Berikut adalah contoh laporan tersebut:

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

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