Infer instrumentation helper classes at build time by sarahchen6 · Pull Request #12059 · DataDog/dd-trace-java

sarahchen6 · 2026-07-23T16:53:26Z

What Does This Do

This PR adds logic to generate each InstrumenterModule's helperClassNames() at build-time instead of the existing logic that requires each module's helper classes to be manually listed. The MuzzleGenerator already crawls through each module's advice in order to gather its references and emit these in a $Muzzle side-class. We simultaneously use this crawl to infer the helperClasses each module needs to load, order them dependency-first, drop build-time-only classes, and write these helperClasses directly into the module's helperClassNames() bytecode.

If a module manually declares its helperClassNames(), we use that list instead of inferring.

Also, this PR migrates a few instrumentations from manual declarations of required helper classes to auto-detecting these classes in order to test the new methodology.

Motivation

Currently, instrumentation helper classes are manually listed for each InstrumenterModule. However, we can instead use Muzzle, which already finds class references for each instrumentation, to automatically discover which helper classes need to be loaded per instrumentation. This is inspired by OTel's muzzle, which generates getMuzzleHelperClassNames() from their single build-time advice crawl.

Additional Notes

The intention is for all instrumentations to discover required helper classes at build time; however, I wanted to keep the scope of this PR low so that it's easier to review. The rest of the instrumentations will be migrated in follow-up PRs.

A follow-up PR #12191 also extracts the helper resolver logic to its own class so that the logic is separate from muzzle reference generation and more easily testable and legible.

Contributor Checklist

Format the title according to the contribution guidelines
Assign the type: and (comp: or inst:) labels in addition to any other useful labels
Avoid using close, fix, or any linking keywords when referencing an issue
Use solves instead, and assign the PR milestone to the issue
Update the CODEOWNERS file on source file addition, migration, or deletion
Update public documentation with any new configuration flags or behaviors
Once approved, use merge queue to merge the PR

Jira ticket: [PROJ-IDENT]

dd-octo-sts · 2026-07-30T12:51:16Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	13.98 s	13.91 s	[-0.1%; +1.1%] (no difference)
startup:insecure-bank:tracing:Agent	12.85 s	12.99 s	[-1.9%; -0.3%] (maybe better)
startup:petclinic:appsec:Agent	17.52 s	17.13 s	[+1.4%; +3.3%] (significantly worse)
startup:petclinic:iast:Agent	17.47 s	17.53 s	[-1.3%; +0.6%] (no difference)
startup:petclinic:profiling:Agent	17.52 s	17.49 s	[-1.1%; +1.4%] (no difference)
startup:petclinic:sca:Agent	17.48 s	17.19 s	[+0.7%; +2.7%] (maybe worse)
startup:petclinic:tracing:Agent	16.60 s	16.74 s	[-1.7%; +0.0%] (no difference)

Commit: 9139e4e6 · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

sarahchen6 · 2026-08-11T21:07:44Z

 * 1. Must implement [net.bytebuddy.build.Plugin]
- * 2. Must have a constructor accepting a [java.io.File] parameter (target directory)
+ * 2. Must have a constructor accepting a [java.io.File] (target directory), or a two-`File`
+ *    `(sourceDirectory, targetDirectory)` constructor when the plugin also needs the source folder


sourceDirectory is needed to determine whether it was the particular submodule that compiled the className (done in isOwnOutput(className) - if yes then inject).

💭 thought: The fact that target moved from the 1st position to the 2nd position make the implementation weird. Can’t we infer isOwnOutput() some otherway?‏

You should be able to compute the source directory using the TypeDefinition and the ClassLoader.
You can load the module as URL and infer its source folder for example.

Good point!! Addressed this in 9139e4e by getting the module's codeSource location.

sarahchen6 · 2026-08-11T21:18:49Z

  }

+  /**
+   * Same as above, but reads bytecode via the passed locator (e.g. during build time when the agent


MuzzleGenerator needs to call HelperScanner.withClassDependencies at build-time to expand and order the helpers found, but there's no AgentClassLoader during the build (there is during runtime which is previously the only place we called HelperScanner.withClassDependencies) - so we need to pass in the build classpath's locator to use.

dd-octo-sts · 2026-08-12T15:10:00Z

Hi! 👋 Thanks for your pull request! 🎉

To help us review it, please make sure to:

Add at least one type, and one component or instrumentation label to the pull request

If you need help, please check our contributing guidelines.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9cea7a8021

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

datadog-official

More details

Generated methods preserved all four migrated instrumentations’ former helper sets and correctly handled dependency ordering, nested helpers, and unresolved-class fallback. Runtime instrumentation also loaded the generated helpers successfully for locally executable requests.

Was this helpful? React 👍 or 👎

_{📊 Validated against 10 scenarios · Open Bits AI session}

_{🤖 Datadog Autotest · Commit 9cea7a8 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest}

PerfectSlayer

I start reviewing and will drop few inline comments for now.

📝 notes: The plugin is enabled for all instrumentations so it will apply to all instrumentations that do not explicitly override the helper declaration method, not only the few that are migrated as demo.

PerfectSlayer · 2026-08-13T14:29:20Z

-    return classVisitor;
+
+    // Write the resolved helpers into the module's helperClassNames() so agent reads them directly.
+    return new HelperClassNamesWriter(classVisitor, orderedHelpers);


❔ question: ‏How is that work with class that defines helper on their parent class? Like the one extending AbstractPreparedStatementInstrumentation?

Because it feels you will always end up overriding the parent method in child classes 🤔

Yep you're right - the child will override the parent here.... I think we should only generate the helpers for child classes if the parent doesn't have any defined classes. Did this in e1a67f9

PerfectSlayer · 2026-08-13T14:43:54Z

+      InstrumenterModule module, List<Reference> allReferences, Set<String> adviceClasses) {
+    // A module that declares its own helper list uses it directly.
+    Set<String> manualHelpers = new LinkedHashSet<>(asList(module.helperClassNames()));
+    if (!manualHelpers.isEmpty()) {


🎯 suggestion: ‏The empty path could be improved. When module.helperClassNames() is empty, there is no need to create an arraylist than a hashset.

Done in e1a67f9

PerfectSlayer · 2026-08-13T14:49:29Z

+    int lastDot = className.lastIndexOf('.');
+    String pkg = lastDot < 0 ? "" : className.substring(0, lastDot + 1);
+    String prefix = (lastDot < 0 ? className : className.substring(lastDot + 1)) + "$";
+    File[] siblings = dir.listFiles();


💭 thought: ‏listFiles() has no deterministic order by the helpers are collected into a LinkedHashSet

Good point we should sort the siblings to better reproduce the helper ordering... Done in e1a67f9

This comment has been minimized.

Sign in to view

DataDog deleted a comment from dd-octo-sts Bot Jul 23, 2026

sarahchen6 force-pushed the sarahchen6/infer-helper-classes-pt-1 branch from 98edf9d to a09ff60 Compare July 28, 2026 18:24

DataDog deleted a comment from dd-octo-sts Bot Jul 29, 2026

This was referenced Aug 3, 2026

Write helpers into module bytecode directly #12134

Closed

Add index for instrumentation helper classes #12116

Closed

sarahchen6 added 12 commits August 11, 2026 12:51

Implement auto-inferring helper methods

d38bdd4

Migrate some instrumentations

dd6a4ac

Fix class crawl logic

8666030

Clean comments

af1a4cb

Make helper-name resolution lazy

dfa4605

Do not capture entire module instanc at prepareInstrumentation

b2e3704

Undo lazy loading

2a0c4b3

Use source file to determine helpers

5704828

Avoid injecting build-time-only muzzle classes

7d9966d

Add tests for full helper inference for manual specification

b90f639

Clean up

6d82a50

Clean comments

a8cdba9

sarahchen6 force-pushed the sarahchen6/infer-helper-classes-pt-1 branch from 29b0bff to a8cdba9 Compare August 11, 2026 16:52

sarahchen6 added 3 commits August 11, 2026 15:29

Write helpers into module bytecode directly

d569e4e

Only auto-generate if not manually listed

04b01e4

Use either manual list or auto-generation

eb22da6

sarahchen6 changed the title ~~Auto-infer instrumentation required helper classes at build time~~ Infer instrumentation helper classes at build time Aug 11, 2026

sarahchen6 commented Aug 11, 2026

View reviewed changes

Clean up

9cea7a8

sarahchen6 marked this pull request as ready for review August 12, 2026 15:09

sarahchen6 requested review from a team as code owners August 12, 2026 15:09

sarahchen6 requested review from ValentinZakharov and amarziali and removed request for a team August 12, 2026 15:09

sarahchen6 added type: feature Enhancements and improvements comp: tooling Build & Tooling labels Aug 12, 2026

chatgpt-codex-connector Bot reviewed Aug 12, 2026

View reviewed changes

Comment thread ...va-agent/agent-tooling/src/main/java/datadog/trace/agent/tooling/muzzle/MuzzleGenerator.java Outdated

datadog-official Bot reviewed Aug 12, 2026

View reviewed changes

PerfectSlayer self-requested a review August 13, 2026 12:36

PerfectSlayer reviewed Aug 13, 2026

View reviewed changes

sarahchen6 added 3 commits August 13, 2026 14:00

Infer source folder instead of passing in as param

5241bcf

Address review comments

e1a67f9

Address ForbiddenAPI

9139e4e

Uh oh!

Conversation

sarahchen6 commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Additional Notes

Contributor Checklist

Uh oh!

This comment has been minimized.

dd-octo-sts Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dd-octo-sts Bot commented Aug 12, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

datadog-official Bot left a comment

Choose a reason for hiding this comment

Uh oh!

PerfectSlayer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sarahchen6 commented Jul 23, 2026 •

edited

Loading

dd-octo-sts Bot commented Jul 30, 2026 •

edited

Loading