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

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

clientInfo = CLIENT_INFO.tryGetOrNull(connection);

The catch around the call narrows from Throwable to SQLException, still logged with EXCLUDE_TELEMETRY and still falling back to a URL-only DBInfo. Unexpected failures now reach the outer handler, which logs without EXCLUDE_TELEMETRY, so a new failure shape becomes visible in Error Tracking instead of being muted.

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

• tryGetOrNull is public final: skip if the target is null or latched, otherwise call get. A null result means nothing is available (skipped, unsupported, or no value), so the caller chooses the fallback; tryGetOrDefault(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 get 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.
• 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 built at setup; Zulu 17.0.7, M1, single thread; results in its Javadoc). The numbers are provisional: a cleaner run with more forks is planned.

• A latched class costs about 5 ns instead of about 4.5 µs, and allocates nothing (the status quo allocates 896 B at depth 0, 2,256 B at depth 50).
• A wrapper, which cannot be latched, performs like the status quo.
• On the working path the latch adds about 0.5 ns at depth 0. At depth 0 the method-reference form and a dedicated-subclass form are indistinguishable on the latched path.
• At depth 50 the latched arms showed two stable per-fork JIT modes (about 85 ns and about 32 ns), so their means are not reported and the ranking of the two forms at that depth is not established. The cause was not investigated.
• JDK 8 and x86 are not measured.

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) still yields URL-based DBInfo; an unexpected exception falls back to DBInfo.DEFAULT.

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

[dougqh]

To Claude - let's add StrategyConsumer & Strategy annotations

[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.00 s	13.95 s	[-0.3%; +1.0%] (no difference)
startup:insecure-bank:tracing:Agent	13.00 s	13.10 s	[-1.5%; -0.1%] (maybe better)
startup:petclinic:appsec:Agent	17.59 s	17.40 s	[+0.2%; +2.0%] (maybe worse)
startup:petclinic:iast:Agent	17.50 s	17.04 s	[-1.7%; +7.1%] (no difference)
startup:petclinic:profiling:Agent	17.23 s	17.39 s	[-2.0%; +0.2%] (no difference)
startup:petclinic:sca:Agent	16.89 s	17.44 s	[-7.4%; +1.1%] (no difference)
startup:petclinic:tracing:Agent	16.68 s	16.65 s	[-0.8%; +1.2%] (no difference)

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

[dougqh]

To Claude, let's call this CLIENT_INFO_LATCH

[dougqh]

With the latch handling AbstractMethodError, I'm not sure that we need to EXCLUDE_TELEMETRY anymore. I'm curious what others think.