Skip repeated AbstractMethodError from JDBC getClientInfo

[dougqh]

What Does This Do

Adds ClassLatch, a small abstract type for calls that fail the same way every time for a given class, and uses it for Connection.getClientInfo() in JDBCDecorator.parseDBInfoFromConnection. Once a class is known to lack the method, the call is skipped instead of throwing and catching an AbstractMethodError on every call.

A call site holds a static final subclass and calls tryApply:

private static final ClassLatch<Connection, Properties, SQLException> CLIENT_INFO_LATCH =
    new ClassLatch<Connection, Properties, SQLException>() {
      @Override
      protected Properties apply(Connection connection) throws SQLException {
        return handleAbstractMethod(connection, "getClientInfo", Connection::getClientInfo);
      }
    };

clientInfo = CLIENT_INFO_LATCH.tryApply(connection);

The catch around the call is unchanged: it still catches Throwable, logs with EXCLUDE_TELEMETRY, and falls back to a URL-only DBInfo, so the latch is purely an optimization and the behavior is the same as before. (An earlier revision of this PR narrowed the catch to SQLException, which broke existing tests: TestConnection.getClientInfo() throws a bare Throwable, and JDBCInstrumentationV0Test and JDBCWrappedInterfacesTest expect the URL-derived DB info to survive any failure. Narrowing it, so that an unexpected failure reaches the outer handler and shows up in Error Tracking, is a separate decision and would need those tests changed.)

Motivation

Connections from old JDBC drivers and pool proxies lack getClientInfo, so every call threw and caught an AbstractMethodError. #11412 muted the log line (telemetry dropped to zero from 1.63), but the throw and catch still happen on every call. See Error Tracking issue b449bd64, which was ~650k events/day from old tracers.

The JVM does not fast-throw AbstractMethodError (that optimisation covers only a fixed set of implicit exceptions), and it cannot cache the failure on the call site because the error comes from method selection, which depends on the receiver. The latch memoises per call site and receiver class, and skips the call entirely when it can prove the class lacks the method.

Additional Notes

Design

• tryApply (formerly tryApplyOrNull, renamed once the result was no longer necessarily null) is public final: returns null for a null target, fallback(target) for a latched one, otherwise calls apply. A null result always means "nothing available," whether skipped or genuinely absent, so the caller's fallback behaves the same either way; tryApplyOrDefault is null-coalescing sugar over it. No wrapper result type — a null return needs no allocation. Subclasses write apply as an ordinary try/catch and touch state only via latch/unlatch/latchIfNamed.
• fallback(target) is an overridable hook: what a latched target yields instead of the operation, and what the handle* helpers return when the call fails, so the failing call and every skipped call after it agree. It defaults to null, which is what JDBC uses. Override it when there is a slower alternative (e.g. an older API, as in Convert JMSDecorator.getDestination to ClassLatch #12720's JMS getQueue/getTopic), instead of re-checking isLatched at the call site to tell a skipped call from an operation that legitimately returned null.
• handleAbstractMethod(target, methodName, fn) is the common-case helper, taking a new ThrowingFunction<T, R, E> (alongside TriFunction/TriConsumer) so a throwing method reference like getClientInfo can be passed directly. Both AbstractMethodError and UnsupportedOperationException yield fallback(target), but only AbstractMethodError latches, and only when its message names the key class and methodName — a wrapper delegating to a deficient object still gets the fallback, but is never latched. Anything else propagates.
• handleNoSuchMethod and handleNoSuchOrAbstractMethod are also provided but unused so far (the JDBC site uses handleAbstractMethod). handleNoSuchMethod latches the target's key rather than the whole site, since NoSuchMethodError can originate inside one receiver's implementation.
• keyOf picks the class the latch is keyed on (default: the target's class) — override it when the target is a wrapper around the actually-deficient object.
• State is an eager final ClassValue behind a plain (non-volatile) anyLatched flag: one flag read on the common path; a stale read just costs one extra failure, since each thread always sees its own write.
• Parses both JDK 8 and JDK 11+ AbstractMethodError message formats, verified on real JVMs (8, 11, 17, 21, 25, GraalVM 21). An unparseable message means no latch, never a wrong one.

Observed traffic. Last 3h of "Could not get client info from DB" (~98.8k events, mostly tracer <1.63): 83.5% AbstractMethodError, 14.4% SQLFeatureNotSupportedException, 1.3% other SQLException, 0.8% UnsupportedOperationException. ~85% of the AbstractMethodError events have a non-Datadog top frame — likely a wrapper/pool proxy delegating to a deficient object (inferred from stack shape, not confirmed). This PR's latch isn't keyed on the leaf, so it only covers the direct-call minority; wrapped connections are unaffected.

Not in this PR (tracked in APMLP-1894)

• An unwrap keyOf for pooled connections, to cover the dominant wrapped case.
• Latching on SQLFeatureNotSupportedException (needs an attribution approach first).
• The still-reported "Could not get metadata from DB" catch.
• Latch, the call-site-wide sibling; lands with its first user (Stop repeated NoSuchFieldError in Jackson 2.16 IAST interner lookup (quick fix) #12670).

Benchmark. ClassLatchBenchmark (JMH), Zulu 17.0.7 on an M1, single thread, 5 forks. Full table in the benchmark's Javadoc; JDK 8/x86 not measured. Error margins 0.1–3.4%.

Arm	depth 0	depth 50	Allocation (0 / 50)
status quo (throw and catch every call)	4,391 ns	6,054 ns	896 B / 2,256 B
wrapper, cannot latch	4,304 ns	5,838 ns	896 B / 2,256 B
latched, handleAbstractMethod	4.87 ns	85.2 ns	0
latched, dedicated subclass	4.86 ns	84.4 ns	0
working path, direct call	4.46 ns	28.5 ns	0
working path, latch	4.76 ns	28.5 ns	0
working path, dedicated subclass	4.72 ns	27.8 ns	0

• A latched class is ~900x cheaper than the status quo at depth 0, ~70x at depth 50, with zero allocation.
• A wrapper (can't latch) performs like the status quo, as designed.
• Method reference vs. dedicated subclass: indistinguishable (within 1%).
• The latch itself adds ~0.3 ns on the working path at depth 0, nothing measurable at depth 50.
• Unexplained: at depth 50 a latched skip (~85 ns) is slower than a call that runs (~28.5 ns); all 5 forks agreed, so not noise. Latch (Stop repeated NoSuchFieldError in Jackson 2.16 IAST interner lookup (quick fix) #12670) doesn't show this (~28 ns skip), so it's specific to this per-class path (ClassValue.get/keyOf) or to how this benchmark's recursion inlines it — not investigated further.

Tests. ClassLatchTest/HandleAbstractMethodTest/HandleNoSuchMethodTest cover latching, fallback (on the failing call, once latched, for an unattributed error, never for a real null or a null target), keyOf, wrapper non-latching, both message formats, collisions, null target, and checked/unchecked propagation, including a real AbstractMethodError built with the JDK compiler (JDK 8, 11, 17, 21). ParseDBInfoClientInfoTest confirms URL-based DBInfo survives any getClientInfo failure. Existing JDBC tests (JDBCInstrumentationV0Test, JDBCWrappedInterfacesTest, IastJDBCTest) pass on both regular and latest-dependency tasks; the Docker-backed RemoteJDBCInstrumentationV0Test wasn't run locally.

CODEOWNERS. New files fall under the already-owned /internal-api/src/*/*/datadog/trace/util/ path — no change needed.

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: APMLP-1894

🤖 Generated with Claude Code

[datadog-prod-us1-3]

🎯 Code Coverage (details)
• Patch Coverage: 85.71%
• Overall Coverage: 59.26% (+0.01%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 9e5b445 | Docs | Give us feedback!}

[dd-octo-sts]

🟢 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	14.84 s	14.68 s	[+0.0%; +2.1%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.61 s	13.75 s	[-1.7%; -0.2%] (maybe better)
startup:petclinic:appsec:Agent	17.01 s	16.79 s	[+0.4%; +2.2%] (maybe worse)
startup:petclinic:iast:Agent	16.83 s	17.05 s	[-2.0%; -0.5%] (maybe better)
startup:petclinic:profiling:Agent	16.80 s	16.78 s	[-0.8%; +0.9%] (no difference)
startup:petclinic:sca:Agent	17.07 s	16.78 s	[+0.8%; +2.7%] (maybe worse)
startup:petclinic:tracing:Agent	15.74 s	16.20 s	[-7.0%; +1.4%] (no difference)

Commit: 9e5b4459 · 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.

[datadog-prod-us1-3]

Two distinct correctness issues exist in ClassLatch.java: a NoSuchMethodError can escape the catch block if a method reference is resolved before the helper is entered, and the latch incorrectly keys on the receiver class alone rather than the specific failing method, causing unrelated valid calls to be permanently suppressed.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit d176106 · @DataDog review to ask questions}

[dougqh]

I kind of hate this, but it makes the latching mechanism safer.

[ygree]

The provided ClassLatch is a flexible and thoughtful abstraction for handling various errors. However, many of the provided methods are not used for the intended use case.
I will approve it assuming it will have more applications than just the JDBCDecorator use case.

[dougqh]

Yeah, I'm trying to find the right balance for these toolbox PRs.
I don't want to overbuild something that we won't use, but I also don't want someone to skip using it because I didn't handle an obvious use case.

And yes, we do have a few other cases for ClassLatch-es mostly more AbstractMethodError-s, so we'll have to see how this all pans out.