Apm Integrations

Write a new APM end-to-end integration for dd-trace-java, based on library instrumentations, following all project conventions.

Step 1 – Read the authoritative docs and sync this skill (mandatory, always first)

Before writing any code, read all three files in full:

1. docs/how_instrumentations_work.md — full reference (types, methods, advice, helpers, context stores, decorators)
2. docs/add_new_instrumentation.md — step-by-step walkthrough
3. docs/how_to_test.md — test types and how to run them

These files are the single source of truth. Reference them while implementing.

Step 2 – Clarify the task

If the user has not already provided all of the following, ask before proceeding:

• Framework name and minimum supported version (e.g. okhttp-3.0)
• Target class(es) and method(s) to instrument (fully qualified class names preferred)
• Target system: one of Tracing, Profiling, AppSec, Iast, CiVisibility, Usm, ContextTracking
• Whether this is a bootstrap instrumentation (affects allowed imports)

Step 3 – Find a reference instrumentation

Search dd-java-agent/instrumentation/ for a structurally similar integration:

• Same target system
• Comparable type-matching strategy (single type, hierarchy, known types)

Read the reference integration's InstrumenterModule, Advice, Decorator, and test files to understand the established pattern before writing new code. Use it as a template.

Step 4 – Set up the module

1. Create directory: dd-java-agent/instrumentation/$framework/$framework-$minVersion/
2. Under it, create the standard Maven source layout:
   • src/main/java/ — instrumentation code
   • src/test/groovy/ (default) or src/test/java/ if the module's master version and version-siblings are already on the Java/JUnit DSL — check them before creating this directory (see Step 9.1)
3. Create build.gradle with:
   • compileOnly dependencies for the target framework
   • testImplementation dependencies for tests
   • muzzle { pass { } } directives (see Step 9.2)
4. Register the new module in settings.gradle.kts in alphabetical order
5. Register all integration names in metadata/supported-configurations.json — read Supported Configurations for the exact key shapes and CI checks involved. Declaring several names (super("a", "b")) means one entry each.

See Naming Conventions — module directory name must end with a version or an allowed suffix (-common, -stubs, -iast). Java filename and public class name MUST match character-for-character including acronym casing (CRITICAL — see § "Java naming consistency").

Step 4.1 – Span-creating vs context-tracking instrumentation

Read Context-Tracking Instrumentation and decide whether the library needs InstrumenterModule.Tracing (I/O operations that create spans) or InstrumenterModule.ContextTracking (async-boundary bridging, no spans).

If you picked ContextTracking: the same file's "Library-native context maps" section tells you whether the library needs a *ContextBridge-style helper (Reactor is the canonical example) in addition to the subscriber-wrapping pattern — read it before moving to Step 5. Its "Wrap placement" section covers where to allocate wrappers and context-store entries to avoid per-operator overhead on hot reactive paths.

Step 5 – Write the InstrumenterModule

Read InstrumenterModule Guidance. If you're editing an existing module rather than writing a new one, its "Editing an existing module" note applies — read the current file first and change only what the task requires.

Step 6 – Write the Decorator

• Extend the most specific available base decorator:
  • HttpClientDecorator, DatabaseClientDecorator, ServerDecorator, MessagingClientDecorator, etc.
• One public static final DECORATE instance
• Define UTF8BytesString constants for the component name and operation name
• Keep all tag/naming/error logic here — not in the Advice class
• Override spanType(), component(), spanKind() as appropriate
• Override instrumentationNames() to return the primary integration name without a version suffix: return new String[] {"jedis"}; not "jedis-3.0".
• BaseDecorator uses those names to resolve analytics settings (DD_TRACE_<NAME>_ANALYTICS_ENABLED, DD_TRACE_<NAME>_ANALYTICS_SAMPLE_RATE). Search metadata/supported-configurations.json for each returned name — if analytics keys are absent, add them (see Supported Configurations for the JSON shape).

Step 7 – Write the Advice class (highest-risk step)

Read Writing the Advice Class — the highest-risk step. Pay particular attention to: @Advice.OnMethodEnter/Exit annotations; CallDepthThreadLocalMap reentrancy guarding; span lifecycle order; and the "Must NOT do" list. If the target wraps or delegates to another async client, its "Do not double-span async HTTP clients" section covers whether to open a second span or rely on context-propagation-only advice. If a returned CompletableFuture/CompletionStage needs a completion callback, see Context-Tracking Instrumentation's "Preserving cancellation" section for the read-only-return + named-callback pattern — do not reassign the future with future = future.whenComplete(...).

Step 8 – Add SETTER/GETTER adapters (if applicable)

For context propagation to and from upstream services, like HTTP headers, implement AgentPropagation.Setter / AgentPropagation.Getter adapters that wrap the framework's specific header API. Place them in the helpers package, declare them in helperClassNames().

Step 9 – Write tests

Cover all mandatory test types:

1. Instrumentation test (mandatory)

Read Writing Tests. Groovy/Spock (src/test/groovy/) is the default for instrumentation tests — add the tag: override groovy enforcement label to suppress the Enforce Groovy Migration CI check (which blocks new .groovy files by default). Match the sibling module's test DSL is the deciding factor: write your tests in src/test/groovy/ to match the master module and its version-siblings, UNLESS that family is already on the Java/JUnit DSL — do NOT introduce a src/test/java/** JUnit suite into a Groovy family, and do NOT copy the Java AbstractInstrumentationTest examples in references/tests.md (they illustrate style rules for modules already on the Java DSL, they are not a license to migrate a Groovy family to Java). Must cover error/exception scenarios. When adding new integration names, register them per Supported Configurations. When compileOnly and testImplementation use different versions, comment the specific class that requires the higher version. Include sibling version modules as testImplementation dependencies for mutual-exclusion tests.

2. Muzzle directives (mandatory)

Read Muzzle Directives — it covers all three valid patterns and their assertInverse rules. Search adjacent module build.gradle files for skipVersions before declaring a new version-bounded module's muzzle directives. If a prior-major-version sibling module already exists in the repo (e.g. you're writing rxjava-3.0 and rxjava-2.0 exists), add the "Namespace-isolation fail block" that section describes — it's not optional, it's how CI catches accidental cross-version advice matching.

3. Latest dependency test (mandatory)

If the library's API surface changes across minor versions (deprecated/removed methods, changed signatures), see Writing Tests's "Version-sensitive tests belong in a separate latestDepTest source set" section for which tests belong in src/test/ vs src/latestDepTest/.

Use latestDepTestImplementation in build.gradle to pin the latest available version. Run with:

./gradlew :dd-java-agent:instrumentation:$framework:$framework-$version:latestDepTest

latestDepTestImplementation version range must match the instrumented range. If your module instruments version 2.x, use 2.+ as the version constraint, not 3.+:

// WRONG — latestDep tests against 3.x but the module only instruments 2.x
latestDepTestImplementation group: 'commons-httpclient', name: 'commons-httpclient', version: '3.+'

// CORRECT — latestDep tests against the highest 2.x release
latestDepTestImplementation group: 'commons-httpclient', name: 'commons-httpclient', version: '2.+'

Using 3.+ for a 2.x instrumentation means latestDepTest runs against an incompatible API version and will either fail or silently test nothing.