diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index e56931e0525ea..27cc7d457777e 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -3859,16 +3859,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 diff --git a/content/en/dora_metrics/_index.md b/content/en/dora_metrics/_index.md index f3e5c081cf424..aa24413c5f93a 100644 --- a/content/en/dora_metrics/_index.md +++ b/content/en/dora_metrics/_index.md @@ -1,7 +1,7 @@ --- 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 @@ -9,103 +9,64 @@ 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" >}}
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
{{< /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 DORA Metrics calculations and insights in a given 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/ \ No newline at end of file diff --git a/content/en/dora_metrics/data_collected/_index.md b/content/en/dora_metrics/data_collected/_index.md new file mode 100644 index 0000000000000..c95661514c20a --- /dev/null +++ b/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" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /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 \ No newline at end of file diff --git a/content/en/dora_metrics/deployments/_index.md b/content/en/dora_metrics/deployments/_index.md new file mode 100644 index 0000000000000..14fd61fd5ea1e --- /dev/null +++ b/content/en/dora_metrics/deployments/_index.md @@ -0,0 +1,157 @@ +--- +title: How to Set Up Deployment Data for DORA Metrics +kind: documentation +description: Learn how to send deployment events for DORA Metrics. +aliases: +- /continuous_integration/dora_metrics/setup/deployments +- /dora_metrics/setup/deployments +is_beta: true +further_reading: +- link: "/dora_metrics/failures" + tag: "Documentation" + text: "Learn about setting up failure data in DORA Metrics" +- 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" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /site-region >}} + +{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}} +DORA Metrics is in public beta. +{{< /callout >}} + +## Overview + +Deployment events are used to compute [deployment frequency](#calculating-deployment-frequency), [change lead time](#calculating-change-lead-time), and [change failure rate](#calculating-change-failure-rate). + +## Selecting a deployment data source + +{{< whatsnext desc="DORA Metrics supports the following data sources for deployment events. See the respective documentation to set up the data source for your deployment events:" >}} + {{< nextlink href="/dora_metrics/deployments/apm" >}}APM Deployment Tracking{{< /nextlink >}} + {{< nextlink href="/dora_metrics/deployments/deployment_api" >}}Deployment Event API or datadog-ci CLI{{< /nextlink >}} +{{< /whatsnext >}} + +## Calculating deployment frequency + +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 + +For a single Git commit, change lead time (CLT) is calculated as time from the creation of the commit to when the deployment including that commit was executed. + +To calculate change lead time for a deployment, Datadog runs [`git log`][6] between the deployment commit SHA and the previous deployment commit SHA to find all the commits being deployed. Then, it computes the average of the related change lead time values. Datadog doesn't store the actual content of files in your repository, only Git commit and tree objects. + +For more information about the breakdown of change lead time metrics, see [Data Collected][7]. + +### Synchronize repository metadata to Datadog + + + +{{< tabs >}} +{{% tab "GitHub" %}} + +
+GitHub workflows running on pull_request trigger are not currently supported by the GitHub integration. +If you are using the pull_request trigger, use the alternative method. +
+ +If the [GitHub integration][1] is not already installed, install it on the [GitHub integration tile][2]. + +When configuring the GitHub application: +1. Select at least **Read** repository permissions for **Contents** and **Pull Requests**. +2. Subscribe at least to **Push**, **PullRequest** and **PullRequestReview** events. + +To confirm that the setup is valid, select your GitHub application in the [GitHub integration tile][2] and verify that, under the **Features** tab, the **DORA Metrics: Collect Change Lead Time metric** feature is enabled. + +[1]: https://docs.datadoghq.com/integrations/github/ +[2]: https://app.datadoghq.com/integrations/github/ +{{% /tab %}} + +{{% tab "Other Git Providers" %}} + +You can upload your Git repository metadata with the [`datadog-ci git-metadata upload`][1] command. +When this command is executed, Datadog receives the repository URL, the commit SHA of the current branch, and a list of tracked file paths. + +Run this command in CI for every new commit. If a deployment is executed for a specific commit SHA, ensure that the `datadog-ci git-metadata upload` command is run for that commit **before** the deployment event is sent. + +
+Do not provide the --no-gitsync option to the datadog-ci git-metadata upload command. +When that option is included, the commit information is not sent to Datadog and the change lead time metric is not calculated. +
+ +You can validate the correct setup of the command by checking the command output. An example of a correct output is: +``` +Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git. +180 tracked file paths will be reported. +✅ Handled in 0.077 seconds. +``` + +[1]: https://github.com/DataDog/datadog-ci/tree/master/src/commands/git-metadata +{{% /tab %}} +{{< /tabs >}} + + +### Handling multiple services in the same repository + +If the source code of multiple services is present in the same repository, further actions are needed to ensure that the change lead time is calculated by taking into account only the commits affecting the specific service being deployed. + +To filter the commits measured to only the ones that affect the service, specify the source code glob file path patterns in the [service definition][5]. + +If the service definition contains a **full** GitHub URL to the application folder, a single path pattern is automatically used. + +**Example (schema version v2.2):** + +```yaml +links: + - name: shopist + type: repo + provider: github + url: https://github.com/organization/example-repository/tree/main/src/apps/shopist +``` + +DORA Metrics for the `shopist` service only consider the Git commits that include changes within `src/apps/shopist/**`. You can configure more granular control of the filtering with `extensions[datadoghq.com/dora-metrics]`. + +**Example (schema version v2.2):** + +```yaml +extensions: + datadoghq.com/dora-metrics: + source_patterns: + - src/apps/shopist/** + - src/libs/utils/** +``` + +DORA Metrics for the service `shopist` only consider the Git commits that include changes within `src/apps/shopist/**` or `src/libs/utils/**`. + +### Limitations + +- Change lead time stage breakdown metrics are only available for GitHub. +- 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" >}} + +[1]: /api/latest/dora-metrics/#send-a-deployment-event-for-dora-metrics +[2]: https://www.npmjs.com/package/@datadog/datadog-ci +[3]: /tracing/service_catalog +[4]: /tracing/service_catalog/setup +[5]: /tracing/service_catalog/adding_metadata +[6]: https://git-scm.com/docs/git-log +[7]: /dora_metrics/data_collected \ No newline at end of file diff --git a/content/en/dora_metrics/deployments/apm.md b/content/en/dora_metrics/deployments/apm.md new file mode 100644 index 0000000000000..a6830ea05e238 --- /dev/null +++ b/content/en/dora_metrics/deployments/apm.md @@ -0,0 +1,69 @@ +--- +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: "/dora_metrics/deployments" + tag: "Documentation" + text: "See other deployment data source options" +- link: "/dora_metrics/failures/" + tag: "Documentation" + text: "Learn about setting up failure data in DORA Metrics" +- 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" +- link: "https://app.datadoghq.com/release-notes?category=Software%20Delivery" + tag: "Release Notes" + text: "Check out the latest Software Delivery releases! (App login required)" +--- + +{{< site-region region="gov" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /site-region >}} + +{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}} +DORA Metrics is in public beta. +{{< /callout >}} + +## Overview + +APM [Deployment Tracking][2] can be configured as a data source for deployments in DORA Metrics. + +## Setup + +To ensure your service deployments tracked by APM 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 using the `version` tag. + +### Change lead time + +For service deployments tracked by APM to contribute to change lead time, ensure the following: + +- Your application telemetry is tagged with Git information. You can enable this [in APM][4] or see the [Source Code Integration documentation][5]. +- Your repository metadata is synchronized to Datadog through the [GitHub integration][6] or by the `datadog-ci git-metadata upload` command. + +For deployments identified through Deployment Tracking, change lead time is computed from the time of first commit creation to when that commit is first seen in a new version. The `dora.deploy_time` metric is not available. + +For more information about change lead time metrics, see [Data Collected][7]. + +## 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]: /integrations/guide/source-code-integration/?tab=go#tag-your-telemetry-with-git-information +[6]: /integrations/github/ +[7]: /dora_metrics/data_collected/#change-lead-time-metrics \ No newline at end of file diff --git a/content/en/dora_metrics/deployments/deployment_api.md b/content/en/dora_metrics/deployments/deployment_api.md new file mode 100644 index 0000000000000..e43a5abda0a5e --- /dev/null +++ b/content/en/dora_metrics/deployments/deployment_api.md @@ -0,0 +1,123 @@ +--- +title: Configuring Deployment Event Submission for DORA Metrics +kind: documentation +description: Learn how to send deployment events for DORA Metrics by using the API or CLI. +aliases: +- /continuous_integration/dora_metrics/setup/deployments +- /dora_metrics/setup/deployments +is_beta: true +further_reading: +- link: "/dora_metrics/deployments" + tag: "Documentation" + text: "See other deployment data source options" +- link: "/dora_metrics/failures/" + tag: "Documentation" + text: "Learn about setting up failure data in DORA Metrics" +- 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" +- link: "https://app.datadoghq.com/release-notes?category=Software%20Delivery" + tag: "Release Notes" + text: "Check out the latest Software Delivery releases! (App login required)" +--- + +{{< site-region region="gov" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /site-region >}} + +{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}} +DORA Metrics is in public beta. +{{< /callout >}} + +## Overview + +To send your own 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. + +The `repository_url` and `commit_sha` attributes are also required for calculating the Change Lead Time metric. You can optionally specify the `env` attribute to filter your DORA metrics by environment on the [**DORA Metrics** page][7]. + +### Example +{{< tabs >}} +{{% tab "API - cURL" %}} + +See the [DORA Metrics API reference documentation][1] for the full spec and additional code samples. + +For the following example, replace `` 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./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="" +export 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 are 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 becomes unavailable. + +[1]: https://www.npmjs.com/package/@datadog/datadog-ci +[2]: https://app.datadoghq.com/organization-settings/api-keys +{{% /tab %}} +{{< /tabs >}} + + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /api/latest/dora-metrics/#send-a-deployment-event-for-dora-metrics +[2]: https://www.npmjs.com/package/@datadog/datadog-ci +[3]: /tracing/service_catalog +[4]: /tracing/service_catalog/setup +[5]: /tracing/service_catalog/adding_metadata +[6]: https://git-scm.com/docs/git-log +[7]: https://app.datadoghq.com/ci/dora \ No newline at end of file diff --git a/content/en/dora_metrics/failures/_index.md b/content/en/dora_metrics/failures/_index.md new file mode 100644 index 0000000000000..f85f6ef6f095f --- /dev/null +++ b/content/en/dora_metrics/failures/_index.md @@ -0,0 +1,66 @@ +--- +title: How to Set Up Incident Data for DORA Metrics +kind: documentation +description: Learn how to send incident events for DORA Metrics. +aliases: +- /continuous_integration/dora_metrics/setup/incidents +- /dora_metrics/setup/incidents +is_beta: true +further_reading: +- link: "/continuous_integration/dora_metrics/setup/deployments" + tag: "Documentation" + text: "Learn about setting up deployment data in DORA Metrics" +- 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" +- link: "https://app.datadoghq.com/release-notes?category=Software%20Delivery" + tag: "Release Notes" + text: "Check out the latest Software Delivery releases! (App login required)" +--- + +{{< site-region region="gov" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /site-region >}} + +{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}} +DORA Metrics is in public beta. +{{< /callout >}} + +## Overview + +Failed deployments events, currently interpreted through incident events, are used to compute [change failure rate](#calculating-change-failure-rate) and [mean time to restore (MTTR)](#calculating-mean-time-to-restore). + +## Selecting an incident data source + +{{< whatsnext desc="DORA Metrics supports the following data sources for deployment events. See the respective documentation to set up a data source for your deployment events:" >}} + {{< nextlink href="/dora_metrics/failures/pagerduty" >}}PagerDuty{{< /nextlink >}} + {{< nextlink href="/dora_metrics/failures/incident_api" >}}Incident Event API{{< /nextlink >}} +{{< /whatsnext >}} + +## Calculating change failure rate +Change failure rate requires both [deployment data][7] and [incident data](#configuring-failure-data-sources). + +Change failure rate is calculated as the percentage of incident events out of the total number of deployments. Datadog divides `dora.incidents.count` over `dora.deployments.count` for the same services and/or teams associated to both an failure and a deployment event. + +## Calculating time to restore +Time to restore is calculated as the duration distribution for *resolved incident* events. + +DORA Metrics generates the `dora.time_to_restore` metric by recording the start and end times of each incident event. It calculates the mean time to restore (MTTR) as the average of these `dora.time_to_restore` data points over a selected time frame. + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /api/latest/dora-metrics/#send-a-deployment-event-for-dora-metrics +[2]: https://www.npmjs.com/package/@datadog/datadog-ci +[3]: /tracing/service_catalog +[4]: /tracing/service_catalog/setup +[5]: /tracing/service_catalog/adding_metadata +[6]: https://git-scm.com/docs/git-log +[7]: /dora_metrics/deployments diff --git a/content/en/dora_metrics/setup/incidents.md b/content/en/dora_metrics/failures/incident_api.md similarity index 63% rename from content/en/dora_metrics/setup/incidents.md rename to content/en/dora_metrics/failures/incident_api.md index abdeaaa3eddf3..eef57adf5e133 100644 --- a/content/en/dora_metrics/setup/incidents.md +++ b/content/en/dora_metrics/failures/incident_api.md @@ -1,48 +1,55 @@ --- -title: Sending Incident Events for DORA Metrics +title: Configuring Incident Event Submission for DORA Metrics kind: documentation description: Learn how to send incident events for DORA Metrics. aliases: - /continuous_integration/dora_metrics/setup/incidents 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: "/dora_metrics/failures" + tag: "Documentation" + text: "See other incident data source options" - link: "/tracing/service_catalog" tag: "Documentation" text: "Learn about the Service Catalog" -- link: "/code_analysis" +- link: "/continuous_delivery/deployments" tag: "Documentation" - text: "Learn about Code Analysis" + text: "Learn about Deployment Visibility" +- link: "https://app.datadoghq.com/release-notes?category=Software%20Delivery" + tag: "Release Notes" + text: "Check out the latest Software Delivery releases! (App login required)" --- {{< site-region region="gov" >}}
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
{{< /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 -Incident events are used in order to compute Change Failure Rate and Mean Time to Restore. -To send incident events, use the [DORA Metrics API][1]. The following attributes are required: +To send your own incident events, use the [DORA Metrics API][1]. Incident events are used in order to compute change failure rate and mean time to restore. + +Include the `finished_at` attribute in an incident event to mark that the incident is resolved. You can send events at the start of the incident and after incident resolution. Incident events are matched by the `env`, `service`, and `started_at` attributes. + +The following attributes are required: - `services` or `team` (at least one must be present) - `started_at` You can optionally add the following attributes to the incident events: -- `finished_at` for *resolved incidents*. This attribute is required for [time to restore service](#time-to-restore-service). + +- `finished_at` for *resolved incidents*. This attribute is required for calculating the time to restore service. - `id` for identifying incidents when they are created and resolved. This attribute is user-generated; when not provided, the endpoint returns a Datadog-generated UUID. - `name` to describe the incident. - `severity` -- `env` to accurately filter your DORA metrics by environment. +- `env` to filter your DORA metrics by environment on the [**DORA Metrics** page][3]. - `repository_url` - `commit_sha` -See the [DORA Metrics API reference documentation][1] for the full spec and more examples with the API SDKs. +See the [DORA Metrics API reference documentation][1] for the full spec and additional code samples. ### Example @@ -72,22 +79,10 @@ curl -X POST "https://api.{{< region-param key="dd_site" >}}/api/v2/dora/inciden EOF ``` -## Change Failure Rate - -The Change Failure Rate metric is calculated as the percentage of incident events out of the total number of deployments. -Send both [deployment events][2] and [incident events](#overview) to correctly populate this metric. - -## Time to restore service - -The Mean Time to Restore (MTTR) metric is calculated as the duration distribution for *resolved incident* events. -Include the `finished_at` attribute in an incident event to mark that the incident is resolved. - -Events can be sent both at the start of the incident and after incident resolution. Incident events are matched by the `env`, `service`, and `started_at` attributes. - ## Further Reading {{< partial name="whats-next/whats-next.html" >}} - [1]: /api/latest/dora-metrics/#send-an-incident-event-for-dora-metrics -[2]: /continuous_integration/dora_metrics/setup/deployments +[2]: /dora_metrics/deployments +[3]: https://app.datadoghq.com/ci/dora \ No newline at end of file diff --git a/content/en/dora_metrics/failures/pagerduty.md b/content/en/dora_metrics/failures/pagerduty.md new file mode 100644 index 0000000000000..3adedd0840c50 --- /dev/null +++ b/content/en/dora_metrics/failures/pagerduty.md @@ -0,0 +1,79 @@ +--- +title: Configuring PagerDuty for DORA Metrics +kind: documentation +description: Learn how to configure PagerDuty as a data source for DORA Metrics incidents. +is_beta: true +further_reading: +- link: "/dora_metrics/failures" + tag: "Documentation" + text: "See other incident data source options" +- link: "/dora_metrics/deployments" + tag: "Documentation" + text: "Learn about setting up deployments in DORA Metrics" +- link: "/service_management/events" + tag: "Documentation" + text: "Learn about Event Management" +- link: "/monitors/types/metric" + tag: "Documentation" + text: "Learn about Metric Monitors" +- link: "https://app.datadoghq.com/release-notes?category=Software%20Delivery" + tag: "Release Notes" + text: "Check out the latest Software Delivery releases! (App login required)" +--- + +{{< site-region region="gov" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /site-region >}} + +{{< callout url="#" btn_hidden="true" header="Try the Beta!" >}} +DORA Metrics is in public beta. +{{< /callout >}} + +## Overview + +[PagerDuty][7] is an incident management platform that equips IT teams with immediate incident visibility, enabling proactive and effective responses to maintain operational stability and resilience. + +[PagerDuty incidents][1] can be configured as a data source for failures in DORA Metrics. + +## Setup + +To integrate your PagerDuty account with DORA Metrics, navigate to **Integrations > Developer Tools** in PagerDuty and click **Generic Webhooks (v3)**. + +1. Click **+ New Webhook** and enter the following details: + + | Variable | Description | + |---|---| + | Webhook URL | Add `https://webhook-intake.{{< region-param key="dd_site" >}}/api/v2/webhook/`. | + | Scope Type | Select **Account** to send incidents for all PagerDuty services in your account. Alternatively, you can send incidents for specific services or teams by selecting a different scope type. | + | Description | A description helps distinguish the webhook. Add something like `Datadog DORA Metrics integration`. | + | Event Subscription | Select the following events:
-`incident.acknowledged`
-`incident.annotated`
-`incident.custom_field_values.updated`
-`incident.delegated`
-`incident.escalated`
-`incident.priority_updated`
-`incident.reassigned`
-`incident.reopened`
-`incident.resolved`
-`incident.triggered`
-`incident.unacknowledged` | + | Custom Headers | Click **Add custom header**, enter `DD-API-KEY` as the name, and input your [Datadog API key][2] as the value.

Optionally, you can add an environment to all of the PagerDuty incidents sent from the webhook by creating an additional custom header with the name `dd_env` and the desired environment as the value. | + +1. To save the webhook, click **Add Webhook**. + +The severity of the incident in the DORA Metrics product is based on the [incident priority][5] in PagerDuty. + +**Note:** Upon webhook creation, a new secret is created and used to sign all the webhook payloads. That secret is not needed for the integration to work, as the authentication is performed using the API key instead. + +### Mapping PagerDuty services to Datadog services + +When an incident event is received for a specific [PagerDuty service][3], Datadog attempts to retrieve the related Datadog service and team from the [Service Catalog][4]. + +The matching algorithm works in the following scenarios: + +1. If the incident service URL matches with the PagerDuty service URL configured for one or more services in the Service Catalog. In this scenario, the incident metrics and events are emitted with the Datadog team name. For more information on setting the PagerDuty service URL for a Datadog service, see [Use Integrations with Service Catalog][6]. +2. If the PagerDuty service name of the incident matches a Datadog service name in the Service Catalog. In this scenario, the incident metrics and events are emitted with the Datadog service name and team retrieved from Service Catalog. +3. If the PagerDuty team name of the incident matches a Datadog team name in the Service Catalog. In this scenario, the incident metrics and events are emitted with the corresponding Datadog team name. +4. If the PagerDuty service name of the incident matches a Datadog team name in the Service Catalog. In this scenario, the incident metrics and events are emitted with the Datadog team name. + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://support.pagerduty.com/docs/incidents +[2]: https://app.datadoghq.com/organization-settings/api-keys +[3]: https://support.pagerduty.com/docs/services-and-integrations +[4]: /service_catalog/ +[5]: https://support.pagerduty.com/docs/incident-priority +[6]: /service_catalog/integrations/#pagerduty-integration +[7]: /integrations/pagerduty/ \ No newline at end of file diff --git a/content/en/dora_metrics/setup/_index.md b/content/en/dora_metrics/setup/_index.md index a53bd1811c3ad..c046583dc638c 100644 --- a/content/en/dora_metrics/setup/_index.md +++ b/content/en/dora_metrics/setup/_index.md @@ -3,33 +3,55 @@ title: Set up DORA Metrics kind: documentation aliases: - /continuous_integration/dora_metrics/setup/ +further_reading: +- link: '/dora_metrics/' + tag: 'Documentation' + text: 'Learn about DORA Metrics' --- -{{< 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. +{{< site-region region="gov" >}} +
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
+{{< /site-region >}} + +{{< 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. - -Deployment Frequency -: How often an organization successfully releases to production. +The four DORA Metrics are calculated based on two types of events: -Lead Time for Changes -: The amount of time it takes a commit to get into production. +- [**Deployment events**][8]: Indicate that a new deployment has occurred for a service in a specific environment. +- [**Incident events**][9]: Indicate that a new failure has occurred for a service in a specific environment. -Change Failure Rate -: The percentage of deployments causing a failure in production. +Each event type supports different data sources. -Time to Restore Service -: How long it takes an organization to recover from a failure in production. +## Configure data sources -Defining and tracking DORA metrics can help you identify areas of improvement for your team or organization's speed and quality of software delivery. +### Deployments +{{< whatsnext desc="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:" >}} + {{< nextlink href="/dora_metrics/deployments/apm" >}}APM Deployment Tracking{{< /nextlink >}} + {{< nextlink href="/dora_metrics/deployments/deployment_api" >}}Deployment Event API or datadog-ci CLI{{< /nextlink >}} +{{< /whatsnext >}} -{{< 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 >}} +### Failures +{{< whatsnext desc="Failure events, interpreted through incident events, are used to compute change failure rate and mean time to restore. See the respective documentation to set up a data source for your failure events:">}} + {{< nextlink href="/dora_metrics/failures/pagerduty" >}}PagerDuty{{< /nextlink >}} + {{< nextlink href="/dora_metrics/failures/incident_api" >}}Incident Event API{{< /nextlink >}} {{< /whatsnext >}} -[1]: https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance +## Limitations + +Deployments or incidents of the same service cannot occur at the same second. + +## Further Reading + +{{< partial name="whats-next/whats-next.html" >}} + +[3]: /dora_metrics/ +[4]: /service_management/events/explorer/ +[5]: /api/latest/metrics/#query-timeseries-points +[6]: /api/latest/metrics/#query-timeseries-data-across-multiple-products +[7]: /dora_metrics/data_collected/ +[8]: /dora_metrics/deployments/ +[9]: /dora_metrics/failures/ diff --git a/content/en/dora_metrics/setup/deployments.md b/content/en/dora_metrics/setup/deployments.md deleted file mode 100644 index 7ac356a0bf0d7..0000000000000 --- a/content/en/dora_metrics/setup/deployments.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Sending Deployment Events for DORA Metrics -kind: documentation -description: Learn how to send deployment events for DORA Metrics. -aliases: -- /continuous_integration/dora_metrics/setup/deployments -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" >}} -
DORA Metrics is not available in the selected site ({{< region-param key="dd_site_name" >}}) at this time.
-{{< /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 - -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. - -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). - -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 `` 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./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="" -export 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 >}} - -## Calculating Change Lead Time - -For a single Git commit, the Change Lead Time (CLT) is calculated as time from the creation of the commit to when the deployment including that commit was executed. -To calculate the Change Lead Time for a deployment, Datadog runs [`git log`][6] between the deployment commit SHA and the previous deployment commit SHA to find all the commits being deployed. Then, it computes the average of the related Change Lead Time values. -Datadog doesn't store the actual content of files in your repository, only Git commit and tree objects. - -There are two requirements for calculating Change Lead Time: -1. Both the Git repository URL and commit SHA are provided when sending deployment events. -2. Your repository metadata is being [synchronized to Datadog](#synchronize-repository-metadata-to-datadog). - -### Breakdown metrics - -Datadog also provides the following breakdown metrics, which represent the different stages since a commit is made until it is deployed. - -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. - -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.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. -- `dora.deploy_time`: Time from start of deployment to end of deployment. This metric is not available if there is no deployment duration information. - -**Note:** These metrics are emitted for every commit and not per deployment. - -### Synchronize repository metadata to Datadog - - - -{{< tabs >}} -{{% tab "GitHub" %}} - -
-GitHub workflows running on pull_request trigger are not currently supported by the GitHub integration. -If you are using the pull_request trigger, use the alternative method. -
- -If the [GitHub integration][1] is not already installed, install it on the [GitHub integration tile][2]. - -When configuring the GitHub application: -1. Select at least **Read** repository permissions for **Contents** and **Pull Requests**. -2. Subscribe at least to **Push**, **PullRequest** and **PullRequestReview** events. - -To confirm that the setup is valid, select your GitHub application in the [GitHub integration tile][2] and verify that, under the **Features** tab, the **DORA Metrics: Collect Change Lead Time metric** feature is enabled. - -[1]: https://docs.datadoghq.com/integrations/github/ -[2]: https://app.datadoghq.com/integrations/github/ -{{% /tab %}} - -{{% tab "Other Git Providers" %}} - -You can upload your Git repository metadata with the [`datadog-ci git-metadata upload`][1] command. -When this command is executed, Datadog receives the repository URL, the commit SHA of the current branch, and a list of tracked file paths. - -Run this command in CI for every new commit. If a deployment is executed for a specific commit SHA, ensure that the `datadog-ci git-metadata upload` command is run for that commit **before** the deployment event is sent. - -
-Do not provide the --no-gitsync option to the datadog-ci git-metadata upload command. -When that option is included, the commit information is not sent to Datadog and the Change Lead Time metric is not calculated. -
- -You can validate the correct setup of the command by checking the command output. An example of a correct output is: -``` -Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git. -180 tracked file paths will be reported. -✅ Handled in 0.077 seconds. -``` - -[1]: https://github.com/DataDog/datadog-ci/tree/master/src/commands/git-metadata -{{% /tab %}} -{{< /tabs >}} - - -### Handling multiple services in the same repository - -If the source code of multiple services is present in the same repository, further actions are needed to ensure that the Change Lead Time is calculated by taking into account only the commits affecting the specific service being deployed. -To filter the commits measured to only the ones that affect the service, specify the source code glob file path patterns in the [service definition][5]. - -If the service definition contains a **full** GitHub URL to the application folder, a single path pattern is automatically used. - -**Example (schema version v2.2):** - -```yaml -links: - - name: shopist - type: repo - provider: github - url: https://github.com/organization/example-repository/tree/main/src/apps/shopist -``` - -DORA Metrics for the `shopist` service only consider the Git commits that include changes within `src/apps/shopist/**`. You can configure more granular control of the filtering with `extensions[datadoghq.com/dora-metrics]`. - -**Example (schema version v2.2):** - -```yaml -extensions: - datadoghq.com/dora-metrics: - source_patterns: - - src/apps/shopist/** - - src/libs/utils/** -``` - -DORA Metrics for the service `shopist` only consider the Git commits that include changes within `src/apps/shopist/**` or `src/libs/utils/**`. - -### Limitations - -- The retention of Git metadata is 1 month. Commits older than 1 month might not be taken into account when computing Change Lead Time. -- Change Lead Time is not available for the first deployment of a service that includes Git information. - - -## Further Reading - -{{< partial name="whats-next/whats-next.html" >}} - -[1]: /api/latest/dora-metrics/#send-a-deployment-event-for-dora-metrics -[2]: https://www.npmjs.com/package/@datadog/datadog-ci -[3]: /tracing/service_catalog -[4]: /tracing/service_catalog/setup -[5]: /tracing/service_catalog/adding_metadata -[6]: https://git-scm.com/docs/git-log diff --git a/static/images/dora_metrics/dora_page_dark.png b/static/images/dora_metrics/dora_page_dark.png new file mode 100644 index 0000000000000..e659519364e44 Binary files /dev/null and b/static/images/dora_metrics/dora_page_dark.png differ diff --git a/static/images/dora_metrics/dora_page_light.png b/static/images/dora_metrics/dora_page_light.png new file mode 100644 index 0000000000000..024c8ef4c624c Binary files /dev/null and b/static/images/dora_metrics/dora_page_light.png differ diff --git a/static/images/dora_metrics/events.png b/static/images/dora_metrics/events.png new file mode 100644 index 0000000000000..7bd36b10294c7 Binary files /dev/null and b/static/images/dora_metrics/events.png differ diff --git a/static/images/dora_metrics/home.png b/static/images/dora_metrics/home.png new file mode 100644 index 0000000000000..1466c5833138a Binary files /dev/null and b/static/images/dora_metrics/home.png differ