DOCS-7747, DOCS-7795 Adds APM Deployment Tracking Documentation

config/_default/menus/main.en.yaml

@@ -3729,16 +3729,41 @@ menu:
       parent: dora_metrics
       identifier: dora_metrics_setup
       weight: 1
-    - name: Deployment events
-      url: dora_metrics/setup/deployments
-      parent: dora_metrics_setup
-      identifier: dora_metrics_setup_deployments
-      weight: 101
-    - name: Incident events
-      url: dora_metrics/setup/incidents
-      parent: dora_metrics_setup
-      identifier: dora_metrics_setup_incidents
-      weight: 102
+    - name: Deployment Data Sources
+      url: dora_metrics/deployments
+      parent: dora_metrics
+      identifier: dora_metrics_deployments
+      weight: 2
+    - name: APM Deployment Tracking
+      url: dora_metrics/deployments/apm
+      parent: dora_metrics_deployments
+      identifier: dora_metrics_deployment_apm
+      weight: 201
+    - name: API
+      url: dora_metrics/deployments/deployment_api
+      parent: dora_metrics_deployments
+      identifier: dora_metrics_deployment_events_api
+      weight: 202
+    - name: Failure Data Sources
+      url: dora_metrics/failures/
+      parent: dora_metrics
+      identifier: dora_metrics_incidents
+      weight: 3
+    - name: PagerDuty
+      url: dora_metrics/failures/pagerduty
+      parent: dora_metrics_incidents
+      identifier: dora_metrics_incident_pagerduty
+      weight: 301
+    - name: API
+      url: dora_metrics/failures/incident_api
+      parent: dora_metrics_incidents
+      identifier: dora_metrics_incident_events_api
+      weight: 302
+    - name: Data Collected
+      url: dora_metrics/data_collected/
+      parent: dora_metrics
+      identifier: dora_metrics_data_collected
+      weight: 4
     - name: Observability Pipelines
       url: observability_pipelines/
       pre: pipelines

content/en/dora_metrics/_index.md

@@ -1,111 +1,72 @@
 ---
 title: DORA Metrics
 kind: documentation
-description: Learn how to use DORA metrics to measure and improve software development.
+description: Learn how to use DORA metrics to measure and improve your organization's software delivery processes.
 aliases:
 - /continuous_integration/dora_metrics
 is_beta: true
 further_reading:
 - link: "https://app.datadoghq.com/release-notes?category=Software%20Delivery"
   tag: "Release Notes"
   text: "Check out the latest Software Delivery releases! (App login required)"
-- link: "/continuous_integration/pipelines"
-  tag: "Documentation"
-  text: "Learn about Pipeline Visibility"
 - link: "/continuous_delivery/deployments"
   tag: "Documentation"
   text: "Learn about Deployment Visibility"
-- link: "/continuous_integration/tests"
+- link: "/service_management/events"
   tag: "Documentation"
-  text: "Learn about Test Visibility"
-- link: "/code_analysis"
+  text: "Learn about Event Management"
+- link: "/monitors/types/metric"
   tag: "Documentation"
-  text: "Learn about Code Analysis"
+  text: "Learn about Metric Monitors"
 ---
 
 {{< site-region region="gov" >}}
 <div class="alert alert-warning">DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.</div>
 {{< /site-region >}}
 
-{{< callout url="https://forms.gle/Eqq6uXfGjYxmqpjDA" header="false" >}}
-The DORA Metrics private beta is closed. Fill out the form below to be added to the waitlist.
+{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}}
+DORA Metrics is in public beta.
 {{< /callout >}}
 
 ## Overview
 
-DevOps Research and Assessment (DORA) metrics are [four key metrics][1] used to indicate the velocity and stability of software development.
+DevOps Research and Assessment (DORA) metrics are [four key metrics][1] that indicate the velocity and stability of software development. 
 
-Deployment Frequency
+Deployment frequency
 : How often an organization successfully releases to production.
 
-Lead Time for Changes
+Lead time for changes
 : The amount of time it takes a commit to get into production.
 
-Change Failure Rate
+Change failure rate
 : The percentage of deployments causing a failure in production.
 
-Time to Restore Service
+Time to restore service
 : How long it takes an organization to recover from a failure in production.
 
 Defining and tracking DORA metrics can help you identify areas of improvement for your team or organization's speed and quality of software delivery.
 
 ## Set up DORA Metrics
 
-The four DORA Metrics are calculated based on two types of events:
-- **Deployment events**: Indicate that a new deployment has occurred for a service in a specific environment.
-  Deployment events are used to compute Deployment Frequency, Change Lead Time, and Change Failure Rate.
-- **Incident events**: Indicate that a new issue has occurred for a service in a specific environment.
-  Incident events are used to compute Change Failure Rate and Mean Time to Restore.
-
-{{< whatsnext desc="Set up DORA Metrics in Datadog:" >}}
-    {{< nextlink href="continuous_integration/dora_metrics/setup/deployments" >}}Send Deployment Events{{< /nextlink >}}
-    {{< nextlink href="continuous_integration/dora_metrics/setup/incidents" >}}Send Incident Events{{< /nextlink >}}
-{{< /whatsnext >}}
-
-## Use DORA Metrics
-
-You can access and visualize your DORA metrics and filter them by team, service, repository, environment, and time period on the [**DORA Metrics** page][2].
-
-Use the information on this page to identify improvements or regressions for each metric, visualize changes, and compare trends over time. DORA metrics can be exported to dashboards or notebooks and be alerted on using [metric monitors][3].
-
-The metrics can also be queried with the [Query timeseries points][4] and [Query timeseries data across multiple products][5] API endpoints.
-
-The metrics provided by DORA Metrics are:
-
-| Metric | Type | Description |
-| :--- | :--- | :--- |
-| `dora.deployments.count` | count | Used for Deployment Frequency.
-| `dora.change_lead_time` | distribution | Contains the age in `seconds` of the git commits at the time of deployment.
-| `dora.incidents_impact` | count | Tracks the services or teams impacted by incidents. Used for Change Failure Rate with the formula `dora.incidents_impact / dora.deployments.count`. A big time rollup of at least 1 week is recommended to account for time difference between deployments and when the impact starts.
-| `dora.time_to_restore` | distribution | Contains the time in `seconds` between the incident's `started_at` and `finished_at`.
-
-All the metrics contain the following tags when available:
-- `service`
-- `team`
-- `env`
-- `repository_id`
-
-**Note**: The `severity` tag is available for the `dora.incidents_impact` and `dora.time_to_restore` metrics, if provided through the API.
+To start configuring data sources to send deployment and incident events to Datadog, see the [Setup documentation][2].
 
-### Deployment and incident events
+## Analyze DORA Metrics
 
-DORA Metrics also provides individual `deployment`, `incident`, and `incident_finished` events in [Event Management][6] with `source:software_delivery_insights`.
+Once you've set up the data sources for your deployment and failure events, navigate to [**Software Delivery** > **DORA Metrics**][4] to identify improvements or regressions for each metric, aggregate them by service or environment, and compare trends over time. 
 
-The events can be queried and visualized with the [Events Explorer][7].
+{{< img src="dora_metrics/dora_page_light.png" alt="An Overview of your DORA Metrics calculations and insights in the last week" style="width:100%;" >}}
 
-### Limitations
+You can access and visualize your DORA metrics and filter them by team, service, repository, environment, and time period on the [**DORA Metrics** page][4]. For more information about the metrics calculated by DORA Metrics, see the [Data Collected documentation][3].
 
-- Deployment and incident events must be sent as soon as possible. Events for which the `finished_at` timestamp is 1 hour older than the current time are not accepted.
-- Deployments or incidents of the same service cannot occur at the same second.
+You can also export your DORA Metrics data to dashboards or notebooks and create [metric monitors][5] to trigger alerts on your metrics. For more information, see the [Monitors documentation][6].
 
 ## Further Reading
 
 {{< partial name="whats-next/whats-next.html" >}}
 
-[1]: https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance
-[2]: https://app.datadoghq.com/ci/dora
-[3]: https://docs.datadoghq.com/monitors/types/metric/?tab=threshold
-[4]: https://docs.datadoghq.com/api/latest/metrics/#query-timeseries-points
-[5]: https://docs.datadoghq.com/api/latest/metrics/#query-timeseries-data-across-multiple-products
-[6]: https://app.datadoghq.com/event/explorer?query=source%3Asoftware_delivery_insights
-[7]: https://docs.datadoghq.com/service_management/events/explorer/
+[1]: https://www.datadoghq.com/knowledge-center/dora-metrics/
+[2]: /dora_metrics/setup/
+[3]: /dora_metrics/data_collected/
+[4]: https://app.datadoghq.com/ci/dora
+[5]: /monitors/types/metric/?tab=threshold
+[6]: /monitors/

content/en/dora_metrics/data_collected/_index.md

@@ -0,0 +1,92 @@
+---
+title: DORA Metrics Data Collected
+kind: documentation
+further_reading:
+- link: '/dora_metrics/'
+  tag: 'Documentation'
+  text: 'Learn about DORA Metrics'
+- link: '/dora_metrics/setup/'
+  tag: 'Documentation'
+  text: 'Set up data sources for DORA Metrics'
+- link: '/metrics/'
+  tag: 'Documentation'
+  text: 'Learn about metrics'
+- link: '/getting_started/tagging/'
+  tag: 'Documentation'
+  text: 'Getting Started with Tags'
+---
+
+{{< site-region region="gov" >}}
+<div class="alert alert-warning">DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.</div>
+{{< /site-region >}}
+
+{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}}
+DORA Metrics is in public beta.
+{{< /callout >}}
+
+## Overview
+
+DORA Metrics generates [metrics][9] for each one of the four core DORA Metrics, as well as events with associated tags and attributes that are available in the [Events Explorer][1].
+
+## Default metrics
+
+DORA Metrics provides the following default metrics:
+
+| Metric | Type | Description |
+| :--- | :--- | :--- |
+| `dora.deployments.count` | count | The number of deployments detected by Datadog based on your selected [deployment data source][10].
+| `dora.change_lead_time` | distribution | The age in `seconds` of associated Git commits at the time of deployment.
+| `dora.incidents_impact` | count | Tracks the services or teams impacted by incidents. Used for change failure rate with the formula `dora.incidents_impact / dora.deployments.count`. A big time rollup of at least 1 week is recommended to account for the time difference between deployments and when the impact starts.
+| `dora.time_to_restore` | distribution | The time in `seconds` between an incident's `started_at` and `finished_at` timestamps.
+
+### Default tags
+
+All default metrics contain the following tags if any are available:
+
+- `service`
+- `team`
+- `env`
+- `repository_id`
+
+**Note**: The `severity` tag is available for `dora.incidents_impact` and `dora.time_to_restore` metrics when it is provided by the failure's data source.
+
+For more information about using `env`, `service`, and `version` tags, see [Getting Started with Tags][6].
+
+## Change lead time metrics
+
+Datadog breaks down change lead time into the following metrics, which represent the different stages from commit creation to deployment.
+
+| Metric | Type | Description |
+|---|---|---|
+| `dora.time_to_pr_ready` | duration | Time from when the commit is created until the PR is ready for review. This metric is only available for commits that were made before the PR was marked as ready for review. |
+| `dora.review_time` | duration | Time from when the PR is marked ready for review until it receives the last approval. This metric is only available for commits that were made before the PR is approved. |
+| `dora.merge_time` | duration | Time from the last approval until the PR is merged. |
+| `dora.time_to_deploy` | duration | Time from PR merge to start of deployment. If a commit does not have an associated PR, this metric is calculated as the time from commit creation to start of deployment. |
+| `dora.deploy_time` | duration | Time from start of deployment to end of deployment. This metric is not available if there is no deployment duration information. |
+
+These metrics are only computed when the source of the repository metadata is GitHub, and there must be a pull request (PR) associated with a commit, if any. A commit is associated with a PR if the commit is first introduced to the target branch when merging that PR. If a commit does not have an associated PR, only `dora.time_to_deploy` and `dora.deploy_time` metrics are available.
+
+**Note:** These metrics are emitted for every commit and not per deployment.
+
+## Examine metrics in Event Management
+
+Default DORA Metrics are available in the [Events Explorer][1]. To search and filter on your DORA Metrics events, navigate to [**Service Management** > **Event Management** > **Explorer**][11] and enter `source:software_delivery_insights` in the search query.
+
+{{< img src="dora_metrics/events.png" alt="Events collected from DORA Metrics in the Events Explorer" style="width:100%;" >}}
+
+These metrics can be queried programmatically by using the [Query timeseries points][5] and [Query timeseries data across multiple products][6] API endpoints with the source `software_delivery_insights`.
+
+## Further Reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: /service_management/events/explorer/
+[2]: /api/latest/metrics/#query-timeseries-points
+[3]: /api/latest/metrics/#query-timeseries-data-across-multiple-products
+[5]: https://app.datadoghq.com/event/explorer?query=source%3Asoftware_delivery_insights
+[6]: /getting_started/tagging/
+[7]: /api/latest/dora-metrics/
+[8]: https://app.datadoghq.com/ci/dora
+[9]: https://docs.datadoghq.com/metrics/
+[10]: /dora_metrics/deployments/
+[11]: https://app.datadoghq.com/event/explorer?query=source%3Asoftware_delivery_insights%20&cols=&messageDisplay=expanded-lg&options=&refresh_mode=sliding&sort=DESC&from_ts=1714391730343&to_ts=1714392630343&live=true