Statusüberwachung

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

OEM-definierte Dienst-Bundles müssen die verschiedenen vom HM gemeldeten Statussignale überwachen und basierend auf den Daten Wiederherstellungsaktionen ausfü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 Dienst-Bundle-Instanzen. Sie können Dienst-Bundles so konfigurieren, dass sie bei einem Absturz automatisch neu gestartet werden. Der HM liefert Signale, um diesen Wiederherstellungsprozess zu überwachen.
    • Dienstqualität für Kommunikation
  • Lebendigkeit von SDV- und OEM-spezifischen KI-Agenten

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

Terminologie

Diese Begriffe werden auf dieser Seite verwendet.

Aliveness-Heartbeat (HB)
Eine von einem Dienst-Bundle generierte Nachricht, die angibt, dass das Dienst-Bundle aktiv ist. Die Nachricht enthält einen Zeitstempel, der angibt, wann die Nachricht generiert wurde. Weitere Informationen finden Sie unter Heartbeats für die Verfügbarkeit veröffentlichen.

Dienstqualität-Heartbeat (QoS)
SDV unterstützt mehrere Pub/Sub- und RPC-Kommunikationsmodelle (Remote-Prozeduraufruf). Eine Dienst-Bundle-Instanz, die auf Kommunikation wartet, kann QoS-Heartbeats veröffentlichen, sodass der HM-Agent QoS-Verstöße erkennen kann. Weitere Informationen finden Sie unter QoS-Monitoring.

Monitoring der Wiederherstellung von Dienst-Bundles
SDV-Dienst-Bundle-Instanzen können so konfiguriert werden, dass sie bei einem Absturz neu gestartet werden. Eine Instanz kann entweder erfolgreich wiederhergestellt werden oder die Wiederherstellung schlägt fehl. Der HM verfolgt den Wiederherstellungsstatus der Dienst-Bundle-Instanz und meldet Wiederherstellungsfehler im Rahmen des VM-Zustandsberichts. Weitere Informationen finden Sie unter Wiederherstellung von Dienst-Bundles überwachen.

Monitoring von Abstürzen des KI-Agenten
Im Gegensatz zu Dienst-Bundle-Instanzen sind SDV-Agents für das korrekte Verhalten des Systems entscheidend. Sie sind nicht für die Wiederherstellung konfigurierbar und sollten daher nie abstürzen. Der HM überwacht SDV-Agents und meldet Abstürze im Rahmen des VM-Zustandsberichts. Das Monitoring benutzerdefinierter OEM-Agenten ist möglich. Weitere Informationen finden Sie unter Monitoring von Agent-Abstürzen.

VM-Zustandsbericht
Eine vom HM generierte Nachricht, die den Zustand der VM angibt. Weitere Informationen finden Sie unter VM-Integritätsbericht.

Mit dem HM-Subsystem arbeiten

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

  • Konfigurieren Sie das System zur Zustandsüberwachung, indem Sie Konfigurationsdateien bereitstellen, wie unter HM-System konfigurieren beschrieben.
  • Verwende ein OEM-definiertes HM-Listener-Dienst-Bundle, um die HM-Ausgabe zu überwachen und entsprechende Maßnahmen zu ergreifen.
  • Entwickeln Sie Dienst-Bundles, die gemäß ihrer Integritätskonfiguration aktiv Signale veröffentlichen. Anhand dieser Veröffentlichung kann der HM den Systemzustand bewerten. Weitere Informationen finden Sie in den Entwicklerleitfäden für Dienst-Bundles.

HM-System konfigurieren

Alle HM-bezogenen Konfigurationen befinden sich in einem der folgenden Konfigurationstypen:

  • Eine globale VM-Zustandskonfiguration
  • Eine dienstspezifische Bundle-Zustandskonfiguration, die Zustandsparameter für alle Instanzen des Bundles definiert

Zustandskonfiguration pro VM

Zur Laufzeit erwartet der HM-Agent eine VM-weite Systemdiagnosekonfiguration: 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-Zustandskonfiguration sollte sich im Pfad befinden, der mit dem Systemattribut androidboot.sdv.health_monitor.config_path für die Bootzeit angegeben wurde. Alternativ können Sie dies dynamisch zur Laufzeit 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.

In der VM-Zustandskonfiguration können Sie Folgendes festlegen:

  • Häufigkeit des VM-Zustandsberichts über period_ms. Die Einstellung ist ein Kompromiss zwischen einer schnelleren Signalisierung, dass Integritätsverletzungen erkannt wurden, und der Leistung des HM-Subsystems. Wir empfehlen einen Wert von 100 ms.

  • Welche Agenten auf Abstürze überwacht werden sollen (siehe Absturzüberwachung für Agenten).

Beispiele für Konfigurationsdateien finden Sie unter //system/software_defined_vehicle/health_monitor/src/prod_configs/. Hier ist eine Beispielkonfigurationsdatei:

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 die SDV-DT- und RPC-Agents für das Absturzmonitoring konfiguriert und der VM-Zustandsbericht wird so konfiguriert, dass er alle 100 ms veröffentlicht wird.

Konfiguration pro Dienst-Bundle

Das Zustandsmonitoring von Dienst-Bundle-Instanzen ist optional. Wenn du die Funktion aktivieren möchtest, speichere die Konfigurationsdatei für die Integrität im APEX deines Dienst-Bundles und definiere einen Pfad dazu im Feld health_config_path von sdv_service_bundle_metadata in sdv_service_bundles_manifest.textproto. Weitere Informationen zu Service-Bundle-Manifesten finden Sie unter Service-Bundle-Metadaten.

Die Konfigurationsdatei für den Zustand 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 des Aliveness-Heartbeats 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 Feature finden Sie unter Monitoring von Aliveness-Heartbeats und QoS-Monitoring.

HM-Ausgabe anhören

Sie können den HM entweder über regelmäßige Berichte oder eine RPC API abhören.

VM-Zustandsbericht

Beim Monitoring des Systemzustands wird regelmäßig ein hochfrequenter VM-Systemzustandsbericht erstellt, der prägnante Informationen zum Systemzustand der überwachten Entitäten 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 OEM-definiertes HM-Listener-Dienst-Bundle sollte auf VMHealth-Berichte warten und je nach Gesamtsystemarchitektur entsprechende Maßnahmen ergreifen. Mögliche Aktionen:

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

HM RPC API

Der VM-Zustandsbericht ist eine Veröffentlichung, die für Häufigkeit und Übertragungsgeschwindigkeit optimiert ist und umfassende Informationen zum Systemzustand bietet.

Mit der HM RPC API kann der HM-Listener detaillierte Informationen zur Quelle von Integritätsverstößen abrufen. Die Schnittstelle ist in //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto definiert. Die Schnittstelle wird hier der Einfachheit halber wiedergegeben:

// 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 ausführlicher beschrieben.

Monitoring von Aliveness-Heartbeats

Wenn das Monitoring der Aktivität für eine Dienst-Bundle-Instanz 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 Dienst-Bundle-Instanzen, die regelmäßige Aufgaben ausführen. Außerdem können Bundles, die asynchrone Laufzeiten verwenden, mithilfe des Aliveness-Monitorings nachweisen, dass der Thread-Pool nicht erschöpft ist.

HM-Ablauf zur Überwachung der Aktivität

Abbildung 1. Ablauf der HM-Aktivitätsüberwachung.

Konfiguration

Wenn Sie den Aktivitäts-HB für eine Dienst-Bundle-Instanz aktivieren möchten, fügen Sie dem Feld health_config in der Bundle-Konfiguration eine Instanz von HealthConfiguration hinzu.

Eine Konfiguration für den Aktivitäts-Heartbeat definiert eine vordefinierte Gruppe 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 Dienst-Bundle als fehlerhaft eingestuft. Dies kann auf einen nicht optimalen Betriebszustand hinweisen.

Ein Dienst-Bundle gilt als fehlerfrei, wenn es gemäß seiner Systemdiagnosekonfiguration rechtzeitig Heartbeats meldet. Im Falle eines Absturzes oder einer hohen Systemlast kann ein Heartbeat fehlen oder verzögert sein, was dazu führt, dass das Dienst-Bundle als fehlerhaft markiert wird. In diesem Fall wird im Bericht VmHealth ein Verstoß angezeigt.

Entwickler von Dienst-Bundles sollten die Integritätskonfiguration eines Dienst-Bundles in den entsprechenden APEX-Metadaten definieren. In der Konfiguration der Systemdiagnose werden die folgenden Kriterien definiert:

  • Die maximal zulässige anfängliche Verzögerung zwischen dem Dienststart und der ersten Heartbeat-Erkennung.

  • Der Zeitraum, in dem das SDV-Dienst-Bundle die Geschäftslogik ausführt. Dies entspricht der Periodizität der Veröffentlichung eines Dienst-Heartbeats.

  • Die Anzahl der Zeiträume, die verpasst werden müssen, bevor der HM das Dienst-Bundle als fehlerhaft einstuft.

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

Das Dienst-Bundle generiert einen Integritätsverstoß, wenn der Dienst-Heartbeat verzögert ist. Es gibt zwei Fälle, die auf dem Zeitpunkt der Integritätsbeobachtung basieren:

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

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

Das Format der Systemdiagnosekonfiguration 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 zum korrekten Registrieren für das Monitoring.

Heartbeats zur Verfügbarkeit veröffentlichen

Eine Dienst-Bundle-Instanz generiert eine Dienst-Heartbeat-Nachricht, die einen Zeitstempel enthält. Generieren Sie die Nachricht routinemäßig, in der Regel direkt nach der Ausführung der Hauptgeschäftslogik. Der Dienst-Heartbeat gibt an, dass das Dienst-Bundle aktiv ist.

Das zu überwachende Bundle-Instanzobjekt muss einen Publisher vom Typ ServiceHeartbeat erstellen, 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 Veröffentlichung zu erkennen.

Wenn Sie das Aktivitätsmonitoring über die im entsprechenden Dienst-Bundle-Manifest verknüpfte Systemdiagnosekonfiguration 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 ein Blockieren des Systemstarts zu vermeiden. Veröffentlichen Sie Heartbeats daher in einer asynchronen Aufgabe, die in on_start gestartet wird.

Bundle-Entwickler können den Zeitpunkt, zu dem 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 die on_stop-Routine abgeschlossen ist.

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

Das unter Monitoring von Aktivitäts-Heartbeats beschriebene Verhalten, bei dem Heartbeats zwischen on_start und on_stop erwartet werden, wird als implizites Aktivitätsmonitoring bezeichnet. Dies ist die empfohlene Methode, um das Feature zu verwenden: Sie vereinfacht die Geschäftslogik des Bundles und sorgt dafür, dass das Bundle immer überwacht wird.

Es kann jedoch Anwendungsfälle geben, in denen der Standard-Monitoring-Zeitraum eine Einschränkung darstellt:

  • Eine Dienst-Bundle-Instanz enthält Geschäftslogik, die in einem Zeitintervall periodisch ist, 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 verfolgt die HBs während der Sperr- und Fortsetzungszeiträume genau. Daher sollte das Bundle möglicherweise auch nach on_stop weiter überwacht werden.
  • Benutzerdefinierte OEM-Agenten werden möglicherweise nicht als Dienst-Bundles implementiert. Daher können sie nicht vom impliziten Aktivitätsmonitoring 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 das Aktivitätsmonitoring zugunsten der expliziten Registrierung umgehen. Wenn Sie die explizite Registrierung verwenden möchten, muss eine Bundle-Instanz die implizite Registrierung deaktivieren. Dazu darf im Manifest des Bundles kein Eintrag vom Typ HealthConfiguration für die jeweilige Instanz enthalten sein. Anschließend sollte die Bundle-Instanz zur Laufzeit 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 abzumelden. Veröffentlichte Heartbeats werden erwartet, sobald der RPC-Aufruf für die Registrierung erfolgreich ist.

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

QoS-Monitoring

Die 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 ob bei regelmäßiger Kommunikation Nachrichten nicht mit der gewählten Häufigkeit empfangen werden.

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

Konfiguration

Wenn Sie das QoS-Monitoring einer Kommunikation aktivieren möchten, müssen Sie zuerst den Kommunikations-Listener identifizieren, der den QoS-Heartbeat veröffentlicht. Fügen Sie dann für die identifizierte Dienst-Bundle-Instanz im Feld qos_config eine oder mehrere Zuordnungen von Themen zu QosMonitoringConfiguration hinzu. Weitere Informationen finden Sie unter Dienstspezifische Bundle-Konfiguration.

Das Thema ist ein String, der das Veröffentlichungsthema definiert, in dem der HM zur Laufzeit QoS-HBs erwartet. Eine Listening-Bundle-Instanz kann an mehreren Kommunikationen teilnehmen und QoS-HBs zu mehreren Themen melden.

Themen sollten aussagekräftig sein, da sie an das HM-Listener-Dienst-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;
}

Erzwingen Sie für Standardanwendungsfälle beide Arten von QoS-Monitoring. Ein qos_latency_threshold_ms-Wert von 30 ist für die Pub/Sub-Kommunikation innerhalb der VM bei normaler Systemlast angemessen.

Überlegungen zur Laufzeit

Ähnlich wie beim HB-Monitoring der Aktivität wird erwartet, dass das Kommunikations-Listening-Bundle eine Art Heartbeat veröffentlicht. In diesem Fall sollte ein QoS-HB veröffentlicht werden, wenn relevante Nachrichten empfangen werden, und nicht am Ende der Ausführung der Geschäftslogik.

Ein QoS-HB ist vom 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. Der HM erwartet QoS-HBs zwischen diesen beiden Ereignissen. Das Message Listening Bundle sollte die QoS-HB-Veröffentlichung registrieren, wenn die überwachte Kommunikation beim SDV-Kommunikationsstack registriert wird. Der HM kann dazu die Availability API verwenden. Weitere Informationen finden Sie unter Dienstverfügbarkeit ermitteln.

Monitoring der Wiederherstellung von Dienst-Bundles

Die Wiederherstellung von Dienst-Bundle-Instanzen wird im Rahmen der Konfigurationsdateien des Orchestrierungs-Agents konfiguriert. Eine vollständige Beschreibung des Themas finden Sie unter Dienst-Bundles. Das HM-Subsystem beobachtet den Wiederherstellungsprozess passiv. Wenn die Wiederherstellung einer Bundle-Instanz fehlschlägt, wird dem Bericht VMHealth ein Verstoß hinzugefügt. Im Gegensatz zu den anderen HM-Monitoring-Funktionen ist das Wiederherstellungsmonitoring obligatorisch und nicht konfigurierbar.

Abstürze von Dienst-Bundle-Instanzen, die nicht für die Wiederherstellung konfiguriert sind, führen beim ersten Absturz zu einem Integritätsverstoß.

Die Wiederherstellung von Dienst-Bundle-Instanzen ist für die Einbindung in das Heartbeat-Monitoring konzipiert. Das HM-System ist bei der Bewertung von Herzschlägen nachsichtiger, wenn es feststellt, dass sich das Bundle erholt. In der Praxis bedeutet diese Nachsicht, dass Service Bundles keine zusätzlichen Schritte zur Abmeldung oder Registrierung des Monitorings unternehmen müssen, wenn sie abstürzen.

Monitoring von Agent-Abstürzen

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

Sie können das Absturzmonitoring im Rahmen der VM-Zustandskonfiguration konfigurieren (siehe Konfiguration pro SDV-Instanz (VM)), insbesondere das wiederkehrende 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, müssen Sie den HM-SELinux-Berechtigungen die Berechtigung erteilen, die entsprechende Binder-Schnittstelle abzuhören.

Mit dem Systemattribut ro.boot.sdv.health_monitor.agent_startup_timeout_sec kann überschrieben werden, wie lange der HM wartet, bis Agents ihre Binder-Schnittstellen registrieren, nachdem der HM gestartet wurde. Sofern nicht für benutzerdefinierte Agents erforderlich, ist der Standardwert von drei Sekunden angemessen.

Entwicklungsleitfäden für Dienst-Bundles

In diesem Abschnitt finden Sie detaillierte Anleitungen zur Verwendung von HM-Funktionen aus Dienst-Bundles, im Gegensatz zur theoretischen Behandlung in den vorherigen Abschnitten. Das aktuelle Referenzbeispiel, auf dem diese Anleitungen basieren, ist das Beispiel qos_monitoring. Folgen Sie der //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README des Beispiels, um praktische Erfahrungen zu sammeln.

Heartbeat-Monitoring für die Aktivität zu einem Dienst-Bundle hinzufügen

Diese Methode ist die direkteste Möglichkeit, das Zustandsmonitoring für ein Dienst-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 APEX-Dienst-Bundle 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. Speichere die Konfiguration für die Systemdiagnose im APEX-Bundle und lege health_config_path im Manifest fest:

    # sdv_service_bundles_manifest.textproto
    sdv_service_bundle_metadata {
      ...
      health_config_path: "etc/config/health_configuration.textproto"
    }
    
  4. Achten Sie darauf, dass das Bundle in der VSIDL-Definition 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 HBs veröffentlichen darf:

      publisher {
        type: "com.android.sdv.health.ServiceHeartbeat"
      }
    
  6. Veröffentlichen Sie regelmäßig Dienst-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()
        })?;
      }
    }
    

Besonderer Anwendungsfall: Explizite Registrierung

Für speziellere Anwendungsfälle, bei denen das Bundle ein HB-Monitoring für benutzerdefinierte Lebenszyklen erfordert (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 für die Registrierung des Aktivitäts-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. Heben Sie die Registrierung für das Monitoring auf, wenn Sie es nicht mehr benötigen:

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

QoS-Monitoring zur Kommunikation hinzufügen

  1. Prüfen Sie, ob die Dienst-Bundle-Instanz ein 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;
    
      // A QoS-monitored message must 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 enthält:

    # 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 zeigt, 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 APEX-Dienst-Bundle 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. Speichere die Health-Konfiguration im APEX-Bundle und lege health_config_path im Manifest fest:

    # sdv_service_bundles_manifest.textproto
    sdv_service_bundle_metadata {
      ...
      health_config_path: "etc/config/health_configuration.textproto"
    }
    
  5. Achten Sie in Ihrer VSIDL-Definition darauf, dass 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 Verfügbarkeits-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 jedes Mal veröffentlichen, wenn eine Nachricht empfangen wird:

    // ...
    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. Löschen Sie das Publisher-Objekt, um das QoS-Monitoring zu beenden:

    // ...
    drop(qos_hb_pub);
    

Statusmonitoring debuggen

Verwenden Sie für die Fehlerbehebung und Systemübersicht das Tool dumpsys, um den Status der VM-Zustandsüberwachung zu überwachen:

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

Der Bericht enthält Details zur Konfiguration der VM-Zustandsberichte, zur Bundle-Konfiguration und zum Monitoring-Status. Hier 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

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