Monitoraggio dello stato di integrità

Health Monitor (HM) è un agente SDV che viene eseguito su ogni macchina virtuale (VM) per monitorare lo stato dei bundle di servizi, determinare l'integrità della VM e generare periodicamente un report sull'integrità della VM.

I bundle di servizi definiti dall'OEM devono ascoltare i vari indicatori di integrità segnalati dall'HM e, in base ai dati, eseguire azioni di ripristino. Ad esempio, un'istanza SDV con bundle di servizi che vanno in crash potrebbe dover essere riavviata o aggiornata.

Puoi configurare l'agente HM per monitorare quanto segue:

• Stato di attività delle entità che eseguono attività periodiche, monitorando gli heartbeat di attività. Questo monitoraggio può essere configurato sia per le istanze del service bundle sia per gli agenti OEM personalizzati.
  • Stato di ripristino delle istanze del pacchetto di servizi. In SDV 2.0, puoi configurare i bundle di servizi per il riavvio automatico in caso di arresto anomalo. L'HM fornisce indicatori per monitorare questa procedura di recupero.
  • QoS per le comunicazioni
• Attività di SDV e agenti personalizzati OEM

Per riferimento, il catalogo VSIDL completo, incluse le definizioni dei proto, è disponibile all'indirizzo //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl.

Terminologia

Questi termini vengono utilizzati in questa pagina.

Utilizzare il sottosistema HM

Per utilizzare le funzionalità di HM, un'implementazione OEM deve:

• Configura il sistema di monitoraggio dell'integrità fornendo i file di configurazione come descritto in Configurare il sistema HM.
• Utilizza un pacchetto di servizi HM Listener definito dal produttore OEM per ascoltare l'output HM e intraprendere l'azione appropriata.
• Sviluppa bundle di servizi che pubblicano attivamente gli indicatori, in base alla loro configurazione di integrità. Questa pubblicazione consente al medico curante di valutare il suo stato di salute. Per maggiori informazioni, consulta le guide per sviluppatori dei bundle di servizi.

Configura il sistema HM

Qualsiasi configurazione correlata a HM si trova in uno di questi tipi di configurazione:

• Una configurazione di controllo dell'integrità globale per VM
• Una configurazione dell'integrità per bundle di servizi, che definisce i parametri di integrità per tutte le istanze del bundle

Configurazione dello stato di integrità per VM

In fase di runtime, l'agente HM prevede una configurazione di integrità a livello di VM: si tratta di un file textproto (con estensione .textproto) di tipo VMHealth definito in //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto. La configurazione di VM Health deve trovarsi nel percorso specificato utilizzando la proprietà di sistema androidboot.sdv.health_monitor.config_path all'avvio. In alternativa, puoi configurare questa impostazione in modo dinamico in fase di runtime impostando la proprietà di sistema persist.sdv.health_monitor.config_path su un percorso personalizzato. L'impostazione persist.* ha la precedenza sull'impostazione androidboot.*. Devi riavviare il dispositivo per applicare la nuova configurazione.

La configurazione dell'integrità della VM ti consente di impostare quanto segue:

• Periodicità del report sull'integrità della VM tramite period_ms. L'impostazione è un compromesso tra una segnalazione più rapida del rilevamento di violazioni dello stato e le prestazioni del sottosistema HM. Ti consigliamo un valore di 100 ms.

• Quali agenti devono essere monitorati per i blocchi (vedi Monitoraggio dei blocchi degli agenti).

Esempi di file di configurazione sono presenti in //system/software_defined_vehicle/health_monitor/src/prod_configs/. Ecco un file di configurazione di esempio:

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

In questo esempio, gli agenti SDV DT e RPC sono configurati per il monitoraggio degli arresti anomali e il report sull'integrità della VM è configurato per essere pubblicato ogni 100 ms.

Configurazione per bundle di servizi

Il monitoraggio dell'integrità delle istanze del bundle di servizi è facoltativo. Per attivare la funzionalità, archivia il file di configurazione dello stato in APEX del bundle di servizi e definisci un percorso nel campo health_config_path di sdv_service_bundle_metadata in sdv_service_bundles_manifest.textproto. Per saperne di più sui manifest dei pacchetti di servizi, consulta la sezione Metadati dei pacchetti di servizi.

Il file di configurazione dell'integrità è un file textproto del seguente tipo:

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

Per ogni istanza, puoi specificare sia la configurazione del battito cardiaco di attività sia la configurazione 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;
}

Per saperne di più sulla configurazione per funzionalità, consulta Monitoraggio dei battiti del cuore di attività e Monitoraggio della qualità del servizio.

Ascolta l'output di HM

Puoi ascoltare l'HM tramite report periodici o un'API RPC.

Report sullo stato della VM

Il monitoraggio dell'integrità genera un report periodico ad alta frequenza sull'integrità della VM, fornendo informazioni concise sullo stato di integrità delle entità monitorate.

La sintassi del tipo di VmHealth è definita in //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;
}

Un bundle di servizi di ascolto HM definito dal produttore OEM deve essere in ascolto dei report VMHealth e intraprendere le azioni appropriate a seconda dell'architettura completa del sistema. Le potenziali azioni includono:

• Esegui routine di diagnostica sulla VM.
• Riavvia la VM.
• Esegui una campagna di telemetria per determinare la causa.
• Aggiorna il sistema o interrompi un aggiornamento se il sistema non funziona correttamente.

API HM RPC

Il report sull'integrità della VM è una pubblicazione ottimizzata per la frequenza e la velocità di trasmissione e fornisce informazioni generali sullo stato di integrità del sistema.

L'API RPC HM consente al listener HM di ottenere informazioni dettagliate sull'origine delle violazioni della salute. L'interfaccia è definita in //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto. L'interfaccia è riprodotta qui per comodità:

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

Descrizione dettagliata delle funzionalità

Questa sezione descrive in modo più dettagliato vari aspetti dell'HM.

Monitoraggio dei battiti del cuore di attività

Quando il monitoraggio dell'attività è configurato per un'istanza del bundle di servizi, HM si aspetta che l'istanza pubblichi heartbeat periodici per dimostrare che la logica di business funziona correttamente. Questo monitoraggio è ideale per le istanze di bundle di servizi che eseguono attività periodiche. Inoltre, i bundle che utilizzano runtime asincroni possono utilizzare il monitoraggio dell'attività per dimostrare che il pool di thread non è esaurito.

Figura 1. Flusso di monitoraggio dell'attività di HM.

Configurazione

Per abilitare il controllo di attività HB su un'istanza del bundle di servizi, aggiungi un'istanza di HealthConfiguration al campo health_config nella configurazione del bundle.

Una configurazione del battito cardiaco di attività definisce un insieme predeterminato di parametri che stabiliscono i criteri per valutare il segnale periodico di battito cardiaco di un servizio. Se le caratteristiche del battito cardiaco del servizio si discostano da questi parametri, il battito cardiaco viene classificato come ritardato e il bundle di servizi corrispondente come non integro, il che potrebbe indicare uno stato operativo non ottimale.

Un bundle di servizi è considerato integro quando segnala heartbeat in tempo in base alla sua configurazione di integrità. In caso di arresto anomalo o carico elevato del sistema, un heartbeat potrebbe mancare o essere ritardato, causando la classificazione del bundle di servizi come non integro. In questo caso, una violazione viene visualizzata nel report VmHealth.

Gli sviluppatori di bundle di servizi devono definire la configurazione dell'integrità di un bundle di servizi nei metadati APEX corrispondenti. La configurazione dell'integrità definisce questi criteri:

• Il ritardo iniziale massimo consentito tra l'avvio del servizio e il primo rilevamento del battito cardiaco.

• Il periodo durante il quale il bundle di servizi SDV esegue la logica di business, che corrisponde alla periodicità di pubblicazione di un heartbeat del servizio.

• Il numero di periodi da saltare prima che HM consideri il bundle di servizi in stato non integro.

• Il tempo di esecuzione è il tempo necessario a un bundle di servizi SDV per eseguire la sua logica di business prima di poter pubblicare un heartbeat del servizio.

Il pacchetto di servizi genera una violazione dell'integrità se il battito cardiaco del servizio viene ritardato. Esistono due casi in base all'ora dell'osservazione dello stato di salute:

• Scenario 1: il battito iniziale non è stato ricevuto. Se è trascorso più tempo del ritardo iniziale consentito tra l'inizio del bundle di servizi e il momento dell'osservazione, il bundle di servizi viene considerato non integro.

• Caso 2: sono già stati ricevuti heartbeat. Se è trascorso un periodo di tempo tra l'ultimo battito e il momento dell'osservazione, il bundle di servizi viene considerato non integro. Questa soglia viene calcolata come somma del periodo del report (moltiplicato per il numero di periodi) e della durata dell'attività.

Il formato della configurazione del controllo di integrità è definito in //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;
}

Considerazioni sul runtime

Questa sezione fornisce indicazioni per la pubblicazione di heartbeat di attività e la registrazione corretta per il monitoraggio.

Pubblica heartbeat di attività

Un'istanza del pacchetto di servizi genera un messaggio di heartbeat del servizio che include un timestamp. Genera regolarmente il messaggio, in genere subito dopo l'esecuzione della logica di business principale. Il battito cardiaco del servizio indica che il bundle di servizi è attivo.

L'oggetto istanza del bundle da monitorare deve creare un publisher di tipo ServiceHeartbeat, disponibile nella libreria libhealth_api:

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

Scegli l'argomento della pubblicazione in modo arbitrario. L'agente HM utilizza il rilevamento per tipo di messaggio per rilevare la pubblicazione.

Quando configuri il monitoraggio dell'attività tramite la configurazione di integrità collegata nel manifest del bundle di servizi corrispondente, l'agente HM prevede che gli HB vengano pubblicati non appena l'istanza ha terminato la routine on_start. Ti consigliamo di mantenere on_start breve per evitare di bloccare l'avvio del sistema, quindi pubblica i battiti in un'attività asincrona avviata in on_start.

Gli sviluppatori di bundle possono personalizzare l'ora in cui è previsto il primo battito cardiaco utilizzando la voce di configurazione initial_delay_ms.

L'istanza del bundle deve continuare a pubblicare heartbeat finché non viene arrestata. Un'istanza viene considerata arrestata al termine della routine on_stop.

Caso d'uso speciale: registrazione esplicita al monitoraggio heartbeat

Il comportamento descritto in Monitoraggio dei battiti di attività, in cui i battiti sono previsti tra on_start e on_stop, è chiamato monitoraggio implicito dell'attività. Questo è il modo consigliato per utilizzare la funzionalità: semplifica la logica di business del bundle e garantisce che il bundle venga sempre monitorato.

Tuttavia, potrebbero esistere alcuni casi d'uso in cui il periodo di monitoraggio predefinito è una limitazione:

• Un'istanza del bundle di servizi contiene una logica di business periodica in un intervallo di tempo non collegato agli eventi start e stop. Il monitoraggio dell'attività potrebbe essere necessario solo in questo periodo personalizzato.
• La metrica HM tiene traccia con precisione degli HB durante i periodi di sospensione e ripresa. Pertanto, il bundle potrebbe voler continuare a essere monitorato dopo il giorno on_stop.
• Gli agenti OEM personalizzati potrebbero non essere implementati come bundle di servizi. Pertanto, non possono usufruire del monitoraggio implicito dell'attività. Tuttavia, potrebbero comunque richiedere il monitoraggio dell'attività.

Per questi casi, HM ti consente di bypassare la registrazione implicita al monitoraggio della vitalità a favore della registrazione esplicita. Per utilizzare la registrazione esplicita, un'istanza del bundle deve disattivare la registrazione implicita non includendo una voce di tipo HealthConfiguration per l'istanza specifica nel manifest del bundle. Poi, in fase di runtime, l'istanza del bundle deve utilizzare l'API RPC definita in //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto per registrarsi e annullare la registrazione manualmente dal monitoraggio. I battiti vengono pubblicati non appena la chiamata RPC di registrazione va a buon fine.

Per un esempio di implementazione, vedi //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/.

Monitoraggio della qualità del servizio

La qualità del servizio (QoS) è una misurazione della comunicazione. L'HM monitora se il messaggio inviato impiega troppo tempo per essere recapitato o, nel caso di comunicazione periodica, se i messaggi non vengono ricevuti con la frequenza scelta.

SDV fornisce diverse varianti di comunicazione Pub/Sub e RPC. Il denominatore comune è che tutti gli schemi di comunicazione contengono almeno un listener. Affinché l'HM monitori la comunicazione, questa istanza del bundle di servizi di ascolto deve pubblicare heartbeat QoS speciali ogni volta che riceve un messaggio di interesse.

Configurazione

Per abilitare il monitoraggio della qualità del servizio di una comunicazione, identifica innanzitutto il listener di comunicazione che pubblicherà il battito cardiaco della qualità del servizio. Poi, per l'istanza del bundle di servizi identificata, aggiungi uno o più argomenti ai mapping QosMonitoringConfiguration nel campo qos_config. Per saperne di più, consulta la sezione Configurazione dei bundle per servizio.

L'argomento è una stringa che definisce l'argomento di pubblicazione in cui HM prevede HB QoS in fase di runtime. Un'istanza del bundle di ascolto può partecipare a più comunicazioni e può segnalare heartbeat QoS su più argomenti.

Gli argomenti devono essere descrittivi, in quanto vengono segnalati al bundle di servizi del listener HM se vengono rilevate violazioni della QoS in fase di runtime.

Il tipo QosMonitoringConfiguration è definito in //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;
}

Per i casi d'uso predefiniti, applica entrambi i tipi di monitoraggio QoS. Un valore di qos_latency_threshold_ms di 30 è ragionevole per la comunicazione Pub/Sub in-VM in condizioni di carico normale del sistema.

Considerazioni sul runtime

Analogamente al monitoraggio del battito cardiaco di attività, il bundle di ascolto della comunicazione dovrebbe pubblicare un tipo di heartbeat. In questo caso, un HB QoS deve essere pubblicato ogni volta che vengono ricevuti messaggi di interesse, anziché alla fine dell'esecuzione della logica di business.

Un heartbeat QoS è di tipo QosHeartbeat, definito in //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;
}

L'ora di registrazione e annullamento della registrazione della pubblicazione QoS HB è fondamentale per un monitoraggio accurato. L'HM prevede HB QoS tra questi due eventi. Il pacchetto di ascolto dei messaggi deve registrare la pubblicazione QoS HB quando la comunicazione monitorata viene registrata con lo stack di comunicazione SDV. L'HM può utilizzare l'API Availability per farlo. Per saperne di più, consulta Determinare la disponibilità del servizio.

Monitoraggio del recupero dei bundle di servizi

Il recupero delle istanze del bundle di servizi è configurato come parte dei file di configurazione dell'agente di orchestrazione. Per un trattamento completo dell'argomento, consulta Pacchetti di servizi. Il sottosistema HM osserva passivamente il processo di recupero. Quando viene rilevato un errore di recupero di un'istanza del bundle, viene aggiunta una violazione al report VMHealth. A differenza delle altre funzionalità di monitoraggio di HM, il monitoraggio del recupero è obbligatorio e non configurabile.

Gli arresti anomali delle istanze del bundle di servizi non configurate per il ripristino generano una violazione dell'integrità al primo arresto anomalo.

Il recupero delle istanze del pacchetto di servizi è progettato per integrarsi con il monitoraggio dell'attività heartbeat. Il sistema HM è più indulgente nella valutazione dei battiti cardiaci quando rileva che il bundle è in recupero. In pratica, questa tolleranza significa che i bundle di servizi non devono eseguire ulteriori passaggi di monitoraggio, annullamento della registrazione o registrazione in caso di arresto anomalo.

Monitoraggio degli arresti anomali dell'agente

L'HM rileva potenziali arresti anomali degli agenti SDV utilizzando il meccanismo binder linkToDeath.

Puoi configurare il monitoraggio degli arresti anomali nell'ambito della configurazione dell'integrità della VM (vedi Configurazione per istanza SDV (VM)), in particolare il campo ripetuto monitored_agent. Questo campo deve contenere voci di tipo 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;
}

Gli agenti personalizzati possono anche essere monitorati se espongono un'interfaccia binder. Per monitorare un agente personalizzato, concedi le autorizzazioni HM SELinux per ascoltare l'interfaccia binder appropriata.

La proprietà di sistema ro.boot.sdv.health_monitor.agent_startup_timeout_sec può ignorare il tempo di attesa di HM per la registrazione delle interfacce Binder degli agenti dopo l'avvio di HM. A meno che non sia richiesto da agenti personalizzati, il valore predefinito di tre secondi è appropriato.

Guide per sviluppatori di pacchetti di servizi

Questa sezione fornisce guide passo passo su come utilizzare le funzionalità di HM dei bundle di servizi, in contrasto con il trattamento teorico nelle sezioni precedenti. L'esempio di riferimento aggiornato su cui si basano queste guide è l'esempio qos_monitoring. Segui l'esempio //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README per un'esperienza pratica.

Aggiungere il monitoraggio heartbeat di attività a un bundle di servizi

Questo metodo è il modo più diretto per attivare il monitoraggio dello stato di integrità per un bundle di servizi:

1. Definisci un'istanza di ServiceBundleHealthConfiguration per le istanze del bundle in un file denominato 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. Aggiungi il file di configurazione al bundle APEX del servizio. In un 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. Archivia la configurazione di integrità nell'APEX e imposta health_config_path nel manifest:

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

4. Nella definizione VSIDL, assicurati che il bundle pubblichi com.android.sdv.health.ServiceHeartbeat:

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

5. Aggiungi le autorizzazioni SDV al bundle in modo che sia autorizzato a pubblicare HB:

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

6. Pubblica periodicamente i battiti del servizio nel codice, a partire da 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()
       })?;
     }
   }
   

Caso d'uso speciale: registrazione esplicita

Per casi d'uso più speciali, in cui il bundle deve monitorare HB per cicli di vita personalizzati (ad esempio, il monitoraggio inizia prima o termina dopo lo stato STARTED standard), puoi utilizzare il metodo di registrazione esplicita:

1. Nella definizione VSIDL, aggiungi un client 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. Aggiungi l'autorizzazione SDV per l'utilizzo della RPC di registrazione HB di aliveness:

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

3. Registrati con HM tramite RPC, ad esempio in on_start o 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. Pubblica HBs.

5. Annulla la registrazione al monitoraggio quando non è più necessario:

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

Aggiungere il monitoraggio QoS alla comunicazione

1. Verifica che l'istanza del pacchetto di servizi sia un abbonato a un argomento denominato fog-light-status nel catalogo VSIDL:

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

   Il formato del messaggio è il seguente:

   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. Definisci un'istanza di ServiceBundleHealthConfiguration per le istanze del bundle in un file health_configuration.textproto che include il monitoraggio della qualità del servizio:

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

   L'argomento scelto nel campo key illustra che gli HB QoS verranno pubblicati in questo argomento, consentendo il monitoraggio di un argomento chiamato fog-light-status.

3. Aggiungi il file di configurazione al bundle APEX del servizio. In un 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. Memorizza la configurazione di integrità nell'APEX e imposta health_config_path nel manifest:

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

5. Nella definizione VSIDL, assicurati che il bundle sia un editore di 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. Aggiungi le autorizzazioni SDV al bundle in modo che sia autorizzato a pubblicare HB QoS:

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

7. Registra la pubblicazione di QoS HB solo quando la comunicazione monitorata è registrata. Utilizza l'API Availability da 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. Pubblica HB QoS ogni volta che viene ricevuto un messaggio:

   // ...
   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. Per interrompere il monitoraggio della qualità del servizio, rilascia l'oggetto editore:

   // ...
   drop(qos_hb_pub);
   

Debug del monitoraggio dello stato di integrità

Per scopi di debug e panoramica del sistema, utilizza lo strumento dumpsys per monitorare lo stato di monitoraggio dell'integrità della VM:

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

Il report descrive in dettaglio la configurazione dei report sullo stato di integrità della VM, la configurazione del bundle e lo stato di monitoraggio. Di seguito è riportato un esempio di report:

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

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