Theo dõi sức khỏe

Health Monitor (HM) là một tác nhân SDV chạy trên mỗi máy ảo (VM) để theo dõi trạng thái của các gói dịch vụ, xác định tình trạng của VM và định kỳ tạo báo cáo về tình trạng của VM.

Các gói dịch vụ do OEM xác định phải lắng nghe nhiều tín hiệu sức khoẻ do HM báo cáo và dựa trên dữ liệu đó để thực hiện các hành động khôi phục. Ví dụ: một phiên bản SDV có các gói dịch vụ gặp sự cố có thể cần được khởi động lại hoặc cập nhật.

Bạn có thể định cấu hình tác nhân HM để theo dõi những nội dung sau:

  • Trạng thái hoạt động của các thực thể thực hiện các tác vụ định kỳ, bằng cách theo dõi nhịp tim hoạt động. Bạn có thể định cấu hình chế độ giám sát này cho cả các thực thể gói dịch vụ và các tác nhân OEM tuỳ chỉnh.
    • Trạng thái khôi phục của các phiên bản gói dịch vụ. Trong SDV 2.0, bạn có thể định cấu hình các gói dịch vụ để tự động khởi động lại khi gặp sự cố. HM cung cấp các tín hiệu để theo dõi quy trình khôi phục này.
    • QoS giao tiếp
  • Trạng thái hoạt động của SDV và tác nhân tuỳ chỉnh của OEM

Để tham khảo, bạn có thể xem toàn bộ danh mục VSIDL, bao gồm cả định nghĩa proto, tại //system/software_defined_vehicle/health_monitor/catalog/health_monitor.vsidl.

Thuật ngữ

Các thuật ngữ này được dùng trên trang này.

xung nhịp hoạt động (HB)
Thông báo do một gói dịch vụ tạo ra để cho biết gói dịch vụ đang hoạt động. Thông báo này có dấu thời gian cho biết thời điểm thông báo được tạo. Để biết thêm thông tin, hãy xem phần Xuất bản nhịp tim hoạt động.

xung nhịp chất lượng dịch vụ (QoS)
SDV hỗ trợ một số mô hình giao tiếp Pub/Sub và lệnh gọi quy trình từ xa (RPC). Một phiên bản gói dịch vụ đang lắng nghe thông tin liên lạc có thể xuất bản nhịp tim QoS, cho phép tác nhân HM phát hiện các lỗi vi phạm QoS. Để biết thêm thông tin, hãy xem bài viết Giám sát QoS.

giám sát việc khôi phục gói dịch vụ
Bạn có thể định cấu hình các phiên bản gói dịch vụ
SDV để khởi động lại nếu chúng gặp sự cố. Một phiên bản có thể khôi phục thành công hoặc không khôi phục được. HM theo dõi trạng thái khôi phục của phiên bản gói dịch vụ và báo cáo các lỗi khôi phục trong báo cáo tình trạng của VM. Để biết thêm thông tin, hãy xem bài viết Giám sát quá trình khôi phục gói dịch vụ.

giám sát sự cố của tác nhân
Không giống như các thực thể gói dịch vụ, các tác nhân SDV rất quan trọng đối với hành vi chính xác của hệ thống. Chúng không thể định cấu hình để khôi phục và do đó không bao giờ gặp sự cố. HM giám sát các tác nhân SDV và báo cáo sự cố trong báo cáo về tình trạng của VM. Bạn có thể giám sát các tác nhân tuỳ chỉnh của OEM. Để biết thêm thông tin, hãy xem phần Giám sát sự cố của tác nhân.

Báo cáo về tình trạng của máy ảo
Thông báo do HM tạo để cho biết tình trạng của VM. Để biết thêm thông tin, hãy xem Báo cáo tình trạng máy ảo.

Làm việc với hệ thống con HM

Để sử dụng các tính năng của HM, quá trình triển khai của OEM cần phải:

  • Định cấu hình hệ thống giám sát tình trạng bằng cách cung cấp các tệp cấu hình như được mô tả chi tiết trong phần Định cấu hình hệ thống HM.
  • Sử dụng gói dịch vụ Trình nghe HM do OEM xác định để nghe đầu ra HM và thực hiện hành động thích hợp.
  • Phát triển các gói dịch vụ chủ động xuất bản tín hiệu, theo cấu hình sức khoẻ của chúng. Ấn phẩm này giúp HM đánh giá tình trạng sức khoẻ của họ. Để biết thêm thông tin, hãy xem Hướng dẫn dành cho nhà phát triển gói dịch vụ.

Định cấu hình hệ thống HM

Mọi cấu hình liên quan đến HM đều nằm trong một trong các loại cấu hình sau:

  • Cấu hình trạng thái chung cho mỗi máy ảo
  • Cấu hình tình trạng theo gói dịch vụ, xác định các thông số về tình trạng cho tất cả các phiên bản của gói

Cấu hình tình trạng hoạt động cho từng máy ảo

Trong thời gian chạy, tác nhân HM dự kiến sẽ có một cấu hình tình trạng trên toàn VM: đây là một tệp textproto (có đuôi .textproto) thuộc loại VMHealth được xác định tại //system/software_defined_vehicle/health_monitor/catalog/health_monitoring_config.proto. Cấu hình VM Health phải nằm ở đường dẫn được chỉ định bằng cách sử dụng thuộc tính hệ thống thời gian khởi động androidboot.sdv.health_monitor.config_path. Ngoài ra, bạn có thể định cấu hình chế độ này một cách linh động trong thời gian chạy bằng cách đặt thuộc tính hệ thống persist.sdv.health_monitor.config_path thành một đường dẫn tuỳ chỉnh. Chế độ cài đặt persist.* được ưu tiên hơn chế độ cài đặt androidboot.*. Bạn phải khởi động lại thiết bị để cấu hình mới có hiệu lực.

Cấu hình trạng thái của VM cho phép bạn đặt các thông tin sau:

  • Tính định kỳ của báo cáo tình trạng máy ảo thông qua period_ms. Việc đặt giá trị này là sự đánh đổi giữa việc báo hiệu nhanh hơn rằng các lỗi vi phạm về trạng thái hoạt động đã được phát hiện và hiệu suất của hệ thống con HM. Bạn nên đặt giá trị là 100 mili giây.

  • Những tác nhân nào sẽ được giám sát sự cố (xem phần Giám sát sự cố của tác nhân).

Ví dụ về tệp cấu hình có trong //system/software_defined_vehicle/health_monitor/src/prod_configs/. Sau đây là một tệp cấu hình mẫu:

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

Trong ví dụ này, các tác nhân SDV DT và RPC được định cấu hình để giám sát sự cố và báo cáo tình trạng VM được định cấu hình để xuất bản sau mỗi 100 mili giây.

Cấu hình theo gói dịch vụ

Bạn không bắt buộc phải theo dõi tình trạng của các phiên bản gói dịch vụ. Để chọn sử dụng, hãy lưu trữ tệp cấu hình sức khoẻ trong APEX của gói dịch vụ và xác định một đường dẫn đến tệp đó trong trường health_config_path của sdv_service_bundle_metadata trong sdv_service_bundles_manifest.textproto. Để biết thêm thông tin về tệp kê khai gói dịch vụ, hãy xem phần Siêu dữ liệu của gói dịch vụ.

Tệp cấu hình về tình trạng là một tệp textproto thuộc loại sau:

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

Đối với mỗi phiên bản, bạn có thể chỉ định cả cấu hình nhịp tim duy trì hoạt động và cấu hình 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;
}

Để biết thêm thông tin về cấu hình theo tính năng, hãy xem phần Giám sát nhịp tim về trạng thái hoạt động và Giám sát QoS.

Nghe đầu ra của HM

Bạn có thể nghe HM thông qua báo cáo định kỳ hoặc RPC API.

Báo cáo về tình trạng của máy ảo

Tính năng giám sát sức khoẻ tạo ra báo cáo sức khoẻ định kỳ tần suất cao cho VM, cung cấp thông tin ngắn gọn về trạng thái sức khoẻ của các thực thể được giám sát.

Cú pháp loại của VmHealth được xác định trong //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;
}

Gói dịch vụ trình nghe HM do OEM xác định sẽ theo dõi các báo cáo VMHealth và thực hiện hành động thích hợp tuỳ thuộc vào cấu trúc hệ thống hoàn chỉnh. Các hành động có thể thực hiện bao gồm:

  • Chạy các quy trình chẩn đoán trên VM.
  • Khởi động lại máy ảo.
  • Chạy chiến dịch đo từ xa để xác định nguyên nhân.
  • Cập nhật hệ thống hoặc dừng cập nhật nếu hệ thống gặp trục trặc.

HM RPC API

Báo cáo trạng thái máy ảo là một ấn phẩm được tối ưu hoá về tần suất và tốc độ truyền, cung cấp thông tin chung về trạng thái của hệ thống.

HM RPC API cho phép trình nghe HM lấy thông tin chi tiết về nguồn gốc của các lỗi vi phạm về sức khoẻ. Giao diện được xác định trong //system/software_defined_vehicle/health_monitor/catalog/health_monitor_service.proto. Để thuận tiện, giao diện này được sao chép tại đây:

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

Nội dung mô tả chi tiết về các tính năng

Phần này mô tả chi tiết hơn về nhiều khía cạnh của HM.

Theo dõi nhịp tim để xác định trạng thái hoạt động

Khi tính năng giám sát trạng thái hoạt động được định cấu hình cho một phiên bản gói dịch vụ, HM sẽ yêu cầu phiên bản này xuất bản các nhịp tim định kỳ để chứng minh rằng logic nghiệp vụ đang hoạt động chính xác. Hoạt động giám sát này phù hợp nhất với các phiên bản gói dịch vụ thực hiện các tác vụ định kỳ. Ngoài ra, các gói sử dụng thời gian chạy không đồng bộ có thể sử dụng tính năng giám sát trạng thái hoạt động để chứng minh rằng nhóm luồng không bị cạn kiệt.

Quy trình theo dõi trạng thái hoạt động của HM

Hình 1. Luồng giám sát trạng thái hoạt động của HM.

Cấu hình

Để bật HB aliveness trên một phiên bản gói dịch vụ, hãy thêm một phiên bản của HealthConfiguration vào trường health_config trong cấu hình gói.

Cấu hình nhịp tim hoạt động xác định một tập hợp các tham số được xác định trước để thiết lập tiêu chí đánh giá tín hiệu nhịp tim định kỳ của dịch vụ. Nếu các đặc điểm của tín hiệu nhịp tim dịch vụ khác với các tham số này, thì tín hiệu nhịp tim sẽ được phân loại là bị trễ và gói dịch vụ tương ứng là không ổn định, điều này có thể cho thấy trạng thái hoạt động không tối ưu.

Một gói dịch vụ được coi là hoạt động bình thường khi báo cáo nhịp tim đúng giờ theo cấu hình trạng thái của gói. Trong trường hợp xảy ra sự cố hoặc hệ thống có tải cao, có thể thiếu hoặc trễ tín hiệu nhịp tim, khiến gói dịch vụ bị đánh dấu là không hoạt động bình thường. Trong trường hợp này, lỗi vi phạm sẽ xuất hiện trong báo cáo VmHealth.

Nhà phát triển gói dịch vụ nên xác định cấu hình trạng thái của một gói dịch vụ trong siêu dữ liệu APEX tương ứng. Cấu hình về tình trạng xác định các tiêu chí sau:

  • Độ trễ ban đầu tối đa được phép giữa thời điểm bắt đầu dịch vụ và lần phát hiện nhịp tim đầu tiên.

  • Khoảng thời gian mà gói dịch vụ SDV thực thi logic nghiệp vụ, tương ứng với tần suất xuất bản tín hiệu nhịp tim của dịch vụ.

  • Số lượng khoảng thời gian bị bỏ lỡ trước khi HM coi gói dịch vụ là không hoạt động bình thường.

  • Thời gian thực thi là khoảng thời gian mà một gói dịch vụ SDV cần để thực hiện logic nghiệp vụ trước khi có thể xuất bản một tín hiệu nhịp tim của dịch vụ.

Gói dịch vụ sẽ tạo ra một lỗi vi phạm về tình trạng nếu nhịp tim của dịch vụ bị trễ. Có 2 trường hợp dựa trên thời gian theo dõi sức khoẻ:

  • Trường hợp 1: Không nhận được nhịp tim ban đầu. Nếu thời gian trôi qua giữa thời điểm bắt đầu gói dịch vụ và thời điểm quan sát lớn hơn độ trễ ban đầu cho phép, thì gói dịch vụ đó sẽ được coi là không hoạt động bình thường.

  • Trường hợp 2: Đã nhận được tín hiệu nhịp tim. Nếu đã hết một ngưỡng thời gian giữa lần truyền tín hiệu gần đây nhất và thời gian quan sát, thì gói dịch vụ sẽ được coi là không hoạt động bình thường. Ngưỡng này được tính bằng tổng của kỳ báo cáo (nhân với số kỳ) và thời lượng của nhiệm vụ.

Định dạng cấu hình sức khoẻ được xác định trong //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;
}

Các yếu tố cần cân nhắc trong thời gian chạy

Phần này cung cấp hướng dẫn về cách xuất bản tín hiệu nhịp tim hoạt động và đăng ký đúng cách để theo dõi.

Xuất bản nhịp tim hoạt động

Một phiên bản gói dịch vụ sẽ tạo ra một thông báo xung nhịp dịch vụ bao gồm dấu thời gian. Tạo thông báo theo định kỳ, thường là ngay sau khi logic nghiệp vụ chính được thực thi. Gói heartbeat của dịch vụ cho biết gói dịch vụ đang hoạt động.

Đối tượng thực thể gói cần được theo dõi cần tạo một nhà xuất bản thuộc loại ServiceHeartbeat. Loại này có trong thư viện libhealth_api:

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

Chọn chủ đề xuất bản tuỳ ý. Tác nhân HM sử dụng tính năng phát hiện theo loại thông báo để phát hiện ấn phẩm.

Khi định cấu hình tính năng giám sát trạng thái hoạt động thông qua cấu hình trạng thái được liên kết trong tệp kê khai gói dịch vụ tương ứng, tác nhân HM dự kiến sẽ xuất bản HB ngay khi phiên bản hoàn tất quy trình on_start. Bạn nên giữ on_start ở mức ngắn để tránh chặn quá trình khởi động hệ thống. Vì vậy, hãy xuất bản các xung nhịp trong một tác vụ không đồng bộ được bắt đầu trong on_start.

Nhà phát triển gói có thể tuỳ chỉnh thời gian dự kiến cho nhịp tim đầu tiên bằng cách sử dụng mục cấu hình initial_delay_ms.

Phiên bản gói sẽ tiếp tục xuất bản các nhịp tim cho đến khi dừng. Một phiên bản được coi là đã dừng khi quy trình on_stop của phiên bản đó đã hoàn tất.

Trường hợp sử dụng đặc biệt: Đăng ký rõ ràng để theo dõi tín hiệu nhịp tim

Hành vi được mô tả trong phần Giám sát nhịp tim hoạt động, trong đó nhịp tim dự kiến nằm trong khoảng từ on_start đến on_stop, được gọi là giám sát trạng thái hoạt động ngầm. Đây là cách nên dùng để sử dụng tính năng này: cách này giúp đơn giản hoá logic nghiệp vụ của gói và đảm bảo rằng gói luôn được giám sát.

Tuy nhiên, có thể có một số trường hợp sử dụng mà khoảng thời gian giám sát mặc định là một hạn chế:

  • Một phiên bản gói dịch vụ chứa logic nghiệp vụ theo định kỳ trong một khoảng thời gian không liên kết với các sự kiện start và stop. Bạn chỉ cần theo dõi trạng thái hoạt động trong khoảng thời gian tuỳ chỉnh này.
  • HM theo dõi chính xác các HB trong khoảng thời gian tạm ngưng và tiếp tục. Do đó, gói này có thể muốn tiếp tục được giám sát sau on_stop.
  • Các tác nhân OEM tuỳ chỉnh có thể không được triển khai dưới dạng gói dịch vụ. Do đó, chúng không thể hưởng lợi từ tính năng giám sát trạng thái hoạt động ngầm. Tuy nhiên, chúng vẫn có thể yêu cầu giám sát trạng thái hoạt động.

Đối với những trường hợp này, HM cho phép bạn bỏ qua quy trình đăng ký ngầm để theo dõi trạng thái hoạt động thay vì đăng ký rõ ràng. Để sử dụng đăng ký rõ ràng, một thực thể gói phải chọn không sử dụng đăng ký ngầm bằng cách không đưa một mục nhập thuộc loại HealthConfiguration cho thực thể cụ thể vào tệp kê khai của gói. Sau đó, trong thời gian chạy, phiên bản gói sẽ dùng API RPC được xác định trong //system/software_defined_vehicle/health_monitor/catalog/health_monitor_registration_service.proto để đăng ký và huỷ đăng ký theo cách thủ công từ hoạt động giám sát. Bạn sẽ nhận được các tín hiệu nhịp tim đã xuất bản ngay sau khi lệnh gọi RPC đăng ký thành công.

Để biết ví dụ về cách triển khai, hãy xem //system/software_defined_vehicle/samples/health/stable/health_monitored_service_bundle/.

Giám sát QoS

Chất lượng dịch vụ (QoS) là một chỉ số đo lường hoạt động giao tiếp. HM giám sát xem thông báo đã gửi có mất quá nhiều thời gian để truyền hay không, hoặc trong trường hợp giao tiếp định kỳ, HM giám sát xem thông báo có được nhận với tần suất đã chọn hay không.

SDV cung cấp nhiều loại hình thức giao tiếp Pub/Sub và RPC. Mẫu số chung là tất cả các lược đồ giao tiếp đều chứa ít nhất một trình nghe. Để HM giám sát hoạt động giao tiếp, phiên bản gói dịch vụ nghe này phải xuất bản các nhịp tim QoS đặc biệt bất cứ khi nào nhận được một thông báo quan trọng.

Cấu hình

Để bật tính năng giám sát QoS của một hoạt động giao tiếp, trước tiên, hãy xác định trình nghe giao tiếp sẽ xuất bản tín hiệu nhịp tim QoS. Sau đó, đối với phiên bản gói dịch vụ đã xác định, hãy thêm một hoặc nhiều chủ đề vào các mối liên kết QosMonitoringConfiguration trong trường qos_config. Để biết thêm thông tin, hãy xem phần Cấu hình gói theo từng dịch vụ.

topic là một chuỗi xác định chủ đề xuất bản mà HM dự kiến sẽ có QoS HB tại thời gian chạy. Một phiên bản gói nghe có thể tham gia vào nhiều hoạt động giao tiếp và có thể báo cáo HB QoS trên nhiều chủ đề.

Các chủ đề phải mang tính mô tả, vì chúng được báo cáo lại cho gói dịch vụ trình nghe HM nếu phát hiện thấy các lỗi vi phạm QoS tại thời gian chạy.

Loại QosMonitoringConfiguration được xác định trong //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;
}

Đối với các trường hợp sử dụng mặc định, hãy thực thi cả hai loại hoạt động giám sát QoS. qos_latency_threshold_ms của 30 là hợp lý cho hoạt động giao tiếp Pub/Sub trong VM trong điều kiện tải hệ thống bình thường.

Các yếu tố cần cân nhắc trong thời gian chạy

Tương tự như tính năng giám sát HB về trạng thái hoạt động, gói nghe giao tiếp dự kiến sẽ xuất bản một loại tín hiệu nhịp tim. Trong trường hợp này, HB QoS sẽ được xuất bản bất cứ khi nào nhận được thông báo quan trọng, thay vì vào cuối quá trình thực thi logic nghiệp vụ.

QoS HB thuộc loại QosHeartbeat, được xác định trong //system/software_defined_vehicle/health_monitor/catalog/qos_heartbeat.proto:

message QosHeartbeat {
  option (.sdv.vsidl.v1.publication) = {
    message_count: 2
    model: SINGLE_PUB
  };
  // Required.
  // Current timestamp at heartbeat transmission. The heartbeat should be sent
  // immediately after the listener receives the related QoS-monitored message.
  .google.protobuf.Timestamp timestamp = 1;

  // Required.
  // Timestamp corresponding to the creation time of the underlying data. This
  // implies that, in addition to the data of interest, the monitored message includes
  // a data creation timestamp field. The listener is responsible for routing this
  // timestamp to the QosHeartbeat upon receiving a QoS-monitored message.
  .google.protobuf.Timestamp data_timestamp = 2;
}

Thời gian đăng ký và huỷ đăng ký việc xuất bản QoS HB là yếu tố quan trọng để giám sát chính xác. HM dự kiến sẽ có các HB QoS giữa hai sự kiện này. Gói nghe thông báo sẽ đăng ký thông báo QoS HB khi thông báo được giám sát được đăng ký với ngăn xếp giao tiếp SDV. HM có thể sử dụng API tình trạng còn hàng để thực hiện việc này. Để biết thêm thông tin, hãy xem phần Xác định phạm vi cung cấp dịch vụ.

Giám sát việc khôi phục gói dịch vụ

Quá trình khôi phục các thực thể gói dịch vụ được định cấu hình trong tệp cấu hình của tác nhân điều phối. Để biết toàn bộ thông tin về chủ đề này, hãy xem phần Gói dịch vụ. Hệ thống con HM thụ động quan sát quy trình khôi phục. Khi phát hiện thấy không khôi phục được một phiên bản gói, một lỗi vi phạm sẽ được thêm vào báo cáo VMHealth. Không giống như các chức năng giám sát HM khác, chức năng giám sát quá trình khôi phục là bắt buộc và không thể định cấu hình.

Các phiên bản gói dịch vụ không được định cấu hình để khôi phục sẽ tạo ra lỗi vi phạm về tình trạng sức khoẻ trong lần gặp sự cố đầu tiên.

Tính năng khôi phục phiên bản gói dịch vụ được thiết kế để tích hợp với tính năng giám sát trạng thái hoạt động của tín hiệu nhịp tim. Hệ thống HM sẽ khoan dung hơn khi đánh giá các nhịp tim khi phát hiện thấy gói đang khôi phục. Trên thực tế, sự khoan dung này có nghĩa là các gói dịch vụ không cần thực hiện thêm bất kỳ bước đăng ký hoặc huỷ đăng ký giám sát nào nếu chúng gặp sự cố.

Giám sát sự cố của tác nhân

HM phát hiện các sự cố có thể xảy ra của các tác nhân SDV bằng cơ chế liên kết linkToDeath.

Bạn có thể định cấu hình tính năng giám sát sự cố trong quá trình định cấu hình tình trạng của máy ảo (xem phần Cấu hình cho từng phiên bản SDV (máy ảo)), cụ thể là trường lặp lại monitored_agent. Trường này phải chứa các mục thuộc loại 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;
}

Bạn cũng có thể giám sát các tác nhân tuỳ chỉnh nếu tác nhân đó hiển thị một giao diện liên kết. Để theo dõi một tác nhân tuỳ chỉnh, hãy cấp cho HM quyền SELinux để theo dõi giao diện liên kết thích hợp.

Thuộc tính hệ thống ro.boot.sdv.health_monitor.agent_startup_timeout_sec có thể ghi đè thời gian HM chờ các tác nhân đăng ký giao diện liên kết sau khi HM khởi động. Trừ phi các tác nhân tuỳ chỉnh yêu cầu, thời gian mặc định là 3 giây là phù hợp.

Hướng dẫn phát triển gói dịch vụ

Phần này cung cấp hướng dẫn từng bước về cách sử dụng các tính năng HM từ các gói dịch vụ, trái ngược với cách xử lý lý thuyết trong các phần trước. Mẫu tham chiếu mới nhất mà các hướng dẫn này dựa trên đó là mẫu qos_monitoring. Làm theo //system/software_defined_vehicle/samples/health/stable/qos_monitoring/README của mẫu để có trải nghiệm thực tế.

Thêm tính năng giám sát xung nhịp hoạt động vào một gói dịch vụ

Đây là phương thức trực tiếp nhất để bật tính năng theo dõi tình trạng cho một gói dịch vụ:

  1. Xác định một thực thể của ServiceBundleHealthConfiguration cho các thực thể gói trong một tệp có tên là 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. Thêm tệp cấu hình vào APEX của gói dịch vụ. Trong 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. Lưu trữ cấu hình về sức khoẻ trong APEX và đặt health_config_path trong tệp kê khai:

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

  4. Trong định nghĩa VSIDL, hãy đảm bảo gói xuất bản com.android.sdv.health.ServiceHeartbeat:

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

  5. Thêm quyền SDV vào gói để gói được phép xuất bản HB:

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

  6. Định kỳ xuất bản tín hiệu nhịp tim của dịch vụ trong mã, bắt đầu từ 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()
    })?;
  }
}

Trường hợp sử dụng đặc biệt: Đăng ký rõ ràng

Đối với các trường hợp sử dụng đặc biệt hơn, trong đó gói cần giám sát HB cho các vòng đời tuỳ chỉnh (ví dụ: giám sát bắt đầu sớm hơn hoặc kết thúc muộn hơn trạng thái STARTED tiêu chuẩn), bạn có thể sử dụng phương thức đăng ký rõ ràng:

  1. Trong định nghĩa VSIDL, hãy thêm một ứng dụng com.android.sdv.health.HealthMonitorRegistrationService:

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

  2. Thêm quyền SDV để sử dụng RPC đăng ký HB về trạng thái hoạt động:

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

  3. Đăng ký với HM thông qua RPC, ví dụ: trong on_start hoặc 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. Xuất bản HB.

  5. Huỷ đăng ký theo dõi khi không cần thiết nữa:

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

Thêm tính năng giám sát QoS vào quá trình giao tiếp

  1. Xác minh rằng phiên bản gói dịch vụ là một người đăng ký của một chủ đề có tên fog-light-status trong danh mục VSIDL:

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

    Định dạng thông báo như sau:

    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. Xác định một thực thể của ServiceBundleHealthConfiguration cho các thực thể gói trong tệp health_configuration.textproto bao gồm tính năng giám sát QoS:

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

    Chủ đề được chọn trong trường key minh hoạ rằng QoS HB sẽ được xuất bản trên chủ đề này, cho phép theo dõi một chủ đề có tên là fog-light-status.

  3. Thêm tệp cấu hình vào APEX của gói dịch vụ. Trong 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. Lưu trữ cấu hình sức khoẻ trong APEX và đặt health_config_path trong tệp kê khai:

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

  5. Trong định nghĩa VSIDL, hãy đảm bảo rằng gói là nhà xuất bản của com.android.sdv.health.QosHeartbeat:

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

  6. Thêm quyền SDV vào gói để gói được phép xuất bản QoS HB:

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

  7. Chỉ đăng ký thông báo HB QoS khi thông báo được theo dõi đã được đăng ký. Sử dụng API về tình trạng còn hàng từ 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. Xuất bản HB QoS mỗi khi nhận được một thông báo:

    // ...
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. Để ngừng giám sát QoS, hãy thả đối tượng nhà xuất bản:

    // ...
drop(qos_hb_pub);

Gỡ lỗi tính năng giám sát tình trạng

Để gỡ lỗi và xem tổng quan về hệ thống, hãy sử dụng công cụ dumpsys để theo dõi trạng thái giám sát tình trạng của VM:

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

Báo cáo này trình bày chi tiết cấu hình báo cáo tình trạng máy ảo, cấu hình gói và trạng thái giám sát. Sau đây là một ví dụ về báo cáo như vậy:

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

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