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: Send Deployment Events
+      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: api/latest/dora-metrics/#send-a-deployment-event-for-dora-metrics
+      parent: dora_metrics_deployments
+      identifier: dora_metrics_deployment_events_api
+      weight: 202
+    - name: Send Incident Events
+      url: dora_metrics/incidents/
+      parent: dora_metrics
+      identifier: dora_metrics_incidents
+      weight: 3
+    - name: PagerDuty
+      url: dora_metrics/incidents/pagerduty
+      parent: dora_metrics_incidents
+      identifier: dora_metrics_incident_pagerduty
+      weight: 301
+    - name: API
+      url: api/latest/dora-metrics/#send-an-incident-event-for-dora-metrics
+      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,26 +1,23 @@
 ---
 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" >}}
@@ -33,7 +30,7 @@ The DORA Metrics private beta is closed. Fill out the form below to be added to
 
 ## 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
 : How often an organization successfully releases to production.
@@ -51,6 +48,9 @@ Defining and tracking DORA metrics can help you identify areas of improvement fo
 
 ## Set up DORA Metrics
 
+
+To start configuring data sources to send deployment and incident events to Datadog, see the [Setup documentation][2].
+
 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.
@@ -62,50 +62,31 @@ The four DORA Metrics are calculated based on two types of events:
     {{< 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`.
+## Analyze DORA Metrics
 
-All the metrics contain the following tags when available:
-- `service`
-- `team`
-- `env`
-- `repository_id`
+Once you've set up the data sources for your deployment and incident events, navigate to [**Software Delivery** > **DORA Metrics**][4] to identify improvements or regressions for each metric, examine deployments by service or environment, and compare trends over time. 
 
-**Note**: The `severity` tag is available for the `dora.incidents_impact` and `dora.time_to_restore` metrics, if provided through the API.
+{{< img src="dora_metrics/home.png" alt="An Overview of your DORA Metrics calculations and insights in the last week" style="width:100%;" >}}
 
-### Deployment and incident events
+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].
 
-DORA Metrics also provides individual `deployment`, `incident`, and `incident_finished` events in [Event Management][6] with `source:software_delivery_insights`.
+## Explore DORA Metrics events in Event Management
 
-The events can be queried and visualized with the [Events Explorer][7].
+DORA Metrics provides individual `deployment`, `incident`, and `incident_finished` events under the `Software Delivery Insights` source in [Event Management][7]. Navigate to [**Service Management** > **Event Management** > **Explorer**][8] and enter `source:software_delivery_insights` in the search query to filter on DORA Metrics events.
 
-### Limitations
+{{< img src="dora_metrics/events.png" alt="Events collected from DORA Metrics in the Events Explorer" style="width:100%;" >}}
 
-- 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 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/
+[2]: /dora_metrics/setup/
+[3]: /dora_metrics/data_collected/
+[4]: https://app.datadoghq.com/ci/dora
+[5]: /monitors/types/metric/?tab=threshold
+[6]: /monitors/
+[7]: /service_management/events/
+[8]: https://app.datadoghq.com/event/explorer

content/en/dora_metrics/data_collected/_index.md

@@ -0,0 +1,55 @@
+---
+title: DORA Metrics Data Collected
+kind: documentation
+further_reading:
+- link: '/dora_metrics/'
+  tag: 'Documentation'
+  text: 'Learn about DORA Metrics'
+- link: '/getting_started/tagging/'
+  tag: 'Documentation'
+  text: 'Getting Started with Tags'
+- link: '/dora_metrics/setup/'
+  tag: 'Documentation'
+  text: 'Send deployment and incident events to Datadog'
+---
+
+## Overview
+
+DORA Metrics generates events that have associated tags and attributes. These events are available in the [Events Explorer][1].
+
+## Default metrics
+
+DORA Metrics provides the following default metrics:
+
+| Metric | Type | Description |
+| :--- | :--- | :--- |
+| `dora.deployments.count` | count | Used to calculate 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 the 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`.
+
+### 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, if it is provided through the [DORA Metrics API][7].
+
+For more information about using `env`, `service`, and `version` tags, see [Getting Started with Tags][6].
+
+## 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
+[4]: /service_management/events/
+[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

content/en/dora_metrics/setup/deployments.md → content/en/dora_metrics/deployments/_index.md

@@ -31,80 +31,17 @@ further_reading:
 The DORA Metrics private beta is closed. Fill out the form below to be added to the waitlist.
 {{< /callout >}}
 
-## Overview
+## Configure Deployment Data Sources 
+Deployment events are used to compute Deployment Frequency, Change Lead Time, and Change Failure Rate. See the respective documentation to set up a data source for your deployment events:
 
-Deployment events are used to compute Deployment Frequency, Change Lead Time, and Change Failure Rate.
-To send deployment events, use the [DORA Metrics API][1] or the [`datadog-ci dora deployment`][2] command. The following attributes are required:
-- `started_at`: The time the deployment started.
-- `finished_at`: The time the deployment finished.
-- `service`: The service that was deployed. The provided service must be registered in the [Service Catalog][3] (see [Adding Entries to Service Catalog][4]) with metadata set up (see [Adding Metadata][5]).
-The `team` ownership of the service is automatically inferred from the Service Catalog and associated with all metrics.
+{{< whatsnext desc="DORA Metrics supports the following data sources for deployment events:" >}}
+  {{< nextlink href="/dora_metrics/deployments/apm" >}}APM Deployment Tracking{{< /nextlink >}}
+  {{< nextlink href="/dora_metrics/deployments/" >}}Send a Deployment Event API or use the datadog-ci CLI{{< /nextlink >}}
+{{< /whatsnext >}}
 
-The `repository_url` and `commit_sha` attributes are required for calculating the Change Lead Time metric. For more information, see [Calculating Change Lead Time](#calculating-change-lead-time).
+## Calculating Deployment Frequency
 
-You can optionally specify the `env` attribute to accurately filter your DORA metrics by environment.
-
-### Example
-{{< tabs >}}
-{{% tab "API - cURL" %}}
-
-See the [DORA Metrics API reference documentation][1] for the full spec and more examples with the API SDKs.
-
-For the following example, replace `<DD_SITE>` in the URL with {{< region-param key="dd_site" code="true" >}} and `${DD_API_KEY}` with your [Datadog API Key][2]:
-```shell
-  curl -X POST "https://api.<DD_SITE>/api/v2/dora/deployment" \
-  -H "Accept: application/json" \
-  -H "Content-Type: application/json" \
-  -H "DD-API-KEY: ${DD_API_KEY}" \
-  -d @- << EOF
-  {
-    "data": {
-      "attributes": {
-        "service": "shopist",
-        "started_at": 1693491974000000000,
-        "finished_at": 1693491984000000000,
-        "git": {
-          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
-          "repository_url": "https://github.com/organization/example-repository"
-        },
-        "env": "prod"
-      }
-    }
-  }
-EOF
-```
-
-[1]: /api/latest/dora-metrics/#send-a-deployment-event-for-dora-metrics
-[2]: https://app.datadoghq.com/organization-settings/api-keys
-{{% /tab %}}
-
-{{% tab "datadog-ci CLI" %}}
-
-The [`datadog-ci`][1] CLI tool provides a shortcut to send deployment events within your Continuous Integration environment.
-
-For the following example, set the `DD_SITE` environment variable to {{< region-param key="dd_site" code="true" >}} and set the `DD_API_KEY` environment variable to your [Datadog API Key][2]:
-```shell
-export DD_BETA_COMMANDS_ENABLED=1
-export DD_SITE="<DD_SITE>"
-export DD_API_KEY="<DD_API_KEY>"
-
-export deploy_start=`date +%s`
-./your-deploy-script.sh
-datadog-ci dora deployment --service shopist --env prod \
-    --started-at $deploy_start --finished-at `date +%s` \
-    --git-repository-url "https://github.com/organization/example-repository" \
-    --git-commit-sha 66adc9350f2cc9b250b69abddab733dd55e1a588
-```
-
-The deployment finish time is automatically set to now if `--finished-at` is not provided.
-
-If the deployment CI job is running on the exact same Git revision that is being deployed, `git-repository-url` and `git-commit-sha` can be omitted and will be automatically inferred from the CI context.
-The `--skip-git` option can be provided to disable sending the repository URL and commit SHA. When this option is added, the Change Lead Time metric will not be available.
-
-[1]: https://www.npmjs.com/package/@datadog/datadog-ci
-[2]: https://app.datadoghq.com/organization-settings/api-keys
-{{% /tab %}}
-{{< /tabs >}}
+Deployment frequency is calculated based on the `dora.deployments.count` metric that is generated and increased with each deployment detected from your selected deployment data source. Frequency is calculated by dividing `dora.deployments.count` over a specific time frame.
 
 ## Calculating Change Lead Time
 
@@ -118,13 +55,13 @@ There are two requirements for calculating Change Lead Time:
 
 ### Breakdown metrics
 
-Datadog also provides the following breakdown metrics, which represent the different stages since a commit is made until it is deployed.
+Datadog breaks down change lead time into the following metrics, which represent the different stages from commit creation to deployment.
 
-To compute these metrics, the PR associated with a commit must be identified, if any. A commit is associated with a PR if the commit is first introduced to the target branch when merging that PR.
+To compute these metrics, there must be a 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 Time to Deploy and Deploy Time are available.
 
-- `dora.time_to_pr_ready`: Time from the commit creation until the PR is ready for review. This metric is only available for commits that were made before the PR is ready for review.
+- `dora.time_to_pr_ready`: 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 is ready for review.
 - `dora.review_time`: 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`: Time from the last approval until the PR is merged.
 - `dora.time_to_deploy`: 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.
@@ -220,6 +157,9 @@ DORA Metrics for the service `shopist` only consider the Git commits that includ
 - Change Lead Time is not available for the first deployment of a service that includes Git information.
 
 
+## Calculating Change Failure Rate
+Change failure rate is calculated by dividing `dora.incidents.count` over `dora.deployments.count` for the same services and/or teams associated to both an incident and a deployment event. 
+
 ## Further Reading
 
 {{< partial name="whats-next/whats-next.html" >}}

content/en/dora_metrics/deployments/apm.md

@@ -0,0 +1,56 @@
+---
+title: Configuring APM Deployment Tracking for DORA Metrics
+kind: documentation
+description: Learn how to configure APM Deployment Tracking as a data source for DORA Metrics deployments.
+aliases:
+- /continuous_integration/dora_metrics/setup/apm
+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/dora_metrics/setup/incidents"
+  tag: "Documentation"
+  text: "Learn about sending incident events"
+- link: "/tracing/service_catalog"
+  tag: "Documentation"
+  text: "Learn about the Service Catalog"
+- link: "https://github.com/DataDog/datadog-ci"
+  tag: "Source Code"
+  text: "Learn about the datadog-ci CLI tool"
+- link: "/continuous_delivery/deployments"
+  tag: "Documentation"
+  text: "Learn about Deployment Visibility"
+---
+
+{{< 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 >}}
+
+## Overview
+APM [Deployment Tracking][2] can be configured as a data source for deployments in DORA Metrics.
+
+For service deployments tracked by APM to contribute to DORA Metrics, the following requirements must be met:
+- Your service has [metadata][1] defined in the Service Catalog.
+- Your service has [unified service tagging][3] enabled. Deployments are identified via the `version` tag.
+
+## Change lead time
+For service deployments tracked by APM to contribute to Change Lead Time, the following requirement must be met:
+- Your application telemetry is tagged with git information. You can enable this [in APM][4] or see [documentation][5].
+- Your repository metadata is synchronized to Datadog via the GitHub integration.
+
+For deployments identified via Deployment Tracking, change lead time is computed from time of first commit creation to when that commit is first seen in a new version. `dora.deploy_time` metric is not available. 
+
+## Further Reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: /service_catalog/add_metadata
+[2]: /tracing/services/deployment_tracking
+[3]: /getting_started/tagging/unified_service_tagging/?tab=kubernetes
+[4]: https://app.datadoghq.com/source-code/setup/apm
+[5]: https://docs.datadoghq.com/integrations/guide/source-code-integration/?tab=go#tag-your-telemetry-with-git-information