Adding Custom Spans to Pipeline Traces

Adding Custom Spans to Pipeline Traces

Custom spans provide a way to trace individual commands in your CI pipelines, allowing you to measure the time your command takes without taking into account any setup or teardown actions that the job might have (for example, downloading Docker images or waiting for an available node in a Kubernetes-based infrastructure). These spans appear as part of the pipeline’s trace:

Compatibility

Custom spans work with the following CI providers:

  • Jenkins with Datadog plugin >= v3.2.0
  • CircleCI

Installing the Datadog CI CLI

Install the datadog-ci (>=v0.17.0) CLI globally using npm:

npm install -g @datadog/datadog-ci

Tracing a command

To trace a command, run:

datadog-ci trace [--name <name>] -- <command>

Specify a valid Datadog API key in the DATADOG_API_KEY environment variable. For example:

DATADOG_API_KEY=<api_key> datadog-ci trace \
  --name "Greet" \
  -- \
  echo "Hello World"

DATADOG_API_KEY=<api_key> DATADOG_SITE=datadoghq.eu datadog-ci trace \
  --name "Greet" \
  -- \
  echo "Hello World"

DATADOG_API_KEY=<api_key> DATADOG_SITE=us3.datadoghq.com datadog-ci trace \
--name "Greet" \
-- \
echo "Hello World"

Configuration settings

These options are available for the datadog-ci trace command:

--name
Display name of the custom span.
Default: same value as <command>
Example: Wait for DB to be reachable
--tags
Key-value pairs in the form key:value to be attached to the custom span (the --tags parameter can be specified multiple times). When specifying tags using DD_TAGS, separate them using commas (for example, team:backend,priority:high).
Environment variable: DD_TAGS
Default: (none)
Example: team:backend
Note: Tags specified using --tags and with the DD_TAGS environment variable are merged. If the same key appears in both --tags and DD_TAGS, the value in the environment variable DD_TAGS takes precedence.
--no-fail
Prevents datadog-ci from failing even if run in an unsupported CI provider. In this case, the command is run and nothing is reported to Datadog.
Default: false
Positional arguments
The command that is launched and traced.

The following environment variables are supported:

DATADOG_API_KEY (Required)
Datadog API key used to authenticate the requests.
Default: (none)

Additionally, configure the Datadog site to use the selected one ():

DATADOG_SITE (Required)
The Datadog site to upload results to.
Default: datadoghq.com
Selected site:

The selected Datadog site () does not support this feature.