From 3afcff29858a65c4fa89650b7370d6a76f1efd16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ab=C3=ADlio=20Costa?= Date: Wed, 5 Feb 2025 16:40:09 +0000 Subject: [PATCH] Add integration system health documentation page (#2549) Co-authored-by: Martin Hjelmare --- docs/core/integration_system_health.md | 56 ++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 57 insertions(+) create mode 100644 docs/core/integration_system_health.md diff --git a/docs/core/integration_system_health.md b/docs/core/integration_system_health.md new file mode 100644 index 00000000..b334ff72 --- /dev/null +++ b/docs/core/integration_system_health.md @@ -0,0 +1,56 @@ +--- +title: Integration system health +sidebar_label: "System health" +--- + +The system health platform allows integrations to provide information that helps users understand the state of the integration. This can include details such as the availability of an endpoint, the current server that the integration is connected to, how much of a request quota is still available, etc. + +Users can find the aggregated system health by going to **Settings** > **Repairs** and selecting **System information** in the three dots menu. + +## Implementing the system health platform + +Add a `system_health.py` file to the integration and implement the `async_register` method, to register the info callback: + +```python +"""Provide info to system health.""" + +from homeassistant.components import system_health +from homeassistant.core import HomeAssistant, callback + +@callback +def async_register(hass: HomeAssistant, register: system_health.SystemHealthRegistration) -> None: + """Register system health callbacks.""" + register.async_register_info(system_health_info) +``` + +The info callback should return a dictionary whose values can be of any type, including coroutines. In case a coroutine is set for a dictionary entry, the frontend will display a waiting indicator and will automatically update once the coroutine finishes and provides a result. + +```python +async def system_health_info(hass: HomeAssistant) -> dict[str, Any]: + """Get info for the info page.""" + config_entry: ExampleConfigEntry = hass.config_entries.async_entries(DOMAIN)[0] + quota_info = await config_entry.runtime_data.async_get_quota_info() + + return { + "consumed_requests": quota_info.consumed_requests, + "remaining_requests": quota_info.requests_remaining, + # checking the url can take a while, so set the coroutine in the info dict + "can_reach_server": system_health.async_check_can_reach_url(hass, ENDPOINT), + } +``` + +:::tip +The system_health component provides the `async_check_can_reach_url` helper as a way to easily implement checking the availability of a URL. +::: + + +Translate each key in the info dictionary using the `system_health` section in the `strings.json` file, to provide good descriptions: + +```json + "system_health": { + "info": { + "can_reach_server": "Reach Example server", + "remaining_requests": "Remaining allowed requests" + } + } +``` diff --git a/sidebars.js b/sidebars.js index a711dd5e..a91bc636 100644 --- a/sidebars.js +++ b/sidebars.js @@ -118,6 +118,7 @@ module.exports = { "config_entries_config_flow_handler", "config_entries_options_flow_handler", "core/integration_diagnostics", + "core/integration_system_health", "configuration_yaml_index", "dev_101_services", "creating_platform_index",