Manual Instrumentation by Runtime
Open this in step 3 when the CI provider does not support auto-instrumentation (Buildkite, Jenkins, Bitbucket, Azure Pipelines, Travis CI), when tests run inside a prebuilt Docker image, when the framework requires manual setup (Cypress, BenchmarkDotNet, Swift), or when the user asks for manual instrumentation.
Contents
- Shared environment variables and CI provider rules
- Node.js (Jest, Vitest, Mocha, Playwright, Cucumber, Cypress)
- Python (pytest, unittest, pytest-benchmark)
- Java / JVM (Maven, Gradle, SBT)
- Go (
orchestrion) - Ruby (RSpec, Minitest, Cucumber)
- .NET (xUnit, NUnit, MSTest v2, BenchmarkDotNet)
- Swift (XCTest, Swift Testing)
Shared environment variables and CI provider rules
Every manual test run needs these environment variables on the test step or job:
DD_CIVISIBILITY_ENABLED: true
DD_CIVISIBILITY_AGENTLESS_ENABLED: true
DD_SITE: <SITE>Plus DD_API_KEY from the CI provider's secret store:
- GitHub Actions:
DD_API_KEY: ${{ secrets.DD_API_KEY }}andJOB_CHECK_RUN_ID: ${{ job.check_run_id }}(the tracers read it to link test runs to the exact job) - GitLab CI / Bitbucket / Travis CI:
DD_API_KEY: $DD_API_KEY - Buildkite:
DD_API_KEY: $DD_API_KEY(write single$, never$$DD_API_KEY) - CircleCI:
echo "export DD_API_KEY=${DD_API_KEY}" >> $BASH_ENV - Azure Pipelines:
DD_API_KEY: $(DD_API_KEY)
Node.js (Jest, Vitest, Mocha, Playwright, Cucumber, Cypress)
- Install
dd-traceas a dev dependency before tests run (with the project's package manager:npm install --save-dev dd-trace,yarn add --dev dd-trace,pnpm add --save-dev dd-trace, orbun add --dev dd-trace). - Set
NODE_OPTIONSfor the test command:- Jest, Mocha, Playwright, Cucumber:
NODE_OPTIONS: "-r dd-trace/ci/init" - Vitest (>=1.6.0):
NODE_OPTIONS: "--import dd-trace/register.js -r dd-trace/ci/init" - Apply it only to commands that run after
dd-traceis installed. Every Node process preloadsNODE_OPTIONS, includingnpm,yarn, andpnpmthemselves, so a preload set before the install fails withCannot find module 'dd-trace/ci/init'. In GitHub Actions, put it in the test step'senv:(installs run in earlier steps). When one step installs and tests (Buildkite, GitLab, Bitbucket, Travis CI),exportit on a line after the install command, or prefix only the test command. - If
package.jsonalready setsNODE_OPTIONSinside the test script, preserve${NODE_OPTIONS:-}so the CI variable is not overwritten.
- Jest, Mocha, Playwright, Cucumber:
- Cypress (>=6.7.0): auto-instrumentation and
NODE_OPTIONSalone do not instrument Cypress browser specs. Installdd-trace, require'dd-trace/ci/cypress/plugin'incypress.config.{js,ts}insidesetupNodeEvents(on, config), and import'dd-trace/ci/cypress/support'incypress/support/e2e.{js,ts}(see the JavaScript Test Optimization setup docs).
Example (Buildkite buildkite/pipeline.yml for Jest):
steps:
- label: "Run tests"
command:
- npm install --save-dev dd-trace
- export NODE_OPTIONS="-r dd-trace/ci/init"
- npm test
env:
DD_CIVISIBILITY_ENABLED: true
DD_CIVISIBILITY_AGENTLESS_ENABLED: true
DD_SITE: datadoghq.com
DD_API_KEY: $DD_API_KEYPython (pytest, unittest, pytest-benchmark)
- Install
ddtracein the CI job before tests run:pip install -U ddtrace. - Set
DD_CIVISIBILITY_ENABLED: true,DD_CIVISIBILITY_AGENTLESS_ENABLED: true,DD_SITE, andDD_API_KEY. - Update the test command:
- pytest / pytest-benchmark: append
--ddtrace(for examplepytest --ddtrace). - unittest: prefix with
ddtrace-run(for exampleddtrace-run python -m unittest).
- pytest / pytest-benchmark: append
Java / JVM (Maven, Gradle, SBT)
- Download the Datadog Java tracer JAR before tests run:
mkdir -p "$HOME/.datadog" wget -O "$HOME/.datadog/dd-java-agent.jar" https://dtdg.co/latest-java-tracer - Set environment variables on the test step:
DD_CIVISIBILITY_ENABLED: true DD_CIVISIBILITY_AGENTLESS_ENABLED: true DD_AGENTLESS_LOG_SUBMISSION_ENABLED: true DD_SITE: <SITE> DD_API_KEY: <secret reference> - Set the
-javaagentflag from a shell command, not from a YAMLenv:value: most CI providers do not expand$HOMEin YAML values, and the JVM then cannot open the JAR. Use the build tool's variable (MAVEN_OPTSfor Maven,GRADLE_OPTSfor Gradle,SBT_OPTSfor SBT,JAVA_TOOL_OPTIONSfor other JVMs), shown here for Maven:- GitHub Actions: in the download step,
echo "MAVEN_OPTS=-javaagent:$HOME/.datadog/dd-java-agent.jar" >> "$GITHUB_ENV" - CircleCI:
echo "export MAVEN_OPTS=\"-javaagent:$HOME/.datadog/dd-java-agent.jar\"" >> "$BASH_ENV" - Other providers:
export MAVEN_OPTS="-javaagent:$HOME/.datadog/dd-java-agent.jar ${MAVEN_OPTS:-}"on a line before the test command
- GitHub Actions: in the download step,
Go (orchestrion)
- Install
orchestrionbefore running tests:go install github.com/DataDog/orchestrion@latest - Set
DD_CIVISIBILITY_ENABLED: true,DD_CIVISIBILITY_AGENTLESS_ENABLED: true,DD_SITE, andDD_API_KEY. - Prefix the
go testcommand withorchestrion:orchestrion go test ./...
Ruby (RSpec, Minitest, Cucumber)
- Add
datadog-cito the test group (in theGemfile/Dockerfileor right before tests run):bundle add datadog-ci --group "test" - Set environment variables on the test step (or forward them into
docker run):DD_CIVISIBILITY_ENABLED: true DD_CIVISIBILITY_AGENTLESS_ENABLED: true DD_SITE: <SITE> DD_API_KEY: <secret reference> RUBYOPT: "-rbundler/setup -rdatadog/ci/auto_instrument"RUBYOPTauto-instruments RSpec, Minitest, and Cucumber without modifying the test command. Apply it only to commands that run afterdatadog-ciis installed: every Ruby process preloadsRUBYOPT, Bundler included, sobundle installorbundle addrun with it fails withcannot load such file -- datadog/ci/auto_instrument. When one step installs and tests,exportit on a line after the install command.
.NET (xUnit, NUnit, MSTest v2, BenchmarkDotNet)
- Install the global
dd-trace.NET tool before tests run:dotnet tool update --global dd-trace - Set
DD_CIVISIBILITY_ENABLED: true,DD_CIVISIBILITY_AGENTLESS_ENABLED: true,DD_SITE, andDD_API_KEY. - Prefix the test command with
dd-trace ci run --:
For BenchmarkDotNet, also install thedd-trace ci run -- dotnet testDatadog.Trace.BenchmarkDotNetNuGet package.
Swift (XCTest, Swift Testing)
Follow the Swift Test Optimization setup documentation: add the dd-sdk-swift-testing package dependency and pass TEST_RUNNER_DD_CIVISIBILITY_ENABLED=true, TEST_RUNNER_DD_CIVISIBILITY_AGENTLESS_ENABLED=true, TEST_RUNNER_DD_SITE=<SITE>, and TEST_RUNNER_DD_API_KEY to xcodebuild test or swift test.