Teddy.gesbert/doc dora (#28783)

* Replaced incidents by failures

* v1

* v1.1

* Little update of some requirements (DORA settings)

* Upper case small changes

* Update content/en/dora_metrics/data_collected/_index.md

Co-authored-by: Jorge Calvar <[email protected]>

* Applied feedback from Jorge

Change deployment.merge_time to Merge Time (i.e. metric to field) to avoid any confusion with previous Metrics type

* Applied feedback from Guillaume

* Fix typos and improve consistency in DORA metrics documentation

Applied suggestions from Joe Peeples

* Applying Joe's feedback and fixing small tweak

* Added Incident Management as a DORA Failure data source

* Update content/en/dora_metrics/setup/failures.md

Co-authored-by: Alicia Scott <[email protected]>

* Update content/en/dora_metrics/setup/failures.md

Co-authored-by: Alicia Scott <[email protected]>

* Applied feedback from alicia

- Added consistency between data sources requirements.
- Remove /dora_metrics/failures/datadog_incidents alias as not needed.

* Applied feedback from Jorge

* Update content/en/dora_metrics/setup/failures.md

Co-authored-by: Alicia Scott <[email protected]>

* Update failures.md

---------

Co-authored-by: Jorge Calvar <[email protected]>
Co-authored-by: Alicia Scott <[email protected]>

Author: 3 people

content/en/dora_metrics/setup/_index.md

@@ -36,8 +36,9 @@ The four DORA Metrics are calculated based on two types of events that support d
 ### Select a failure data source
 
 {{< whatsnext desc="DORA Metrics supports the following data sources for failure events. See the respective documentation to set up one or more data sources for your failure events:" >}}
+  {{< nextlink href="/dora_metrics/setup/failures?tab=datadog_incidents" >}}Datadog Incidents{{< /nextlink >}}
   {{< nextlink href="/dora_metrics/setup/failures?tab=pagerduty" >}}PagerDuty{{< /nextlink >}}
-  {{< nextlink href="/dora_metrics/setup/failures?tab=api" >}}Incident Event API{{< /nextlink >}}
+  {{< nextlink href="/dora_metrics/setup/failures?tab=api" >}}Failure Event API{{< /nextlink >}}
 {{< /whatsnext >}}
 
 ## Limitations

content/en/dora_metrics/setup/failures.md

@@ -39,12 +39,34 @@ Failed deployment events, currently interpreted through failure events, are used
 ## Selecting and configuring a failure data source
 
 {{< tabs >}}
+{{% tab "Datadog Incidents" %}}
+DORA Metrics can automatically identify and track failures through [Datadog Incidents][201]. Once incidents are declared, DORA uses them to measure change failure rate and time to restore.
+
+**Note**: Only incidents that are in a `stable` or `resolved` state are used to calculate time to restore.
+
+### Requirements
+
+- **Incidents** is enabled as a **Failures** event data source in [DORA settings][202].
+
+For incidents to appear in filtered DORA metrics views, Incidents must be tagged with the following attributes:
+  - `Teams`
+  - `Services`
+  - `Envs`: The `Envs` attribute can be added in the [Incident Settings][203] if it doesn’t already exist.
+
+If provided with Incidents, the `Severity` tag will be added to failure events.
+
+[201]: /service_management/incident_management/
+[202]: https://app.datadoghq.com/ci/settings/dora
+[203]: https://app.datadoghq.com/incidents/settings?section=property-fields
+
+
+{{% /tab %}}
 {{% tab "PagerDuty" %}}
 [PagerDuty][104] is an incident management platform that equips IT teams with immediate incident visibility, enabling proactive and effective responses to maintain operational stability and resilience.
 
 To integrate your PagerDuty account with DORA Metrics: 
 
-1. Enable PagerDuty as a failure data source in [DORA settings][111]. 
+1. Enable **PagerDuty** as a **Failures** event data source in [DORA settings][111]. 
 
 1. Navigate to **Integrations > Developer Tools** in PagerDuty and click **Generic Webhooks (v3)**. 
 
@@ -132,7 +154,7 @@ Include the `finished_at` attribute in a failure event to mark that the failure
 
 ### Requirements
 
-- datadog-ci CLI / API is enabled as a failure events data source in [DORA settings][15].
+- **datadog-ci CLI / API** is enabled as a **Failures** event data source in [DORA settings][15].
 - The following attributes are required:
   - `services` or `team` (at least one must be present)
   - `started_at`