Set up Tracing on a GitLab Pipeline

Compatibility

Supported GitLab versions:

GitLab.com (SaaS)
GitLab >= 14.1 (self-hosted)

Other supported versions with additional configuration:

GitLab >= 13.7.0 (self-hosted), by enabling the datadog_ci_integration feature flag.

Configuring the Datadog integration

Dropdown

Configure the integration on a project or group by going to Settings > Integrations > Datadog for each project or group you want to instrument.

You can also activate the integration at the GitLab instance level, by going to Admin > Settings > Integrations > Datadog.

Enable the datadog_ci_integration feature flag to activate the integration. Run one of the following commands, which use GitLab’s Rails Runner, depending on your installation type:

Omnibus installations

sudo gitlab-rails runner "Feature.enable(:datadog_ci_integration)"

From source installations

sudo -u git -H bundle exec rails runner \
  -e production \
  "Feature.enable(:datadog_ci_integration)"

Kubernetes installations

kubectl exec -it <task-runner-pod-name> -- \
  /srv/gitlab/bin/rails runner "Feature.enable(:datadog_ci_integration)"

Then, configure the integration on a project by going to Settings > Integrations > Datadog for each project you want to instrument.

Note: Due to a bug in early versions of GitLab, the Datadog integration cannot be enabled at group or instance level on GitLab versions < 14.1, even if the option is available on GitLab's UI

Fill in the integration configuration settings:

Active: Enables the integration.
Datadog site: Specifies which Datadog site to send data to.
Default: datadoghq.com
Selected site:
API URL (optional): Allows overriding the API URL used for sending data directly, only used in advanced scenarios.
Default: (empty, no override)
API key: Specifies which API key to use when sending data. You can generate one in the APIs tab of the Integrations section on Datadog.
Service (optional): Specifies which service name to attach to each span generated by the integration. Use this to differentiate between GitLab instances.
Default: gitlab-ci
Env (optional): Specifies which environment (env tag) to attach to each span generated by the integration. Use this to differentiate between groups of GitLab instances (for example: staging or production).
Default: none
Tags (optional): Specifies any custom tags to attach to each span generated by the integration. Provide one tag per line in the format: key:value.
Default: (empty, no additional tags)
Note: Available only in GitLab.com and GitLab >= 14.8 self-hosted.

You can test the integration with the Test settings button (only available when configuring the integration on a project). After it’s successful, click Save changes to finish the integration set up.

Integrating through webhooks

As an alternative to using the native Datadog integration, you can use webhooks to send pipeline data to Datadog.

Note: The native Datadog integration is the recommended approach and the option that is actively under development.

Go to Settings > Webhooks in your repository (or GitLab instance settings), and add a new webhook:

URL: https://webhook-intake./api/v2/webhook/?dd-api-key=<API_KEY> where <API_KEY> is your Datadog API key.
Secret Token: leave blank
Trigger: Select Job events and Pipeline events.

To set custom env or service parameters, add more query parameters in the webhooks URL: &env=<YOUR_ENV>&service=<YOUR_SERVICE_NAME>

Setting custom tags

To set custom tags to all the pipeline and job spans generated by the integration, add to the URL a URL-encoded query parameter tags, with key:value pairs separated by commas. If a key:value pair contains any commas, surround it with quotes. For example, to add key1:value1,"key2: value with , comma",key3:value3, the following string would need to be appended to the Webhook URL:

?tags=key1%3Avalue1%2C%22key2%3A+value+with+%2C+comma%22%2Ckey3%3Avalue3