2026 年より、トランク安定版開発モデルに沿ってエコシステムのプラットフォームの安定性を確保するため、第 2 四半期と第 4 四半期に AOSP にソースコードを公開します。AOSP のビルドと投稿には、android-latest-release を使用します。android-latest-release マニフェストブランチは、常に AOSP にプッシュされた最新のリリースを参照します。詳細については、AOSP の変更点をご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

稼働状況のモニタリング

ヘルスモニター（HM）は、各仮想マシン（VM）で実行される SDV エージェントです。サービスバンドルの状態を追跡し、VM の健全性を判断し、VM の健全性レポートを定期的に生成します。

OEM 定義のサービスバンドルは、HM によってレポートされるさまざまなヘルスシグナルをリッスンし、データに基づいて復元アクションを実行する必要があります。たとえば、サービスバンドルがクラッシュしている SDV インスタンスは、再起動または更新が必要になる場合があります。

次の項目を追跡するように HM エージェントを構成できます。

存続シグナルをモニタリングして、定期的なタスクを実行するエンティティの存続ステータスを取得します。このモニタリングは、サービスバンドルインスタンスとカスタム OEM エージェントの両方で構成できます。
- サービスバンドルインスタンスの復元状態。SDV 2.0 では、クラッシュ時に自動的に再起動するようにサービスバンドルを構成できます。HM は、この復元プロセスをモニタリングするためのシグナルを提供します。
- 通信 QoS
SDV と OEM カスタムエージェントの稼働状況

リファレンスとして、プロトコル定義を含む完全な VSIDL カタログは //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl で入手できます。

用語

このページでは以下の用語を使用します。

存続性ハートビート（HB）

サービスバンドルがアクティブであることを示すためにサービスバンドルによって生成されるメッセージ。メッセージには、メッセージが生成された日時を示すタイムスタンプが含まれます。詳細については、存続シグナルをパブリッシュするをご覧ください。

サービス品質（QoS）ハートビート

SDV は、複数の Pub/Sub およびリモートプロシージャコール（RPC）通信モデルをサポートしています。通信をリッスンしているサービスバンドルインスタンスは、QoS ハートビートをパブリッシュできます。これにより、HM エージェントは QoS 違反を検出できます。詳細については、QoS モニタリングをご覧ください。

サービスバンドル復元のモニタリング

SDV サービスバンドルインスタンスは、クラッシュした場合に再起動するように構成できます。インスタンスは、正常に復元されるか、復元に失敗します。HM はサービスバンドルインスタンスの復元状態を追跡し、復元失敗を VM ヘルスレポートの一部として報告します。詳細については、サービスバンドルの復元モニタリングをご覧ください。

エージェントのクラッシュモニタリング

サービスバンドルインスタンスとは異なり、SDV エージェントはシステムの正しい動作に不可欠です。リカバリ用に構成できないため、クラッシュすることはありません。HM は SDV エージェントをモニタリングし、クラッシュを VM ヘルスレポートの一部として報告します。カスタム OEM エージェントのモニタリングは可能です。詳細については、エージェントクラッシュのモニタリングをご覧ください。

VM の健全性レポート

HM によって生成され、VM の健全性を示すメッセージ。詳細については、VM ヘルスレポートをご覧ください。

HM サブシステムを操作する

HM 機能を使用するには、OEM 実装で次のことを行う必要があります。

HM システムを構成するで説明されているように、構成ファイルを提供してヘルスモニタリングシステムを構成します。
OEM 定義の HM リスナーサービスバンドルを使用して HM 出力をリッスンし、適切なアクションを実行します。
ヘルス構成に従ってシグナルを積極的に公開するサービスバンドルを開発します。このパブリケーションにより、HM は健康状態を評価できます。詳しくは、サービスバンドルのデベロッパーガイドをご覧ください。

HM システムを構成する

HM 関連の構成は、次のいずれかの構成タイプに存在します。

VM ごとのグローバルなヘルス構成
サービスバンドルごとのヘルス構成。バンドルのすべてのインスタンスのヘルスパラメータを定義します。

VM ごとの健全性構成

実行時に、HM エージェントは VM 全体のヘルス構成を想定しています。これは、//system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto で定義された VMHealth 型の textproto ファイル（.textproto 拡張子付き）です。VM Health 構成は、起動時のシステムプロパティ androidboot.sdv.health_monitor.config_path を使用して指定されたパスに配置する必要があります。または、persist.sdv.health_monitor.config_path システムプロパティをカスタムパスに設定して、実行時に動的に構成することもできます。persist.* 設定は androidboot.* 設定よりも優先されます。新しい構成を有効にするには、デバイスを再起動する必要があります。

VM の健全性構成では、次の設定を行うことができます。

period_ms を介した VM ヘルスレポートの定期性。この設定は、健全性違反が検出されたことをより迅速に通知することと、HM サブシステムのパフォーマンスとのトレードオフになります。100 ミリ秒の値をおすすめします。
クラッシュモニタリングの対象となるエージェント（エージェントのクラッシュモニタリングを参照）。

構成ファイルの例は //system/software_defined_vehicle/health_monitor/src/prod_configs/ にあります。構成ファイルの例を次に示します。

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

この例では、SDV DT エージェントと RPC エージェントがクラッシュモニタリング用に構成され、VM ヘルスレポートが 100 ミリ秒ごとに公開されるように構成されています。

サービスバンドルごとの構成

サービスバンドルインスタンスのヘルスモニタリングは省略可能です。オプトインするには、サービスバンドルの APEX にヘルス構成ファイルを保存し、sdv_service_bundles_manifest.textproto の sdv_service_bundle_metadata の health_config_path フィールドでそのパスを定義します。サービスバンドルマニフェストの詳細については、サービスバンドルのメタデータをご覧ください。

ヘルス構成ファイルは、次のタイプの textproto ファイルです。

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

インスタンスごとに、存続可能性のハートビート構成と 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;
}

機能ごとの構成の詳細については、存続シグナルのモニタリングと QoS モニタリングをご覧ください。

HM 出力をリッスンする

HM は、定期的なレポートまたは RPC API を介してリッスンできます。

VM の健全性レポート

ヘルスモニタリングは、高頻度の定期的な VM ヘルスレポートを生成し、モニタリング対象エンティティのヘルス状態に関する簡潔な情報を提供します。

VmHealth の型構文は //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;
}

OEM 定義の HM リスナーサービスバンドルは、VMHealth レポートをリッスンし、完全なシステムアーキテクチャに応じて適切なアクションを実行する必要があります。考えられる対応は次のとおりです。

VM で診断ルーティンを実行します。
VM を再起動します。
テレメトリーキャンペーンを実行して原因を特定します。
システムが誤動作している場合は、システムを更新するか、更新を停止します。

HM RPC API

VM ヘルスレポートは、頻度と伝送速度に最適化されたパブリケーションで、システムの健全性ステータスに関する広範な情報を提供します。

HM RPC API を使用すると、HM リスナーはヘルス違反のソースに関する詳細情報を取得できます。インターフェースは //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto で定義されます。便宜上、インターフェースを以下に示します。

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

機能の詳細な説明

このセクションでは、HM のさまざまな側面について詳しく説明します。

Aliveness ハートビートのモニタリング

サービスバンドルインスタンスに稼働状況モニタリングが構成されている場合、HM は、ビジネスロジックが正しく動作していることを証明するために、インスタンスが定期的なハートビートをパブリッシュすることを想定しています。このモニタリングは、定期的なタスクを実行するサービスバンドルインスタンスに最適です。また、非同期ランタイムを使用するバンドルは、活性モニタリングを使用して、スレッドプールが枯渇していないことを証明できます。

HM 稼働状況モニタリングフロー

図 1. HM の存続可能性モニタリングフロー。

構成

サービスバンドルインスタンスで存続性 HB を有効にするには、バンドル構成の health_config フィールドに HealthConfiguration のインスタンスを追加します。

存続性ハートビート構成は、サービスの定期的なハートビート信号を評価するための基準を確立する、事前定義されたパラメータのセットを定義します。サービスハートビートの特性がこれらのパラメータから逸脱すると、ハートビートは遅延として分類され、対応するサービスバンドルは異常と分類されます。これは、最適な運用状態ではないことを示している可能性があります。

サービスバンドルは、ヘルス構成に従ってハートビートを時間どおりに報告すると、正常とみなされます。クラッシュやシステム負荷が高い場合、ハートビートが欠落または遅延し、サービスバンドルが異常とマークされることがあります。この場合、違反が VmHealth レポートに表示されます。

サービスバンドルデベロッパーは、対応する APEX メタデータでサービスバンドルのヘルス構成を定義する必要があります。ヘルス構成では、次の条件が定義されます。

サービスの開始から最初のハートビート検出までの最大初期遅延。
SDV サービスバンドルがビジネスロジックを実行する期間。サービスのハートビートを公開する周期に対応します。
HM がサービスバンドルを異常とみなすまでに欠落する期間の数。

注: この数は 1 または 2 にすることをおすすめします。
実行時間は、SDV サービスバンドルがサービスハートビートを公開する前にビジネスロジックを実行するために必要な時間です。

サービスハートビートが遅延すると、サービスバンドルは健全性違反を生成します。ヘルスモニタリングのタイミングに基づいて、次の 2 つのケースがあります。

ケース 1: 最初のハートビートが受信されませんでした。サービスバンドルの開始からモニタリングの時点までの経過時間が、許容される初期遅延を超えている場合、サービスバンドルは異常と見なされます。
ケース 2: ハートビートはすでに受信されています。最後のハートビートとモニタリングの時刻の間にしきい値が経過した場合、サービスバンドルは異常と見なされます。この基準は、レポート対象期間（期間数で乗算）とタスクの期間の合計として計算されます。

ヘルス構成の形式は //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;
}

実行時の考慮事項

このセクションでは、存続シグナルを公開し、モニタリング用に正しく登録するためのガイダンスを提供します。

存続期間のハートビートを公開する

サービスバンドルインスタンスは、タイムスタンプを含むサービスハートビート メッセージを生成します。通常はメインのビジネスロジックが実行された直後に、メッセージを定期的に生成します。サービスハートビートは、サービスバンドルがアクティブであることを示します。

モニタリング対象のバンドルインスタンスオブジェクトは、libhealth_api ライブラリで利用可能な ServiceHeartbeat 型のパブリッシャーを作成する必要があります。

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

パブリケーションのトピックを任意に選択します。HM エージェントは、メッセージタイプによる検出を使用してパブリケーションを検出します。

対応するサービスバンドルマニフェストにリンクされているヘルス構成を通じて実行状況のモニタリングを構成する場合、HM エージェントは、インスタンスが on_start ルーティンを完了するとすぐに HB が公開されることを想定しています。システムの起動をブロックしないように、on_start を短くすることをおすすめします。そのため、on_start で開始された非同期タスクでハートビートを公開します。

バンドルデベロッパーは、initial_delay_ms 構成エントリを使用して、最初のハートビートが想定される時間をカスタマイズできます。

バンドルインスタンスは、停止されるまでハートビートのパブリッシュを継続する必要があります。インスタンスの on_stop ルーティンが終了すると、インスタンスは停止したと見なされます。

特別なユースケース: ハートビートモニタリングに明示的に登録する

存続性ハートビートのモニタリングで説明されている、on_start と on_stop の間でハートビートが想定される動作は、暗黙的な存続性モニタリングと呼ばれます。この機能を使用する場合は、この方法をおすすめします。バンドルのビジネスロジックが簡素化され、バンドルが常にモニタリングされるようになります。

ただし、デフォルトのモニタリング期間が制限となるユースケースもあります。

サービスバンドルインスタンスには、start イベントと stop イベントにリンクされていない時間間隔で定期的に実行されるビジネスロジックが含まれています。このカスタム期間でのみ、存続可能性のモニタリングが必要になることがあります。
HM は、停止期間と再開期間にわたって HB を正確に追跡します。そのため、バンドルは on_stop 後もモニタリングを継続したい場合があります。
カスタム OEM エージェントはサービスバンドルとして実装されない場合があります。したがって、暗黙的な活性モニタリングのメリットを享受できません。ただし、存続性モニタリングが必要になる場合があります。

このような場合、HM では、暗黙的な登録をバイパスして、明示的な登録を行うことができます。明示的な登録を使用するには、バンドルインスタンスのバンドルマニフェストに、そのインスタンスの HealthConfiguration 型のエントリを含めないことで、暗黙的な登録をオプトアウトする必要があります。実行時に、バンドルインスタンスは //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto で定義された RPC API を使用して、モニタリングへの登録と登録解除を手動で行う必要があります。登録 RPC 呼び出しが成功すると、すぐに公開されたハートビートが想定されます。

実装例については、//system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/ をご覧ください。

QoS モニタリング

Quality of Service（QoS）は、コミュニケーションの測定値です。HM は、送信されたメッセージが転送に時間がかかりすぎているかどうか、または定期的な通信の場合に、選択した頻度でメッセージが受信されていないかどうかをモニタリングします。

SDV は、Pub/Sub と RPC 通信のいくつかのフレーバーを提供します。すべての通信スキームに少なくとも 1 つのリスナーが含まれていることが共通の分母です。HM が通信をモニタリングするには、このリスニングサービスバンドルインスタンスが、対象のメッセージを受信するたびに特別な QoS ハートビートをパブリッシュする必要があります。

構成

通信の QoS モニタリングを有効にするには、まず QoS ハートビートをパブリッシュする通信リスナーを特定します。次に、特定されたサービスバンドルインスタンスの qos_config フィールドに、1 つ以上のトピックと QosMonitoringConfiguration マッピングを追加します。詳細については、サービスごとのバンドル構成をご覧ください。

topic は、HM が実行時に QoS HB を想定するパブリケーショントピックを定義する文字列です。リスニングバンドルインスタンスは複数の通信に参加でき、複数のトピックで QoS HB をレポートできます。

トピックは、実行時に QoS 違反が検出された場合に HM リスナーサービスバンドルにレポートされるため、説明的なものにする必要があります。

QosMonitoringConfiguration 型は //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;
}

デフォルトのユースケースでは、両方のタイプの QoS モニタリングを適用します。通常のシステム負荷での VM 内 Pub/Sub 通信では、30 の qos_latency_threshold_ms が妥当です。

実行時の考慮事項

生存性 HB モニタリングと同様に、通信リスニングバンドルはハートビートのタイプを公開することが想定されています。この場合、ビジネスロジックの実行の終了時ではなく、対象のメッセージが受信されるたびに QoS HB が公開される必要があります。

QoS HB は //system/software_defined_vehicle/health_monitor/catalog/qos_heartbeat.proto で定義される QosHeartbeat 型です。

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

QoS HB パブリケーションの登録と登録解除のタイミングは、正確なモニタリングに不可欠です。HM は、これらの 2 つのイベント間で QoS HB を想定しています。メッセージリスニングバンドルは、モニタリング対象の通信が SDV 通信スタックに登録されたときに、QoS HB パブリケーションを登録する必要があります。HM は、可用性 API を使用してこれを行うことができます。詳細については、サービスの可用性を確認するをご覧ください。

サービスバンドルの復元モニタリング

サービスバンドルインスタンスの復元は、オーケストレーションエージェント構成ファイルの一部として構成されます。このトピックの詳細については、サービスバンドルをご覧ください。HM サブシステムは、復元プロセスをパッシブに監視します。バンドルインスタンスの復元に失敗すると、違反が VMHealth レポートに追加されます。他の HM モニタリング機能とは異なり、復元モニタリングは必須であり、構成できません。

復元用に構成されていないサービスバンドルインスタンスがクラッシュすると、最初クラッシュ時に健全性違反が生成されます。

サービスバンドルインスタンスの復元は、ハートビートの存続モニタリングと統合するように設計されています。バンドルが復元中であることを検出すると、HM システムは心拍数の評価をより緩やかに行います。実際には、この寛大さにより、サービスバンドルがクラッシュした場合、追加のモニタリング登録解除や登録の手順を行う必要がなくなります。

エージェントのクラッシュのモニタリング

HM は、バインダ linkToDeath メカニズムを使用して SDV エージェントのクラッシュの可能性を検出します。

クラッシュモニタリングは、VM の健全性構成（SDV インスタンス（VM）ごとの構成を参照）の一部として、具体的には monitored_agent 繰り返しフィールドとして構成できます。このフィールドには、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;
}

エージェントがバインダインターフェースを公開している場合は、カスタムエージェントもモニタリングできます。カスタムエージェントをモニタリングするには、適切なバインダーインターフェースをリッスンする HM SELinux 権限を付与します。

システムプロパティ ro.boot.sdv.health_monitor.agent_startup_timeout_sec は、HM が起動してからエージェントがバインダインターフェースを登録するまで HM が待機する時間をオーバーライドできます。カスタムエージェントで必要な場合を除き、デフォルトの 3 秒が適切です。

サービスバンドルデベロッパーガイド

このセクションでは、前のセクションの理論的な扱いとは対照的に、サービスバンドルから HM 機能を使用する方法について段階的に説明します。これらのガイドの基盤となる最新の参照サンプルは、qos_monitoring サンプルです。実際の操作については、サンプルの //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README をご覧ください。

サービスバンドルに存続可能性のハートビートモニタリングを追加する

この方法は、サービスバンドルのヘルスモニタリングを有効にする最も直接的な方法です。

health_configuration.textproto という名前のファイルで、バンドルインスタンスの ServiceBundleHealthConfiguration のインスタンスを定義します。

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

  }
}

構成ファイルをサービスバンドル APEX に追加します。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"],
}

ヘルス構成を APEX に保存し、マニフェストで health_config_path を設定します。

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

VSIDL 定義で、バンドルが com.android.sdv.health.ServiceHeartbeat を公開していることを確認します。
```
sdv_service_bundle {
  name: "SampleBundle"
  publisher {
    message: "com.android.sdv.health.ServiceHeartbeat"
    topic: "arbitrary-topic"
    capacity: 2
  }
}
```
注: トピックは任意に選択できます。
バンドルに SDV 権限を追加して、バンドルが HB を公開する権限を持つようにします。
```
  publisher {
    type: "com.android.sdv.health.ServiceHeartbeat"
  }
```

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()
    })?;
  }
}

特別なユースケース: 明示的な登録

バンドルがカスタムライフサイクル（標準の STARTED 状態よりも早く開始または遅く終了するモニタリングなど）の HB モニタリングを必要とする特別なユースケースでは、明示的な登録メソッドを使用できます。

VSIDL 定義に com.android.sdv.health.HealthMonitorRegistrationService クライアントを追加します。

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

aliveness HB 登録 RPC を使用するための SDV 権限を追加:

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

RPC を介して HM に登録します（on_start や 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();

HB を公開します。

不要になったらモニタリングの登録を解除します。

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

通信に QoS モニタリングを追加する

サービスバンドルインスタンスが VSIDL カタログの fog-light-status という名前のトピックのサブスクライバーであることを確認します。

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

メッセージの形式は次のとおりです。

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

QoS モニタリングを含む health_configuration.textproto ファイルで、バンドルインスタンスの ServiceBundleHealthConfiguration のインスタンスを定義します。
```
# 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 }
    }
  }
}
```
key フィールドで選択されたトピックは、QoS HB がこのトピックに公開され、fog-light-status というトピックのモニタリングが可能になることを示しています。

構成ファイルをサービスバンドル APEX に追加します。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"],
}

ヘルス構成を APEX に保存し、マニフェストで health_config_path を設定します。

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

VSIDL 定義で、バンドルが 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
  }
}
```
重要: トピックは、ヘルス設定で指定されたトピックエントリと一致している必要があります。

バンドルに SDV 権限を追加して、バンドルが QoS HB を公開できるようにします。

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

モニタリング対象の通信が登録されている場合にのみ、QoS HB パブリケーションを登録します。libsdv_mw_clientlib の可用性 API を使用します。

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

// ...

メッセージを受信するたびに QoS HB をパブリッシュします。

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

QoS モニタリングを停止するには、パブリッシャーオブジェクトを削除します。
```
// ...
drop(qos_hb_pub);
```
注: 通信が登録されたときに QoS モニタリングを登録し、モニタリングが不要になったときに登録を解除するメカニズムは、1 回限りのメッセージの QoS モニタリングを可能にするのに十分な柔軟性があります。1 回限りのメッセージを受信したときに 1 回限りの HB を送信した後、QoS HB パブリッシャーをドロップします。

ヘルスモニタリングをデバッグする

デバッグとシステム概要の目的で、dumpsys ツールを使用して VM のヘルスモニタリング状態をモニタリングします。

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

レポートには、VM のヘルスレポート構成、バンドル構成、モニタリングの状態が詳しく記載されています。このようなレポートの例を次に示します。

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

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

稼働状況のモニタリング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

用語

HM サブシステムを操作する

HM システムを構成する

VM ごとの健全性構成

サービス バンドルごとの構成

HM 出力をリッスンする

VM の健全性レポート

HM RPC API

機能の詳細な説明

Aliveness ハートビートのモニタリング

構成

実行時の考慮事項

存続期間のハートビートを公開する

特別なユースケース: ハートビート モニタリングに明示的に登録する

QoS モニタリング

構成

実行時の考慮事項

サービス バンドルの復元モニタリング

エージェントのクラッシュのモニタリング

サービス バンドル デベロッパー ガイド

サービス バンドルに存続可能性のハートビート モニタリングを追加する

特別なユースケース: 明示的な登録

通信に QoS モニタリングを追加する

ヘルス モニタリングをデバッグする

稼働状況のモニタリング

サービスバンドルごとの構成

特別なユースケース: ハートビートモニタリングに明示的に登録する

サービスバンドルの復元モニタリング

サービスバンドルデベロッパーガイド

サービスバンドルに存続可能性のハートビートモニタリングを追加する

ヘルスモニタリングをデバッグする