Skip to content

Add support for span links - #8218

Open
wperron wants to merge 8 commits into
mainfrom
wperron/wo-1767-span-links
Open

wperron wants to merge 8 commits into
mainfrom
wperron/wo-1767-span-links

Conversation

@wperron

@wperron wperron commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

Adds span links to workerd’s tracing API. Links are a part of the OpenTelemetry Tracing specification that associate a span with other spans, including spans in different traces, without changing its parent or active context. This is useful to highlight causal relationship that sometimes differ from parent-child context relationship.

interface Span {
  addLink(link: TracingSpanLink): this;
  addLinks(links: readonly TracingSpanLink[]): this;
}

Each link contains:

  • context: traceId, spanId, traceFlags, and optional isRemote and serialized traceState.
  • attributes: optional string, number, or boolean attributes describing the relationship.

Both methods are chainable, preserve order and duplicates, and snapshot their inputs. Invalid attributes are discarded and counted. Recorded links flow through production tracing and appear as spanLinks streaming-tail events.

OpenTelemetry specification

OpenTelemetry JS reference

@codecov-commenter

codecov-commenter commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 81.90476% with 57 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.68%. Comparing base (10c34c6) to head (7c27d31).
⚠️ Report is 4 commits behind head on main.

Files with missing lines Patch % Lines
src/workerd/io/trace-test.c++ 56.00% 0 Missing and 22 partials ⚠️
src/workerd/api/tracing.c++ 88.28% 3 Missing and 12 partials ⚠️
src/workerd/io/trace.c++ 87.67% 7 Missing and 2 partials ⚠️
src/workerd/io/tracer.c++ 68.75% 0 Missing and 5 partials ⚠️
src/workerd/api/tracing.h 70.00% 0 Missing and 3 partials ⚠️
src/workerd/io/tracer.h 0.00% 2 Missing ⚠️
src/workerd/io/trace.h 75.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8218      +/-   ##
==========================================
+ Coverage   66.46%   66.68%   +0.22%     
==========================================
  Files         797      798       +1     
  Lines      203737   204148     +411     
  Branches    31623    31721      +98     
==========================================
+ Hits       135406   136144     +738     
+ Misses      49815    49422     -393     
- Partials    18516    18582      +66     

☔ View full report in Codecov by Harness.
📢 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.

@wperron
wperron marked this pull request as ready for review November 5, 2026 21:47
@wperron
wperron requested review from a team as code owners November 5, 2026 21:47
@wperron
wperron requested a review from cjol November 5, 2026 21:47

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 536a244c.

This review, of 9da5419f

💬 Approved with comments — The implementation is complete and well tested. The only finding is an optional SUGGESTION: put a bound on the addLinks loop.

Findings: 1 suggestion (1 is an inline comment on the diff)

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 suggestion

The change is clean and thoroughly tested; one optional hardening suggestion for Span::addLinks.

Recommendation: 💬 Optional Nits

  • [SUGGESTION] Span::addLinks iterates to array->Length() with no upper bound, so a huge sparse or all-invalid array spins for its full length (src/workerd/api/tracing.c++:633)
View full review
  • Span::addLinks walks the whole input array while the span is still traced (src/workerd/api/tracing.c++:633). Entries that are invalid, undefined or holes never consume byte budget, so a huge sparse array keeps the loop running for its full length. Only the caller's own isolate pays for this, and the CPU limit bounds it.

Checked and found fine:

  • Every KJ_SWITCH_ONEOF over TailEvent::Event handles SpanLinks.
  • BaseTracer::addSpanLinks and SpanSubmitter::submitSpanLinks default to no-ops.
  • The byte-budget test matches MAX_SPAN_BYTES.

✅ All other checks passed

🔒 Security: ✅ LGTM

No security issues found.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


⚡ Performance: ✅ LGTM

No performance issues found.


📝 Documentation: ✅ LGTM

The new public type declarations document the link payload and the chaining behaviour.


Reviewed commit: 9da5419f

Comment thread src/workerd/api/tracing.c++ Resolved

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 9fdeb2dd.

This review, of 536a244c

✅ Approved — The earlier suggestion to bound the addLinks loop is fixed and tested, and nothing new came up in code quality, security, performance or documentation.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Link inputs are validated and bounded:

  • Trace and span IDs are checked for length and hex format.
  • traceFlags must be in the range 0–255.
  • tracestate is validated against W3C limits.
  • Attributes accept scalar values only.
  • Each link counts against the 64 KB per-span byte budget.
  • addLinks caps a batch at 512 entries.

The Cap'n Proto reader copies incoming strings.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

Earlier suggestion, now fixed. Span::addLinks checks the length against MAX_SPAN_LINK_ARRAY_ELEMENTS (512) before it reads any element. It also re-checks getIsTraced() on every pass, so a getter that ends the span stops further reads. The batch-limit tests and the instrumentation test cover this.

Also checked:

  • Every TailEvent::Event switch handles SpanLinks.
  • BaseTracer::addSpanLinks and SpanSubmitter::submitSpanLinks default to no-ops.
  • A zero span ID survives the Cap'n Proto round-trip.
  • SpanState::addLinks re-checks spans that end during link conversion.

⚡ Performance: ✅ LGTM

The link paths are bounded by the 512-entry batch cap and the per-span byte budget. Tracer paths return early when tail streaming is off. The duplicate-key scan in parseTracestate is limited to 32 keys.


📝 Documentation: ✅ LGTM

The new public type declarations document the link payload and the chaining behaviour.


Reviewed commit: 536a244c

@petebacondarwin
petebacondarwin removed the request for review from cjol November 6, 2026 15:19

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of e4d6ce4c.

This review, of 9fdeb2dd

✅ Approved — The earlier suggestion to bound the addLinks loop is fixed and tested, and nothing new came up in code quality, security, performance or documentation.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Link inputs are validated and bounded:

  • Trace and span IDs are checked for length and hex format.
  • traceFlags must be in the range 0–255.
  • tracestate is validated against W3C limits.
  • Attributes accept scalar values only.
  • Each link counts against the 64 KB per-span byte budget.
  • addLinks caps a batch at 512 entries.

The Cap'n Proto reader copies incoming strings.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

Earlier suggestion, now fixed. Span::addLinks checks the length against MAX_SPAN_LINK_ARRAY_ELEMENTS (512) before it reads any element. It also re-checks getIsTraced() on every pass, so a getter that ends the span stops further reads. The batch-limit tests and the instrumentation test cover this.

Also checked:

  • Every TailEvent::Event switch handles SpanLinks.
  • BaseTracer::addSpanLinks and SpanSubmitter::submitSpanLinks default to no-ops.
  • A zero span ID survives the Cap'n Proto round-trip.
  • SpanState::addLinks re-checks spans that end during link conversion.

⚡ Performance: ✅ LGTM

The link paths are bounded by the 512-entry batch cap and the per-span byte budget. Tracer paths return early when tail streaming is off. The duplicate-key scan in parseTracestate is limited to 32 keys.


📝 Documentation: ✅ LGTM

The new public type declarations document the link payload and the chaining behaviour.


Reviewed commit: 9fdeb2dd — same changes as 536a244c, so this is that commit's review (no new review was run; line numbers are as of 536a244c)

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 00c24454.

This review, of e4d6ce4c

✅ Approved — No issues found. The only change since the last approved review adds the tracing tests to CI coverage, and the span-link implementation still checks out.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

The coverage workflow change only widens the Bazel build and test targets. It adds no secrets, permissions or untrusted input. Link inputs are still validated, and batches are capped at 512 entries.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

Nothing wrong found in the link conversion, the per-span byte accounting, tracer forwarding, the Cap'n Proto schema or the streaming serialization. The coverage workflow edit only adds the Cloudflare tracing tests to the build and test targets.


⚡ Performance: ✅ LGTM

The workflow change only adds CI test targets and has no runtime performance impact. Link handling is still bounded by the 512-entry batch cap and the per-span byte budget.


📝 Documentation: ✅ LGTM

The generated type snapshots match the source definitions in types/defines/trace.d.ts.


Reviewed commit: e4d6ce4c

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 8f31aec4.

This review, of 00c24454

✅ Approved — No issues found. The change since the last approved review is a clean merge of main, and the span-link implementation, limits and generated types still check out.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Link IDs, flags and tracestate are validated strictly before use. Only own enumerable string keys with string, number or boolean values are accepted as attributes. Batches are capped at 512 entries and each span has a byte budget.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

Nothing wrong found in the link conversion, the per-span byte accounting, tracer forwarding, the Cap'n Proto schema or the streaming serialization. The tests cover round-trip, validation, sanitization, the 512-element batch cap and the no-op paths.


⚡ Performance: ✅ LGTM

Link handling is bounded by the 512-entry batch cap and the per-span byte budget. Forwarding returns early when no tail-stream writer is attached or the link list is empty, so spans nobody observes pay no extra cost.


📝 Documentation: ✅ LGTM

The generated type snapshots match the source definitions in types/defines/trace.d.ts.


Reviewed commit: 00c24454

@dom96 dom96 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly a few questions, but one major thing that I think needs to be fixed: the trace parsing. Please move it to Rust for safety.

Comment thread src/cloudflare/internal/tracing.d.ts Resolved
Comment thread src/cloudflare/internal/tracing.d.ts Resolved
Comment thread src/workerd/api/tracing.c++ Resolved
Comment thread src/workerd/io/trace.c++ Resolved
Comment thread src/workerd/io/trace.c++ Resolved
Comment thread src/workerd/io/trace.c++ Resolved
@wperron
wperron force-pushed the wperron/wo-1767-span-links branch from 00c2445 to 8f31aec Compare November 13, 2026 16:22

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 69c108f3.

This review, of 8f31aec4

✅ Approved — No issues found. Parsing tracestate with the opentelemetry crate through the new cxx bridge is safe and well tested, and the rest of the span-link implementation still checks out.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

  • The bridge takes &[u8] and returns an owned String. Invalid UTF-8 and any value TraceState rejects become an empty string, so no panic is possible on untrusted input.
  • Only the normalized header is recorded, and its size counts toward the per-span byte budget.
  • The new opentelemetry dependency is limited to the trace feature.

📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

  • The trace-state crate and its bridge match how the existing Rust crates in the repository are set up.
  • SpanLink::parseTracestate maps an empty result to kj::none, which matches the documented behaviour of the bridge function.
  • The per-span byte accounting, the 512-entry batch limit and the forwarding through the tracer are unchanged and correct.

⚡ Performance: ✅ LGTM

Link handling stays bounded by the 512-entry batch limit and the per-span byte budget.


📝 Documentation: ✅ LGTM

The generated type snapshots match the source definitions in types/defines/trace.d.ts.


Reviewed commit: 8f31aec4

@dom96 dom96 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for switching to parsing using a crate, much better. Accepting!

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 6d921b81.

This review, of 69c108f3

✅ Approved — No issues found. The only change since the last review is type declarations and comments in tracing.d.ts, and they match the runtime implementation.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Since the last review, only type declarations changed, so there is no new runtime surface.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

TracingSpanLinkContext and TracingSpanLink reference SpanAttributes and TracingSpanContext, both defined in the same file, and they match the JSG type definitions in src/workerd/api/tracing.h. The comments on addLink() and addLinks() describe what tracing.c++ does.


⚡ Performance: ✅ LGTM

Since the last review, only declarations and comments changed, so there is no runtime impact.


📝 Documentation: ✅ LGTM

The new declarations and comments in tracing.d.ts match the code.


Reviewed commit: 69c108f3

@wperron
wperron force-pushed the wperron/wo-1767-span-links branch from 69c108f to 6d921b8 Compare November 13, 2026 20:42

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of ab899d07.

This review, of 6d921b81

✅ Approved — No issues found. The only change since the last review is type declarations and comments in tracing.d.ts, and they match the runtime implementation.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

Since the last review, only type declarations changed, so there is no new runtime surface.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

TracingSpanLinkContext and TracingSpanLink reference SpanAttributes and TracingSpanContext, both defined in the same file, and they match the JSG type definitions in src/workerd/api/tracing.h. The comments on addLink() and addLinks() describe what tracing.c++ does.


⚡ Performance: ✅ LGTM

Since the last review, only declarations and comments changed, so there is no runtime impact.


📝 Documentation: ✅ LGTM

The new declarations and comments in tracing.d.ts match the code.


Reviewed commit: 6d921b81 — same changes as 69c108f3, so this is that commit's review (no new review was run; line numbers are as of 69c108f3)

@wperron
wperron force-pushed the wperron/wo-1767-span-links branch from 6d921b8 to ab899d0 Compare November 17, 2026 16:04

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 73469248.

This review, of ab899d07

✅ Approved — No issues found. The only changes since the last review are the Rust dependency and Bazel wiring for the opentelemetry-based tracestate parser, and they look correct.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

The new opentelemetry dependency is limited to the trace feature, and tracestate parsing happens in Rust. No security concerns.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

The dependency and Bazel wiring for the trace-state crate are consistent, and no correctness issues were found in the span links implementation.


⚡ Performance: ✅ LGTM

No runtime performance concerns. addLinks() rejects arrays longer than 512 entries before reading any elements.


📝 Documentation: ✅ LGTM

The type declarations and comments match the runtime behaviour.


Reviewed commit: ab899d07

@wperron
wperron force-pushed the wperron/wo-1767-span-links branch from ab899d0 to 7346924 Compare November 17, 2026 19:58

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 7c27d31e.

This review, of 73469248

✅ Approved — No issues found. The only changes since the last review are the Rust dependency and Bazel wiring for the opentelemetry-based tracestate parser, and they look correct.

Not opened by the correctness review: 4 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.d.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

The new opentelemetry dependency is limited to the trace feature, and tracestate parsing happens in Rust. No security concerns.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

The dependency and Bazel wiring for the trace-state crate are consistent, and no correctness issues were found in the span links implementation.


⚡ Performance: ✅ LGTM

No runtime performance concerns. addLinks() rejects arrays longer than 512 entries before reading any elements.


📝 Documentation: ✅ LGTM

The type declarations and comments match the runtime behaviour.


Reviewed commit: 73469248 — same changes as ab899d07, so this is that commit's review (no new review was run; line numbers are as of ab899d07)

Comment thread types/generated-snapshot/index.ts Resolved
@wperron
wperron force-pushed the wperron/wo-1767-span-links branch from 7346924 to 7c27d31 Compare November 17, 2026 21:09

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 2d6f0bee.

This review, of 7c27d31e

💬 Approved with comments — No correctness, security or performance issues. The only finding is an INFO about the wording of the addLinks() comment.

Findings: 1 info (1 is an inline comment on the diff)

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📝 Documentation: 💬 1 info

One comment on addLinks() is slightly imprecise.

Recommendation: 💬 Optional Nits

  • [INFO] The addLinks() comment says oversized arrays are ignored with a warning, but untraced spans return before the length check and log nothing. (src/cloudflare/internal/tracing.d.ts:87)
View full review
  • src/cloudflare/internal/tracing.d.ts:87: the warning for oversized arrays is only logged on traced spans.

✅ All other checks passed

🔒 Security: ✅ LGTM

No security concerns. Link input is bounded by element count and by the per-span byte budget.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

Context parsing, the zero-ID rule, the batch bound, the shared byte budget and the SpanLinks tail-event plumbing (capnp, clone, toString, JS serialization, observers, submitters, tracer) are consistent, and the tests cover them. Removing isRemote/traceState leaves no dangling references.


⚡ Performance: ✅ LGTM

No performance concerns. addLinks() rejects arrays longer than 512 entries before reading any elements.


Reviewed commit: 7c27d31e

Comment thread src/cloudflare/internal/tracing.d.ts Resolved
Expose addLink() and addLinks() behind the experimental span_links compatibility flag. Preserve receiver-owned attribution, sanitize scalar link attributes using the OpenTelemetry JS SDK model, and carry links through streaming tail.
Allow RPC-based tracing to report links with the caller's timestamp,\nmatching span updates and attributes.
Treat addLink() and addLinks() as additive Span API and explicitly
accept their availability for all compatibility dates. Remove the
experimental flag and emit the link types in stable declarations.

Keep recording and no-op coverage without opt-in. The flag-disabled
fixture is obsolete; no-op spans still avoid reading link payloads.
Reject addLinks arrays longer than 512 entries before reading elements.\nThis bounds sparse and invalid batches while allowing accepted calls to\nrecord more than 512 links on one span.\n\nExercise both oversized arrays and the accepted boundary, and include\nCloudflare tracing integration tests in the coverage workflow.
Replace the hand-written W3C tracestate parser with TraceState from the
opentelemetry Rust crate (0.33.1, trace feature only), reached through a
cxx bridge in the new src/workerd/io/trace-state crate. The crate's
normalized header is recorded, and values it rejects or that have no
list members are discarded without discarding the link. The 512-character
cap on the input string is removed; the span-data budget still bounds it.

0.33.1 is less strict than W3C Trace Context Level 2: it accepts empty
keys and values, duplicate keys, control and non-ASCII value characters,
and digit-led keys and vendors, and keeps the first 32 list members
instead of rejecting longer values. Stricter validation is expected from
a later crate release rather than a local wrapper.

Accept trace and span IDs in either case. hexToUint64() already parses
uppercase digits, and the recorded IDs are always lowercase.
The tracing API does not support OpenTelemetry's optional isRemote and
traceState SpanContext fields yet. A link's context is now a
TracingSpanContext: traceId, spanId and traceFlags. Any other properties
of the input context are ignored, so a zero-ID link is kept only when its
attributes carry the relationship.

Remove the fields from the native SpanLink, its Cap'n Proto struct and
the streaming-tail event and its types, along with the tracestate parser
that supported them: the trace-state Rust crate and the opentelemetry
dependency.
@wperron
wperron force-pushed the wperron/wo-1767-span-links branch from 7c27d31 to 2d6f0be Compare November 18, 2026 01:19

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 Approved with comments — No correctness, security or performance issues. The only finding is an INFO about the wording of the addLinks() comment.

Findings: 1 info

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📝 Documentation: 💬 1 info

One comment on addLinks() is slightly imprecise.

Recommendation: 💬 Optional Nits

  • [INFO] The addLinks() comment says oversized arrays are ignored with a warning, but untraced spans return before the length check and log nothing. (src/cloudflare/internal/tracing.d.ts:87)
View full review
  • src/cloudflare/internal/tracing.d.ts:87: the warning for oversized arrays is only logged on traced spans.

✅ All other checks passed

🔒 Security: ✅ LGTM

No security concerns. Link input is bounded by element count and by the per-span byte budget.


📖 AGENTS.md: ✅ LGTM

No AGENTS.md updates needed.


📋 Code Quality: ✅ LGTM

Context parsing, the zero-ID rule, the batch bound, the shared byte budget and the SpanLinks tail-event plumbing (capnp, clone, toString, JS serialization, observers, submitters, tracer) are consistent, and the tests cover them. Removing isRemote/traceState leaves no dangling references.


⚡ Performance: ✅ LGTM

No performance concerns. addLinks() rejects arrays longer than 512 entries before reading any elements.


Reviewed commit: 2d6f0bee — same changes as 7c27d31e, so this is that commit's review (no new review was run; line numbers are as of 7c27d31e)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants