APM Deployment Tracking can be configured as a data source for deployments in DORA Metrics.

Requirements

• APM Deployment Tracking is enabled as a Deployments event data source in DORA settings.
• Your service has metadata defined in the Software Catalog.
• Your service has unified service tagging enabled. Deployments are identified using the version tag.

For more information about ensuring service deployments that are tracked by APM contribute to change lead time, see Enrich deployments with commit information.

To send your own deployment events, use the DORA Metrics API or the datadog-ci dora deployment command.

Requirements

• datadog-ci CLI / API is enabled as a Deployments event data source in DORA settings.
• 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. If the provided service is registered in the Software Catalog with metadata set up (see Adding Metadata), the team of the service is automatically retrieved and associated with all metrics.

You can optionally add the following attributes to the deployment events:

• repository_url: The source code repository of the service. Required for calculating change lead time.
• commit_sha: The SHA of the HEAD commit associated with the deployment. Required for calculating change lead time.
• team: Associate a deployment with a different team than the one found automatically for the service.
• env: Filter your DORA metrics by environment on the DORA Metrics page.
• id: Identify a deployment. This attribute is user-generated; when not provided, the endpoint returns a Datadog-generated UUID.
• version: The deployment version.
• custom_tags: Tags in the form key:value that can be used to filter events on the DORA Metrics page.

API (cURL) Example

See the DORA Metrics API reference documentation for the full spec and additional code samples.

For the following example, replace <DD_SITE> in the URL with and ${DD_API_KEY} with your Datadog API Key:

  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",
        "team": "backend",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF

CLI Example

The datadog-ci 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 and set the DD_API_KEY environment variable to your Datadog API Key:

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` \
    --version v1.12.07 --custom-tags department:engineering \
    --custom-tags app_type:backend \
    --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.

For deployments identified through APM Deployment Tracking, ensure your application telemetry is tagged with Git information:

• Enable Git tagging in APM or see the Source Code Integration documentation

Note: For APM-tracked deployments, change lead time is calculated from commit creation to when the commit is first observed in a new version. The Deploy Time metric is not available.

For deployments tracked by the DORA Metrics API or the datadog-ci dora deployment command, ensure:

• The attributes repository_url and commit_sha are included in the deployment events payload

If the GitHub integration is not already installed, install it on the GitHub integration tile.

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 and verify that the Datadog Features table shows Pull Request Information meets all requirements.

If the GitLab Source Code integration is not already installed, install it on the GitLab Source Code integration tile.

Note: The scope of the service account’s personal access token needs to be at least read_api.

Handling GitLab groups and subgroups

If your repositories are organized under GitLab groups or subgroups (for example, https://gitlab.com/my-org/group(/subgroup)/repo), the automatic service path detection may not resolve correctly due to GitLab’s nested group structure.

To ensure that DORA metrics handle your service’s source code paths correctly, you can use the following configuration in your service definition:

extensions:
  datadoghq.com/dora-metrics:
    source_patterns:
      # All paths relative to the repository URL provided with the deployment
      - **
      # or specific paths related to this service (for monorepos)
      - src/apps/shopist/**
      - src/libs/utils/**

You can upload your Git repository metadata with the datadog-ci git-metadata upload 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.

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.

DORA Metrics can automatically identify and track failures through Datadog Incidents. After incidents are declared, DORA uses them to measure change failure rate and time to restore.

Note: The time to restore is measured as the total duration an incident spends in the active state. For cases like active → stable → active → stable, it includes all active periods. The time to restore is shown only when an incident is in a stable or resolved state. If a resolved incident is reactivated, the metric is hidden until it’s resolved again.

Requirements

• Incidents is enabled as a Failures event data source in DORA settings.

To avoid having unlabeled failures, Datadog strongly recommends adding the following attributes to incidents:

• Teams
• Services
• Envs: The Envs attribute can be added in the Incident Settings if it doesn’t already exist.

If provided with incidents, the Severity tag is added to failure events.

Recommended: In the Incident Settings, set attributes field Prompted to At Resolution to ensure you never forget to add these attributes to your incidents.

Include historical incidents

You can retroactively include incidents from the past two years by selecting Backfill Data in the DORA settings, which creates failures from those incidents. Backfilling data can take up to an hour to complete.

PagerDuty is an incident management platform that equips IT teams with immediate incident visibility, enabling proactive and effective responses to maintain operational stability and resilience.

To integrate your PagerDuty account with DORA Metrics:

1. Enable PagerDuty as a Failures event data source in DORA settings.

2. Navigate to Integrations > Developer Tools in PagerDuty and click Generic Webhooks (v3).

3. Click + New Webhook and enter the following details:

   Variable	Description
   Webhook URL	Add https://webhook-intake./api/v2/webhook/.
   Scope Type	Select the scope of which incidents you want to send. You can send incidents for a specific Service or Team, or all PagerDuty services in your Account. Depending on your environment and access level, some scope types may not be available.
   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 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.

4. To save the webhook, click Add Webhook.

The severity of the failure in the DORA Metrics product is based on the incident priority 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, Datadog attempts to retrieve the related Datadog service and team from any triggering Datadog monitors and from the Software Catalog.

The matching algorithm works in the following steps:

1. If the PagerDuty incident event was triggered from a Datadog monitor:

   • If the monitor is in Multi Alert mode, the incident metrics and events are emitted with the env, service, and team from the alerted group.
   • If the monitor has tags for env, service, or team:
     • env: If the monitor has a single env tag, the incident metrics and events are emitted with the environment.
     • service: If the monitor has one or more service tags, the incident metrics and events are emitted with the provided services.
     • team: If the monitor has a single team tag, the incident metrics and events are emitted with the team.

2. If the service URL of the incident matches the PagerDuty service URL for any services in the Software Catalog:

   • If a single Datadog service matches, the incident metrics and events are emitted with the service and team.
   • If multiple Datadog services match, the incident metrics and events are emitted with the team.

   For more information about setting the PagerDuty service URL for a Datadog service, see Use Integrations with Software Catalog.

3. If the PagerDuty service name of the incident matches a service name in the Software Catalog, the incident metrics and events are emitted with the service and team.

4. If the PagerDuty team name of the incident matches a team name in the Software Catalog, the incident metrics and events are emitted with the team.

5. If the PagerDuty service name of the incident matches a team name in the Software Catalog, the incident metrics and events are emitted with the team.

6. If there have been no matches up to this point, the incident metrics and events are emitted with the PagerDuty service and PagerDuty team provided in the incident.

To send your own failure events, use the DORA Metrics API. Failure events are used in order to calculate change failure rate and time to restore.

Include the finished_at attribute in a failure event to mark that the failure is resolved. You can send events at the start of the failure and after it has been resolved. Failure events are matched by the env, service and started_at attributes.

Requirements

• datadog-ci CLI / API is enabled as a Failures event data source in DORA settings.
• 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 failure events:

• finished_at for resolved failures. Required for calculating time to restore
• id for identifying failures. This attribute is user-generated; when not provided, the endpoint returns a Datadog-generated UUID.
• name to describe the failure.
• severity
• env to filter your DORA metrics by environment on the DORA Metrics page.
• repository_url
• commit_sha
• version
• custom_tags: Tags in the form key:value that can be used to filter events on the DORA Metrics page.

See the DORA Metrics API reference documentation for the full spec and additional code samples.

API (cURL) Example

For the following configuration, replace <DD_SITE> with :

curl -X POST "https://api.<DD_SITE>/api/v2/dora/failure" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "services": ["shopist"],
        "team": "shopist-devs",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "name": "Web server is down failing all requests",
        "severity": "High",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF