Add references to traces for automation debugging (#18496)

Co-authored-by: Franck Nijhof <git@frenck.dev>

source/_docs/automation/troubleshooting.markdown

@@ -3,6 +3,18 @@ title: "Troubleshooting Automations"
 description: "Tips on how to troubleshoot your automations."
 ---
 
+## Using debug traces
+
+Every time an automation runs, a debugging trace is generated regardless of whether the automation was completed, aborted, or suffered an error. Traces allow you to interactively inspect the state of the automation at every step and also check the values of [variables](/docs/scripts/#variables) and rendered [templates](/docs/configuration/templating/). Traces can be accessed in the {% my automations title="Automations Section" %} of {% my configuration %}.
+
+![Automation debug trace example](/images/integrations/automation/automation-tracing.png)
+
+Automations created in YAML must have an [`id`](/docs/automation/yaml/#migrating-your-yaml-automations-to-automationsyaml) assigned in order for debugging traces to be stored.
+
+By default the last 5 traces are stored for each automation, this can be adjusted in the [YAML configuration](/docs/automation/yaml/#number-of-debug-traces-stored) of an automation. Stored traces are reset each time Home Assistant restarts.
+
+## Inspecting logs and the Logbook
+
 You can verify that your automation rules are being initialized correctly by watching both the realtime logs (`homeassistant.log` in the configuration directory) and also the [Logbook](/integrations/logbook/). The realtime logs will show the rules being initialized (once for each trigger), example:
 
 ```text
@@ -18,7 +30,7 @@ The Logbook integration will show a line entry when an automation is triggered.
 
 [template]: /topics/templating/
 
-### Testing your automation
+## Testing your automation
 
 It is generally a difficult task to test an automation, especially if it includes several triggers and some conditions.
 

source/_docs/automation/yaml.markdown

@@ -16,7 +16,7 @@ automation: !include automations.yaml
 # Labeled automation block
 automation kitchen:
   - trigger:
-    - platform: ...
+      - platform: ...
 ```
 
 You can add as many labeled `automation` blocks as you want.
@@ -30,8 +30,8 @@ Example of a YAML based automation that you can add to `configuration.yaml`.
 ```yaml
 # Example of entry in configuration.yaml
 automation my_lights:
-# Turns on lights 1 hour before sunset if people are home
-# and if people get home between 16:00-23:00
+  # Turns on lights 1 hour before sunset if people are home
+  # and if people get home between 16:00-23:00
   - alias: "Rule 1 Light on in the evening"
     trigger:
       # Prefix the first line of each trigger configuration
@@ -57,7 +57,7 @@ automation my_lights:
         target:
           entity_id: group.living_room
 
-# Turn off lights when everybody leaves the house
+  # Turn off lights when everybody leaves the house
   - alias: "Rule 2 - Away Mode"
     trigger:
       - platform: state
@@ -68,7 +68,7 @@ automation my_lights:
         target:
           entity_id: all
 
-# Notify when Paulus leaves the house in the evening
+  # Notify when Paulus leaves the house in the evening
   - alias: "Leave Home notification"
     trigger:
       - platform: zone
@@ -83,7 +83,7 @@ automation my_lights:
         data:
           message: "Paulus left the house"
 
-# Send a notification via Pushover with the event of a Xiaomi cube. Custom event from the Xiaomi component.
+  # Send a notification via Pushover with the event of a Xiaomi cube. Custom event from the Xiaomi component.
   - alias: "Xiaomi Cube Action"
     initial_state: false
     trigger:
@@ -110,10 +110,23 @@ At startup, automations by default restore their last state of when Home Assista
 
 ```yaml
 automation:
-- alias: "Automation Name"
-  initial_state: false
-  trigger:
-    - platform: ...
+  - alias: "Automation Name"
+    initial_state: false
+    trigger:
+      - platform: ...
+```
+
+### Number of debug traces stored
+
+When using YAML you can configure the number of debugging traces stored for an automation. This is controlled with the `stored_traces` option under `traces`. Set `stored_traces` to the number of traces you wish to store for the particular automation. If not specified the default value of 5 will be used.
+
+```yaml
+automation:
+  - alias: "Automation Name"
+    traces:
+      stored_traces: 10
+    trigger:
+      - platform: ...
 ```
 
 ## Migrating your YAML automations to `automations.yaml`