open-telemetry / open-telemetry/opentelemetry-java-instrumentation

Apply advice binding matcher guidance across javaagent instrumentations

Open
#20,103 0 comments 0 reactions 1 assignee View on GitHub

@trask is already working on this.

Since Sep 11, 2026.

enhancement needs triage
Dominant language
Java
Stars
2.6k
Forks
1.2k
Avg merge
2d 18h
Merged PRs (30d)
228

Description

Is your feature request related to a problem? Please describe.

The method matcher guidance documented in #20102 is not applied consistently across existing TypeInstrumentation implementations. Some advice binds statically typed @Advice.Argument or @Advice.Return values without a matcher that proves those bindings are compatible with every selected method. Other matchers constrain argument positions that neither identify the intended overload nor appear in the advice.

The cleanup should wait until #20102 merges so the repository agrees on the rule before existing modules are changed.

Describe the solution you'd like

After #20102 merges, audit production javaagent method matchers and apply the documented rule:

  • Match each non-optional, statically typed advice argument or return binding with a compatible method-signature constraint.
  • Use hierarchy matchers when supported versions declare different concrete subtypes accepted by the advice.
  • Keep constraints for values the advice does not bind only when they distinguish intended overloads or supported-version signatures.
  • Preserve intentionally broad optional = true, Object, and Assigner.Typing.DYNAMIC bindings.
  • Validate each affected module with its focused tests and muzzle checks.
Describe alternatives you've considered

Including the repository-wide cleanup in #20102 would mix guidance with many unrelated instrumentation changes and make the rule harder to review. Updating modules before that PR merges risks rework if reviewers change the guidance.

Additional context

#20072 applies the proposed rule to its Lettuce cluster connection matcher. This issue tracks the broader cleanup only and depends on #20102.

Tip

React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.