[reference] R2DBC net-new instrumentation — regen vs sharpened DB skill (toolkit output)

[jordan-wong]

What

Toolkit-generated R2DBC instrumentation (io.r2dbc:r2dbc-spi:1.0.0.RELEASE), regenerated by the apm-instrumentation-toolkit against its sharpened database-category rules. This is a reference/research artifact — NOT a merge candidate. It supersedes nothing; the original reference PR #12032 stays as-is.

Generated module: dd-java-agent/instrumentation/r2dbc/r2dbc-1.0/.

Why this regen exists

#12032 was generated before the toolkit's database-category rules were sharpened (SPI-first targeting, eager connection-metadata capture, muzzle handling). This run tests whether the improved skill produces a better R2DBC — and it does, in architecture. But a live-trace comparison against the OpenTelemetry SDK surfaced that it still doesn't actually emit spans on a real driver, for a new, mechanical reason.

Improvement over #12032 (architecture)

The DBM feature step now hooks the OTel-correct entry point:

• ConnectionFactory.create() + ConnectionFactoryOptions (host/port/database/user live here, not on ConnectionMetadata), threaded via a new MetadataWrappingPublisher → R2dbcConnectionInfo → statement/batch spans.
• R2dbcDecorator now populates db.name / peer.hostname / db.user / peer.port (in [reference] R2DBC net-new instrumentation (io.r2dbc:r2dbc-spi 1.0.0, toolkit output) #12032 these were hardcoded null).

Known defect — the finding (do NOT fix on this branch)

The module is CI-green but emits ZERO spans on a real driver.

• :check, :muzzle, :allLatestDepTests all pass; 11/11 unit tests pass.
• But every advice declares a writable @Advice.Return(readOnly = false) Publisher<...>, while real driver methods return the concrete Mono/Flux. Byte Buddy refuses to bind the interface into the concrete return slot, so class transformation fails at runtime and the classes load uninstrumented:

Cannot assign interface org.reactivestreams.Publisher to class reactor.core.publisher.Mono
    → io.r2dbc.pool.ConnectionPool        (ConnectionFactoryCreateAdvice)
Cannot assign interface org.reactivestreams.Publisher to class reactor.core.publisher.Mono
    → io.r2dbc.h2.H2ConnectionFactory     (ConnectionFactoryCreateAdvice)
Cannot assign interface org.reactivestreams.Publisher to class reactor.core.publisher.Flux
    → io.r2dbc.h2.H2Statement             (StatementExecuteAdvice)

So the (correct) new connection-metadata architecture never runs. The SPI-fake test suite binds where real drivers won't, which is why CI is green.

Live verification — Spring Data R2DBC / H2 app (eugenp spring-reactive-data), GET /products ×3:

	this PR (regen)	#12032	OpenTelemetry Java 2.30.0
R2DBC spans	0	0	13
Byte Buddy transformation failures on real driver	3	1	—
Connection-metadata architecture	✅ ConnectionFactoryOptions (but dead)	❌	✅ works
CI-equivalent	✅ BUILD SUCCESSFUL	(was red on muzzle scaffolding)	—

Remediation (for a future working version, not this branch)

Type the writable @Advice.Return so Byte Buddy can bind it against a concrete-Mono/Flux-returning method — e.g. @Advice.Return(readOnly = false) Object + cast, or Advice.AssignReturned — on all three advices (ConnectionFactoryCreateAdvice, StatementExecuteAdvice, BatchExecuteAdvice). AND add at least one integration test against a real driver (r2dbc-h2), not only an SPI fake.

Provenance

• Toolkit branch eval/java @ d9dcb160 (force-read DB rules R-DB-1..6).
• Full write-up + generated-source snapshot + logs: apm-instrumentation-toolkit docs/eval-research/runs/r2dbc/attempt-dbskill-20260818/outcome.md and docs/eval-research/r2dbc-live-trace-comparison-2026-08-17.md.

---

🤖 Generated by apm-instrumentation-toolkit. Reference/research artifact — not a merge candidate.

[datadog-prod-us1-4]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 58.32% (-0.20%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 882acfb | Docs | View more details | Give us feedback!}