Help us improve
Share bugs, ideas, or general feedback.
From sentry
Migrate JavaScript Sentry SDKs from transaction-based to span streaming (span-first trace lifecycle) for lower latency per-span delivery.
npx claudepluginhub getsentry/sentry-for-ai --plugin sentryHow this skill is triggered — by the user, by Claude, or both
Slash command
/sentry:sentry-span-streaming-jsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> [All Skills](../../SKILL_TREE.md) > [Feature Setup](../sentry-feature-setup/SKILL.md) > Span Streaming (JavaScript)
Migrates Python SDK from transaction-based to span-first trace lifecycle for Sentry span streaming. Use when asked to enable span streaming or switch to streamed span delivery.
Configures Sentry SDK v8+ for performance monitoring, distributed tracing, sampling, and profiling in Node.js/TypeScript and Python apps.
Creates p5.js generative art with seeded randomness, noise fields, and interactive parameter exploration. Use for algorithmic art, flow fields, or particle systems.
Share bugs, ideas, or general feedback.
All Skills > Feature Setup > Span Streaming (JavaScript)
Migrate from the default transaction-based trace lifecycle (static) to span streaming (stream), where spans are sent individually as they complete instead of being batched into a transaction at the end.
This skill covers the JavaScript SDK (Browser, Node.js, Bun, Deno, Cloudflare). For Python, see Span Streaming (Python).
traceLifecycle, spanStreamingIntegration, or withStreamedSpan# Detect if browser, server, or both
grep -rn "from '@sentry/browser'\|from '@sentry/react'\|from '@sentry/vue'\|from '@sentry/angular'\|from '@sentry/svelte'\|from '@sentry/nextjs'\|from '@sentry/nuxt'\|from '@sentry/sveltekit'\|from '@sentry/remix'\|from '@sentry/solidstart'\|from '@sentry/astro'\|from '@sentry/react-router'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null | head -20
grep -rn "from '@sentry/node'\|from '@sentry/bun'\|from '@sentry/deno'\|from '@sentry/cloudflare'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null | head -20
# Find Sentry.init calls
grep -rn "Sentry\.init\|init({" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null | head -20
# Find beforeSendSpan usage
grep -rn "beforeSendSpan" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null
# Find beforeSendTransaction usage
grep -rn "beforeSendTransaction" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null
# Find ignoreSpans usage
grep -rn "ignoreSpans" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" -l 2>/dev/null
Based on detection results, classify each Sentry.init call as:
| Environment | Packages | Migration Path |
|---|---|---|
| Browser | @sentry/browser, @sentry/react, @sentry/vue, @sentry/angular, @sentry/svelte | Add spanStreamingIntegration() |
| Server | @sentry/node, @sentry/bun, @sentry/deno, @sentry/cloudflare | Add traceLifecycle: 'stream' |
| Framework (both) | @sentry/nextjs, @sentry/nuxt, @sentry/sveltekit, @sentry/remix, @sentry/astro, @sentry/solidstart, @sentry/react-router | Migrate both client and server configs separately |
Prerequisites: Sentry JavaScript SDK >=10.53.1 with tracing enabled (tracesSampleRate or tracesSampler configured).
Apply changes to each Sentry.init call. Work through each file identified above.
Add traceLifecycle: 'stream' to Sentry.init():
// Before
Sentry.init({
dsn: '...',
tracesSampleRate: 1.0,
});
// After
Sentry.init({
dsn: '...',
tracesSampleRate: 1.0,
traceLifecycle: 'stream',
});
Add Sentry.spanStreamingIntegration() to the integrations array. The integration automatically enables traceLifecycle: 'stream' — you do not need to set it manually.
// Before
Sentry.init({
dsn: '...',
integrations: [
Sentry.browserTracingIntegration(),
],
tracesSampleRate: 1.0,
});
// After
Sentry.init({
dsn: '...',
integrations: [
Sentry.spanStreamingIntegration(),
Sentry.browserTracingIntegration(),
],
tracesSampleRate: 1.0,
});
The order of spanStreamingIntegration() relative to other integrations does not matter.
Apply the browser migration to client config files and the server migration to server config files. Common patterns:
| Framework | Client Config | Server Config |
|---|---|---|
| Next.js | sentry.client.config.ts | sentry.server.config.ts, sentry.edge.config.ts |
| Nuxt | Client-side Sentry.init in module | Server-side Sentry.init in module |
| SvelteKit | src/hooks.client.ts | src/hooks.server.ts |
| Remix | entry.client.tsx | entry.server.tsx |
| Astro | Client-side init | Server-side init |
beforeSendSpanIf the user has a beforeSendSpan callback, it must be wrapped with Sentry.withStreamedSpan() to work in streaming mode. Without this wrapper, the SDK falls back to static mode.
The callback shape also changes:
description is now namedata is now attributesStreamedSpanJSON instead of SpanJSON// Before (static mode)
Sentry.init({
beforeSendSpan: (span) => {
if (span.description?.includes('/health')) {
span.description = '[filtered]';
}
// 'data' contains span attributes
delete span.data?.['http.request.body'];
return span;
},
});
// After (streaming mode)
Sentry.init({
beforeSendSpan: Sentry.withStreamedSpan((span) => {
if (span.name?.includes('/health')) {
span.name = '[filtered]';
}
// 'attributes' replaces 'data'
if (span.attributes) {
delete span.attributes['http.request.body'];
}
return span;
}),
});
Key differences in the callback:
Static (SpanJSON) | Streaming (StreamedSpanJSON) |
|---|---|
span.description | span.name |
span.data (processed attributes) | span.attributes (raw attributes) |
span.timestamp (end time) | span.end_timestamp |
span.status (optional string) | span.status ('ok' or 'error') |
span.op | span.attributes['sentry.op'] |
Returning null from beforeSendSpan does not drop the span — it is ignored and a warning is logged.
beforeSendTransactionbeforeSendTransaction has no effect in streaming mode. Spans are sent individually, not batched into transactions.
// Before
Sentry.init({
beforeSendTransaction: (event) => {
// This entire callback is ignored in streaming mode
if (event.transaction === '/health') {
return null;
}
return event;
},
});
Migration paths depending on what beforeSendTransaction was used for:
| Use Case | Streaming Replacement |
|---|---|
| Drop spans by name/route | Use ignoreSpans option |
| Modify span data before send | Use beforeSendSpan with withStreamedSpan |
| Filter by transaction name | Use ignoreSpans with string/RegExp pattern |
| Add tags/context to transaction | Use beforeSendSpan with withStreamedSpan |
Remove the beforeSendTransaction option from Sentry.init() after migrating its logic.
ignoreSpans (Optional)ignoreSpans works in both static and streaming modes, but the filter is evaluated at different points in the span lifecycle:
In both modes, a match prevents the span from being recorded or sent. Because matching can run as early as span start (streaming), only the span name and attributes set when the span begins are guaranteed to be available — do not rely on attributes added later in the span's lifetime.
Sentry.init({
traceLifecycle: 'stream',
ignoreSpans: [
// String match against span name
'/health',
'/ready',
// RegExp match against span name
/^OPTIONS /,
// Object filter — all conditions must match
{
op: 'middleware.handle',
name: /^corsMiddleware/,
},
// Filter by attributes (string = substring match, RegExp for patterns)
{
op: 'http.server',
attributes: {
'http.route': /^\/internal\//,
},
},
],
});
Filter object properties:
| Property | Type | Matches Against |
|---|---|---|
name | string | RegExp | Span name (description) |
op | string | RegExp | Span operation |
attributes | Record<string, string | RegExp | number | boolean | Array> | Span attributes |
When multiple properties are specified in a filter object, all must match for the span to be ignored.
When using span streaming in the browser, use the v2 profiling options — not the legacy profilesSampleRate. The legacy option is deprecated and does not integrate with the span streaming lifecycle.
Add browserProfilingIntegration() and configure the two v2 options:
// Before (legacy profiling — do NOT use with span streaming)
Sentry.init({
integrations: [
Sentry.browserTracingIntegration(),
],
tracesSampleRate: 1.0,
profilesSampleRate: 0.5, // deprecated
});
// After (v2 profiling with span streaming)
Sentry.init({
integrations: [
Sentry.spanStreamingIntegration(),
Sentry.browserTracingIntegration(),
Sentry.browserProfilingIntegration(),
],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace',
});
v2 profiling options:
| Option | Type | Description |
|---|---|---|
profileSessionSampleRate | number (0–1) | Percentage of user sessions that have profiling enabled. Default: 0 (disabled). |
profileLifecycle | 'trace' | 'manual' | 'trace': profiler runs automatically while sampled root spans exist. 'manual': start/stop profiler explicitly via Sentry.uiProfiler.startProfiler() / stopProfiler(). Default: 'manual'. |
profileLifecycle: 'trace' requires tracing to be enabled (tracesSampleRate or tracesSampler). The profiler starts when a root span begins and stops when no sampled root spans remain. Profile chunks are sent independently every 60 seconds or when the last root span ends.
Do not mix legacy and v2 options. If profilesSampleRate is set, profileSessionSampleRate has no effect and the SDK logs a warning.
After applying changes, verify the migration works correctly.
# TypeScript check
npx tsc --noEmit 2>&1 | head -30
# Build
npm run build 2>&1 | tail -20
Instruct the user to verify in their browser devtools or server logs:
application/vnd.sentry.items.span.v2+json rather than transaction envelopesbeforeSendSpan callback is likely missing the withStreamedSpan wrapper| Symptom | Cause | Fix |
|---|---|---|
| SDK falls back to static mode | beforeSendSpan not wrapped with withStreamedSpan | Wrap callback: Sentry.withStreamedSpan(callback) |
beforeSendTransaction not called | Expected in streaming mode | Migrate logic to beforeSendSpan or ignoreSpans |
| Spans still arrive as transactions | traceLifecycle not set or integration missing | Server: add traceLifecycle: 'stream'; Browser: add spanStreamingIntegration() |
Type errors on span.description | StreamedSpanJSON uses name not description | Change span.description to span.name in callback |
Type errors on span.data | StreamedSpanJSON uses attributes not data | Change span.data to span.attributes in callback |
profileSessionSampleRate has no effect | Legacy profilesSampleRate is also set | Remove profilesSampleRate and use only profileSessionSampleRate + profileLifecycle |
import * as Sentry from '@sentry/node';
Sentry.init({
dsn: '__DSN__',
tracesSampleRate: 1.0,
traceLifecycle: 'stream',
});
import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: '__DSN__',
integrations: [
Sentry.spanStreamingIntegration(),
Sentry.browserTracingIntegration(),
],
tracesSampleRate: 1.0,
});
import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: '__DSN__',
integrations: [
Sentry.spanStreamingIntegration(),
Sentry.browserTracingIntegration(),
Sentry.browserProfilingIntegration(),
],
tracesSampleRate: 1.0,
profileSessionSampleRate: 1.0,
profileLifecycle: 'trace',
});
>=10.53.1traceLifecycle: 'stream'spanStreamingIntegration()beforeSendSpan callbacks wrapped with Sentry.withStreamedSpan()beforeSendSpan callbacks updated: description -> name, data -> attributesbeforeSendTransaction logic migrated to beforeSendSpan or ignoreSpansbeforeSendTransaction removed from configprofilesSampleRate with profileSessionSampleRate + profileLifecyclebrowserProfilingIntegration() to integrations