Skip to content

docs(javascript): Document span streaming as the default #19429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
msonnb wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

docs(javascript): Document span streaming as the default #19429

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 11 additions & 15 deletions docs/platforms/javascript/common/configuration/apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,13 +134,12 @@ Sentry.withScope((scope) => {
});
```

<Expandable title='What is the difference to `beforeSend`, `beforeSendTransaction`, and `beforeSendSpan`?'>
`beforeSend`, `beforeSendTransaction`, and `beforeSendSpan` are guaranteed to be run last, after all other event processors, (which means they get the final version of the event right before it's sent, hence the name). Event processors added with `addEventProcessor` are run in an undetermined order, which means changes to the event may still be made after the event processor runs.
<Expandable title='What is the difference to `beforeSend` and `beforeSendSpan`?'>
`beforeSend` runs after all event processors and receives the final error or message event before it is sent. Event processors added with `addEventProcessor` run in an undetermined order, so another processor may still change the event afterward.

There can only be a single `beforeSend` / `beforeSendTransaction` / `beforeSendSpan` callback, but you can add multiple event processors via `addEventProcessor()`.

If you're using <PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink>, use `beforeSendSpan`, since event processors are not applied to spans.
You can configure one `beforeSend` callback and add multiple event processors with `addEventProcessor()`.

Event processors do not run on streamed spans. Use `beforeSendSpan` to modify each finished span before it is sent. In static mode, event processors also run on transaction events, followed by `beforeSendTransaction`. You can configure one `beforeSendTransaction` callback.
</Expandable>
</SdkApi>

Expand Down Expand Up @@ -842,18 +841,15 @@ Sentry.reportPageLoaded();

These utilities can be used for more advanced tracing use cases.

<SdkApi name="spanToJSON" signature="function spanToJSON(span: Span): SpanJSON">
Convert a span to a JSON object. If you're using{" "}
<PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink>, we
recommend using [`spanToStreamedSpanJSON`](#spanToStreamedSpanJSON) instead.
<SdkApi name="spanToJSON" signature="function spanToJSON(span: Span): StreamedSpanJSON">
Convert a span to a JSON object. If you're using {" "}
<PlatformLink to="/configuration/options/#traceLifecycle">`traceLifecycle: 'static'`</PlatformLink>,
use [`spanToStaticSpanJSON`](#spanToStaticSpanJSON) to get the `SpanJSON` format.
</SdkApi>

<SdkApi
name="spanToStreamedSpanJSON"
signature="function spanToStreamedSpanJSON(span: Span): StreamedSpanJSON"
>
Convert a span to a JSON object. Only available in{" "}
<PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink>.
<SdkApi name="spanToStaticSpanJSON" signature="function spanToStaticSpanJSON(span: Span): SpanJSON">
Convert a span to the static `SpanJSON` format. Use this when working with transaction data in
static mode.
</SdkApi>

<SdkApi
Expand Down
74 changes: 31 additions & 43 deletions docs/platforms/javascript/common/configuration/filtering.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,53 +111,17 @@ This is the case because the Sentry Loader Script and CDN Bundles are detected a

</Alert>

## Filtering Transaction Events

<Alert>
The options in this section are only available in transaction mode. If you're
using <PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink>, go to
[Filtering Spans](#filtering-spans).
</Alert>

To prevent certain transactions from being reported to Sentry, use the <PlatformIdentifier name="traces-sampler" /> or <PlatformIdentifier name="before-send-transaction" /> configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want.

### Using <PlatformIdentifier name="ignore-transactions" />

You can use the <PlatformIdentifier name="ignore-transactions" /> option to filter out transactions that match a certain pattern. This option receives a list of strings and regular expressions to match against the transaction name. When using strings, partial matches will be filtered out. If you need to filter by exact match, use regex patterns instead.

<PlatformContent includePath="configuration/ignore-transactions" />

See <PlatformLink to="/configuration/options/#ignoreTransactions">ignoreTransactions</PlatformLink> for details.

### Using <PlatformIdentifier name="traces-sampler" />

You can also use the <PlatformLink to="/configuration/options/#tracesSampler">tracesSampler</PlatformLink> option to prevent certain transactions from being reported to Sentry.

See <PlatformLink to="/configuration/sampling/#setting-a-sampling-function">Sampling</PlatformLink> on information about how to use it.

### Using `beforeSendTransaction`

<PlatformContent includePath="configuration/before-send-transaction" />

See <PlatformLink to="/configuration/options/#beforeSendTransaction">beforeSendTransaction</PlatformLink> for details, and [Using Hints](#using-hints) for details on the `hint` object.

## Filtering Spans

### Using <PlatformIdentifier name="before-send-span" />

Use the <PlatformIdentifier name="before-send-span" /> configuration option, which lets you provide a function to modify a span.
This function is called for the transaction (service span in stream mode) and all child spans.
Use `beforeSendSpan` to change span data and `ignoreSpans` to drop spans. To make sampling decisions when spans start, use <PlatformLink to="/configuration/sampling/#setting-a-sampling-function">`tracesSampler`</PlatformLink>.

If you want to drop the transaction/service span, including its child spans:

- Use [`beforeSendTransaction`](#using-beforesendtransaction) in transaction mode.
- Use [`ignoreSpans`](#using-ignore-spans) in stream mode.
### Using <PlatformIdentifier name="before-send-span" />

<Alert>
Use the <PlatformIdentifier name="before-send-span" /> configuration option to modify each finished span before it is sent. This function is called for all spans, including service spans and their child spans.

If you're using <PlatformLink to="/tracing/streamed-spans" fallbackPlatform="javascript">stream mode</PlatformLink>, make sure to wrap <PlatformIdentifier name="before-send-span" /> with `Sentry.withStreamedSpan()`.
Check `span.is_segment` to modify only service spans. In static mode, wrap the callback with `Sentry.withStaticSpan()` to modify the transaction and its child spans using the `SpanJSON` format.

</Alert>
To drop a service span and its child spans, use [`ignoreSpans`](#using-ignore-spans). `beforeSendSpan` cannot return `null` to drop spans.

<PlatformContent includePath="configuration/before-send-span" />

Expand All @@ -169,12 +133,14 @@ You can use the <PlatformIdentifier name="ignore-spans" /> option to filter out

You can also provide an object with `name`, `op`, and `attributes` properties to match on multiple conditions. At least one property must be provided.

In stream mode, rules run when the span starts, so later name and attribute changes do not affect matching. In static mode, rules use the final name and attributes when the transaction ends. Ignoring a service span drops its child spans; ignoring a child span reparents its children to the nearest ancestor.

```javascript
Sentry.init({
dsn: "___PUBLIC_DSN___",
ignoreSpans: [
"partial/match",
/^Exact Span Name$/,
{ name: "partial/match", op: "http.server" },
{ name: /^Exact Span Name$/, op: "http.server" },
{
name: /^GET \//,
attributes: {
Expand All @@ -185,8 +151,30 @@ Sentry.init({
});
```

Use the operation of your service span, such as `http.server`, `pageload`, or `navigation`, to avoid matching unrelated child spans with the same name.

See <PlatformLink to="/configuration/options/#ignoreSpans">ignoreSpans</PlatformLink> for details.

## Filtering Transaction Events

These options apply when <PlatformLink to="/configuration/options/#traceLifecycle">`traceLifecycle: 'static'`</PlatformLink> is set. In the default stream mode, use [Filtering Spans](#filtering-spans).

### Using <PlatformIdentifier name="ignore-transactions" />

Use `ignoreTransactions` to drop transactions whose names match a string or regular expression. Strings match part of the name. Use an anchored regular expression for an exact match. Matching transactions and their child spans are dropped.

<PlatformContent includePath="configuration/ignore-transactions" />

See <PlatformLink to="/configuration/options/#ignoreTransactions">`ignoreTransactions`</PlatformLink> for details.

### Using `beforeSendTransaction`

Use `beforeSendTransaction` to modify or drop a completed transaction before it is sent. Return the transaction event to send it, or `null` to drop it and its child spans.

<PlatformContent includePath="configuration/before-send-transaction" />

See <PlatformLink to="/configuration/options/#beforeSendTransaction">`beforeSendTransaction`</PlatformLink> for details and [Using Hints](#using-hints) for the `hint` argument.

## Filtering Breadcrumbs

You can filter breadcrumbs by using the `beforeBreadcrumb` configuration option:
Expand Down
92 changes: 44 additions & 48 deletions docs/platforms/javascript/common/configuration/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -617,37 +617,15 @@ This is useful to prevent traces of unknown third-party services from being cont

</SdkOption>

<SdkOption name="beforeSendTransaction" type='(event: TransactionEvent, hint: EventHint) => TransactionEvent | null'>

This function is called with a transaction event object, and can return a modified transaction event object, or `null` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending.

Not available in stream mode. Instead, use [`ignoreSpans`](#ignoreSpans) to drop spans, or [`beforeSendSpan`](#beforeSendSpan) to modify spans.

</SdkOption>

<SdkOption name="beforeSendSpan" type='(span: SpanJSON) => SpanJSON'>

This function is called with a serialized span object and can return a modified span object. Use it, for example, to manually strip PII from spans or filter data from spans before they're sent to Sentry. It runs for all spans, including transactions and their child spans.

Note that `beforeSendSpan` can only modify span data, meaning you cannot use it to drop spans. Use [`ignoreSpans`](#ignoreSpans) to drop spans, or [`beforeSendTransaction`](#beforeSendTransaction) to drop transactions.

The `span` you receive as an argument is a serialized object, not a `Span` class instance.

If you're using stream mode, wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` — otherwise the SDK falls back to transaction mode.
<SdkOption name="beforeSendSpan" type='(span: StreamedSpanJSON) => StreamedSpanJSON'>

<Expandable level="warning" title="Span object property names in stream mode">
Called for each finished span before it is sent to Sentry, including service spans and their child spans. Return the modified span to rename it or remove sensitive data. Check `span.is_segment` to apply changes only to service spans.

In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and has different property names:
`beforeSendSpan` can only modify spans. It cannot drop them or return `null`. Use [`ignoreSpans`](#ignoreSpans) to drop spans.

| 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']` |
The callback receives a serialized `StreamedSpanJSON` object, not a `Span` instance. <PlatformLink to="/configuration/apis/#spanToJSON">`Sentry.spanToJSON()`</PlatformLink> returns the same shape.

</Expandable>
With [`traceLifecycle: 'static'`](#traceLifecycle), wrap the callback with `Sentry.withStaticSpan()` to receive and return `SpanJSON`. The static callback runs for the transaction and its child spans. A callback that doesn't match the trace lifecycle is ignored.

<Expandable title="Examples">

Expand All @@ -657,30 +635,32 @@ In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and

</SdkOption>

<SdkOption name="ignoreTransactions" type='Array<string | RegExp>' defaultValue='[]'>
<SdkOption name="beforeSendTransaction" type='(event: TransactionEvent, hint: EventHint) => TransactionEvent | null'>

Deprecated. This callback has no effect in stream mode. Use [`beforeSendSpan`](#beforeSendSpan) to modify spans and check `span.is_segment` to target service spans. Use [`ignoreSpans`](#ignoreSpans) to drop spans.

With [`traceLifecycle: 'static'`](#traceLifecycle), this callback receives a transaction event and an event hint after all event processors have run. Return the modified event to change its data, or `null` to drop the transaction and its child spans.

<Include name="platforms/configuration/options/ignore-transactions.mdx" />
<Expandable title="Example in static mode">

Not available in stream mode. Use [`ignoreSpans`](#ignoreSpans) instead.
<PlatformContent includePath="configuration/before-send-transaction" />

</Expandable>

</SdkOption>

<SdkOption name="ignoreSpans" type='Array<string | RegExp | {name?: string | RegExp, op?: string | RegExp, attributes?: Record<string, string | number | boolean | null | undefined>}>' defaultValue='[]' availableSince='10.2.0'>

A list of strings or regex patterns matching spans that shouldn't be sent to Sentry. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. You can also provide an object with `name`, `op`, and `attributes` properties to match on multiple conditions. At least one property must be provided.

If a matching span is a transaction or service span, the entire local trace will be dropped. If a child span matches, its children will be reparented to the dropped span's parent span.
If a matching span is a service span, its child spans are also dropped. If a child span matches, its children will be reparented to the dropped span's parent span.
By default, no spans are ignored.

In <PlatformLink to="/tracing/streamed-spans" fallbackPlatform="javascript">stream mode</PlatformLink>, `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.

<Alert level="warning" title="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 you're matching on are passed when the span is created.
In static mode, `ignoreSpans` is evaluated when the transaction ends, using the span's final name and attributes.

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 <PlatformLink to="/configuration/options/#debug">`debug: true`</PlatformLink> when initializing the SDK.

</Alert>
To inspect the initial names of automatically created spans, enable SDK debug logging during development with <PlatformLink to="/configuration/options/#debug">`debug: true`</PlatformLink>.

<Expandable title="Examples">

Expand Down Expand Up @@ -727,6 +707,20 @@ Sentry.init({
</Expandable>
</SdkOption>

<SdkOption name="ignoreTransactions" type='Array<string | RegExp>' defaultValue='[]'>

Deprecated. This option has no effect in stream mode. Use [`ignoreSpans`](#ignoreSpans) to filter spans by name, operation, or attributes.

With [`traceLifecycle: 'static'`](#traceLifecycle), this option filters transaction names against a list of strings and regular expressions. Strings match part of the name. Use a regular expression anchored with `^` and `$` for an exact match. A matching transaction and its child spans are dropped.

<Expandable title="Example in static mode">

<PlatformContent includePath="configuration/ignore-transactions" />

</Expandable>

</SdkOption>

<SdkOption name="propagateTraceparent" type='boolean' defaultValue='false' availableSince='10.10.0'>

If set to `true`, the SDK adds the [W3C `traceparent` header](https://www.w3.org/TR/trace-context/) to outgoing Http requests made via `fetch` or `XMLHttpRequest`.
Expand Down Expand Up @@ -756,22 +750,24 @@ Self-hosted Sentry users should set this option to `false`, as standalone `gen_a

</SdkOption>

<SdkOption name="traceLifecycle" type="'static' | 'stream'" defaultValue="'static'" availableSince='10.53.1'>
<SdkOption name="traceLifecycle" type="'static' | 'stream'" defaultValue="'stream'" availableSince='10.53.1'>

Controls how spans are sent to Sentry:

- In transaction mode (`'static'`, the default), all spans are collected in memory and sent to Sentry as a single transaction once the root span ends.
- In <PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink> (`'stream'`), spans are sent in batches as they finish.
- In <PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink> (`'stream'`, the default), spans are sent in batches as they finish.
- In transaction mode (`'static'`), spans are collected in memory and sent as a transaction once the root span ends. This mode is available for backwards compatibility.

<PlatformCategorySection supported={["browser"]}>
<Alert>

You don't need to use this option if you're using a browser-based SDK (for example, React or Vue) or a framework SDK that handles client-side rendering (for example Next.js or Remix).
Instead, <PlatformLink to="/tracing/streamed-spans" fallbackPlatform="javascript">enable stream mode</PlatformLink> by adding `spanStreamingIntegration` to your integrations when initializing the SDK.

</Alert>
To opt out of span streaming, set `traceLifecycle: 'static'`. If you use `beforeSendSpan`, wrap it with `Sentry.withStaticSpan()` to receive the `SpanJSON` format:

</PlatformCategorySection>
```javascript
Sentry.init({
traceLifecycle: "static",
beforeSendSpan: Sentry.withStaticSpan((span) => {
span.description = "[filtered]";
return span;
}),
});
```

</SdkOption>

Expand Down
6 changes: 3 additions & 3 deletions docs/platforms/javascript/common/data-management/sensitive-data/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,17 @@ If you _do not_ wish to use the default PII behavior, you can also choose to ide

### Scrubbing in `beforeSend*` SDK Hooks

SDKs provide various `beforeSend*` hooks, which are invoked before an errors, messages, spans, logs or metrics are sent and can be used to modify event data to remove sensitive information. The following hooks are available:
SDKs provide various `beforeSend*` hooks, which are invoked before errors, messages, spans, logs, or metrics are sent and can be used to modify event data to remove sensitive information. The following hooks are available:

- <PlatformLink to="/configuration/options/#beforeSend">`beforeSend`</PlatformLink> applies to error and message events
- <PlatformLink to="/configuration/options/#beforeSendSpan">`beforeSendSpan`</PlatformLink> applies to spans
- <PlatformLink to="/configuration/options/#beforeSendLog">`beforeSendLog`</PlatformLink> applies to logs
- <PlatformLink to="/configuration/options/#beforeSendMetric">`beforeSendMetric`</PlatformLink> applies to metrics
- <PlatformLink to="/configuration/options/#beforeSendTransaction">`beforeSendTransaction`</PlatformLink> applies to transactions (only in transaction mode)
- <PlatformLink to="/configuration/options/#beforeSendTransaction">`beforeSendTransaction`</PlatformLink> applies to transaction events in static mode

<Alert>

If you're using span <PlatformLink to="/tracing/streamed-spans/" fallbackPlatform="javascript">stream mode</PlatformLink>, `beforeSendTransaction` has no effect. Instead, use `beforeSendSpan` with the `withStreamedSpan` helper to modify streamed spans directly.
Use `beforeSendSpan` to remove sensitive data from spans, including service spans and child spans. In static mode, wrap the callback with `Sentry.withStaticSpan()` and use `beforeSendTransaction` to scrub transaction events.

</Alert>

Expand Down
Loading
Loading