Adding Custom Commands to Pipeline Traces

Custom commands 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 commands work with the following CI providers:

• GitHub.com (SaaS) with datadog-ci CLI >= 2.40.
• GitLab (SaaS or self-hosted >= 14.1) with datadog-ci CLI >= 2.40.
• Jenkins with the Datadog plugin >= v3.2.0
• CircleCI
• Azure DevOps Pipelines with datadog-ci CLI >= 2.40.
• AWS Codepipeline with datadog-ci CLI >= 2.40. Follow Adding custom commands to set up custom commands in AWS Codepipeline.
• Buildkite with datadog-ci CLI >= 2.40.

Install the Datadog CI CLI

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

npm install -g @datadog/datadog-ci

Trace a command line

To trace a command line, 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=<key> DATADOG_SITE= 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 command.
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 command (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.

--measures

Key-value pairs in the form key:value to be attached to the custom command as numerical values (the --measures parameter can be specified multiple times).
(Requires datadog-ci >=v2.35.0)
Default: (none)
Example: size:1024

--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

--dry-run

Prevents datadog-ci from sending the custom span to Datadog. All other checks are performed.
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)

Trace a command block

It is possible to trace multiple command lines at once by manually specifying the start and end timestamps (or the duration).

datadog-ci trace span [--name <name>] [--start-time <timestamp-ms>] [--end-time <timestamp-ms>] # [--duration <duration-ms>] can be used instead of start / end time

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

DATADOG_API_KEY=<key> DATADOG_SITE= datadog-ci trace span \
--name "Build Step" \
--duration 10000

Configuration settings

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

--name

Display name of the custom span.
Example: Build Step

--start-time

Timestamp in milliseconds since the UNIX epoch representing the start time of the span.
Note: There are two ways to specify start and end time, by using --start-time and --end-time or using --duration.

--end-time

Timestamp in milliseconds since the UNIX epoch representing the end time of the span.
Note: There are two ways to specify start and end time, by using --start-time and --end-time or using --duration.

--duration

Duration amount in milliseconds. Using this, the end time is the current time when executing this command.
Note: There are two ways to specify start and end time, by using --start-time and --end-time or using --duration.

--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.

--measures

Key-value pairs in the form key:value to be attached to the custom span as numerical values (the --measures parameter can be specified multiple times).
(Requires datadog-ci >=v2.35.0)
Default: (none)
Example: size:1024

--dry-run

Prevents datadog-ci from sending the custom span to Datadog. All other checks are performed.
Default: false

The following environment variables are supported:

DATADOG_API_KEY (Required)

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

Troubleshooting

Payload too large

The size limit is approximately 4MB. The most common cause for this error is extremely large tags. Use the --dry-run option to see the traced command’s contents before sending it to Datadog.

GitHub Actions custom commands not appearing in Datadog

Older versions of the datadog-ci CLI may require additional setup:

Further reading

Request a personalized demo