From e34755845c0cb0fd50142163e609f199644cef0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ab=C3=ADlio=20Costa?= <abmantis@users.noreply.github.com>
Date: Wed, 27 Nov 2024 13:21:46 +0000
Subject: [PATCH] Add page for config entry diagnostics (#2469)

* Add page for config entry diagnostics

* Address review suggestions

* Revert sidebar

* Move page out of config entries and address suggestions

* Update docs/core/integration_diagnostics.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Reword warning

* Remove device ids from sensitive list; link cleanup

* Clarify diag download methods

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 .../rules/diagnostics.md                      |  6 ++-
 docs/core/integration_diagnostics.md          | 49 +++++++++++++++++++
 sidebars.js                                   |  1 +
 3 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 docs/core/integration_diagnostics.md

diff --git a/docs/core/integration-quality-scale/rules/diagnostics.md b/docs/core/integration-quality-scale/rules/diagnostics.md
index 9a16ecec..31fa156a 100644
--- a/docs/core/integration-quality-scale/rules/diagnostics.md
+++ b/docs/core/integration-quality-scale/rules/diagnostics.md
@@ -33,6 +33,10 @@ async def async_get_config_entry_diagnostics(
     }
 ```
 
+## Additional resources
+
+To learn more information about diagnostics, check out the [diagnostics documentation](/docs/core/integration_diagnostics).
+
 ## Exceptions
 
-There are no exceptions to this rule.
\ No newline at end of file
+There are no exceptions to this rule.
diff --git a/docs/core/integration_diagnostics.md b/docs/core/integration_diagnostics.md
new file mode 100644
index 00000000..b32480bc
--- /dev/null
+++ b/docs/core/integration_diagnostics.md
@@ -0,0 +1,49 @@
+---
+title: Integration diagnostics
+sidebar_label: "Diagnostics"
+---
+
+Integrations can provide diagnostics to help the user gather data to aid in troubleshooting. Diagnostics can be provided for config entries but also individually for each device entry.
+
+Users can download config entry diagnostics from the config entry options menu, on the integration page. For device diagnostics, users can download them from the device info section (or from its menu, depending on the integration). Note that if an integration does not implement device diagnostics, the device page will provide config entry diagnostics.
+
+:::warning
+It is critical to ensure that no sensitive data is exposed. This includes but is not limited to:
+- Passwords and API keys
+- Authentication tokens
+- Location data
+- Personal information
+
+Home Assistant provides the `async_redact_data` utility function which you can use to safely remove sensitive data from the diagnostics output.
+:::
+
+The following is an example on how to implement both config entry and device entry diagnostics:
+
+```python
+TO_REDACT = [
+    CONF_API_KEY,
+    APPLIANCE_CODE
+]
+
+async def async_get_config_entry_diagnostics(
+    hass: HomeAssistant, entry: MyConfigEntry
+) -> dict[str, Any]:
+    """Return diagnostics for a config entry."""
+
+    return {
+        "entry_data": async_redact_data(entry.data, TO_REDACT),
+        "data": entry.runtime_data.data,
+    }
+
+async def async_get_device_diagnostics(
+    hass: HomeAssistant, entry: MyConfigEntry, device: DeviceEntry
+) -> dict[str, Any]:
+    """Return diagnostics for a device."""
+    appliance = _get_appliance_by_device_id(hass, device.id)
+    return {
+        "details": async_redact_data(appliance.raw_data, TO_REDACT),
+        "data": appliance.data,
+    }
+```
+
+An integration can provide both types of diagnostics or just one of them.
diff --git a/sidebars.js b/sidebars.js
index 28803c6e..a711dd5e 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -117,6 +117,7 @@ module.exports = {
         "creating_integration_manifest",
         "config_entries_config_flow_handler",
         "config_entries_options_flow_handler",
+        "core/integration_diagnostics",
         "configuration_yaml_index",
         "dev_101_services",
         "creating_platform_index",