Statusüberwachung

Der Health Monitor (HM) ist ein SDV-Agent, der auf jeder VM ausgeführt wird, um den Status von Dienstpaketen zu verfolgen, den Zustand der VM zu ermitteln und regelmäßig einen VM-Zustandsbericht zu erstellen.

OEM-definierte Service-Bundles müssen auf die verschiedenen vom HM gemeldeten Gesundheitssignale reagieren und auf Grundlage der Daten Wiederherstellungsmaßnahmen durchführen. Beispielsweise muss eine SDV-Instanz mit abstürzenden Dienst-Bundles möglicherweise neu gestartet oder aktualisiert werden.

Sie können den HM-Agent so konfigurieren, dass er Folgendes erfasst:

• Aktivitätsstatus von Entitäten, die regelmäßige Aufgaben ausführen, durch Überwachung von Aktivitäts-Heartbeats. Dieses Monitoring kann sowohl für Service-Bundle-Instanzen als auch für benutzerdefinierte OEM-Agents konfiguriert werden.
  • Wiederherstellungsstatus von Service-Bundle-Instanzen. In SDV 2.0 können Sie Dienstbündel für den automatischen Neustart bei Abstürzen konfigurieren. Der HM liefert Signale, um diesen Wiederherstellungsprozess zu überwachen.
  • QoS für die Kommunikation
• Aktivität von SDV- und OEM-Agenten

Der vollständige VSIDL-Katalog, einschließlich der Proto-Definitionen, ist unter //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl verfügbar.

Terminologie

Diese Begriffe werden auf dieser Seite verwendet.

Mit dem HM-Subsystem arbeiten

Damit HM-Funktionen verwendet werden können, muss eine OEM-Implementierung Folgendes erfüllen:

• Konfigurieren Sie das System zur Zustandsüberwachung, indem Sie Konfigurationsdateien wie in HM-System konfigurieren beschrieben bereitstellen.
• Verwenden Sie ein vom OEM definiertes HM-Listener-Dienstbündel, um auf HM-Ausgaben zu reagieren und entsprechende Maßnahmen zu ergreifen.
• Entwickeln Sie Dienstpakete, die gemäß ihrer Konfiguration für den Zustand aktiv Signale veröffentlichen. Mit dieser Publikation kann die HM ihren Gesundheitszustand einschätzen. Weitere Informationen finden Sie in den Entwicklerleitfäden für Service-Bundles.

HM-System konfigurieren

Alle HM-bezogenen Konfigurationen befinden sich in einem dieser Konfigurationstypen:

• Eine globale Systemdiagnosekonfiguration pro VM
• Eine Konfiguration für die Systemdiagnose pro Service-Bundle, in der Systemdiagnoseparameter für alle Instanzen des Bundles definiert werden

Pro VM-Systemdiagnosekonfiguration

Zur Laufzeit erwartet der HM-Agent eine VM-weite Gesundheitskonfiguration. Dies ist eine Textproto-Datei (mit der Erweiterung .textproto) vom Typ VMHealth, die unter //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto definiert ist. Die VM Health-Konfiguration sollte sich unter dem Pfad befinden, der mit der System-Bootzeit-Eigenschaft androidboot.sdv.health_monitor.config_path angegeben wird. Alternativ können Sie dies zur Laufzeit dynamisch konfigurieren, indem Sie das Systemattribut persist.sdv.health_monitor.config_path auf einen benutzerdefinierten Pfad festlegen. Die Einstellung persist.* hat Vorrang vor der Einstellung androidboot.*. Sie müssen das Gerät neu starten, damit die neue Konfiguration wirksam wird.

Mit der VM-Systemstatuskonfiguration können Sie Folgendes festlegen:

• Häufigkeit des VM-Systemzustandsberichts über period_ms. Die Einstellung ist ein Kompromiss zwischen einer schnelleren Benachrichtigung über erkannte Gesundheitsverstöße und der Leistung des HM-Subsystems. Wir empfehlen einen Wert von 100 ms.

• Welche Agents auf Abstürze überwacht werden sollen (siehe Agent-Absturzüberwachung).

Beispiele für Konfigurationsdateien finden Sie unter //system/software_defined_vehicle/health_monitor/src/prod_configs/. Hier sehen Sie ein Beispiel für eine Konfigurationsdatei:

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 diesem Beispiel sind SDV-DT- und RPC-Agents für die Absturzüberwachung konfiguriert und der VM-Systemstatusbericht wird alle 100 ms veröffentlicht.

Pro Dienstpaketkonfiguration

Die Statusüberwachung von Dienstbundle-Instanzen ist optional. Wenn Sie die Funktion aktivieren möchten, speichern Sie die Konfigurationsdatei für die Gesundheits-API im APEX Ihres Dienstbündels und definieren Sie einen Pfad dazu im Feld health_config_path von sdv_service_bundle_metadata in sdv_service_bundles_manifest.textproto. Weitere Informationen zu Dienstpaketmanifesten finden Sie unter Dienstpaket-Metadaten.

Die Konfigurationsdatei für die Systemdiagnose ist eine Textproto-Datei des folgenden Typs:

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

Für jede Instanz können Sie sowohl die Konfiguration für den Aliveness-Heartbeat als auch die QoS-Konfiguration angeben:

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

Weitere Informationen zur Konfiguration pro Funktion finden Sie unter Aliveness-Heartbeats überwachen und QoS-Monitoring.

HM-Ausgabe anhören

Sie können die HM entweder über regelmäßige Berichte oder eine RPC-API abrufen.

Bericht zum VM-Zustand

Bei der Systemzustandsüberwachung wird in hoher Frequenz ein regelmäßiger Systemzustandsbericht für VMs erstellt, der präzise Informationen zum Systemzustand der überwachten Einheiten enthält.

Die Typsyntax von VmHealth ist in //system/software_defined_vehicle/health_monitor/catalog/health_topic.proto definiert:

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

Ein vom OEM definiertes HM-Listener-Dienst-Bundle sollte auf VMHealth-Berichte warten und je nach der gesamten Systemarchitektur entsprechende Maßnahmen ergreifen. Mögliche Maßnahmen:

• Führen Sie Diagnoseroutinen auf der VM aus.
• Starten Sie die VM neu.
• Führen Sie eine Telemetriekampagne durch, um die Ursache zu ermitteln.
• Aktualisieren Sie das System oder stoppen Sie ein Update, wenn das System nicht richtig funktioniert.

HM RPC API

Der VM-Zustandsbericht ist eine Publikation, die für Häufigkeit und Übertragungsgeschwindigkeit optimiert ist und allgemeine Informationen zum Systemzustand bietet.

Mit der HM RPC API kann der HM-Listener detaillierte Informationen zur Quelle von Gesundheitsverstößen abrufen. Die Schnittstelle ist in //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto definiert. Die Benutzeroberfläche wird hier noch einmal aufgeführt:

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

Detaillierte Beschreibung der Funktionen

In diesem Abschnitt werden verschiedene Aspekte des HM genauer beschrieben.

Überwachung von Aliveness-Heartbeats

Wenn die Aktivitätsüberwachung für eine Dienstbündelinstanz konfiguriert ist, erwartet der HM, dass die Instanz regelmäßig Heartbeats veröffentlicht, um zu beweisen, dass die Geschäftslogik ordnungsgemäß funktioniert. Dieses Monitoring eignet sich am besten für Dienstpaketinstanzen, die regelmäßig Aufgaben ausführen. Außerdem können Bundles, die asynchrone Runtimes verwenden, mit dem Aliveness-Monitoring nachweisen, dass der Thread-Pool nicht erschöpft ist.

Abbildung 1. Ablauf des HM-Alive-Monitorings.

Konfiguration

Wenn Sie Aliveness-HBs für eine Dienstbundle-Instanz aktivieren möchten, fügen Sie dem Feld health_config in der Bundle-Konfiguration eine Instanz von HealthConfiguration hinzu.

Eine Konfiguration für Aliveness-Heartbeats definiert eine vorgegebene Reihe von Parametern, die die Kriterien für die Bewertung des regelmäßigen Heartbeat-Signals eines Dienstes festlegen. Wenn die Merkmale des Dienst-Heartbeats von diesen Parametern abweichen, wird der Heartbeat als verzögert und das entsprechende Dienstbündel als fehlerhaft eingestuft. Dies kann auf einen nicht optimalen Betriebszustand hinweisen.

Ein Dienstpaket gilt als fehlerfrei, wenn es gemäß seiner Konfiguration für den Zustand rechtzeitig Heartbeats meldet. Bei einem Absturz oder einer hohen Systemlast kann ein Heartbeat fehlen oder sich verzögern, wodurch das Dienstpaket als fehlerhaft markiert wird. In diesem Fall wird ein Verstoß im VmHealth-Bericht angezeigt.

Entwickler von Service-Bundles sollten die Konfiguration des Systemzustands eines Service-Bundles in den entsprechenden APEX-Metadaten definieren. In der Konfiguration für Systemdiagnosen werden die folgenden Kriterien definiert:

• Die maximal zulässige anfängliche Verzögerung zwischen dem Start des Dienstes und der Erkennung des ersten Heartbeats.

• Der Zeitraum, in dem das SDV-Dienstpaket Geschäftslogik ausführt. Dies entspricht der Häufigkeit der Veröffentlichung eines Dienst-Heartbeats.

• Die Anzahl der Zeiträume, die übersprungen werden müssen, bevor der HM das Service-Bundle als fehlerhaft betrachtet.

• Die Ausführungszeit ist die Zeit, die ein SDV-Dienstpaket benötigt, um seine Geschäftslogik auszuführen, bevor es einen Dienst-Heartbeat veröffentlichen kann.

Das Dienstpaket generiert einen Integritätsverstoß, wenn der Dienst-Heartbeat verzögert wird. Es gibt zwei Fälle, die vom Zeitpunkt der Systemdiagnose abhängen:

• Fall 1:Der erste Heartbeat wurde nicht empfangen. Wenn zwischen dem Start des Dienstpakets und dem Zeitpunkt der Beobachtung mehr als die zulässige anfängliche Verzögerung verstrichen ist, gilt das Dienstpaket als fehlerhaft.

• Fall 2:Es wurden bereits Heartbeats empfangen. Wenn zwischen dem letzten Heartbeat und dem Beobachtungszeitpunkt ein Schwellenwert überschritten wurde, gilt das Dienstpaket als fehlerhaft. Dieser Grenzwert wird als Summe des Berichtszeitraums (multipliziert mit der Anzahl der Zeiträume) und der Dauer der Aufgabe berechnet.

Das Format der Konfiguration für die Systemdiagnose ist in //system/software_defined_vehicle/health_monitor/catalog/health_config.proto definiert:

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

Überlegungen zur Laufzeit

In diesem Abschnitt finden Sie eine Anleitung zum Veröffentlichen von Aliveness-Heartbeats und zur korrekten Registrierung für das Monitoring.

Lebenszeichen-Heartbeats veröffentlichen

Eine Dienstbündelinstanz generiert eine Service-Heartbeat-Nachricht mit einem Zeitstempel. Generieren Sie die Nachricht routinemäßig, in der Regel direkt nach Ausführung der Hauptgeschäftslogik. Der Service-Heartbeat gibt an, dass das Service-Bundle aktiv ist.

Für das zu überwachende Bundle-Instanzobjekt muss ein Publisher vom Typ ServiceHeartbeat erstellt werden, der in der Bibliothek libhealth_api verfügbar ist:

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

Wählen Sie das Thema der Publikation beliebig aus. Der HM-Agent verwendet die Erkennung nach Nachrichtentyp, um die Publikation zu erkennen.

Wenn Sie die Aktivitätsüberwachung über die in der entsprechenden Dienstbündelmanifestdatei verknüpfte Gesundheitskonfiguration konfigurieren, erwartet der HM-Agent, dass HBs veröffentlicht werden, sobald die Instanz ihre on_start-Routine abgeschlossen hat. Wir empfehlen, on_start kurz zu halten, um das Starten des Systems nicht zu blockieren. Veröffentlichen Sie daher Heartbeats in einer asynchronen Aufgabe, die in on_start gestartet wird.

Bundle-Entwickler können die Zeit, zu der der erste Heartbeat erwartet wird, mit dem Konfigurationseintrag initial_delay_ms anpassen.

Die Bundle-Instanz sollte weiterhin Heartbeats veröffentlichen, bis sie beendet wird. Eine Instanz gilt als beendet, wenn ihre on_stop-Routine abgeschlossen ist.

Besonderer Anwendungsfall: Explizite Registrierung für das Heartbeat-Monitoring

Das in Aliveness-Heartbeats überwachen beschriebene Verhalten, bei dem Heartbeats zwischen on_start und on_stop erwartet werden, wird als implizites Aliveness-Monitoring bezeichnet. Dies ist die empfohlene Methode für die Verwendung der Funktion, da sie die Geschäftslogik des Bundles vereinfacht und dafür sorgt, dass das Bundle immer überwacht wird.

Es gibt jedoch einige Anwendungsfälle, in denen der Standardzeitraum für das Monitoring eine Einschränkung darstellen kann:

• Eine Dienstbundle-Instanz enthält Geschäftslogik, die in einem Zeitintervall ausgeführt wird, das nicht mit start- und stop-Ereignissen verknüpft ist. Das Monitoring der Aktivität ist möglicherweise nur in diesem benutzerdefinierten Zeitraum erforderlich.
• Der HM erfasst HBs während der Pausen und Fortsetzungen genau. Daher sollte das Bundle auch nach dem on_stop weiter überwacht werden.
• Benutzerdefinierte OEM-Agents werden möglicherweise nicht als Dienst-Bundles implementiert. Daher können sie nicht von der impliziten Aktivitätsüberwachung profitieren. Möglicherweise ist jedoch weiterhin ein Aktivitätsmonitoring erforderlich.

In diesen Fällen können Sie mit dem HM die implizite Registrierung für die Überwachung der Lebendigkeit zugunsten der expliziten Registrierung umgehen. Wenn Sie die explizite Registrierung verwenden möchten, muss eine Bundle-Instanz die implizite Registrierung deaktivieren, indem sie keinen Eintrag vom Typ HealthConfiguration für die jeweilige Instanz im Manifest des Bundles enthält. Zur Laufzeit sollte die Bundle-Instanz dann die in //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto definierte RPC API verwenden, um sich manuell für das Monitoring zu registrieren und die Registrierung aufzuheben. Veröffentlichte Heartbeats werden erwartet, sobald der Registrierungs-RPC-Aufruf erfolgreich ist.

Eine Beispielimplementierung finden Sie unter //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/.

QoS-Monitoring

Dienstqualität (Quality of Service, QoS) ist ein Maß für die Kommunikation. Der HM überwacht, ob die gesendete Nachricht zu lange unterwegs ist, oder, im Falle einer regelmäßigen Kommunikation, ob Nachrichten nicht mit der gewählten Häufigkeit empfangen werden.

SDV bietet verschiedene Varianten von Pub/Sub- und RPC-Kommunikation. Der gemeinsame Nenner ist, dass alle Kommunikationsschemata mindestens einen Listener enthalten. Damit der HM die Kommunikation überwachen kann, muss diese Listening-Dienst-Bundle-Instanz spezielle QoS-Heartbeats veröffentlichen, wenn sie eine relevante Nachricht empfängt.

Konfiguration

Wenn Sie die QoS-Überwachung einer Kommunikation aktivieren möchten, müssen Sie zuerst den Kommunikationslistener identifizieren, der den QoS-Heartbeat veröffentlicht. Fügen Sie dann für die identifizierte Dienstpaketinstanz dem Feld qos_config ein oder mehrere Themen zu QosMonitoringConfiguration-Zuordnungen hinzu. Weitere Informationen finden Sie unter Bundle-Konfiguration pro Dienst.

Das Thema ist ein String, der das Publikationsthema definiert, für das das HM zur Laufzeit QoS-HBs erwartet. Eine Instanz eines Listening-Bundles kann an mehreren Kommunikationen teilnehmen und QoS-HBs zu mehreren Themen melden.

Themen sollten aussagekräftig sein, da sie an das HM-Listener-Service-Bundle zurückgemeldet werden, wenn zur Laufzeit QoS-Verstöße erkannt werden.

Der Typ QosMonitoringConfiguration ist in //system/software_defined_vehicle/health_monitor/catalog/health_config.proto definiert:

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

Für Standardanwendungsfälle müssen beide Arten von QoS-Monitoring erzwungen werden. Eine qos_latency_threshold_ms von 30 ist für die Pub/Sub-Kommunikation in der VM bei normaler Systemlast angemessen.

Überlegungen zur Laufzeit

Ähnlich wie beim Monitoring von Aliveness-Heartbeats wird erwartet, dass das Kommunikations-Listening-Bundle einen Heartbeat-Typ veröffentlicht. In diesem Fall sollte ein QoS-HB immer dann veröffentlicht werden, wenn relevante Nachrichten empfangen werden, und nicht erst am Ende der Ausführung der Geschäftslogik.

Ein QoS-Heartbeat hat den Typ QosHeartbeat, der in //system/software_defined_vehicle/health_monitor/catalog/qos_heartbeat.proto definiert ist:

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

Der Zeitpunkt der Registrierung und Deregistrierung der QoS-HB-Veröffentlichung ist für ein genaues Monitoring entscheidend. Das HM erwartet QoS-HBs zwischen diesen beiden Ereignissen. Das Bundle für das Abhören von Nachrichten sollte die QoS HB-Veröffentlichung registrieren, wenn die überwachte Kommunikation beim SDV-Kommunikationsstack registriert ist. Der HM kann dazu die Availability API verwenden. Weitere Informationen finden Sie unter Dienstverfügbarkeit ermitteln.

Monitoring der Wiederherstellung von Dienstpaketen

Die Wiederherstellung von Service-Bundle-Instanzen wird in den Konfigurationsdateien des Orchestrierungs-Agents konfiguriert. Eine ausführliche Behandlung des Themas finden Sie unter Dienstpakete. Das HM-Subsystem beobachtet den Wiederherstellungsprozess passiv. Wenn ein Fehler beim Wiederherstellen einer Bundle-Instanz erkannt wird, wird dem VMHealth-Bericht ein Verstoß hinzugefügt. Im Gegensatz zu den anderen HM-Monitoringfunktionen ist die Überwachung der Erholung obligatorisch und nicht konfigurierbar.

Abstürze von Dienstbündelinstanzen, die nicht für die Wiederherstellung konfiguriert sind, führen beim ersten Absturz zu einem Statusverstoß.

Die Wiederherstellung von Dienstbündelinstanzen ist für die Integration in das Heartbeat-Alive-Monitoring konzipiert. Das HM-System ist bei der Bewertung von Herzschlägen nachsichtiger, wenn es erkennt, dass sich das Bundle erholt. In der Praxis bedeutet diese Kulanz, dass für Dienstbündel keine zusätzlichen Schritte zur Deregistrierung oder Registrierung für die Überwachung erforderlich sind, wenn sie abstürzen.

Monitoring von Agent-Abstürzen

Der HM erkennt potenzielle Abstürze von SDV-Agents mithilfe des Binder-Mechanismus linkToDeath.

Sie können die Absturzüberwachung als Teil der VM-Systemzustandskonfiguration konfigurieren (siehe Konfiguration pro SDV-Instanz (VM)), insbesondere das wiederholte Feld monitored_agent. Dieses Feld sollte Einträge vom Typ BinderServiceAgent enthalten:

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

Benutzerdefinierte Agents können auch überwacht werden, wenn der Agent eine Binder-Schnittstelle bereitstellt. Wenn Sie einen benutzerdefinierten Agenten überwachen möchten, gewähren Sie dem HM SELinux-Berechtigungen, damit er auf die entsprechende Binder-Schnittstelle hören kann.

Mit der Systemeigenschaft ro.boot.sdv.health_monitor.agent_startup_timeout_sec kann überschrieben werden, wie lange der HM nach dem Starten des HM wartet, bis Agents ihre Binder-Schnittstellen registrieren. Sofern nicht von benutzerdefinierten Agents erforderlich, ist der Standardwert von drei Sekunden angemessen.

Entwicklungshandbücher für Dienstpakete

In diesem Abschnitt finden Sie Schritt-für-Schritt-Anleitungen zur Verwendung von HM-Funktionen aus Service-Bundles im Gegensatz zur theoretischen Behandlung in den vorherigen Abschnitten. Die aktuelle Referenzstichprobe, auf der diese Anleitungen basieren, ist die qos_monitoring-Stichprobe. Folgen Sie dem Beispiel unter //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README, um die Funktion in der Praxis auszuprobieren.

Lebenszeichen-Heartbeat-Monitoring zu einem Dienstpaket hinzufügen

Diese Methode ist der direkteste Weg, um die Statusüberwachung für ein Service-Bundle zu aktivieren:

1. Definieren Sie eine Instanz von ServiceBundleHealthConfiguration für die Bundle-Instanzen in einer Datei mit dem Namen 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. Fügen Sie die Konfigurationsdatei dem Service-Bundle-APEX hinzu. In einem 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. Speichern Sie die Gesundheitskonfiguration im APEX und legen Sie health_config_path im Manifest fest:

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

4. Prüfe in der VSIDL-Definition, ob das Bundle com.android.sdv.health.ServiceHeartbeat veröffentlicht:

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

5. Fügen Sie dem Bundle SDV-Berechtigungen hinzu, damit das Bundle zum Veröffentlichen von HBs autorisiert ist:

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

6. Veröffentlichen Sie regelmäßig Service-Heartbeats im Code, beginnend mit 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()
       })?;
     }
   }
   

Sonderfall: Explizite Registrierung

Für spezielle Anwendungsfälle, in denen das Bundle HB-Monitoring für benutzerdefinierte Lebenszyklen benötigt (z. B. Monitoring, das früher beginnt oder später endet als der Standardstatus STARTED), können Sie die explizite Registrierungsmethode verwenden:

1. Fügen Sie in der VSIDL-Definition einen com.android.sdv.health.HealthMonitorRegistrationService-Client hinzu:

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

2. Fügen Sie die SDV-Berechtigung für die Verwendung des RPC zur Registrierung von Aliveness-Heartbeats hinzu:

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

3. Registrieren Sie sich über RPC beim HM, z. B. in on_start oder 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. HBs veröffentlichen

5. Registrierung für das Monitoring aufheben, wenn es nicht mehr benötigt wird:

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

QoS-Monitoring für die Kommunikation hinzufügen

1. Prüfe, ob die Dienstbündelinstanz Abonnent eines Themas mit dem Namen fog-light-status im VSIDL-Katalog ist:

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

   Das Nachrichtenformat ist:

   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. Definieren Sie eine Instanz von ServiceBundleHealthConfiguration für die Bundle-Instanzen in einer health_configuration.textproto-Datei, die QoS-Monitoring umfasst:

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

   Das im Feld key ausgewählte Thema veranschaulicht, dass QoS-HBs zu diesem Thema veröffentlicht werden, sodass ein Thema namens fog-light-status überwacht werden kann.

3. Fügen Sie die Konfigurationsdatei dem Service-Bundle-APEX hinzu. In einem 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. Speichern Sie die Gesundheitskonfiguration im APEX und legen Sie health_config_path im Manifest fest:

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

5. Prüfen Sie in Ihrer VSIDL-Definition, ob das Bundle ein Publisher von com.android.sdv.health.QosHeartbeat ist:

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

6. Fügen Sie dem Bundle SDV-Berechtigungen hinzu, damit das Bundle QoS-HBs veröffentlichen darf:

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

7. Registrieren Sie die QoS-HB-Veröffentlichung nur, wenn die überwachte Kommunikation registriert ist. Verwenden Sie die Availability API von 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. QoS-HBs bei jedem Empfang einer Nachricht veröffentlichen:

   // ...
   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. Wenn Sie die QoS-Überwachung beenden möchten, löschen Sie das Publisher-Objekt:

   // ...
   drop(qos_hb_pub);
   

Statusmonitoring debuggen

Verwenden Sie das dumpsys-Tool, um den Status des VM-Zustandsmonitorings zu überwachen:

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

Der Bericht enthält Details zur Konfiguration der VM-Statusberichterstellung, zur Bundle-Konfiguration und zum Monitoring-Status. Hier sehen Sie ein Beispiel für einen solchen Bericht:

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

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