Agent context for dd-trace-java

What is this project?

Datadog Java APM agent (dd-trace-java): a Java agent that auto-instruments JVM applications at runtime via bytecode manipulation. It ships ~120 integrations (~200 instrumentations) for tracing, profiling, AppSec, IAST, CI Visibility, USM, and LLM Observability.

Project layout

See ARCHITECTURE.md for detailed module descriptions.

dd-java-agent/            Main agent (shadow jar, instrumentations, product modules)
dd-trace-api/             Public API & configuration constants
dd-trace-core/            Core tracing engine (spans, propagation, writer)
dd-trace-ot/              Legacy OpenTracing compatibility library
internal-api/             Internal shared API across modules
components/               Shared low-level components (context, environment, json)
products/                 Sub-products (feature flagging, metrics)
communication/            HTTP transport to Datadog Agent
remote-config/            Remote configuration support
telemetry/                Agent telemetry
utils/                    Shared utility modules (config, time, socket, test, etc.)
dd-smoke-tests/           Smoke tests (real apps + agent)
docs/                     Developer documentation (see below)

Key documentation (read on demand, don't load upfront)

When working on a topic above, read the linked file first — they are the source of truth maintained by humans.

Build quick reference

./gradlew clean assemble                  # Build without tests
./gradlew :dd-java-agent:shadowJar        # Build agent jar only (dd-java-agent/build/libs/)
./gradlew :path:to:module:test            # Run tests for a specific module
./gradlew :path:to:module:test -PtestJvm=11  # Test on a specific JVM version
./gradlew spotlessApply                   # Auto-format code (google-java-format)
./gradlew spotlessCheck                   # Verify formatting

Code conventions

• Formatting: google-java-format enforced via Spotless. Run ./gradlew spotlessApply before committing.
• Static imports: Prefer static imports over class-qualified calls for call-style helpers, in both test (Assertions.assertEquals, Mockito.mock) and production code (Collections.emptyList). Wildcard imports disallowed — see CONTRIBUTING.md.
• Documentation: Use concise Javadoc comments (/** ... */) for class, method, and field documentation.
• Instrumentation layout: dd-java-agent/instrumentation/{framework}/{framework}-{minVersion}/
• Instrumentation pattern: Type matching → Method matching → Advice class (bytecode advice, not AOP)
• Test frameworks: Always use JUnit 5 for unit tests. Only use Groovy / Spock tests for instrumentation and smoke tests.
• Parameterized tests: Prefer @TableTest for multi-column literal data, with named scenarios and aligned columns. Prefer a simple @TypeConverter over switching to @MethodSource when it can turn table values into the required arguments. Use @MethodSource for cases requiring complex object construction, builders, or mocks. See the JUnit testing guide.
• Forked tests: Use ForkedTest suffix when tests need a separate JVM
• Flaky tests: Annotate with @Flaky — they are skipped in CI by default

PR conventions

• Title: imperative verb sentence describing user-visible change (e.g. "Fix span sampling rule parsing")
• Description: follow the section guidance in the PR template. Write for a human reviewer first: short, plain and skimmable. Explain the intent and rationale of the change, not its content: the diff already shows the code, so don't walk through it file by file or list the classes and methods touched.
• Size: keep PRs small (under 1000 added lines), split larger changes into stacked PRs.
• Labels: always add tag: ai generated and at least one comp: or inst: label + one type: label
• Use tag: no release notes for internal/refactoring changes
• Open as draft first, convert to ready when reviewable
• Dependency changes: when adding, updating, or removing dependencies, regenerate all affected gradle.lockfile files and include them in the same PR. See lockfile updates.

Review Guidelines

• CI flakiness: use reproduce-ci-flakiness for local reproduction of intermittent timeouts, races, or asynchronous test failures. Match the CI task/JDK first, then compare bounded reruns with -Xint and reduced JVM-visible CPUs. See the testing guide for commands and CPU-limit distinctions.
• Technical debt: run /techdebt over branch changes before marking a PR ready to catch code duplication, unnecessary complexity, and dead code (refactor-only, never changes behavior) — see .agents/skills/techdebt/SKILL.md.
• Performance: run /perf-review over branch changes before marking a PR ready (advisory, not a merge gate) — see .agents/skills/perf-review/SKILL.md.

Core performance rules

These rules are strict for shipped runtime code in dd-trace-core/src/main/ and internal-api/src/main/. Elsewhere, including those modules' tests, benchmarks and build files, treat them as advice.

• Measure performance claims. A PR that claims to be faster or to allocate less must include JMH before/after results from the same machine, JDK, JVM flags and benchmark settings, with time and allocation (-Pjmh.profilers=gc). Without them, reviewers should flag the claim as unmeasured and the author should either add numbers or drop the claim.

CI scripts

Every curl that runs in CI (.gitlab-ci.yml, .gitlab/, GitHub Actions, the scripts they call, and the Dockerfiles they build) should:

• Fail on HTTP errors: pass -f/--fail. Without it, a 4xx/5xx exits 0 and the error page is used as if it were the real response (e.g. piped into bash or jq).
• Retry transient errors: pass --retry 5 --retry-delay 2 (add --retry-connrefused for remote endpoints).
• Propagate the failure: the job must stop when curl fails. Never pipe curl straight into bash/sh: download to a file with -f, then run it.

Example: curl -fsSL --retry 5 --retry-delay 2 --retry-connrefused -o out.tar.gz "$url"

Exception: a script that checks the HTTP status itself (-w "%{http_code}", e.g. .gitlab/check_test_agent_results.sh) may skip --fail, but still needs --retry.

Critical constraints

• Bootstrap: never use java.util.logging.*, java.nio.file.*, or javax.management.* in premain code — see docs/bootstrap_design_guidelines.md.
• Advice: never call a static interface method from advice — can cause a VerifyError — see docs/instrumentation_design_guidelines.md.