--- title: Adding Custom Tags and Measures to Pipeline Traces description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Continuous Integration Visibility > CI Pipeline Visibility in Datadog > Adding Custom Tags and Measures to Pipeline Traces --- # Adding Custom Tags and Measures to Pipeline Traces {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). (). {% /alert %} {% /callout %} ## Overview{% #overview %} Use the custom tags and measures commands to add user-defined text and numerical tags to your pipeline traces in [CI Pipeline Visibility](https://docs.datadoghq.com/continuous_integration/pipelines.md). You can use the [`datadog-ci` NPM package](https://www.npmjs.com/package/@datadog/datadog-ci) to add custom tags or measures to a pipeline, job, stage, or step span. From these custom tags and measures, you can create facets (string value tags) or measures (numerical value tags). You can use facets and measures to filter, create visualizations, or create monitors for your pipelines in the [CI Visibility Explorer](https://docs.datadoghq.com/continuous_integration/explorer.md). ### Compatibility{% #compatibility %} Custom tags and measures work with the following CI providers: - Buildkite - CircleCI - GitLab (SaaS or self-hosted >= 14.1) - GitHub.com (SaaS) - Jenkins: For Jenkins, follow [these instructions](https://docs.datadoghq.com/continuous_integration/pipelines/jenkins.md?tab=usingui#setting-custom-tags-for-your-pipelines) to set up custom tags in your pipelines. - Azure DevOps Pipelines ## Install the Datadog CI CLI{% #install-the-datadog-ci-cli %} Install the [`datadog-ci`](https://www.npmjs.com/package/@datadog/datadog-ci) (>=v1.15.0) CLI globally using `npm`: ```shell npm install -g @datadog/datadog-ci ``` {% alert level="info" %} See [More ways to install the CLI](https://github.com/DataDog/datadog-ci?tab=readme-ov-file#more-ways-to-install-the-cli) in the datadog-ci repo for alternative installation options. {% /alert %} ## Add tags to pipeline traces{% #add-tags-to-pipeline-traces %} Tags can be added to the pipeline, job, stage, or step span. To do this, run the `tag` command: ```shell DATADOG_SITE= datadog-ci tag [--level ] [--tags ] [--tags ] ... ``` You must specify a valid [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) using the environment variable `DATADOG_API_KEY` and the [Datadog site](https://docs.datadoghq.com/getting_started/site.md) using the environment variable `DATADOG_SITE`. The following example adds `team` and `service` tags to the pipeline span. ```shell DATADOG_SITE= datadog-ci tag --level pipeline --tags team:backend --tags service:processor ``` The following example adds the tag `go.version` to the span for the current job: ```shell DATADOG_SITE= datadog-ci tag --level job --tags "go.version:`go version`" ``` To create a facet from a tag, click the gear icon next to a tag name on the [Pipeline Executions page](https://app.datadoghq.com/ci/pipeline-executions), and click **Create Facet**. {% video url="https://docs.dd-static.net/images/ci/custom-tags-create-facet.mp4" /%} ## Add measures to pipeline traces{% #add-measures-to-pipeline-traces %} To add numerical tags to the pipeline, job, stage, or step span, run the `measure` command: ```shell DATADOG_SITE= datadog-ci measure [--level ] [--measures ] [--measures ]... ``` You must specify a valid [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) using the environment variable `DATADOG_API_KEY` and the [Datadog site](https://docs.datadoghq.com/getting_started/site.md) using the environment variable `DATADOG_SITE`. The following example adds `error_rate` and `size` measures to the pipeline span: ```shell DATADOG_SITE= datadog-ci measure --level pipeline --measures "error_rate:0.56" --measures "size:2327" ``` The following example adds a measure `binary.size` to the span for the currently running job: ```shell DATADOG_SITE= 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 a measures name on the [Pipeline Executions page](https://app.datadoghq.com/ci/pipeline-executions) and click **Create Measure**. ## Troubleshooting{% #troubleshooting %} ### Limitations{% #limitations %} - The maximum amount of tags that can be added to a pipeline or job is 100. - The maximum amount of measures that can be added to a pipeline or job is 100. - The maximum length of a tag or measure is 300 characters (key + value). ### GitHub Actions custom commands not appearing in Datadog{% #github-actions-custom-commands-not-appearing-in-datadog %} Older versions of the datadog-ci CLI may require additional setup: {% collapsible-section %} **For datadog-ci versions prior to 4.1.1 in GitHub Actions** If you are using `datadog-ci` version `2.29.0` to `4.1.0` and the job name does not match the entry defined in the workflow configuration file (the GitHub [job ID](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_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](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#name): ```yaml jobs: build: name: My build job name env: DD_GITHUB_JOB_NAME: My build job name steps: - run: datadog-ci tag ... ``` 1. If the [matrix strategy](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs#using-a-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: ```yaml 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 ... ``` {% /collapsible-section %} ## Further reading{% #further-reading %} - [Troubleshooting CI Visibility](https://docs.datadoghq.com/continuous_integration/troubleshooting.md) - [Configure pipeline alerts with Datadog CI monitors](https://www.datadoghq.com/blog/configure-pipeline-alerts-with-ci-monitors/)