Monitor stanu (HM) to agent SDV, który działa na każdej maszynie wirtualnej, aby śledzić stan pakietów usług, określać stan maszyny wirtualnej i okresowo generować raport o stanie maszyny wirtualnej.
Zdefiniowane przez producenta OEM pakiety usług muszą nasłuchiwać różnych sygnałów dotyczących stanu zdrowia zgłaszanych przez moduł HM i na podstawie tych danych podejmować działania naprawcze. Na przykład instancja SDV z pakietami usług, które ulegają awarii, może wymagać ponownego uruchomienia lub aktualizacji.
Agenta HM możesz skonfigurować tak, aby śledził te elementy:
- Stan aktywności jednostek wykonujących zadania okresowe poprzez monitorowanie pakietów podtrzymujących aktywność. Monitorowanie można skonfigurować zarówno w przypadku instancji pakietu usług, jak i niestandardowych agentów OEM.
- Stan odzyskiwania instancji pakietu usług. W SDV 2.0 możesz skonfigurować pakiety usług tak, aby w przypadku awarii automatycznie się ponownie uruchamiały. HM wysyła sygnały, które umożliwiają monitorowanie tego procesu odzyskiwania.
- Jakość usługi komunikacji
- Aktywność SDV i niestandardowych agentów OEM
Pełny katalog VSIDL, w tym definicje protokołów, znajdziesz na stronie //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl.
Terminologia
Te terminy są używane na tej stronie.
Korzystanie z podsystemu HM
Aby korzystać z funkcji HM, implementacja OEM musi:
- Skonfiguruj system monitorowania stanu, podając pliki konfiguracyjne zgodnie z opisem w sekcji Konfigurowanie systemu HM.
- Użyj zdefiniowanego przez producenta pakietu usług HM Listener, aby nasłuchiwać danych wyjściowych HM i podejmować odpowiednie działania.
- Opracowywanie pakietów usług, które aktywnie publikują sygnały zgodnie z konfiguracją stanu. Ta publikacja umożliwia osobie z HM ocenę stanu zdrowia. Więcej informacji znajdziesz w przewodnikach dla programistów dotyczących pakietów usług.
Konfigurowanie systemu HM
Każda konfiguracja związana z HM należy do jednego z tych typów:
- Globalna konfiguracja stanu zdrowia na maszynę wirtualną
- Konfiguracja stanu pakietu usług, która określa parametry stanu wszystkich instancji pakietu.
Konfiguracja stanu na maszynę wirtualną
W czasie działania agent HM oczekuje konfiguracji stanu w całej maszynie wirtualnej: jest to plik textproto (z rozszerzeniem .textproto) typu VMHealth zdefiniowany w //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto.
Konfiguracja stanu maszyny wirtualnej powinna znajdować się w ścieżce określonej za pomocą właściwości systemu czasu rozruchu androidboot.sdv.health_monitor.config_path.
Możesz też skonfigurować to dynamicznie w czasie działania, ustawiając właściwość systemową persist.sdv.health_monitor.config_path na ścieżkę niestandardową. Ustawienie persist.* ma pierwszeństwo przed ustawieniem androidboot.*. Aby nowa konfiguracja zaczęła obowiązywać, musisz ponownie uruchomić urządzenie.
Konfiguracja stanu maszyny wirtualnej umożliwia ustawienie tych opcji:
Częstotliwość raportu o stanie maszyny wirtualnej za pomocą
period_ms. Ustawienie tej wartości to kompromis między szybszym sygnalizowaniem wykrycia naruszeń stanu a wydajnością podsystemu HM. Zalecamy wartość 100 ms.Których agentów należy monitorować pod kątem awarii (patrz Monitorowanie awarii agentów).
Przykłady plików konfiguracji znajdziesz w //system/software_defined_vehicle/health_monitor/src/prod_configs/. Oto przykładowy plik konfiguracji:
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"
}
W tym przykładzie agenci SDV DT i RPC są skonfigurowani do monitorowania awarii, a raport o stanie maszyny wirtualnej jest skonfigurowany tak, aby był publikowany co 100 ms.
Konfiguracja pakietu usług
Monitorowanie stanu instancji pakietu usług jest opcjonalne. Aby włączyć tę funkcję, zapisz plik konfiguracji stanu w pakiecie APEX usługi i zdefiniuj ścieżkę do niego w polu health_config_path w sdv_service_bundle_metadata w sdv_service_bundles_manifest.textproto. Więcej informacji o manifestach pakietów usług znajdziesz w artykule Metadane pakietu usług.
Plik konfiguracji stanu to plik textproto tego typu:
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;
}
W przypadku każdej instancji możesz określić konfigurację sygnału życia i konfigurację jakości usługi:
// 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;
}
Więcej informacji o konfiguracji poszczególnych funkcji znajdziesz w artykułach Monitorowanie sygnałów o aktywności i Monitorowanie jakości usług.
Odsłuchaj wynik HM
Możesz słuchać HM za pomocą okresowych raportów lub interfejsu RPC API.
Raport o stanie maszyny wirtualnej
Monitorowanie stanu generuje okresowy raport o stanie maszyny wirtualnej o wysokiej częstotliwości, który zawiera zwięzłe informacje o stanie monitorowanych jednostek.
Składnia typu VmHealth jest zdefiniowana w //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;
}
Zdefiniowany przez producenta OEM pakiet usług detektora HM powinien nasłuchiwać raportów VMHealth i podejmować odpowiednie działania w zależności od pełnej architektury systemu.
Możliwe działania:
- Uruchom procedury diagnostyczne na maszynie wirtualnej.
- Uruchom ponownie maszynę wirtualną.
- Uruchom kampanię telemetryczną, aby określić przyczynę.
- Zaktualizuj system lub zatrzymaj aktualizację, jeśli system działa nieprawidłowo.
HM RPC API
Raport o stanie maszyny wirtualnej to publikacja zoptymalizowana pod kątem częstotliwości i szybkości transmisji, która zawiera ogólne informacje o stanie systemu.
Interfejs HM RPC API umożliwia odbiornikowi HM uzyskiwanie szczegółowych informacji o źródle naruszeń zasad dotyczących zdrowia. Interfejs jest zdefiniowany w //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto.
Interfejs został tu odtworzony dla wygody użytkowników:
// 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) {}
}
Szczegółowy opis funkcji
W tej sekcji znajdziesz bardziej szczegółowe informacje o różnych aspektach HM.
Monitorowanie sygnałów o aktywności
Gdy monitorowanie aktywności jest skonfigurowane dla instancji pakietu usług, HM oczekuje, że instancja będzie okresowo publikować sygnały aktywności, aby potwierdzić, że logika biznesowa działa prawidłowo. Ten rodzaj monitorowania najlepiej sprawdza się w przypadku instancji pakietów usług, które wykonują okresowe zadania. Dodatkowo pakiety korzystające z asynchronicznych środowisk wykonawczych mogą używać monitorowania aktywności, aby udowodnić, że pula wątków nie jest wyczerpana.
Rysunek 1. Proces monitorowania aktywności HM.
Konfiguracja
Aby włączyć sygnał aktywności w instancji pakietu usług, dodaj instancję HealthConfiguration do pola health_config w konfiguracji pakietu.
Konfiguracja sygnału o aktywności określa z góry zestaw parametrów, które stanowią kryteria oceny okresowego sygnału o aktywności usługi. Jeśli charakterystyka sygnału o stanie usługi odbiega od tych parametrów, sygnał jest klasyfikowany jako opóźniony, a odpowiedni pakiet usług jako nieprawidłowy, co może wskazywać na nieoptymalny stan operacyjny.
Pakiet usług jest uznawany za działający prawidłowo, gdy zgłasza sygnały w odpowiednim czasie zgodnie z konfiguracją stanu. W przypadku awarii lub dużego obciążenia systemu sygnał może być nieobecny lub opóźniony, co spowoduje oznaczenie pakietu usług jako nieprawidłowego. W takim przypadku naruszenie pojawi się w raporcie VmHealth.
Deweloperzy pakietów usług powinni zdefiniować konfigurację stanu pakietu usług w odpowiednich metadanych APEX. Konfiguracja stanu określa te kryteria:
Maksymalne początkowe opóźnienie między uruchomieniem usługi a wykryciem pierwszego sygnału.
Okres, w którym pakiet usług SDV wykonuje logikę biznesową, co odpowiada okresowi publikowania sygnału o działaniu usługi.
Liczba okresów, które muszą zostać pominięte, zanim HM uzna pakiet usług za nieprawidłowy.
Czas wykonania to czas, którego pakiet usług SDV potrzebuje na wykonanie logiki biznesowej, zanim będzie mógł opublikować sygnał o stanie usługi.
Pakiet usług generuje naruszenie stanu, jeśli sygnał stanu usługi jest opóźniony. W zależności od czasu obserwacji stanu zdrowia występują 2 przypadki:
Przypadek 1. Nie otrzymano początkowego sygnału. Jeśli od rozpoczęcia pakietu usług do momentu obserwacji upłynął czas dłuższy niż dopuszczalne opóźnienie początkowe, pakiet usług jest uznawany za nieprawidłowy.
Przypadek 2. Sygnały już zostały odebrane. Jeśli od ostatniego sygnału do momentu obserwacji upłynął próg, pakiet usług jest uznawany za nieprawidłowy. Ten próg jest obliczany jako suma okresu raportowania (pomnożonego przez liczbę okresów) i czasu trwania zadania.
Format konfiguracji stanu jest zdefiniowany w //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;
}
Kwestie związane z czasem działania
W tej sekcji znajdziesz wskazówki dotyczące publikowania sygnałów aktywności i prawidłowej rejestracji na potrzeby monitorowania.
Publikowanie pakietów podtrzymujących
Instancja pakietu usług generuje wiadomość sygnału aktywności usługi, która zawiera sygnaturę czasową. Regularnie generuj wiadomość, zwykle bezpośrednio po wykonaniu głównej logiki biznesowej. Sygnał aktywności usługi wskazuje, że pakiet usług jest aktywny.
Obiekt instancji pakietu, który ma być monitorowany, musi utworzyć wydawcę typu ServiceHeartbeat, który jest dostępny w bibliotece libhealth_api:
message ServiceHeartbeat {
// Required.
// The timestamp.
.google.protobuf.Timestamp timestamp = 1;
}
Wybierz temat publikacji w sposób dowolny. Agent HM wykrywa publikację za pomocą wykrywania według typu wiadomości.
Podczas konfigurowania monitorowania aktywności za pomocą konfiguracji stanu, która jest połączona z odpowiednim manifestem pakietu usług, agent HM oczekuje, że sygnały HB będą publikowane natychmiast po zakończeniu przez instancję procedury on_start. Zalecamy, aby czas on_start był krótki, aby uniknąć blokowania uruchamiania systemu. Dlatego publikuj sygnały w zadaniu asynchronicznym rozpoczętym w on_start.
Deweloperzy pakietów mogą dostosować czas, w którym oczekiwane jest pierwsze wysłanie sygnału, za pomocą wpisu konfiguracyjnego initial_delay_ms.
Instancja pakietu powinna nadal publikować sygnały do momentu zatrzymania. Instancja jest uważana za zatrzymaną, gdy zakończy się jej procedura on_stop.
Specjalny przypadek użycia: rejestracja w monitorowaniu sygnału o stanie
Zachowanie opisane w sekcji Monitorowanie sygnałów o aktywności, w której sygnały o aktywności
są oczekiwane w zakresie od on_start do on_stop, nazywa się niejawnym monitorowaniem aktywności. Jest to zalecany sposób korzystania z tej funkcji: upraszcza logikę biznesową pakietu i zapewnia, że pakiet jest zawsze monitorowany.
W niektórych przypadkach domyślny okres monitorowania może być jednak ograniczeniem:
- Instancja pakietu usług zawiera logikę biznesową, która jest okresowa w przedziale czasu niepowiązanym ze zdarzeniami
startistop. Monitorowanie aktywności może być potrzebne tylko w tym niestandardowym okresie. - HM dokładnie śledzi HBs w okresach zawieszenia i wznowienia. Dlatego pakiet może być nadal monitorowany po dacie
on_stop. - Agenci OEM mogą nie być zaimplementowani jako pakiety usług. Nie mogą więc korzystać z niejawnego monitorowania aktywności. Mogą jednak nadal wymagać monitorowania aktywności.
W takich przypadkach HM umożliwia pominięcie rejestracji domyślnej na potrzeby monitorowania aktywności na rzecz rejestracji jawnej. Aby używać rejestracji jawnej, instancja pakietu musi zrezygnować z rejestracji niejawnej, nie uwzględniając w pliku manifestu pakietu wpisu typu HealthConfiguration dla danej instancji. Następnie w czasie działania instancja pakietu powinna używać interfejsu RPC API zdefiniowanego w //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto, aby ręcznie rejestrować się w monitorowaniu i wyrejestrowywać z niego. Opublikowane sygnały są oczekiwane natychmiast po pomyślnym zakończeniu wywołania RPC rejestracji.
Przykładową implementację znajdziesz w sekcji //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/.
Monitorowanie jakości usług
Jakość usługi (QoS) to pomiar komunikacji. Moduł HM sprawdza, czy wysłana wiadomość nie jest zbyt długo w trakcie przesyłania, a w przypadku komunikacji okresowej – czy wiadomości nie są odbierane z wybraną częstotliwością.
SDV udostępnia kilka wersji komunikacji Pub/Sub i RPC. Wspólnym mianownikiem jest to, że wszystkie schematy komunikacji zawierają co najmniej 1 odbiorcę. Aby HM mógł monitorować komunikację, ta instancja pakietu usługi nasłuchiwania musi publikować specjalne sygnały QoS, gdy tylko otrzyma interesującą wiadomość.
Konfiguracja
Aby włączyć monitorowanie jakości usługi w przypadku komunikacji, najpierw określ odbiornik komunikacji, który będzie publikować sygnał o jakości usługi. Następnie w przypadku zidentyfikowanej instancji pakietu usług dodaj co najmniej 1 temat do QosMonitoringConfiguration mapowań
w polu qos_config. Więcej informacji znajdziesz w artykule Konfigurowanie pakietu dla poszczególnych usług.
Temat to ciąg znaków, który określa temat publikacji, w którym moduł HM oczekuje w czasie działania sygnałów HB o jakości usługi. Instancja pakietu nasłuchiwania może brać udział w wielu komunikatach i zgłaszać sygnały QoS na wiele tematów.
Tematy powinny być opisowe, ponieważ w przypadku wykrycia naruszeń jakości usługi w czasie działania są one zgłaszane z powrotem do pakietu usług odbiornika HM.
Typ QosMonitoringConfiguration jest zdefiniowany w //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;
}
W przypadku domyślnych przypadków użycia wymuś oba typy monitorowania QoS. W przypadku komunikacji Pub/Sub w ramach maszyny wirtualnej przy normalnym obciążeniu systemu rozsądna jest wartość A
qos_latency_threshold_ms wynosząca 30.
Kwestie związane z czasem działania
Podobnie jak w przypadku monitorowania sygnału HB aktywności, pakiet nasłuchiwania komunikacji powinien publikować sygnał HB. W takim przypadku publikowanie QoS HB powinno następować po otrzymaniu interesujących wiadomości, a nie po zakończeniu wykonywania logiki biznesowej.
Atrybut QoS HB jest typu QosHeartbeat, zdefiniowanego w dokumencie
//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;
}
Czas rejestracji i wyrejestrowania publikacji QoS HB ma kluczowe znaczenie dla dokładnego monitorowania. Menedżer stanu oczekuje między tymi 2 zdarzeniami sygnałów o jakości usługi. Pakiet nasłuchiwania wiadomości powinien rejestrować publikację QoS HB, gdy monitorowana komunikacja jest zarejestrowana w stosie komunikacyjnym SDV. Aby to zrobić, platforma zarządzania może użyć interfejsu Availability API. Więcej informacji znajdziesz w artykule Sprawdzanie dostępności usługi.
Monitorowanie odzyskiwania pakietu usług
Przywracanie instancji pakietu usług jest konfigurowane w ramach plików konfiguracji agenta orkiestracji. Szczegółowe informacje na ten temat znajdziesz w artykule Pakiety usług. Podsystem HM pasywnie obserwuje proces odzyskiwania. Gdy wykryjemy, że nie udało się odzyskać instancji pakietu, do raportu VMHealth dodamy naruszenie. W przeciwieństwie do pozostałych funkcji monitorowania HM monitorowanie powrotu do zdrowia jest obowiązkowe i nie można go skonfigurować.
Awarie instancji pakietów usług, które nie są skonfigurowane pod kątem przywracania, powodują naruszenie stanu zdrowia przy pierwszej awarii.
Odzyskiwanie instancji pakietu usług jest zintegrowane z monitorowaniem aktywności za pomocą sygnału życia. System HM jest bardziej pobłażliwy w ocenie uderzeń serca, gdy wykryje, że pęczek się regeneruje. W praktyce oznacza to, że jeśli pakiety usług ulegną awarii, nie muszą podejmować żadnych dodatkowych działań związanych z monitorowaniem, wyrejestrowaniem ani rejestracją.
Monitorowanie awarii agenta
HM wykrywa potencjalne awarie agentów SDV za pomocą mechanizmu linkToDeathbinder.
Monitorowanie awarii możesz skonfigurować w ramach konfiguracji stanu maszyny wirtualnej (patrz Konfiguracja poszczególnych instancji SDV (maszyn wirtualnych)), a w szczególności w przypadku pola monitored_agent. To pole powinno zawierać wpisy typu 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;
}
Agenty niestandardowe można też monitorować, jeśli udostępniają interfejs bindera. Aby monitorować niestandardowego agenta, przyznaj uprawnienia HM SELinux do nasłuchiwania odpowiedniego interfejsu bindera.
Właściwość systemowa ro.boot.sdv.health_monitor.agent_startup_timeout_sec może zastąpić czas, przez jaki menedżer sprzętu czeka na zarejestrowanie interfejsów Binder przez agentów po uruchomieniu menedżera sprzętu. O ile nie jest to wymagane przez agentów niestandardowych, odpowiednia jest domyślna wartość 3 sekund.
Przewodniki dla deweloperów dotyczące pakietów usług
W tej sekcji znajdziesz szczegółowe instrukcje korzystania z funkcji HM z pakietów usług, w przeciwieństwie do teoretycznego omówienia w poprzednich sekcjach. Aktualny przykład referencyjny, na którym opierają się te przewodniki, to qos_monitoring. Aby zdobyć praktyczne doświadczenie, postępuj zgodnie z przykładem//system/software_defined_vehicle/samples/health/stable/qos_monitoring/README.
Dodawanie monitorowania sygnału aktywności do pakietu usług
Ta metoda to najbardziej bezpośredni sposób na włączenie monitorowania stanu pakietu usług:
Zdefiniuj instancję
ServiceBundleHealthConfigurationdla instancji pakietu w pliku o nazwiehealth_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 { ... } } }Dodaj plik konfiguracji do pakietu APEX usługi. W
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"], }Zapisz konfigurację stanu w APEX i ustaw
health_config_pathw manifeście:# sdv_service_bundles_manifest.textproto sdv_service_bundle_metadata { ... health_config_path: "etc/config/health_configuration.textproto" }W definicji VSIDL upewnij się, że pakiet publikuje:
com.android.sdv.health.ServiceHeartbeatsdv_service_bundle { name: "SampleBundle" publisher { message: "com.android.sdv.health.ServiceHeartbeat" topic: "arbitrary-topic" capacity: 2 } }Dodaj do pakietu uprawnienia SDV, aby pakiet był uprawniony do publikowania HBs:
publisher { type: "com.android.sdv.health.ServiceHeartbeat" }Okresowo publikuj w kodzie sygnały o stanie usługi, zaczynając od
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() })?; } }
Specjalny przypadek użycia: rejestracja jawna
W przypadku bardziej złożonych zastosowań, w których pakiet wymaga monitorowania HB w przypadku niestandardowych cykli życia (np. monitorowanie rozpoczyna się wcześniej lub kończy później niż standardowy stan STARTED), możesz użyć metody jawnej rejestracji:
W definicji VSIDL dodaj klienta:
com.android.sdv.health.HealthMonitorRegistrationServicesdv_service_bundle { # ... client { service: "com.android.sdv.health.HealthMonitorRegistrationService" channel: "com-android-sdv-health-health-monitor-registration-service" } }Dodaj uprawnienie SDV do korzystania z RPC rejestracji HB aktywności:
# ... client { service: "com.android.sdv.health.HealthMonitorRegistrationService" channel: "com-android-sdv-health-health-monitor-registration-service" }Zarejestruj się w HM za pomocą RPC, np. w
on_startlubnew: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();publikować HBs,
Wyrejestrowanie się z monitorowania, gdy nie jest już potrzebne:
let _ = rpc_client .UnregisterConfiguration(&UnregisterConfigurationRequest { ..Default::default() }) .await .unwrap();
Dodawanie monitorowania jakości usług do komunikacji
Sprawdź, czy instancja pakietu usług subskrybuje temat o nazwie
fog-light-statusw katalogu VSIDL:subscriber { message: "QosMonitoredFogLightStatus" topic: "left-fog-light-status" }Format wiadomości jest następujący:
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; }Zdefiniuj instancję
ServiceBundleHealthConfigurationdla instancji pakietu w plikuhealth_configuration.textproto, który zawiera monitorowanie jakości usługi:# 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 } } } }Temat wybrany w polu
keypokazuje, że na ten temat będą publikowane sygnały o jakości usługi, co umożliwi monitorowanie tematu o nazwiefog-light-status.Dodaj plik konfiguracji do pakietu APEX usługi. W
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"], }Zapisz konfigurację stanu w APEX i ustaw
health_config_pathw pliku manifestu:# sdv_service_bundles_manifest.textproto sdv_service_bundle_metadata { ... health_config_path: "etc/config/health_configuration.textproto" }W definicji VSIDL upewnij się, że pakiet jest wydawcą:
com.android.sdv.health.QosHeartbeatsdv_service_bundle { name: "SampleBundle" publisher { message: "com.android.sdv.health.QosHeartbeat" topic: "qos-hb-right-fog-light-status" capacity: 2 } }Dodaj do pakietu uprawnienia SDV, aby pakiet był uprawniony do publikowania sygnałów HB dotyczących jakości usług:
publisher { message: "com.android.sdv.health.QosHeartbeat" topic: "qos-hb-right-fog-light-status" }Rejestruj publikację QoS HB tylko wtedy, gdy monitorowana komunikacja jest zarejestrowana. Skorzystaj z interfejsu Availability API z
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?; // ...Publikuj sygnały QoS HB za każdym razem, gdy otrzymasz wiadomość:
// ... 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 // ... } }Aby zatrzymać monitorowanie QoS, usuń obiekt wydawcy:
// ... drop(qos_hb_pub);
Debugowanie monitorowania stanu
Aby debugować i sprawdzać stan systemu, użyj narzędzia dumpsys do monitorowania stanu maszyny wirtualnej:
adb shell dumpsys com.google.sdv.ISdvAgent/hm
Raport zawiera szczegóły konfiguracji raportowania stanu maszyny wirtualnej, konfiguracji pakietu i stanu monitorowania. Oto przykładowy raport:
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
----------------