docs(js): Add New Spans guide by inventarSarah · Pull Request #17834 · getsentry/sentry-docs

inventarSarah · 2026-05-21T12:23:07Z

DESCRIBE YOUR PR

Adds a new page documenting stream mode for all JS SDKs, covering:

How to enable stream mode
Migration path from transaction mode
Manual instrumentation (start a span, add attributes)
Distributed tracing
Extended configuration (beforeSendSpan, ignoreSpans)
Verify setup

Based on this draft: #17621
Michi's draft includes sections on distributed tracing, which I removed in this version. The APIs work identically in both modes; the topics are advanced enough that users are better served by the existing page, where all the details live, and users who already have distributed tracing set up don't need to change anything when switching to stream mode. Happy to discuss if you disagree.

Questions/Considerations for you

Filter Spans and Drop Spans currently use a single snippet per environment (browser/server) rather than framework-specific snippet file -> is that sufficient or should we create framework-specific snippet files, instead?
Does the reasoning for removing the Distributed Tracing sections make sense to you? (see explanation above)
please leave a comment when the guide uses a wrong (or not the ideal) span name (eg root span vs service span, service span vs child span, ...)

Closes: #17835

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

Urgent deadline (GA date, etc.):
Other deadline: end of May
None: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

EXTRA RESOURCES

Sentry Docs contributor guide

…ick-start/splitlayout-cleanup

…an-first/js

… smi/span-first/js

…an-first/js

vercel · 2026-05-21T12:23:13Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	May 22, 2026 1:17pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	May 22, 2026 1:17pm

…an-first/js

…into smi/span-first/js

…an-first/js

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

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

Lms24 · 2026-05-22T10:19:48Z

we mix "service span" and "root span" in this doc. A couple of thoughts:

I really like the "service span" name (as opposed to "segment span" how we call it in SDK code). I've probably been quite out of the loop here: Is this the public name we ended up choosing for it? Just want to confirm.

It's probably fine to use "root span" when we talk about how things used to be with transactions but further below, we explain the ignoreSpans behaviour differences for child vs. root spans. Should we adjust to "child vs. service spans" there?

"service span" is a naming recommendation provided by Shannon -- I've collected the full list here

I would really like to get use all the different span correctly -- it would be great if you (reviewers) leave a comment when the guide uses the wrong (or not best fitting) name

I think it could be useful to add two parts to the index to help:

Definitions (root span, service span, child span)

A chart like you had in our notes doc, Sarah, to show where each span would live in a trace

Let me know if this is true, though @Lms24 -

Root span - the topmost span connected to a trace ID

Child spans - any span nested under a parent, connected to the same trace ID

Service span - a parent-level span at the top of a service, nested under the same trace ID as the root span

Lms24 · 2026-05-22T10:24:59Z

+
+<PlatformSection notSupported={["javascript.nextjs", "javascript.nuxt", "javascript.sveltekit", "javascript.astro", "javascript.solidstart", "javascript.capacitor", "javascript.tanstackstart-react", "javascript.remix", "javascript.react-router"]}>
+
+- **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look the same as in transaction mode, but without transactions.


Traces look the same as in transaction mode, but without transactions

This is true but unless I missed something, there are very few visual indications that actually point out that a span is a (new) span and not a transaction 😬 The only thing that comes to mind is that it's not showing a JSON button anymore. I don't think there's harm in leaving in this sentence but users might get confused at what they should be looking in the product.

This is of course not a primary docs issue but rather a product/UI issue. We might want to think about some kind of indicator (and, separate topic, please bring back JSON for streamed spans lol). That is assuming, I didn't miss any obvious indication 😅 Will ask product folks about this.

In that case, I will update this to something like
"Traces look almost the same as in transaction mode. The main difference is that they have no transactions and only consist of spans."

In the new experience, what do we call those attributes that we currently call transaction?

…an-first/js

sentry · 2026-05-22T13:07:22Z

+);
+
+const MainLive = HttpLive.pipe(Layer.provide(SentryLive));
+MainLive.pipe(Layer.launch, NodeRuntime.runMain);


Bug: The Effect server-side code snippet calls NodeRuntime.runMain but is missing the required import for NodeRuntime, which will cause a runtime ReferenceError.
_{Severity: CRITICAL}

Suggested Fix

Add the import statement import { NodeRuntime } from "@effect/platform-node"; to the server-side code snippet in platform-includes/performance/enable-stream-mode/javascript.effect.mdx.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: platform-includes/performance/enable-stream-mode/javascript.effect.mdx#L54 Potential issue: The server-side initialization code snippet in the documentation file `platform-includes/performance/enable-stream-mode/javascript.effect.mdx` uses `NodeRuntime.runMain` to launch the application. However, it fails to import `NodeRuntime` from `@effect/platform-node`. Users who copy and paste this code will encounter a `ReferenceError: NodeRuntime is not defined` when they try to run their server, causing the application to crash immediately on startup.

sfanahata · 2026-05-26T18:12:18Z

@@ -0,0 +1,370 @@
+---
+title: New Spans
+description: "Learn how to use stream mode to send spans to Sentry as they finish, removing the 1,000-span limit and making trace data visible sooner."


@cleptric - should we be calling out the 1k span limit as a benefit? Seems really valuable, but want to make sure we're not locking ourselves into something unnecessarily.

sfanahata · 2026-05-26T18:13:00Z

+  - javascript.cordova
+---
+
+<AvailableSince version="10.53.1" />


This is SDK version? Would be good to clarify.

sfanahata · 2026-05-26T18:35:05Z

+
+## Extended Configuration (Optional)
+
+### Filter Spans


I think this may be the right place for it, but somewhere on this page I believe we should mention with a slight bit more detail in the description that you also need to modify span.op to span.attributes?.["sentry.op"] and that description becomes name in this new paradigm.

sfanahata · 2026-05-26T18:38:24Z

+
+</Alert>
+
+### Drop Spans


@Lms24 - just wanting to verify that this behavior is true:

In transaction mode, ignoreSpans is evaluated at transaction end (so all attributes accumulated during the span's lifetime are available). In stream mode, it's evaluated at span start (so only initial attributes are considered).

If so, @inventarSarah, it may be useful to add that detail or heads up here.

cleptric and others added 12 commits May 5, 2026 16:20

docs(js): add Node stream spans guide

fac1de3

Merge branch 'master' into span-first-js

d67f9cd

Add srubbing and filtering

4461c9c

clean up platform include files created for split layout update

29765bb

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/qu…

497dc78

…ick-start/splitlayout-cleanup

finalize split layout include file cleanup

c84d25e

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/qu…

93fed8f

…ick-start/splitlayout-cleanup

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/sp…

6f89d79

…an-first/js

Merge branch 'span-first-js' of github.com:getsentry/sentry-docs into…

2d06907

… smi/span-first/js

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/sp…

f0e25a6

…an-first/js

create New Spans guide for JS SDKs

9b703d3

update sdk snippets

4865de9

inventarSarah requested review from Lms24, chargome, cleptric, mydea and sfanahata May 21, 2026 12:23

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/sp…

31c975c

…an-first/js

vercel Bot deployed to Preview – develop-docs May 21, 2026 12:31 View deployment

vercel Bot deployed to Preview – sentry-docs May 21, 2026 12:35 View deployment

inventarSarah marked this pull request as ready for review May 21, 2026 12:37

sentry Bot reviewed May 21, 2026

View reviewed changes

Comment thread platform-includes/performance/enable-stream-mode/javascript.tanstackstart-react.mdx Outdated

inventarSarah added 3 commits May 21, 2026 16:20

update missing info and fix some snippets

2f89f55

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/sp…

04a40f8

…an-first/js

Merge branch 'master' into smi/span-first/js

1688a5a

sentry Bot reviewed May 21, 2026

View reviewed changes

Comment thread platform-includes/performance/enable-stream-mode/javascript.remix.mdx Outdated

inventarSarah added 3 commits May 21, 2026 16:26

fix remix snippet

653aa8f

Merge branch 'smi/span-first/js' of github.com:getsentry/sentry-docs …

e3d3699

…into smi/span-first/js

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/sp…

034a6cb

…an-first/js

describe service spans

0b511d5

vercel Bot deployed to Preview – sentry-docs May 22, 2026 09:46 View deployment

add effect and elysia

b8d6819

sentry-warden Bot reviewed May 22, 2026

View reviewed changes

Comment thread platform-includes/performance/enable-stream-mode/javascript.effect.mdx

cursor Bot reviewed May 22, 2026

View reviewed changes

Comment thread platform-includes/performance/enable-stream-mode/javascript.effect.mdx Outdated

vercel Bot deployed to Preview – sentry-docs May 22, 2026 11:06 View deployment

Lms24 reviewed May 22, 2026

View reviewed changes

inventarSarah added 2 commits May 22, 2026 14:21

Merge branch 'master' of github.com:getsentry/sentry-docs into smi/sp…

0120dc6

…an-first/js

minor fixes

bd5bdf0

vercel Bot deployed to Preview – sentry-docs May 22, 2026 12:34 View deployment

update span names in Drop Spans section

95337d2

sentry Bot reviewed May 22, 2026

View reviewed changes

vercel Bot deployed to Preview – sentry-docs May 22, 2026 13:17 View deployment

This was referenced May 26, 2026

js(docs): Update Tracing pages for stream mode #17862

Open

docs(js): Update Extended Configuration pages for stream mode #17879

Draft

sfanahata reviewed May 26, 2026

View reviewed changes


		<PlatformSection notSupported={["javascript.nextjs", "javascript.nuxt", "javascript.sveltekit", "javascript.astro", "javascript.solidstart", "javascript.capacitor", "javascript.tanstackstart-react", "javascript.remix", "javascript.react-router"]}>

		- Check the Sentry dashboard: Spans should appear in the Traces view shortly after they complete. Traces look the same as in transaction mode, but without transactions.


		</Alert>

		### Drop Spans

Uh oh!

Conversation

inventarSarah commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

EXTRA RESOURCES

Uh oh!

vercel Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sentry Bot May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfanahata May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfanahata May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

inventarSarah commented May 21, 2026 •

edited

Loading

vercel Bot commented May 21, 2026 •

edited

Loading

sfanahata May 26, 2026 •

edited

Loading

sfanahata May 26, 2026 •

edited

Loading