---
title: "Streamed 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."
url: https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans/
---

# Streamed Spans | Sentry for React

By default, the Sentry JavaScript SDKs collect all spans in memory and send them to Sentry as a single transaction once the root span ends. This is called transaction mode. Stream mode changes this by sending spans to Sentry in batches as they finish. Service spans, which represent a service's entry point, replace transactions as the main grouping for each service.

Why use stream mode?

* **No 1,000-span limit.** In transaction mode, transactions are capped at 1,000 spans. Stream mode has no upper limit since spans are sent in batches.
* **Lower memory usage.** Spans are flushed periodically and don't need to be held in memory until the root span ends. This is especially useful for long-running processes like queue consumers or cron jobs.
* **Faster visibility.** Span data arrives in Sentry as your application runs, instead of only after the entire operation completes.
* **No data loss from crashes.** If your process terminates unexpectedly, spans that were already flushed are preserved. In transaction mode, a crash before the root span ends means all span data is lost.

You can find the following span types mentioned throughout this page:

* **Root span**: The topmost span in a trace. It has no parent span and is always a service span.
* **Service span**: A parent-level span at the entry of a service. In transaction mode, this is called a transaction.
* **Child span**: Any span nested under a parent span within the same trace.

This graph shows how these span types relate to each other within a trace:

```bash
Trace
│
└── Root span [service A]
     ├── Child span
     │    └── Child span
     └── Service span [service B]
          ├── Child span
          └── Child span
```

Span stream mode will be enabled by default in version `11.0.0` of the SDK. You can already opt into stream mode in version 10 by following the migration guide below.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#prerequisites)

You need:

* [Tracing configured](https://docs.sentry.io/platforms/javascript/guides/react/tracing.md#configure) in your app
* `@sentry/react `SDK version `>=10.66.0`

## [Migrate from Transaction Mode](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#migrate-from-transaction-mode)

For most users, switching to stream mode requires no code changes beyond the initial opt-in. If you use `beforeSendSpan` or `beforeSendTransaction`, follow these steps:

1. [Enable stream mode](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#enable-stream-mode)
2. [Wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` to filter spans](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#filter-spans)
3. [Replace `beforeSendTransaction` with `ignoreSpans` to drop spans](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#drop-spans)
4. [Migrate tags (`Sentry.setTag(s)`) to attributes (`Sentry.setAttribute(s)`)](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#shared-attributes)
5. [Verify the migration](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#verify-your-setup)

### [Agent-Assisted migration](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#agent-assisted-migration)

Copy the following prompt and paste it into your AI agent:

```txt
Use curl to download, read and follow https://raw.githubusercontent.com/getsentry/sentry-for-ai/refs/heads/main/skills-legacy/sentry-span-streaming-js/SKILL.md to enable and migrate to span streaming in the Sentry SDK.
```

## [Enable Stream Mode](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#enable-stream-mode)

Opt in by adding `spanStreamingIntegration()` to your list of integrations when initializing the SDK:

```javascript
import * as Sentry from "<sdk-package-name>";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  tracesSampleRate: 1.0,
  integrations: [
    Sentry.browserTracingIntegration(),
    // enables stream mode
    Sentry.spanStreamingIntegration(),
  ],
});
```

To revert to transaction mode, remove `spanStreamingIntegration()` from your integrations.

##### Mixing tracing modes in distributed tracing

Tracing modes are scoped per SDK, which means you can use, for example, stream mode in your frontend, and transaction mode in your backend, or vice versa.

How does span flushing work?

When stream mode is enabled, the SDK maintains an internal buffer that groups spans by trace ID.

Spans are flushed:

* On a regular interval (every 5 seconds by default).
* When a trace's buffer reaches 1,000 spans or the maximum size limit of a batch.
* When you call `Sentry.flush()` or `Sentry.close()`.

Each flush sends only the spans accumulated since the last flush, grouped into envelopes by trace ID.

## [Manual Instrumentation (Optional)](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#manual-instrumentation-optional)

### [Start a Span](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#start-a-span)

Use `Sentry.startSpan()` to create a span that is automatically ended when the callback completes:

```javascript
const result = await Sentry.startSpan(
  { name: "my-operation", attributes: { "my.attribute": "value" } },
  async () => {
    // Your code here
    return await doWork();
  },
);
```

Child spans created inside the callback are automatically associated with the parent:

```javascript
await Sentry.startSpan({ name: "parent-operation" }, async () => {
  await Sentry.startSpan({ name: "child-step-1" }, async () => {
    await stepOne();
  });

  await Sentry.startSpan({ name: "child-step-2" }, async () => {
    await stepTwo();
  });
});
```

For more details on span creation APIs, such as `startSpan`, `startSpanManual`, or `startInactiveSpan`, see [Instrumentation](https://docs.sentry.io/platforms/javascript/guides/react/tracing/instrumentation.md).

## [Add Attributes](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#add-attributes)

Attach structured metadata to spans using [`attributes`](https://docs.sentry.io/platforms/javascript/guides/react/configuration/apis.md#startSpan), which can be `string`, `number`, or `boolean`, as well as arrays of these types.

You can set attributes when starting a span:

```javascript
Sentry.startSpan(
  {
    name: "process-order",
    attributes: {
      "sentry.op": "queue.process",
      "order.id": "abc-123",
      "order.item_count": 5,
      "order.priority": true,
    },
  },
  () => {
    // Process the order
  },
);
```

Or add them to an already running span:

```javascript
Sentry.startSpan({ name: "handle-request" }, (span) => {
  // Set a single attribute
  span.setAttribute("http.response.status_code", 200);

  // Set multiple attributes at once
  span.setAttributes({
    "http.route": "/api/users",
    "user.id": "user-42",
  });
});
```

Find more examples in our [Sending Span Metrics](https://docs.sentry.io/platforms/javascript/guides/react/tracing/span-metrics.md) documentation.

### [Shared Attributes](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#shared-attributes)

Previously, transaction mode applied shared tags (`Sentry.setTag(s)`) to the service span (transaction). In Stream mode, tags are no longer applied to spans. Set shared attributes on a specific scope instead. You don't need to remove tags from your code, since they still apply to errors. Instead, add attributes for all data that's relevant for spans, logs metrics.

Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all spans (as well as your logs and metrics). These work just like [`Sentry.setTag` and `Sentry.setTags`](https://docs.sentry.io/platforms/javascript/guides/react/apis.md#setTag), but they accept `string`, `number`, and `boolean` values.

To attach attributes to a broader or narrower context, set them on a specific scope instead. Use the global scope for app-wide attributes and the current scope for a single operation.

See [Attributes](https://docs.sentry.io/platforms/javascript/guides/react/enriching-events/attributes.md) for more information.

```javascript
// Applied to all spans, logs and metrics
Sentry.setAttributes({
  org_id: user.orgId,
  user_tier: user.tier,
});
Sentry.setAttribute("service", "checkout");

// Global scope - shared across entire app
Sentry.getGlobalScope().setAttributes({
  service: "checkout",
  version: "2.1.0",
});

// Current scope - single operation
Sentry.withScope((scope) => {
  scope.setAttribute("request_id", req.id);
  Sentry.logger.info("Processing order");
});
```

## [Extended Configuration (Optional)](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#extended-configuration-optional)

### [Filter Spans](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#filter-spans)

To modify or redact span data before it's sent, use [`beforeSendSpan`](https://docs.sentry.io/platforms/javascript/guides/react/configuration/options.md#beforeSendSpan). In stream mode, wrap it with `Sentry.withStreamedSpan()` so the SDK applies it to spans as they are flushed rather than only at transaction time.

`beforeSendSpan` can only modify span data, and you cannot use it to drop spans. Use [`ignoreSpans`](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#drop-spans) instead.

The `span` object also has different property names in stream mode. For example, `span.op` becomes `span.attributes?.["sentry.op"]` and `span.description` becomes `span.name`. See the migration note below for the full list.

```javascript
Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  tracesSampleRate: 1.0,
  integrations: [
    // other integrations
    Sentry.spanStreamingIntegration(),
  ],
  beforeSendSpan: Sentry.withStreamedSpan((span) => {
    // In stream mode, 'op' is accessed via attributes
    if (span.attributes?.["sentry.op"] === "db.query") {
      // In stream mode, 'description' is now renamed to 'name'
      span.name = "[filtered]";
    }
    return span;
  }),
});
```

Migrating from transaction mode?

If you're using `beforeSendSpan`, wrap it with `Sentry.withStreamedSpan()` as shown above, otherwise the SDK falls back to transaction mode.

Note that the `span` object is `StreamedSpanJSON` instead of `SpanJSON` and has different property names:

| Transaction Mode (`SpanJSON`)      | Stream Mode (`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']`      |

If you're using `beforeSendTransaction` to drop spans, use [`ignoreSpans`](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#drop-spans) instead, since `beforeSendTransaction` is not available in stream mode.

### [Drop Spans](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#drop-spans)

In stream mode, `ignoreSpans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped.

To prevent specific spans from being created, use the [`ignoreSpans`](https://docs.sentry.io/platforms/javascript/guides/react/configuration/options.md#ignoreSpans) option:

```javascript
Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  tracesSampleRate: 1.0,
  integrations: [
    // other integrations
    Sentry.spanStreamingIntegration(),
  ],
  ignoreSpans: [
    // Drop spans whose name contains "healthcheck"
    "healthcheck",
    // Drop spans whose name matches a pattern
    /^GET \/api\/v1\/internal/,
    // Drop spans matching name and attribute conditions
    {
      name: /^GET \//,
      attributes: {
        "http.route": "/api/status",
      },
    },
  ],
});
```

If a matching span is a service span, all of its child spans are dropped as well. If a child span matches, only that span is dropped and its children are reparented to the nearest ancestor.

##### Migrating from transaction mode?

In transaction mode, `ignoreSpans` is evaluated at transaction end rather than at span start. Review your existing rules to make sure the attributes and names you're matching on are passed when the span is created.

If you're auto-instrumenting and don't know what the initial name of a span is when it starts, enable SDK debug logging during development by setting [`debug: true`](https://docs.sentry.io/platforms/javascript/guides/react/configuration/options.md#debug) when initializing the SDK.

## [Distributed Tracing (Optional)](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#distributed-tracing-optional)

Distributed tracing works out of the box when tracing is enabled and works the same way in stream mode. If you need to manually propagate trace context, for example, when the SDK can't instrument automatically, see [Custom Trace Propagation](https://docs.sentry.io/platforms/javascript/guides/react/tracing/distributed-tracing/custom-instrumentation.md).

## [Verify Your Setup](https://docs.sentry.io/platforms/javascript/guides/react/tracing/streamed-spans.md#verify-your-setup)

To make sure you've enabled stream mode successfully:

* **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look similar to transaction mode, but contain only spans and no transactions.
* **Check for fallback warnings in your logs**: If the SDK logs warnings about falling back to transaction mode, your `beforeSendSpan` callback is likely missing the `Sentry.withStreamedSpan()` wrapper.
* **Check the network tab in your browser's DevTools**: Span envelopes should appear as individual requests with content type `application/vnd.sentry.items.span.v2+json`