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 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 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, in the form of traces, 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/**

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

To set up the integration:

1. Open the Azure DevOps Source Code integration tile in Datadog.

2. Select the Configuration tab and click Connect Microsoft Entra App.

3. Follow the setup instructions.

4. Click Add Organizations.

5. Follow the repository installation steps and run the setup script. If the script is not run, commits made before a pull request is created will not be associated with that pull request.

6. After the script completes, verify the integration status on the tile. The connected repositories and projects appear in the list.

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.