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 tryApplyOrNull:

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, Connection::getClientInfo);
      }
    };

clientInfo = CLIENT_INFO_LATCH.tryApplyOrNull(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

• tryApplyOrNull is public final: skip if the target is null or latched, otherwise call apply. A null result means nothing is available (skipped, unsupported, or no value), so the caller chooses the fallback; tryApplyOrDefault(target, fallback) is null-coalescing sugar over it, so a call that yields nothing and a skipped call always agree. There is no built-in default and no wrapper result type: a null return needs no allocation and no escape analysis. Subclasses implement apply in an ordinary try/catch (so checked exceptions such as SQLException just work) and change the state only through protected helpers: latch, unlatch, latchIfNamed.
• handleAbstractMethod(target, fn) is a protected higher-order helper for the common case. fn is a ThrowingFunction<T, R, E>, a new top-level interface in datadog.trace.api.function next to TriFunction and TriConsumer, so a method that throws a checked exception (such as getClientInfo) can be passed as a method reference. AbstractMethodError and UnsupportedOperationException both yield null. Only AbstractMethodError can latch, and only when its message names the key class, so a wrapper delegating to a deficient object is never latched. UnsupportedOperationException names no class, so it is caught on every call. Anything else propagates.
• handleNoSuchMethod (NoSuchMethodError; latches the target's key, never the whole site, because its message names the declared type and it can come from a call inside one receiver's implementation) and handleNoSuchOrAbstractMethod (both; the documented default, since the distinction is easy to miss) are also provided. Neither is used at a call site yet: the JDBC site uses handleAbstractMethod. All three are @StrategyConsumer with a @Strategy function parameter.
• keyOf chooses the class the latch is keyed on (default: the target's class). Every operation uses it, so the check and the latch cannot disagree. Override it to key on the object that is actually deficient when the target is a wrapper.
• State is an eager final ClassValue (safely published, no creation race) behind a plain anyLatched flag, so the common path is one flag read and the per-class lookup only happens once something has been latched. The state is deliberately not atomic: a stale read only costs another failure, and a thread always sees its own write, so each thread pays for at most one failure after its own first. A plain flag measured faster than volatile on the working path.
• Both HotSpot message formats are parsed: JDK 8 (Impl.b()Ljava/lang/String;) and JDK 11+ (Receiver class Impl does not define...), checked on real JVMs (8, 11, 17, 21, 25, GraalVM 21). An unparseable message means no latch, never a wrong latch. Anything unattributable keeps today's behaviour: one caught throw per call.

What the observed traffic looks like. Last 3h of "Could not get client info from DB" (~98.8k events, mostly tracer <1.63): AbstractMethodError 83.5%, SQLFeatureNotSupportedException 14.4%, other SQLException 1.3%, UnsupportedOperationException 0.8%. About 85% of the AbstractMethodError events have a non-Datadog top frame, which suggests a wrapper or pool proxy delegating to a deficient object (inference from stack shape, not confirmed). This PR's latch is not keyed on the leaf, so it covers the direct minority; wrapped connections keep today's behaviour.

Not in this PR (design in APMLP-1894)

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

Benchmark. ClassLatchBenchmark (JMH; a real AbstractMethodError is built at setup). One run on Zulu 17.0.7 (HotSpot), MacBook M1, single thread, 5 forks (20 measurement iterations per arm), on a laptop with normal background activity (load about 4). The full table is in the benchmark's Javadoc. JDK 8 and x86 are not measured. The numbers were measured on the commit before the hook was renamed apply and the public methods tryApply*; that rename is naming only. Error margins are 0.1% to 3.4%.

• A latched class is about 900 times cheaper than the status quo at depth 0 and about 70 times at depth 50, and allocates nothing.
• A wrapper, which cannot be latched, performs like the status quo, as designed.
• The method-reference form and a dedicated subclass are indistinguishable (within 1%), so a separate abstract class for the helper is not needed.
• The latch adds about 0.3 ns on the working path at depth 0 and nothing measurable at depth 50.
• Unexplained: at depth 50 a latched skip (about 85 ns) is slower than a call that runs (about 28.5 ns), though at depth 0 the skip is as cheap as expected. All five forks agreed (11.7M to 11.9M ops/s per fork), so it is not noise. Latch (Stop repeated NoSuchFieldError in Jackson 2.16 IAST interner lookup (quick fix) #12670) does not show it: its skip at depth 50 is about 28 ns. So it is specific to the per-class path (ClassValue.get and keyOf), or to how this benchmark's recursion inlines it. It was not investigated. An earlier, shorter run had one fork near 32 ns for this arm, which did not reproduce in these five.

Tests. ClassLatchTest and HandleAbstractMethodTest cover latching, keyOf, wrapper non-latching, both message formats, prefix collisions, null target, checked/unchecked propagation, and a real AbstractMethodError built with the JDK compiler to pin the message format (pass on JDK 8, 11, 17 and 21). ParseDBInfoClientInfoTest: a failing getClientInfo (SQLException, UnsupportedOperationException, AbstractMethodError, and any other Throwable, including a bare one) still yields URL-based DBInfo. The existing JDBCInstrumentationV0Test, JDBCWrappedInterfacesTest and IastJDBCTest pass on both the regular and latest-dependency tasks; the Docker-backed RemoteJDBCInstrumentationV0Test cannot run locally.

CODEOWNERS. The new files are under /internal-api/src/*/*/datadog/trace/util/, which is already owned (@DataDog/apm-java), so no change is 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