Adding Custom Tags and Measures to Pipeline Traces

The custom tags and measures commands provide a way to add user-defined text and numerical tags to your CI Visibility pipeline traces. These tags can be used to create facets (string value tags) or measures (numerical value tags). Facets and measures can then be used to search, graph, or monitor the pipelines.

Compatibility

Custom tags and measures work with the following CI providers:

• Buildkite
• CircleCI
• GitLab (SaaS or self-hosted >= 14.1)
• GitHub.com (SaaS) Note: For adding tags and measures to GitHub jobs, see the section below.
• Jenkins Note: For Jenkins, follow these instructions to set up custom tags in your pipelines.
• Azure DevOps Pipelines

Install the Datadog CI CLI

Install the datadog-ci (>=v1.15.0) CLI globally using npm:

npm install -g @datadog/datadog-ci

Alternatively, you can try and use the beta standalone binary if you don’t want to use npm.

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_linux-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_darwin-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

Invoke-WebRequest -Uri "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_win-x64.exe" -OutFile "datadog-ci.exe"

Add tags to pipeline traces

Tags can be added to the pipeline span or to the job span. To do this, run:

datadog-ci tag [--level <pipeline|job>] [--tags <tags>]

You must specify a valid Datadog API key using the environment variable DATADOG_API_KEY.

The following example adds the tag team to the pipeline span:

datadog-ci tag --level pipeline --tags team:backend

The following example adds the tag go.version to the span for the current job:

datadog-ci tag --level job --tags "go.version:`go version`"

To create facets from the tags, click the gear icon next to the tag name in the pipeline executions page, and then click the create facet option.

Add measures to pipeline traces

To add numerical tags to the pipeline span or the job span, run:

datadog-ci measure [--level <pipeline|job>] [--measures <measures>]

You must specify a valid Datadog API key using the environment variable DATADOG_API_KEY.

The following example adds the measure error_rate to the pipeline span:

datadog-ci measure --level pipeline --measures "error_rate:0.56"

The following example adds a measure binary.size to the span for the currently running job:

datadog-ci measure --level job --measures "binary.size:`ls -l dst/binary | awk '{print \$5}' | tr -d '\n'`"

To create a measure, click the gear icon next to the measures name in the pipeline executions page and then click the create measure option.

Add tags and measures to GitHub jobs

To add tags and measures to GitHub jobs, datadog-ci CLI version 2.29.0 or higher is required. If the job name does not match the entry defined in the workflow configuration file (the GitHub job ID), the DD_GITHUB_JOB_NAME environment variable needs to be exposed, pointing to the job name. For example:

1. If the job name is changed using the name property:

   jobs:
     build:
       name: My build job name
       env:
         DD_GITHUB_JOB_NAME: My build job name
       steps:
       - run: datadog-ci tag ...
   

2. If the matrix strategy is used, several job names are generated by GitHub by adding the matrix values at the end of the job name, within parenthesis. The DD_GITHUB_JOB_NAME environment variable should then be conditional on the matrix values:

   jobs:
     build:
       strategy:
         matrix:
           version: [1, 2]
           os: [linux, macos]
       env:
         DD_GITHUB_JOB_NAME: build (${{ matrix.version }}, ${{ matrix.os }})
       steps:
       - run: datadog-ci tag ...
   

Further reading

Additional helpful documentation, links, and articles:

Troubleshooting CIDOCUMENTATION Configure pipeline alerts with Datadog CI monitorsBLOG