feat(cloudflare): propagate tracing context through Queue messages

[arthurfiorette]

Adds opt-in distributed tracing across Cloudflare Queue producers and consumers.

When enableQueueTracePropagation is enabled on both sides:

• Record-like message bodies carry sentry-trace and baggage under __sentry_queue_meta__.
• Arrays, binary payloads, and non-object payloads remain unchanged.
• Consumers remove the transport metadata before invoking the application handler.
• queue.process remains a root batch span and links to every producer represented in the batch.

Span links are used instead of continuing a producer trace because a Queue batch can contain messages from unrelated traces. Selecting one producer as the parent would create false causal relationships for the other messages.

The option is disabled by default because Cloudflare Queues does not expose a message-header API. Producers must modify record-like message bodies, so consumers without matching instrumentation may observe the additional metadata field.

Closes #22298

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

There are 4 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0bd582c. Configure here.}

[github-actions]

👋 @isaacs, @mydea, @andreiborza — Please review this PR when you get a chance!

[isaacs]

One nit, one minor improvement, and one potentially substantial design choice. Looks good overall, though, and does indeed fix the bug!

Also, since this is a user-facing change (albeit small), we probably want to add a CHANGELOG.md entry like:

- feat(cloudflare): Add `enableQueueTracePropagation` to link Queue producer and consumer traces ([#22303](https://github.com/getsentry/sentry-javascript/pull/22303))

[isaacs]

This feels like it might be a weird fit. A previous_trace value here indicates that the link is part of a sequential chain of traces, for example a series of browser interactions that a user might perform. In the UI, it's going to be presented with that kind of sequential semantics.

However, this is more of a "fan out" relationship, not previous/next relationship, so I don't think previous_trace makes the most sense here. It might be better to just leave the type off, and let it be a plain old link.

@andreiborza @mydea Do you think I'm misreading this? What is your opinion on the semantics here?

[isaacs]

This should use the same const as the rest of the file. Also, delete can throw in strict mode if the object is frozen, so best to try/catch it.

Suggested change

	delete body.__sentry_queue_trace__;
	try {
	delete body[SENTRY_QUEUE_TRACE_KEY];
	} catch {
	// best effort
	}

[isaacs]

So, when trace propagation is enabled, we're calling getBodySize twice, and discarding the original value. It's not a huge cost, but it does incur a JSON.stringify, which can be excessive on large messages.

Consider something like this:

Suggested change

	return startPublishSpan({ bindingName, bodySize: getBodySize(message) }, span => {
	// Read trace data here so the carrier points to queue.publish, not its parent span.
	const tracedMessage = enableTracePropagation
	? addQueueTraceContext(message, getTraceData()['sentry-trace'])
	: message;
	if (enableTracePropagation) {
	span.setAttribute('messaging.message.body.size', getBodySize(tracedMessage));
	}
	return startPublishSpan({ bindingName, bodySize: undefined }, span => {
	// Read trace data here so the carrier points to queue.publish, not its parent span.
	const tracedMessage = enableTracePropagation
	? addQueueTraceContext(message, getTraceData()['sentry-trace'])
	: message;
	span.setAttribute('messaging.message.body.size', getBodySize(tracedMessage));

[isaacs]

Nice. Excludes all "fancy" objects. 👍