[reference] R2DBC net-new instrumentation (io.r2dbc:r2dbc-spi 1.0.0, toolkit output)

[jordan-wong]

What

Reference PR from the apm-instrumentation-toolkit's net-new generation workflow, targeting io.r2dbc:r2dbc-spi:1.0.0.RELEASE. No dd-trace-java module exists for R2DBC today, so this was not a blind regen — there was nothing to hide/restore. This measures from-scratch generation quality against an SPI-only Maven coordinate (no concrete driver dependency).

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

Toolkit reviewer verdict: needs_work

The toolkit's own review_cycle ran 5 iterations and did not reach approved (todos_remaining=15 after iter5, the apparent iteration cap). Total cost: $65.81, duration: ~2h17m.

What went right (structural checks all clean):

• Correct SPI-first targeting throughout (io.r2dbc.spi.Statement/Connection/Batch), no concrete-driver coupling
• Correct single-name super("r2dbc"), no spurious version alias
• Correctly classified as Cat A (span-creating); all Cat B checks correctly "not applicable"
• No scheduler-exclusion, overload-selection, or context-store-hoisting issues

What's broken — real semantic-completeness gaps (dominant finding):

• db.name (REQUIRED tag) is never set. ConnectionInstrumentation only extracts from ConnectionMetadata, which doesn't expose database/host/port/user. Root cause (per reviewer): should hook ConnectionFactory.create() or the Connection constructor instead, which exposes ConnectionFactoryOptions with that data.
• peer.hostname, db.user, network.destination.port (RECOMMENDED tags) — all missing for the same reason.
• Dead code: R2dbcConnectionInfo has fields (dbInstance, dbUser, dbHostname) defined but never populated.
• BatchInstrumentation spans have zero connection metadata tags.
• Test coverage gap mirrors the code gap; inconsistent db.type value between batch ("r2dbc") and statement ("testdb") tests.

Minor: 1 inline narrative comment to remove; missing explicit muzzle fail blocks for 0.8.x/0.9.x version families. Originally noted as "not urgent — assertInverse=true already isolates," but see CI Triage Status below: that assertInverse=true was actually asserting a false compatibility boundary and has been removed as part of a CI fix, so there is now no automated check that pre-1.0 releases are excluded — this remains a real (if low-priority) gap.

This PR is left as-is (not iterated further) so the diff reflects exactly what the toolkit produced — do not fix findings on this branch; it's a research artifact, not a merge candidate.

Comparison with OpenTelemetry's R2DBC instrumentation (reference for the correct hook point)

OTel Java solved exactly the gap above by hooking a different SPI entry point. R2DBC exposes connection identity (host/port/db/user) only in io.r2dbc.spi.ConnectionFactoryOptions at connection-factory creation — not on Connection/ConnectionMetadata (which exposes only getDatabaseProductName()/getDatabaseVersion()). Where you hook decides whether you can populate these tags at all.

	this PR (dd-trace-java)	OpenTelemetry Java
Hook point	Connection.createStatement() + connection.getMetadata() (ConnectionInstrumentation.java:30,38,53)	ConnectionFactories.find(ConnectionFactoryOptions) (instrumentation/r2dbc-1.0/javaagent/.../R2dbcInstrumentation.java)
Carrier	R2dbcConnectionInfo	DbExecution holding captured ConnectionFactoryOptions (.../library/.../internal/DbExecution.java)
db.name/db.namespace	❌ can't — ConnectionMetadata lacks it	✅ ConnectionFactoryOptions.DATABASE
peer.hostname/server.address	❌	✅ ConnectionFactoryOptions.HOST
port	❌	✅ ConnectionFactoryOptions.PORT
db.user	❌	✅ ConnectionFactoryOptions.USER
DBM traceparent (full mode)	❌ passes traceParent=null (ConnectionInstrumentation.java:64)	✅ propagator-driven sqlcommenter injects real W3C traceparent

OTel history check: no PR/issue in opentelemetry-java-instrumentation's r2dbc-1.0 shows these attributes were ever missing-then-added — the factory-level hook is original design, chosen precisely because it's the one place the full connection params are structured data. So this isn't a shared gap; it's a design divergence.

Takeaway: the toolkit correctly recognized R2DBC as SPI-shaped and hooked io.r2dbc.spi.* interfaces — but hooked the wrong SPI entry point for connection identity. The remediation is to capture ConnectionFactoryOptions at factory-create time and thread it forward (as OTel's DbExecution does), instead of reading ConnectionMetadata per statement. Full write-up: toolkit repo docs/eval-research/r2dbc-otel-comparison.md.

CI Triage Status

Last updated: 2026-07-22

Confirmed research findings (do not fix — core instrumentation-logic gap):

• [Reviewer-surfaced, not CI-surfaced] db.name (REQUIRED tag), peer.hostname/db.user/network.destination.port (RECOMMENDED tags) never populated. ConnectionInstrumentation only extracts from ConnectionMetadata (product name/version only) instead of hooking ConnectionFactory.create()/the Connection constructor, which exposes ConnectionFactoryOptions with the actual host/port/db/user data. No CI check catches this — there's no assertion anywhere that these tags must be present — so this finding would otherwise only live in prose. See "What's broken" above for full detail; candidate skill fix is N-DBM-2 (silent-narrowing process gap) in the toolkit's docs/eval-research/BACKLOG.md.
• [Reviewer-surfaced, not CI-surfaced] BatchInstrumentation spans carry zero connection-metadata tags — same root cause as above, compounded (batch path never wires through what statement path partially has).
• [Reviewer-surfaced, not CI-surfaced] Dead code: R2dbcConnectionInfo fields (dbInstance, dbUser, dbHostname) defined but never populated — same root cause.

Fixed (scaffolding, root cause is a documented finding):

• dd-gitlab/muzzle: [4/8] — muzzle-AssertFail-io.r2dbc-r2dbc-spi-0.8.6.RELEASE and -0.9.1.RELEASE FAILED: "Instrumentation unexpectedly passed Muzzle validation". The generated build.gradle declared versions = "[1.0.0.RELEASE,)" with assertInverse = true, asserting pre-1.0 releases must fail — but io.r2dbc.spi.Statement/Connection/Batch are structurally unchanged across 0.8.x/0.9.x/1.0.x, so they pass anyway. Fixed in commit 521b0d52a1: dropped assertInverse = true. Verified locally AND confirmed green in CI (all muzzle: [*/8] shards SUCCESS post-push). Does not touch the hook point, tags, or integration name — the dominant finding above (missing db.name/peer.hostname/db.user/etc.) is unrelated and unaddressed here on purpose.

Fixed (config/mechanical):

• dd-gitlab/build — verifyAgentJarIntegrations failed: "Integration list differs from metadata/agent-jar-checks.properties" — super("r2dbc") registered but the golden file was never updated. Fixed in commit 368d2094ce: added r2dbc,\ alphabetically between quartz and ratpack. Verified locally AND confirmed green in CI post-push.

Classified as flake / unrelated:

• (none yet)

Still unclassified: none.

Process note (not a code finding):

• dd-gitlab/validate_supported_configurations_v2_local_file — Same pattern as PR [reference] eval: blind regeneration of PostgreSQL JDBC driver (toolkit output) #11997's PostgreSQL finding, investigated the same way: manually checked https://feature-parity.us1.prod.dog/#/configurations for DD_TRACE_R2DBC_ENABLED/DD_TRACE_R2DBC_ANALYTICS_ENABLED/DD_TRACE_R2DBC_ANALYTICS_SAMPLE_RATE — none visible in the registry UI, consistent with these being genuinely new config names with no existing registry entry. Our local entries follow the same convention as master's real integrations. Confirmed process note — remediation requires feature-parity registry write access neither of us has, not a dd-trace-java commit.

---

🤖 Generated by apm-instrumentation-toolkit. Not a merge candidate — reference/research artifact only.

[datadog-prod-us1-3]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 57.24% (-0.15%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: ada5972 | Docs | Datadog PR Page | 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	13.99 s	14.07 s	[-1.5%; +0.4%] (no difference)
startup:insecure-bank:tracing:Agent	12.96 s	13.11 s	[-1.9%; -0.4%] (maybe better)
startup:petclinic:appsec:Agent	17.02 s	16.65 s	[+1.0%; +3.4%] (significantly worse)
startup:petclinic:iast:Agent	16.92 s	16.38 s	[-0.9%; +7.6%] (no difference)
startup:petclinic:profiling:Agent	16.86 s	16.92 s	[-1.7%; +1.0%] (no difference)
startup:petclinic:sca:Agent	17.02 s	16.73 s	[+0.8%; +2.8%] (maybe worse)
startup:petclinic:tracing:Agent	16.14 s	16.10 s	[-0.7%; +1.3%] (no difference)

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

[ygree]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 368d2094ce

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Pass an actual traceparent for DBM full mode

When DD_DBM_PROPAGATION_MODE=full, this is the only point where the SQL text is modified, but the traceParent argument is always null because the R2DBC span is not created until execute(); the later execute advice only sets _dd.dbm_trace_injected and cannot update the SQL. The resulting DBM comment has no traceparent, so full-mode DBM cannot correlate the database query with the APM span despite the span being tagged as injected; delay comment injection until a span exists or avoid setting the injected tag unless a traceparent was included.

Useful? React with 👍 / 👎.

[jordan-wong]

No code change — recorded as a documented finding, not fixed on this branch. This is a [reference] not-for-merge research PR, and this is its central instrumentation-logic finding (the missing traceparent + broader connection-metadata gap): it can't be fixed without moving comment injection out of createStatement() to after the span exists, which is the same span-lifecycle restructure as the defer-until-subscribe finding. OpenTelemetry solves it by hooking ConnectionFactories.find() and injecting via a propagator-driven commenter — side-by-side comparison with line refs: https://github.com/DataDog/apm-instrumentation-toolkit/blob/eval/java/docs/eval-research/r2dbc-otel-comparison.md . Captured in the PR body and docs/eval-research/hypotheses/r2dbc.md.

[chatgpt-codex-connector]

Keep spans open through R2DBC result consumption

For R2DBC callers that consume the returned Result later (for example Mono.from(statement.execute()).flatMap(result -> result.map(...)) or getRowsUpdated()), the outer Publisher<Result> can complete before the row/update-count Publisher is consumed, but this line finishes the database span at that outer completion. Errors and latency that occur while consuming rows or update counts are then missed; wrap the emitted Result consumption Publishers or otherwise defer finishing until the result stream terminates.

Useful? React with 👍 / 👎.

[jordan-wong]

No code change — documented finding, not fixed. Correct: the span finishes when the outer Publisher<Result> completes, so errors/latency during row/update-count consumption (e.g. flatMap(result -> result.map(...)), getRowsUpdated()) are missed. Fixing means wrapping the emitted Result's downstream consumption publishers — coupled to the same span-lifecycle restructure as the defer-until-subscribe finding above. Recorded as an instrumentation-logic finding in the PR body + hypotheses/r2dbc.md; left as-generated on this reference PR.

[chatgpt-codex-connector]

Defer R2DBC spans until subscription

When clients assemble a reactive pipeline without immediately subscribing (common with Spring/Reactor, or if a branch never subscribes), this starts a span during Statement.execute() even though no database work has begun. That span is attached to the assembly-time context and can stay open forever if the publisher is never subscribed, or record inflated latency if subscribed later; create/decorate the span in the returned publisher's subscribe path instead.

Useful? React with 👍 / 👎.

[jordan-wong]

No code change — documented finding, not fixed. Correct diagnosis: the span is started in execute()'s OnMethodEnter rather than in the returned publisher's subscribe(), so an assembled-but-never-subscribed pipeline leaks the span or records inflated latency. Fixing this = moving span creation/decoration into TracingPublisher.subscribe(), a fundamental restructure of the module's approach; on a reference PR that would destroy the artifact this experiment exists to show. Recorded as an instrumentation-logic finding in the PR body + docs/eval-research/hypotheses/r2dbc.md rather than patched.

[jordan-wong]

Hook-point difference vs OpenTelemetry (primary). This reads connection identity from Connection.getMetadata() (io.r2dbc.spi.ConnectionMetadata), which by SPI contract exposes only getDatabaseProductName()/getDatabaseVersion() — no host/port/database/user. OTel Java instead hooks io.r2dbc.spi.ConnectionFactories.find(ConnectionFactoryOptions) (R2dbcInstrumentation.java#L25-L34) and captures ConnectionFactoryOptions at factory-creation, then threads it forward per query in DbExecution (DbExecution.java#L84-L97) — which is why OTel can populate db.namespace/server.address/server.port/db.user and this cannot. For a shippable integration, the hook point likely needs to move to the connection factory. Full side-by-side: docs/eval-research/r2dbc-otel-comparison.md (toolkit repo).

[jordan-wong]

DBM injection difference vs OpenTelemetry. Four of six args to R2dbcSQLCommenter.inject(...) are null here — dbService, hostname, dbName, and crucially traceParent (last arg). So even in full DBM mode the SQL comment carries no traceparent, and DB-side query samples cannot be correlated to the APM trace. Root cause is the same as the hook-point comment above: this runs at createStatement() time, before the span exists, so there is no traceparent to pass. OTel avoids this by injecting through a propagator-driven commenter after the span is established (R2dbcSqlCommenterUtil). A shippable version needs the traceparent wired in (which depends on the hook-point/lifecycle change above).

[jordan-wong]

Dead connection-metadata fields (consequence of the hook point). R2dbcConnectionInfo.of(originalSql, dbType, null, null, null) passes null for dbInstance/dbUser/dbHostname — so those fields exist on R2dbcConnectionInfo but are never populated, and the decorator overrides that would consume them (R2dbcDecorator.dbUser/dbInstance/dbHostname, lines 58-69) all return null. Net effect on spans: db.name (REQUIRED), peer.hostname, db.user, network.destination.port are never set. OTel populates all of these from ConnectionFactoryOptions (R2dbcSqlAttributesGetter.java#L50-L116). These three comments are one finding with one fix: move the hook to the connection factory.

[jordan-wong]

Batch spans carry zero connection metadata (secondary). This advice does startSpan + afterStart but never calls onConnection/attaches any R2dbcConnectionInfo, so Batch.execute() spans have no db.*/peer.* tags at all — even less than the statement path. OTel treats batch executions through the same per-execution DbExecution carrying ConnectionFactoryOptions, so batch spans get the same connection attributes as statement spans. Same root fix (connection-factory hook) resolves this too. Lower priority than the statement path, but noting it for completeness of the shippability assessment.