feat: binding span enrichment via jsRpc (v1)

[Ankcorn]

Stacked on #6704. Review that first.

What

New JS API: ctx.tracing.enrichBindingSpan({ name, attributes }). Lets a callee rename and tag the caller's binding-call span. Works for any jsRpc binding — AIG is
the first user but the mechanism is generic (D1, Vectorize, your service binding, anything reachable via env.x.method()).

// Set name + initial attributes up front
this.ctx.tracing.enrichBindingSpan({
  name: "ai_gateway.run",
  attributes: { "gen_ai.request.model": model },
});

// ...later, append more without repeating the name
this.ctx.tracing.enrichBindingSpan({
  attributes: { "gen_ai.usage.output_tokens": N },
});

Both fields are optional, but you should set name at least once — a span called jsRpcSession is meaningless to a user reading their tail stream. Multiple calls
in one method merge: latest name wins, attributes upsert by key.

How

Buffered on the callee's IncomingRequest, drained into a new optional bindingSpanEnrichment field on JsRpcTarget.CallResults, applied in the caller's response
lambda to the in-scope jsRpcSession span. STW sees attribute events and a rename.

Caveats

• Direct service-binding calls only (env.svc.method()). Held-stub calls buffer correctly but the caller has no span to enrich on that path. Documented in JSDoc.
• Input caps: 256 attrs / 256 B key / 128 KB value. NaN/Infinity skip the int64 cast.
• Each call gets its own session, so parallel Promise.all is isolated.

Open questions

• Compat-flag gating?
• Encapsulate JsRpcSessionCustomEvent::jsRpcSessionSpan (currently public so callImpl can take its address)?

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

Adds ctx.tracing.setJsrpcSessionAttributes() allowing a trusted callee to enrich the caller's jsRpcSession user span with a rename and attributes, gated by allowBindingSpanEnrichment on ServiceDesignator.

Issues found (ranked by severity):

1. [MED] Stale TODO in test config — says the capnp field doesn't exist yet, but it was already added in this PR.
2. [MED] Orphaned onUpdateName doc comments in trace.h — the method was removed but two comments still reference it.
3. [LOW] Stale comment in http.c++ referencing ~TraceContext reads pendingEnrichment — PendingEnrichment on TraceContext was removed in a later commit in this PR.

---

This review was generated by an AI assistant and may contain inaccuracies.

[ask-bonk]

This TODO is stale — allowBindingSpanEnrichment already exists in workerd.capnp (added in this PR, at ServiceDesignator @4). The comment should be cleaned up.

Suggested change

	# Service binding with spanEnrichmentPolicy.
	# TODO(impl): allowBindingSpanEnrichment field does not exist yet in workerd.capnp;
	# add it as part of the implementation of this feature.
	# Service binding with allowBindingSpanEnrichment.

[ask-bonk]

Orphaned doc comment — the onUpdateName() virtual method it describes was removed in this PR, but these three comment lines were left behind. The class-level doc comment at line 1156 also still references onUpdateName() (though that line is outside the diff hunk). At minimum these orphaned lines should be deleted.

Suggested change

	// Called when the operation name is changed after the span was opened (via
	// SpanBuilder::setOperationName()). Observers that eagerly stream the open event should handle
	// this; others may simply update their buffered state. Default implementation is a no-op.

[ask-bonk]

Review posted successfully on PR #6695. I found 3 actionable issues — all are stale/orphaned comments from the multi-commit development history, with suggested fixes provided inline. The core design (trust model, capnp schema additions, raw pointer lifetime, enrichment gating) looks sound.

github run

[github-actions]

The generated output of @cloudflare/workers-types has been changed by this PR. If this is intentional, run just generate-types to update the snapshot. Alternatively, you can download the full generated types:

Full Type Diff

diff -r types/generated-snapshot/latest/index.d.ts bazel-bin/types/definitions/latest/index.d.ts
4062a4063
>   enrichBindingSpan(options: TracingEnrichmentOptions): void;
4063a4065,4068
> }
> interface TracingEnrichmentOptions {
>   name?: string;
>   attributes?: Record<string, any>;
diff -r types/generated-snapshot/latest/index.ts bazel-bin/types/definitions/latest/index.ts
4068a4069
>   enrichBindingSpan(options: TracingEnrichmentOptions): void;
4069a4071,4074
> }
> export interface TracingEnrichmentOptions {
>   name?: string;
>   attributes?: Record<string, any>;

[codspeed-hq]

Merging this PR will not alter performance

✅ 72 untouched benchmarks
⏩ 129 skipped benchmarks¹

---

_{Comparing tankcorn/aig-span-enrichment (7f8af52) with tankcorn/jsrpc-span-parenting (a1dafc5)}

Footnotes

1. 129 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov-commenter]

Codecov Report

❌ Patch coverage is 79.77528% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.59%. Comparing base (a1dafc5) to head (7f8af52).

Files with missing lines	Patch %	Lines
src/workerd/api/tracing.c++	77.04%	3 Missing and 11 partials ⚠️
src/workerd/api/worker-rpc.c++	85.71%	0 Missing and 4 partials ⚠️

Additional details and impacted files

@@                        Coverage Diff                        @@
##           tankcorn/jsrpc-span-parenting    #6695      +/-   ##
=================================================================
+ Coverage                          66.54%   66.59%   +0.04%     
=================================================================
  Files                                402      402              
  Lines                             115902   116036     +134     
  Branches                           19412    19439      +27     
=================================================================
+ Hits                               77131    77270     +139     
+ Misses                             27188    27170      -18     
- Partials                           11583    11596      +13     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.