From 32477c512c4bf8e5869e51792aaeb33c447999a5 Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Tue, 22 Sep 2026 14:57:21 +0200 Subject: [PATCH 01/48] docs(javascript): Align tracing attributes and behavior with v11 (#19456) Update JavaScript tracing docs and examples to use v11 span attributes, including HTTP, database, Gen AI, and the root-span source constant. Explain low-cardinality span names as the default behavior. Clarify that `useOperationNameForRootSpan` controls `sentry.graphql.operation` on the enclosing root span in both modes, but only renames it in static mode. The GraphQL span's own operation attributes are recorded regardless of the option. Fixes https://linear.app/getsentry/issue/SDK-1475 ## IS YOUR CHANGE URGENT? - [x] No deadline: Not urgent, can wait up to 1 week+ --- .../common/configuration/integrations/graphql.mdx | 10 +++++----- .../common/configuration/integrations/supabase.mdx | 2 +- .../javascript/common/migration/v10-to-v11/index.mdx | 2 +- .../common/tracing/instrumentation/index.mdx | 7 ++----- .../common/tracing/instrumentation/requests-module.mdx | 2 +- .../javascript-v11/span-attribute-changes.mdx | 2 +- .../performance/add-spans-example/javascript.mdx | 4 ++-- .../javascript.mdx | 6 +++--- 8 files changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/graphql.mdx b/docs/platforms/javascript/common/configuration/integrations/graphql.mdx index 61dd3b73cc9fc..3a4a61a2b0e83 100644 --- a/docs/platforms/javascript/common/configuration/integrations/graphql.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/graphql.mdx @@ -69,10 +69,10 @@ When a resolver function is not defined on the schema for a field, GraphQL will _Type: `boolean`_ -By default, this option is `true`. +By default, this option is `true`. When enabled, it records GraphQL operations on the enclosing root span in the `sentry.graphql.operation` attribute. Its effect on the root span name depends on the tracing mode: -With this setting enabled, the GraphQL instrumentation dynamically updates the name of the `http.server` root span by appending -the operation names. Instead of generic span names like `POST /graphql`, span names will be more descriptive, such as `POST /graphql (query MyQuery)`. -For requests containing multiple operations, the span names will aggregate operation names, for example `POST /graphql (query Query1, query Query2)` +- In streaming mode, the root span name stays unchanged. Set the option to `false` to skip adding `sentry.graphql.operation` to the root span. -Set the option to `false` to preserve the default `http.server` span name without this additional context. +- In static mode, with `traceLifecycle: "static"`, enabling this option also appends operation names to the `http.server` root span name. For example, `POST /graphql` becomes `POST /graphql (query MyQuery)`. Requests containing multiple operations include each operation name, such as `POST /graphql (query Query1, query Query2)`. Set the option to `false` to skip the root span attribute and preserve the original root span name. + +In both modes, the GraphQL span records `graphql.operation.name` and `graphql.operation.type` when available, regardless of this option. diff --git a/docs/platforms/javascript/common/configuration/integrations/supabase.mdx b/docs/platforms/javascript/common/configuration/integrations/supabase.mdx index 944fbfd3f595e..eb831a3382703 100644 --- a/docs/platforms/javascript/common/configuration/integrations/supabase.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/supabase.mdx @@ -92,7 +92,7 @@ These spans are used to populate Sentry's [pre-built Query Dashboards](/product/ - `db.schema`: The database schema - `db.url`: The Supabase instance URL - `db.sdk`: Client information -- `db.system`: Set to 'postgresql' +- `db.system.name`: Set to 'postgresql' - `db.query`: The query parameters - `db.body`: The request body (for mutations) diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index 83aa7dbabd85a..aec09d59042a9 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -597,7 +597,7 @@ The Anthropic integration no longer sets `gen_ai.prompt`. The legacy Completions - The TanStack Router integration reports path parameters as `url.path.parameter.` instead of `url.path.params.`. - The Cloudflare-specific `sentry.cloudflare_tracer` attribute is no longer set. - Import attribute constants from `@sentry/core` directly. The `semanticAttributes` re-export was removed. -- `SEMANTIC_ATTRIBUTE_SENTRY_SOURCE` (`sentry.source`) was replaced by `SENTRY_SEGMENT_NAME_SOURCE` (`sentry.segment.name.source`), which is only set on the root span. +- `sentry.source` (`SEMANTIC_ATTRIBUTE_SENTRY_SOURCE`) was replaced by `sentry.segment.name.source`, which is only set on the root span. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index 3bb8112b3e6ed..b3dd3186db461 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -256,12 +256,9 @@ if (span) { } ``` -Prior to v8.39.0, you had to use `span.updateName('New Name')`, which had some limitations in `@sentry/node` and SDKs depending on it (for example, `@sentry/nextjs`): +Automatically instrumented spans use attributes such as `http.request.method` and `db.system.name` to derive their names. These names are low-cardinality. Raw URL paths, full query statements, and other request-specific details stay in attributes instead of the span name. -- Spans with `http.method` or `http.request.method` attributes would automatically have their name set to the method + the URL path. -- Spans with `db.system` attributes would automatically have their name set to the system + the statement. - -Using `Sentry.updateSpanName()` ensures that the name is updated correctly and no longer overwritten in these cases. +Use `Sentry.updateSpanName()` to override the automatically generated name. Choose a name that groups similar operations, and store request-specific details in span attributes. If you use `@sentry/browser`, `@sentry/react`, and so on in browser environments, `span.updateName()` and `Sentry.updateSpanName()` will function identically, so you can use either one of them. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx b/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx index 4701c5aaf7a77..1edce4069f9df 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx @@ -36,7 +36,7 @@ async function makeRequest(method, url) { span.setAttribute("http.response.status_code", response.status); span.setAttribute( - "http.response_content_length", + "http.response.body.size", Number(response.headers.get("content-length")) ); diff --git a/includes/migration/javascript-v11/span-attribute-changes.mdx b/includes/migration/javascript-v11/span-attribute-changes.mdx index 4c070d672cb27..cdc9c2c2060b6 100644 --- a/includes/migration/javascript-v11/span-attribute-changes.mdx +++ b/includes/migration/javascript-v11/span-attribute-changes.mdx @@ -98,6 +98,6 @@ The Anthropic integration no longer sets `gen_ai.prompt`. The legacy Completions - The TanStack Router integration reports path parameters as `url.path.parameter.` instead of `url.path.params.`. - The Cloudflare-specific `sentry.cloudflare_tracer` attribute is no longer set. - Import attribute constants from `@sentry/core` directly. The `semanticAttributes` re-export was removed. -- `SEMANTIC_ATTRIBUTE_SENTRY_SOURCE` (`sentry.source`) was replaced by `SENTRY_SEGMENT_NAME_SOURCE` (`sentry.segment.name.source`), which is only set on the root span. +- `sentry.source` (`SEMANTIC_ATTRIBUTE_SENTRY_SOURCE`) was replaced by `sentry.segment.name.source`, which is only set on the root span. diff --git a/platform-includes/performance/add-spans-example/javascript.mdx b/platform-includes/performance/add-spans-example/javascript.mdx index 4092a0bf335c7..800967ac2397f 100644 --- a/platform-includes/performance/add-spans-example/javascript.mdx +++ b/platform-includes/performance/add-spans-example/javascript.mdx @@ -45,7 +45,7 @@ function processItem(item) { http.get(`/items/${item.id}`, (response) => { response.on("data", () => {}); response.on("end", () => { - span.setTag("http.status_code", response.statusCode); + span.setAttribute("http.response.status_code", response.statusCode); span.setAttribute( "http.foobarsessionid", getFoobarSessionid(response) @@ -72,7 +72,7 @@ function processItem(item) { const response = await fetch("/items/${item.id}"); const json = await response.json(); - span.setTag("http.status_code", response.statusCode); + span.setAttribute("http.response.status_code", response.status); span.setAttribute("http.foobarsessionid", getFoobarSessionid(response)); } ); diff --git a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx index f1238fabd3b94..99ad8cd43b12e 100644 --- a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx +++ b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx @@ -19,7 +19,7 @@ const client = Sentry.init({ let pageLoadSpan = Sentry.startBrowserTracingPageLoadSpan(client, { name: window.location.pathname, attributes: { - [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "url", + "sentry.segment.name.source": "url", }, }); @@ -29,14 +29,14 @@ myRouter.on("routeChange", (route) => { // After that, each route change should trigger a navigation span (which will automatically finish the previous one) if (pageLoadSpan) { pageLoadSpan.updateName(route.name); - pageLoadSpan.setAttribute(Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, "route"); + pageLoadSpan.setAttribute("sentry.segment.name.source", "route"); pageLoadSpan = undefined; } else { Sentry.startBrowserTracingNavigationSpan(client, { op: "navigation", name: route.name, // or what the name of the span should be attributes: { - [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "route", + "sentry.segment.name.source": "route", }, }); } From 428e2be2febcaf7249c36c5efaafe1bcc40c203c Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Tue, 22 Sep 2026 15:00:11 +0200 Subject: [PATCH 02/48] docs(ember): Document explicit addon setup and tracing (#19472) The Ember setup guide now initializes Sentry in `app/app.ts` and enables tracing through an instance initializer. It also calls `loadInitializers()` so Ember loads that initializer. The options page documents performance settings on `instrumentAppInstancePerformance()`, including component and runloop thresholds, instead of the old addon config. Verified against the v10-to-v11 migration guide and Ember SDK implementation. Fixes [SDK-1484](https://linear.app/getsentry/issue/SDK-1484/rewrite-ember-setup-for-the-v2-embroider-addon-in-docs). ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ --- .../ember/configuration/ember-options.mdx | 89 +++++++------------ .../javascript/guides/ember/index.mdx | 38 +++++++- 2 files changed, 66 insertions(+), 61 deletions(-) diff --git a/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx b/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx index 75210f3a27173..593a3f32f7578 100644 --- a/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx +++ b/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx @@ -1,90 +1,61 @@ --- title: Ember Options -description: "Additional configuration options for the Ember addon." +description: "Configure tracing for Ember routes, classic components, and the runloop." sidebar_order: 1 --- -All Sentry SDK options can be passed to `init`: +Pass Sentry SDK options, such as `dsn` and `tracesSampleRate`, to `Sentry.init()` in `app/app.ts`. See Set Up Sentry for the complete setup and Basic Options for SDK configuration. +Pass Ember performance options to `instrumentAppInstancePerformance()` as shown below. -```javascript -import * as Sentry from "@sentry/ember"; +## Tracing Considerations -Sentry.init({ - // Sentry options - dsn: "___PUBLIC_DSN___", -}); -``` - -The `@sentry/ember` add-on includes options to manage Ember specific instrumentation; these options are set on the add-on config directly. - -```javascript -ENV["@sentry/ember"] = { - // Ember specific options -}; -``` +To capture page loads, navigation, classic component renders, and runloop timings, call `instrumentAppInstancePerformance()` from an instance initializer. Set `tracesSampleRate` or `tracesSampler` in `Sentry.init()` to enable tracing. -The following documentation is for Ember specific configuration, for Sentry options, [see basic options](/platforms/javascript/guides/ember/configuration/options) +```typescript {filename:app/instance-initializers/sentry-performance.ts} +import type ApplicationInstance from "@ember/application/instance"; +import { instrumentAppInstancePerformance } from "@sentry/ember"; -### Tracing Considerations - -The Sentry tracing integration is already set up via the Ember add on with custom Ember instrumentation for routing, components, and the runloop. It sideloads Sentry tracing as a chunk to instrument your application. If you'd like to disable this automatic instrumentation and stop receiving the associated transactions, set `disablePerformance` in your config. See example below: +export function initialize(appInstance: ApplicationInstance): void { + instrumentAppInstancePerformance(appInstance, { + // These are the defaults. Adjust them for your application. + disableInstrumentComponents: false, + minimumComponentRenderDuration: 2, + disableRunloopPerformance: false, + minimumRunloopQueueDuration: 5, + }); +} -```javascript -ENV["@sentry/ember"] = { - disablePerformance: true, -}; +export default { initialize }; ``` -### Routes +The SDK skips this instrumentation during FastBoot server rendering. To disable automatic Ember performance instrumentation, omit the instance initializer. -If you would like to capture timings for the `beforeModel`, `model`, `afterModel` hooks as well as `setupController` in one of your Routes, `@sentry/ember` exports a `instrumentRoutePerformance` function which can be used by replacing the default export with a wrapped Route. +## Routes -```javascript +To capture timings for a route's `beforeModel`, `model`, `afterModel`, and `setupController` hooks, wrap its default export with `instrumentRoutePerformance()`. + +```typescript {filename:app/routes/my-route.ts} import Route from "@ember/routing/route"; import { instrumentRoutePerformance } from "@sentry/ember"; class MyRoute extends Route { model() { - //... + // Load your model here. } } export default instrumentRoutePerformance(MyRoute); ``` -### Classic Components +## Classic Components -The render times of classic components are also enabled by default, with a setting to capture render timings only above a certain duration. To change this minimum, you can modify `minimumComponentRenderDuration` in your config. +After you call `instrumentAppInstancePerformance()`, the SDK captures classic component render timings by default. Set `minimumComponentRenderDuration` in the initializer's options to change the minimum duration in milliseconds. The default is `2`; set it to `0` to capture all classic component render timings. -```javascript -ENV["@sentry/ember"] = { - minimumComponentRenderDuration: 0, // Setting this to zero will capture all classic components. -}; -``` +Set `disableInstrumentComponents: true` in the same options object to disable component instrumentation. -To disable component instrumentation you can set `disableInstrumentComponents` in your config. +## Runloop -```javascript -ENV["@sentry/ember"] = { - disableInstrumentComponents: true, -}; -``` - -### Runloop +After you call `instrumentAppInstancePerformance()`, the SDK instruments queues in your application's runloop by default. Set `minimumRunloopQueueDuration` in the initializer's options to change the minimum duration in milliseconds. The default is `5`; set it to `0` to capture all runloop queue durations. -The duration of each queue in your application's runloop is instrumented by default, as long as the duration of the queue is longer than a threshold defined in your config by `minimumRunloopQueueDuration` - -```javascript -ENV["@sentry/ember"] = { - minimumRunloopQueueDuration: 0, // Setting this to zero will capture all runloop queue durations -}; -``` - -If you would like to disable runloop instrumentation you can set `disableRunloopPerformance` in your config. - -```javascript -ENV["@sentry/ember"] = { - disableRunloopPerformance: true, -}; -``` +Set `disableRunloopPerformance: true` in the same options object to disable runloop instrumentation. diff --git a/docs/platforms/javascript/guides/ember/index.mdx b/docs/platforms/javascript/guides/ember/index.mdx index c704250dff2ec..63893ca7ba547 100644 --- a/docs/platforms/javascript/guides/ember/index.mdx +++ b/docs/platforms/javascript/guides/ember/index.mdx @@ -51,12 +51,12 @@ Choose the features you want to configure, and this guide will show you how: -Configuration should happen as early as possible in your application's lifecycle. Add the following to your `app/app.js` file: +Call `Sentry.init()` in `app/app.ts` before defining your `Application` class. -```javascript {filename:app.js} +```typescript {filename:app/app.ts} import Application from "@ember/application"; import Resolver from "ember-resolver"; import loadInitializers from "ember-load-initializers"; @@ -103,12 +103,46 @@ export default class App extends Application { podModulePrefix = config.podModulePrefix; Resolver = Resolver; } + +loadInitializers(App, config.modulePrefix); +``` + + + + + + + +### Enable Performance Instrumentation + + + + + +To capture page loads, navigation, classic component renders, and runloop timings, create an instance initializer that calls `instrumentAppInstancePerformance()`. The `tracesSampleRate` option in `Sentry.init()` controls how much tracing data Sentry captures. + +The SDK skips this instrumentation during FastBoot server rendering. To customize it, see Ember Options. + + + + +```typescript {filename:app/instance-initializers/sentry-performance.ts} +import type ApplicationInstance from "@ember/application/instance"; +import { instrumentAppInstancePerformance } from "@sentry/ember"; + +export function initialize(appInstance: ApplicationInstance): void { + instrumentAppInstancePerformance(appInstance); +} + +export default { initialize }; ``` + + ### Add Readable Stack Traces With Source Maps (Optional) From cf9487f50d8217a4e676d716302b786657a707d2 Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Tue, 22 Sep 2026 15:00:42 +0200 Subject: [PATCH 03/48] docs(javascript): Document span streaming as the default (#19429) ## DESCRIBE YOUR PR Make streamed spans the default in the JavaScript tracing callback and helper docs. Keep transaction APIs documented for static mode, with separate examples for both modes. Update filtering, naming, sensitive-data scrubbing, and MCP guidance to use the appropriate callbacks. Closes [SDK-1473](https://linear.app/getsentry/issue/SDK-1473/update-span-streaming-callbackhelper-docs). ## IS YOUR CHANGE URGENT? - [x] No deadline: Not urgent, can wait up to 1 week+ --- .../javascript/common/configuration/apis.mdx | 26 +- .../common/configuration/filtering.mdx | 74 ++- .../common/configuration/options.mdx | 92 ++-- .../data-management/sensitive-data/index.mdx | 6 +- .../transaction-name/index.mdx | 16 +- .../common/mcp-monitoring/index.mdx | 12 +- .../common/tracing/instrumentation/index.mdx | 20 +- .../common/tracing/span-metrics/index.mdx | 20 +- .../common/tracing/streamed-spans/index.mdx | 399 +-------------- .../tracing/streamed-spans/index__v10.x.mdx | 463 ++++++++++++++++++ .../common/tracing/troubleshooting/index.mdx | 23 +- .../common/troubleshooting/index.mdx | 6 +- .../before-send-span/javascript.mdx | 23 +- .../before-send-transaction/javascript.mdx | 2 +- .../ignore-transactions/javascript.mdx | 1 + 15 files changed, 648 insertions(+), 535 deletions(-) create mode 100644 docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx diff --git a/docs/platforms/javascript/common/configuration/apis.mdx b/docs/platforms/javascript/common/configuration/apis.mdx index 6838251ae1011..bc4bd902ca6c3 100644 --- a/docs/platforms/javascript/common/configuration/apis.mdx +++ b/docs/platforms/javascript/common/configuration/apis.mdx @@ -134,13 +134,12 @@ Sentry.withScope((scope) => { }); ``` - - `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. + + `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 stream mode, 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 transaction mode, event processors also run on transaction events, followed by `beforeSendTransaction`. You can configure one `beforeSendTransaction` callback. @@ -842,18 +841,15 @@ Sentry.reportPageLoaded(); These utilities can be used for more advanced tracing use cases. - - Convert a span to a JSON object. If you're using{" "} - stream mode, we - recommend using [`spanToStreamedSpanJSON`](#spanToStreamedSpanJSON) instead. + + Convert a span to a JSON object. If you're using {" "} + `traceLifecycle: 'static'`, + use [`spanToStaticSpanJSON`](#spanToStaticSpanJSON) to get the `SpanJSON` format. - - Convert a span to a JSON object. Only available in{" "} - stream mode. + + Convert a span to the static `SpanJSON` format. Use this when working with transaction data in + transaction mode. -## Filtering Transaction Events - - - The options in this section are only available in transaction mode. If you're - using stream mode, go to - [Filtering Spans](#filtering-spans). - - -To prevent certain transactions from being reported to Sentry, use the or 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 - -You can use the 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. - - - -See ignoreTransactions for details. - -### Using - -You can also use the tracesSampler option to prevent certain transactions from being reported to Sentry. - -See Sampling on information about how to use it. - -### Using `beforeSendTransaction` - - - -See beforeSendTransaction for details, and [Using Hints](#using-hints) for details on the `hint` object. - ## Filtering Spans -### Using - -Use the 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 `tracesSampler`. -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 - +Use the 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 stream mode, make sure to wrap with `Sentry.withStreamedSpan()`. +Check `span.is_segment` to modify only service spans. In transaction mode, wrap the callback with `Sentry.withStaticSpan()` to modify the transaction and its child spans using the `SpanJSON` format. - +To drop a service span and its child spans, use [`ignoreSpans`](#using-ignore-spans). `beforeSendSpan` cannot return `null` to drop spans. @@ -169,12 +133,14 @@ You can use the 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 transaction 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: { @@ -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 ignoreSpans for details. +## Filtering Transaction Events + +These options apply when `traceLifecycle: 'static'` is set. In the default stream mode, use [Filtering Spans](#filtering-spans). + +### Using + +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. + + + +See `ignoreTransactions` 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. + + + +See `beforeSendTransaction` for details and [Using Hints](#using-hints) for the `hint` argument. + ## Filtering Breadcrumbs You can filter breadcrumbs by using the `beforeBreadcrumb` configuration option: diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 0cc649fc82b9f..ce8b3a26fe7cc 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -631,37 +631,15 @@ This is useful to prevent traces of unknown third-party services from being cont - - -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. - - - - - -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. + - +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. `Sentry.spanToJSON()` returns the same shape. - +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. @@ -671,11 +649,17 @@ In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and - + + +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. - + -Not available in stream mode. Use [`ignoreSpans`](#ignoreSpans) instead. + + + @@ -683,18 +667,14 @@ Not available in stream mode. Use [`ignoreSpans`](#ignoreSpans) instead. 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 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. - - -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 transaction 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 `debug: true` when initializing the SDK. - - +To inspect the initial names of automatically created spans, enable SDK debug logging during development with `debug: true`. @@ -741,6 +721,20 @@ Sentry.init({ + + +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. + + + + + + + + + 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`. @@ -770,22 +764,24 @@ Self-hosted Sentry users should set this option to `false`, as standalone `gen_a - + 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 stream mode (`'stream'`), spans are sent in batches as they finish. +- In stream mode (`'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. - - - -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, enable stream mode by adding `spanStreamingIntegration` to your integrations when initializing the SDK. - - +To opt out of span streaming, set `traceLifecycle: 'static'`. If you use `beforeSendSpan`, wrap it with `Sentry.withStaticSpan()` to receive the `SpanJSON` format: - +```javascript +Sentry.init({ + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + span.description = "[filtered]"; + return span; + }), +}); +``` diff --git a/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx b/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx index 2863a6c586237..b5c70dd09409f 100644 --- a/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx @@ -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: - `beforeSend` applies to error and message events - `beforeSendSpan` applies to spans - `beforeSendLog` applies to logs - `beforeSendMetric` applies to metrics -- `beforeSendTransaction` applies to transactions (only in transaction mode) +- `beforeSendTransaction` applies to transaction events in transaction mode -If you're using span stream mode, `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 transaction mode, wrap the callback with `Sentry.withStaticSpan()` and use `beforeSendTransaction` to scrub transaction events. diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 9096d38425ae3..caf8ff40a7984 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -104,10 +104,22 @@ Learn more about ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1.0, - traceLifecycle: "stream", }), worker ); ``` -Stream mode sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. See Streamed Spans for the `beforeSendSpan` and `ignoreSpans` configuration. +Use `beforeSendSpan` to modify each finished span's `name` and `attributes`, with an `is_segment` guard to target service spans. Use the object form of `ignoreSpans` to drop spans by name and operation. See Streamed Spans for examples. If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and wrap the Agent class separately with `instrumentAgentWithSentry` to preserve request and RPC context. Agent instrumentation, MCP server wrapping, and span streaming solve different parts of the setup; none replaces the others. See Agents SDK. @@ -90,7 +89,7 @@ If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and ## Hono on Cloudflare Workers -If your Hono app runs on Cloudflare Workers, MCP work can finish after the Worker returns its response. Set `traceLifecycle: "stream"` in the Hono Sentry middleware so each sampled span is sent when it finishes: +If your Hono app runs on Cloudflare Workers, MCP work can finish after the Worker returns its response. The Hono Sentry middleware uses span streaming by default, so each sampled span can be sent when it finishes: ```javascript {filename:index.js} import { sentry } from "@sentry/hono/cloudflare"; @@ -99,12 +98,11 @@ app.use( sentry(app, { dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, - traceLifecycle: "stream", }) ); ``` -This changes how spans are delivered; it doesn't replace `wrapMcpServerWithSentry`. Stream mode requires `@sentry/hono` and `@sentry/cloudflare` version `10.49.0` or newer. See Streamed Spans for configuration and filtering differences. +You still need `wrapMcpServerWithSentry` to instrument MCP operations. See Streamed Spans for configuration and filtering differences. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index b3dd3186db461..d1a0807e2a52e 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -205,14 +205,15 @@ if (span) { ### Adding attributes to all spans To add an attribute to all spans, use the `beforeSendSpan` callback. -Note that the property names differ between transaction mode (the default) and stream mode: +In stream mode, the callback receives span attributes in `span.attributes`. +If you opt into transaction mode with `traceLifecycle: 'static'`, wrap the callback with `Sentry.withStaticSpan()` and use `span.data` instead: -```javascript {tabTitle:Transaction Mode (Default)} +```javascript {tabTitle:Stream Mode (Default)} {mdExpandTabs} Sentry.init({ // dsn, ... beforeSendSpan(span) { - span.data = { - ...span.data, + span.attributes = { + ...span.attributes, "environment.region": "us-west-2", }; @@ -221,17 +222,18 @@ Sentry.init({ }); ``` -```javascript {tabTitle:Stream Mode} +```javascript {tabTitle:Transaction Mode} Sentry.init({ // dsn, ... - beforeSendSpan(span) { - span.attributes = { - ...span.attributes, + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + span.data = { + ...span.data, "environment.region": "us-west-2", }; return span; - }, + }), }); ``` diff --git a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx index d5cdd5beea121..2d84e1a65c313 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx @@ -73,13 +73,14 @@ For detailed examples of how to implement span metrics in common scenarios, see ## Adding Metrics to All Spans To consistently add metrics across all spans in your application, you can use the `beforeSendSpan` callback. -Note that the property names differ between transaction mode (the default) and stream mode: +In stream mode, the callback receives span attributes in `span.attributes`. +If you opt into transaction mode with `traceLifecycle: 'static'`, wrap the callback with `Sentry.withStaticSpan()` and use `span.data` instead: -```javascript {tabTitle:Transaction Mode (Default)} +```javascript {tabTitle:Stream Mode (Default)} {mdExpandTabs} Sentry.init({ beforeSendSpan(span) { - span.data = { - ...span.data, + span.attributes = { + ...span.attributes, "app.version": "1.2.3", "environment.region": "us-west-2", }; @@ -89,17 +90,18 @@ Sentry.init({ }); ``` -```javascript {tabTitle:Stream Mode} +```javascript {tabTitle:Transaction Mode} Sentry.init({ - beforeSendSpan(span) { - span.attributes = { - ...span.attributes, + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + span.data = { + ...span.data, "app.version": "1.2.3", "environment.region": "us-west-2", }; return span; - }, + }), }); ``` diff --git a/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx b/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx index 7dfa22672121e..8d5d9851b0975 100644 --- a/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx +++ b/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx @@ -1,6 +1,6 @@ --- 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." +description: "Learn how the SDK sends spans in batches as they finish, and how to configure span attributes, filtering, and delivery." sidebar_order: 35 new: true notSupported: @@ -8,22 +8,21 @@ notSupported: - javascript.electron --- -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. +The Sentry JavaScript SDKs send spans in batches as they finish. This is called stream mode and is the default trace lifecycle. Service spans represent a service's entry point and group its child spans. -- **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. +- **No 1,000-span limit.** Spans are sent in batches, so a trace can contain more than 1,000 spans. - **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. +- **No data loss from crashes.** If your process terminates unexpectedly, spans that were already flushed are preserved. Spans still buffered in memory can be 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. +- **Service span**: A parent-level span at the entry of a service, identified by `is_segment` in its serialized data. - **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: @@ -39,49 +38,13 @@ Trace └── 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. +## Configuration -## Prerequisites +Configure tracing in your +app. The SDK uses `traceLifecycle: 'stream'` by default, with no additional +integration required. -You need: - -- Tracing configured in - your app -- SDK version `>=10.66.0` - -## 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](#enable-stream-mode) -2. [Wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` to filter spans](#filter-spans) -3. [Replace `beforeSendTransaction` with `ignoreSpans` to drop spans](#drop-spans) -4. [Migrate tags (`Sentry.setTag(s)`) to attributes (`Sentry.setAttribute(s)`)](#shared-attributes) -5. [Verify the migration](#verify-your-setup) - -### Agent-Assisted Migration - -Copy the following prompt and paste it into your AI agent: - -```txt -Follow ___CURRENT_URL___ to enable and migrate to span streaming in the Sentry SDK. -``` - -## Enable Stream Mode - - - - - - - -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. - - - - +To opt out of span streaming, set `traceLifecycle: 'static'`. With this setting, wrap `beforeSendSpan` with `Sentry.withStaticSpan()` to receive and return `SpanJSON`. Transaction mode also supports transaction filtering with `beforeSendTransaction` and `ignoreTransactions`. @@ -99,340 +62,35 @@ Each flush sends only the spans accumulated since the last flush, grouped into e ## Manual Instrumentation (Optional) -### 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. +Use the same span creation APIs in stream mode as in transaction mode. To measure operations the SDK does not instrument automatically, see Instrumentation for `startSpan`, `startSpanManual`, and `startInactiveSpan` examples. ## Add Attributes -Attach structured metadata to spans using `attributes`, 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 documentation. - - +To attach metadata to individual spans, see Adding Span Attributes. ### 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`, 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 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"); -}); -``` - - - - +Use shared attributes to attach the same metadata to spans, logs, and metrics. Scope tags apply to errors and are not included in streamed spans. ## Breadcrumbs -In stream mode, breadcrumbs are no longer sent with spans. -They remain attached to errors, so you don't need to change how you record them. +Breadcrumbs are attached to errors. Streamed spans do not include breadcrumbs. ## Extended Configuration (Optional) -### Filter Spans - - - - - -To modify or redact span data before it's sent, use `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`](#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: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - traceLifecycle: "stream", - 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; - }), -}); -``` - - - - - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - 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; - }), -}); -``` - - - - - - - - - +Modify span data before sending it or filter out spans you do not need. -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: +### Filter 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']` | +Use `beforeSendSpan` to modify each finished span. In stream mode, the callback receives `StreamedSpanJSON` directly. Check `span.is_segment` to target only service spans. -If you're using `beforeSendTransaction` to drop spans, use [`ignoreSpans`](#drop-spans) instead, since `beforeSendTransaction` is not available in stream mode. - - +The callback cannot return `null` to drop spans. See Filtering Spans for examples of modifying and dropping spans. ### 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` option: - - - - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - traceLifecycle: "stream", - 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", - }, - }, - ], -}); -``` - - - - - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - 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", - }, - }, - ], -}); -``` - - - - - - - - +Use `ignoreSpans` to drop spans by name, operation, or attributes. In stream mode, rules are evaluated when a span starts, so later name and attribute updates do not affect matching. -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. - - - -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` when initializing the SDK. - - +Ignoring a service span also drops its child spans. Ignoring a child span reparents its children to the nearest ancestor. See Using `ignoreSpans` for matching rules and examples. ## Distributed Tracing (Optional) @@ -441,23 +99,10 @@ when the SDK can't instrument automatically, see - - - -- **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. -- **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 Traces view in Sentry for spans shortly after they finish. Enable `debug: true` to see SDK warnings, including callbacks that do not match the configured trace lifecycle. -- **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` +In your browser's DevTools network tab, look for span envelopes with content type `application/vnd.sentry.items.span.v2+json`. diff --git a/docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx b/docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx new file mode 100644 index 0000000000000..7dfa22672121e --- /dev/null +++ b/docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx @@ -0,0 +1,463 @@ +--- +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." +sidebar_order: 35 +new: true +notSupported: + - javascript.cordova + - javascript.electron +--- + +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. + + + +- **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: + +``` +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 + +You need: + +- Tracing configured in + your app +- SDK version `>=10.66.0` + +## 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](#enable-stream-mode) +2. [Wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` to filter spans](#filter-spans) +3. [Replace `beforeSendTransaction` with `ignoreSpans` to drop spans](#drop-spans) +4. [Migrate tags (`Sentry.setTag(s)`) to attributes (`Sentry.setAttribute(s)`)](#shared-attributes) +5. [Verify the migration](#verify-your-setup) + +### Agent-Assisted Migration + +Copy the following prompt and paste it into your AI agent: + +```txt +Follow ___CURRENT_URL___ to enable and migrate to span streaming in the Sentry SDK. +``` + +## Enable Stream Mode + + + + + + + +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. + + + + + + + +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) + +### 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. + +## Add Attributes + +Attach structured metadata to spans using `attributes`, 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 documentation. + + + +### 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`, 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 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"); +}); +``` + + + + + +## Breadcrumbs + +In stream mode, breadcrumbs are no longer sent with spans. +They remain attached to errors, so you don't need to change how you record them. + +## Extended Configuration (Optional) + +### Filter Spans + + + + + +To modify or redact span data before it's sent, use `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`](#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: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + traceLifecycle: "stream", + 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; + }), +}); +``` + + + + + + + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + 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; + }), +}); +``` + + + + + + + + + + +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`](#drop-spans) instead, since `beforeSendTransaction` is not available in stream mode. + + + +### 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` option: + + + + + + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + traceLifecycle: "stream", + 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", + }, + }, + ], +}); +``` + + + + + + + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + 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. + + + +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` when initializing the SDK. + + + +## 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 instrumentation for distributed tracing. + +## 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 the same as in transaction mode, but without 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 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` + + diff --git a/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx b/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx index 0024a04c5810c..b4be9f2aa0996 100644 --- a/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx @@ -9,11 +9,20 @@ If you need help managing transactions or spans, start with this page. If you ne ## Group Transactions -When Sentry captures transactions, they are assigned a transaction name. This name is generally auto-generated by the Sentry SDK based on the framework integrations you are using. If you can't leverage the automatic transaction generation (or want to customize how transaction names are generated) you can use a global event processor that is registered when you initialize the SDK with your configuration. +The SDK groups spans by service span. Integrations usually name these spans automatically. To change a service span's name before it is sent, use `beforeSendSpan` and check `is_segment`: -For example: +```javascript +Sentry.init({ + beforeSendSpan(span) { + if (span.is_segment && span.attributes["http.route"] === "/users/:id") { + span.name = "GET /users/:id"; + } + return span; + }, +}); +``` - +Event processors do not apply to streamed spans. In transaction mode, use `beforeSendTransaction` to change `event.transaction`. See Transaction Name for other ways to set names. ## Control Data Truncation @@ -32,16 +41,16 @@ For example, a 200+ character tag like this: ## Traces Miss Spans, High Memory Usage, or Data Loss After Crashes -If you're hitting the 1,000-span limit, experiencing high memory usage from long-running processes, or losing span data when your process crashes, consider enabling stream mode. Stream mode sends spans to Sentry in batches as they finish rather than holding them in memory until the transaction ends. +With `traceLifecycle: 'static'`, the SDK holds spans in memory until the root span ends. This can cause high memory usage, hit the 1,000-span limit, or lose spans if the process crashes. Use the default `traceLifecycle: 'stream'` to send spans in batches as they finish. In stream mode, pass `beforeSendSpan` directly without a `withStaticSpan` wrapper. See Streamed Spans for more information. -## `ignoreSpans` Rules No Longer Work As Expected After Migrating to Stream Mode +## `ignoreSpans` Rules Do Not Match Spans -In stream mode, `ignoreSpans` is evaluated at span start rather than at transaction end as in transaction mode. This means rules that match on names and attributes added or updated while a span is active may no longer match the intended spans. Review your `ignoreSpans` rules after migrating to make sure the names and attributes you're matching on are available when the span is created. +The SDK evaluates `ignoreSpans` when a span starts. Names and attributes added or updated later do not affect matching. Make sure your rules match values available 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` when initializing the SDK. -Finally, make sure you've migrated any entries from `ignoreTransactions` to `ignoreSpans`, as `ignoreTransactions` is not applied in stream mode. +Use the object form of `ignoreSpans` to match both name and operation when you need to distinguish service spans from child spans with the same name. diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index f68922850512e..7215d03e1d5d7 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -695,9 +695,9 @@ shamefully-hoist=true Cloudflare's [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil) lets work continue after the Worker returns a response. Whether those spans arrive depends on your trace lifecycle. - On the static lifecycle, which is the default, the SDK snapshots the request transaction when the response is returned, so anything finishing later is dropped. Streaming sends each sampled span as it finishes instead, which captures deferred work. + In transaction mode (`traceLifecycle: "static"`), the SDK snapshots the request transaction when the response is returned, so spans that finish later may be missing. Stream mode, the default since SDK version 11.0.0, sends sampled spans in batches as they finish, which captures deferred work. - Set `traceLifecycle: "stream"`, which needs `@sentry/cloudflare` version `10.49.0` or newer: + If you use transaction mode, remove `traceLifecycle: "static"` or set it to `"stream"`. On SDK version 10, explicitly set `traceLifecycle: "stream"`, which requires `@sentry/cloudflare` version `10.49.0` or newer: ```javascript {filename:index.js} export default Sentry.withSentry( @@ -710,7 +710,7 @@ shamefully-hoist=true ); ``` - If you need to keep the static lifecycle, wrap the background work in its own span with `forceTransaction: true`, which records it as a separate transaction. `forceTransaction` isn't available in stream mode. + If you need to keep transaction mode, wrap the background work in its own span with `forceTransaction: true`, which records it as a separate transaction. `forceTransaction` isn't available in stream mode. ```javascript {filename:index.js} ctx.waitUntil( diff --git a/platform-includes/configuration/before-send-span/javascript.mdx b/platform-includes/configuration/before-send-span/javascript.mdx index 13b5f9623a3f7..cd707dd185d10 100644 --- a/platform-includes/configuration/before-send-span/javascript.mdx +++ b/platform-includes/configuration/before-send-span/javascript.mdx @@ -1,11 +1,11 @@ -```javascript {tabTitle:Transaction Mode (Default)} +```javascript {tabTitle:Stream Mode (Default)} {mdExpandTabs} Sentry.init({ dsn: "___PUBLIC_DSN___", beforeSendSpan(span) { - if (span.description === "should be renamed") { - span.description = "renamed span"; - span.data = { - ...span.data, + if (span.name === "should be renamed") { + span.name = "renamed span"; + span.attributes = { + ...span.attributes, myExtraAttribute: true, }; } @@ -15,14 +15,15 @@ Sentry.init({ }); ``` -```javascript {tabTitle:Stream Mode} +```javascript {tabTitle:Transaction Mode} Sentry.init({ dsn: "___PUBLIC_DSN___", - beforeSendSpan: Sentry.withStreamedSpan((span) => { - if (span.name === "should be renamed") { - span.name = "renamed span"; - span.attributes = { - ...span.attributes, + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + if (span.description === "should be renamed") { + span.description = "renamed span"; + span.data = { + ...span.data, myExtraAttribute: true, }; } diff --git a/platform-includes/configuration/before-send-transaction/javascript.mdx b/platform-includes/configuration/before-send-transaction/javascript.mdx index c1d1a05093a2c..d49e4d6eab7de 100644 --- a/platform-includes/configuration/before-send-transaction/javascript.mdx +++ b/platform-includes/configuration/before-send-transaction/javascript.mdx @@ -1,9 +1,9 @@ ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", + traceLifecycle: "static", beforeSendTransaction(event) { if (event.transaction === "/unimportant/route") { - // Don't send the event to Sentry return null; } return event; diff --git a/platform-includes/configuration/ignore-transactions/javascript.mdx b/platform-includes/configuration/ignore-transactions/javascript.mdx index 1aa8541e84719..d1728e2f5bc5a 100644 --- a/platform-includes/configuration/ignore-transactions/javascript.mdx +++ b/platform-includes/configuration/ignore-transactions/javascript.mdx @@ -1,6 +1,7 @@ ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", + traceLifecycle: "static", ignoreTransactions: ["partial/match", /^Exact Transaction Name$/], }); ``` From 355f9faff821e963049fbcf770ccd48ff481f5ad Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Tue, 22 Sep 2026 15:01:28 +0200 Subject: [PATCH 04/48] docs(javascript): Prepare browser JavaScript docs for v11 (#19369) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Update the JavaScript browser docs for SDK v11’s session defaults and tracing integrations. Document page-based sessions, the unhandled session status, and the FetchStreamPerformance, Interactions, UserTiming, and WebVitals integrations. Align the migration guide, interactive migration snippets, Next.js tracing guide, and Web Vitals documentation with these behaviors. Closes SDK-1478 Closes SDK-1479 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ --- .../integrations/browsersession.mdx | 16 +++- .../integrations/fetchstreamperformance.mdx | 56 ++++++++++++ .../configuration/integrations/index.mdx | 2 + .../integrations/interactions.mdx | 78 ++++++++++++++++ .../configuration/integrations/usertiming.mdx | 62 +++++++++++++ .../configuration/integrations/webvitals.mdx | 88 +++++++++++++++++++ .../javascript/common/install/loader.mdx | 2 +- .../common/migration/v10-to-v11/index.mdx | 20 +++-- .../automatic-instrumentation.mdx | 71 +++++++++++---- .../guides/nextjs/tracing/index.mdx | 6 +- .../web-vitals/web-vitals-concepts.mdx | 8 +- .../browser-session-lifecycle-page.mdx | 2 + .../browser-session-unhandled.mdx | 2 + .../javascript-v11/browser-user-timing.mdx | 2 + .../browser-web-vital-options.mdx | 8 +- .../javascript-v11/inp-web-vital-span.mdx | 4 +- .../interaction-spans-integration.mdx | 2 +- .../track-fetch-stream-performance.mdx | 2 + .../auto-session-tracking/javascript.mdx | 18 +++- .../integrations/javascript.astro.mdx | 4 + .../integrations/javascript.gatsby.mdx | 4 + .../configuration/integrations/javascript.mdx | 4 + .../integrations/javascript.nextjs.mdx | 4 + .../integrations/javascript.nuxt.mdx | 4 + .../integrations/javascript.remix.mdx | 4 + .../integrations/javascript.solidstart.mdx | 4 + .../integrations/javascript.sveltekit.mdx | 4 + .../integrations/javascript.vue.mdx | 4 + .../integrations/javascript.wasm.mdx | 4 + .../enable-inp-example/javascript.mdx | 4 +- 30 files changed, 453 insertions(+), 40 deletions(-) create mode 100644 docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/interactions.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/usertiming.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/webvitals.mdx diff --git a/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx b/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx index 2dfc4d4e13f09..4708c2bc60018 100644 --- a/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx @@ -27,11 +27,21 @@ Sentry.init({ ## Configuration Options - + Controls how long one session lasts and when a new session is started. -- `'route'`: A new session is started when the route changes, based on the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). This is the default behavior. If you're building a single-page application (SPA), this will result in one session being created per soft navigation. -- `'page'`: A new session is started when the page changes on a hard page reload or navigation. This is useful if you're building a single-page application (SPA) and want to track one session across multiple routes as users navigate through your application. +- `'page'`: Starts a session on page load. Client-side route changes keep the same session. This is the default. +- `'route'`: Starts a session on page load and on each navigation detected through the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). + +Before SDK version 11, the default was `'route'`. + +To create a session on each client-side navigation in a single-page application, set `lifecycle` to `'route'`: + +```javascript +Sentry.init({ + integrations: [Sentry.browserSessionIntegration({ lifecycle: "route" })], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx b/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx new file mode 100644 index 0000000000000..3e765883aaa79 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx @@ -0,0 +1,56 @@ +--- +title: FetchStreamPerformance +description: "Measure how long streamed fetch response bodies take to finish." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 11 or later. + + + +_Import name: `Sentry.fetchStreamPerformanceIntegration`_ + +The FetchStreamPerformance integration measures how long streamed fetch responses take to finish. It captures spans from when response headers arrive until the body finishes, up to 90 seconds. + +Use it with BrowserTracing or your framework's routing integration. + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.fetchStreamPerformanceIntegration(), + ], +}); +``` + +Responses are tracked when they have no `content-length` header and their `content-type` starts with one of these values: + +- `text/event-stream` +- `application/x-ndjson` +- `application/stream+json` + +This integration has no configuration options. diff --git a/docs/platforms/javascript/common/configuration/integrations/index.mdx b/docs/platforms/javascript/common/configuration/integrations/index.mdx index cfedf1d887d79..ea485185e3c5b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/index.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/index.mdx @@ -85,6 +85,8 @@ Lazy loading is available for the following integrations: - `reportingObserverIntegration` - `rewriteFramesIntegration` - `browserProfilingIntegration` +- `userTimingIntegration` +- `interactionsIntegration` diff --git a/docs/platforms/javascript/common/configuration/integrations/interactions.mdx b/docs/platforms/javascript/common/configuration/integrations/interactions.mdx new file mode 100644 index 0000000000000..24fe7b2269a36 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/interactions.mdx @@ -0,0 +1,78 @@ +--- +title: Interactions +description: "Capture clicks and the work they trigger as browser spans." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 11 or later. + + + +_Import name: `Sentry.interactionsIntegration`_ + +The Interactions integration captures clicks and the work they trigger as spans. Use it with BrowserTracing or your framework's routing integration to associate interactions with the current route. + + + +This integration is experimental and can generate a large number of spans. + + + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.interactionsIntegration(), + ], +}); +``` + +Clicks outside an active pageload or navigation start an interaction span. Requests and other spans started during the interaction become its children. The integration also captures individual clicks. + +INP is collected by the WebVitals integration and does not require this integration. + +## Configuration Options + +These timeouts apply to interaction spans, independently of BrowserTracing's pageload and navigation timeouts. + + + +Time in milliseconds to wait before finishing an interaction span when no unfinished child spans remain. + + + + + +Maximum duration of an interaction span in milliseconds, including time spent waiting for child spans. + + + + + +Maximum time in milliseconds a child span can run before the interaction span finishes. + + diff --git a/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx b/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx new file mode 100644 index 0000000000000..d1131ff300dc1 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx @@ -0,0 +1,62 @@ +--- +title: UserTiming +description: "Capture performance.mark() and performance.measure() entries as browser spans." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 11 or later. + + + +_Import name: `Sentry.userTimingIntegration`_ + +The UserTiming integration captures `performance.mark()` and `performance.measure()` entries as spans. Use it with BrowserTracing or your framework's routing integration. Timing entries are added to pageload and navigation spans when those spans end. + +Before SDK version 11, BrowserTracing captured these entries automatically, without a separate integration. + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.userTimingIntegration(), + ], +}); +``` + +## Configuration Options + + + +Skip timing entries whose names match any string or regular expression in this array. Use this to exclude measurements from third-party code. + +```javascript +Sentry.userTimingIntegration({ + ignore: ["third-party-mark", /^framework-/], +}); +``` + + diff --git a/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx b/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx new file mode 100644 index 0000000000000..6876e00145611 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx @@ -0,0 +1,88 @@ +--- +title: WebVitals +description: "Configure browser Web Vitals collection, including INP, LCP, and CLS." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 10.57.0 or later. + + + +_Import name: `Sentry.webVitalsIntegration`_ + +The WebVitals integration captures LCP, CLS, and INP for the [Web Vitals dashboard](/product/dashboards/sentry-dashboards/frontend/web-vitals/). + + + BrowserTracing + +adds this integration automatically. In SDK version 11 and later, configure it through BrowserTracing's +`webVitals` option: + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + webVitals: { + ignore: ["inp"], + }, + }), + ], +}); +``` + +To configure it in SDK versions before 11, add `Sentry.webVitalsIntegration({ ... })` directly to `integrations`: + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.webVitalsIntegration({ ignore: ["inp"] }), + ], +}); +``` + +You can also use this approach in SDK version 11 and later. An explicitly added WebVitals integration takes precedence over BrowserTracing's Web Vitals settings. + +## Configuration Options + + + +Web Vitals to skip. By default, all supported Web Vitals are collected. + + + + + +Collect LCP, CLS, and INP for each soft navigation detected by the browser's Soft Navigations API. Requires stream mode and a browser that supports this API. Set to `false` to collect one set of vitals for the page lifetime. + + + + + +Collect LCP, CLS, and INP when a page is restored from the back/forward cache. Requires stream mode and BrowserTracing with `instrumentBfcacheRestore` enabled. Set to `false` to disable Web Vitals collection for restores. + + diff --git a/docs/platforms/javascript/common/install/loader.mdx b/docs/platforms/javascript/common/install/loader.mdx index d3e03fa9c8abc..1f1609617f1a7 100644 --- a/docs/platforms/javascript/common/install/loader.mdx +++ b/docs/platforms/javascript/common/install/loader.mdx @@ -418,7 +418,7 @@ Our CDN hosts a variety of bundles: - `bundle.tracing.replay.logs.metrics..js` - Error monitoring, tracing, session replay, logs, and metrics - `bundle.tracing.replay.feedback.logs.metrics..js` - Error monitoring, tracing, session replay, feedback, logs, and metrics -Additionally, each of the integrations in `@sentry/integrations` is available as a bundle named `..js`. +Some integrations are available as separate bundles. See Lazy Loading Integrations for the supported list. Since v8 of the SDK, the bundles are ES6 by default. If you need ES5 support, make sure to add a polyfill for ES5 features yourself. Alternatively, you can use the v7 bundles and add the `.es5` modifier. diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index aec09d59042a9..50b3c66731fed 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -866,6 +866,8 @@ Sentry.init({ }); ``` +See BrowserSession for lifecycle configuration and session health details. + ### The `DOMException.code` Tag Was Removed Events created from a `DOMException` no longer carry a `DOMException.code` tag, because the `code` property is deprecated in favor of `DOMException.name`, which is already the exception type. Switch searches and alert rules that use the tag to `error.type`. @@ -897,10 +899,10 @@ Several `browserTracingIntegration` options moved to dedicated integrations, or | Removed option | Replacement | | ------------------------------------- | ----------------------------------------------- | -| `_experiments.enableInteractions` | `interactionsIntegration()` | -| `ignorePerformanceApiSpans` | `userTimingIntegration({ ignore: [...] })` | -| `trackFetchStreamPerformance` | `fetchStreamPerformanceIntegration()` | -| `_experiments.enableStandalone*Spans` | Removed, CLS and LCP are no longer configurable | +| `_experiments.enableInteractions` | `interactionsIntegration()` | +| `ignorePerformanceApiSpans` | `userTimingIntegration({ ignore: [...] })` | +| `trackFetchStreamPerformance` | `fetchStreamPerformanceIntegration()` | +| `_experiments.enableStandalone*Spans` | Removed. The trace lifecycle determines how CLS and LCP are sent. | ```js // Before @@ -925,12 +927,16 @@ Sentry.init({ }); ``` -`browserTracingIntegration` no longer captures `performance.mark()` and `performance.measure()` spans by default, and no longer accepts an `_experiments` object at all. The `idleTimeout`, `finalTimeout`, and `childSpanTimeout` options of interaction spans are configured on `interactionsIntegration` now, with the same defaults as before. +`browserTracingIntegration` no longer captures `performance.mark()` and `performance.measure()` spans by default, and no longer accepts an `_experiments` object. Configure `idleTimeout`, `finalTimeout`, and `childSpanTimeout` for interaction spans on `interactionsIntegration`, with the same defaults as before. BrowserTracing's timeout options still control pageload and navigation spans. -Web vitals also changed: +BrowserTracing now automatically adds the WebVitals integration. Web Vitals changed as follows: - CLS and LCP are recorded as measurements on the pageload span, or as dedicated spans in stream mode. -- INP is always sent as a web vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement (built-in dashboards do not need adjustments). +- When collected, INP is always sent as a Web Vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement. Built-in dashboards do not need adjustments. +- The `enableInp` option is deprecated. To disable INP, use `browserTracingIntegration({ webVitals: { ignore: ["inp"] } })`. The `ignore` array can also contain `"cls"` or `"lcp"` to skip those vitals. +- To configure Web Vitals, pass `webVitals` options to BrowserTracing, or add `webVitalsIntegration()` explicitly. Explicit registration takes precedence over BrowserTracing's `webVitals` and `enableInp` options. +- Soft-navigation vitals are enabled by default in stream mode on browsers that support the Soft Navigations API. Set `webVitals: { softNavigations: false }` to keep one set of vitals for the page lifetime. +- BrowserTracing starts a navigation span after a back/forward-cache restore by default. Set `instrumentBfcacheRestore: false` to disable it. Web Vitals for restores are collected by default in stream mode when `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx index 1ed43c3321d85..d1d6d46ae49b3 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx @@ -29,7 +29,7 @@ Once you enable tracing, the SDK automatically captures performance data without | **Page loads** | Full page load performance | LCP, CLS, TTFB | | **Navigations** | Client-side route changes | Duration, Web Vitals | | **HTTP requests** | All fetch/XHR calls | Duration, status, URL | -| **User interactions** | Clicks, inputs that trigger work | INP (responsiveness) | +| **Responsiveness** | Interaction to Next Paint | INP | | **Long tasks** | Main thread blocking > 50ms | Duration, attribution | @@ -118,36 +118,56 @@ Exclude requests from tracing, such as health checks or analytics pings: -## Web Vitals & Interactions - -### Interaction to Next Paint (INP) + - + -Automatically captures [INP](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/#interaction-to-next-paint-inp) events to measure responsiveness. Results appear in the [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) module. +## Web Vitals & Interactions -Default: `true` in SDK 8.x+, `false` in 7.x. +BrowserTracing automatically captures Web Vitals. To capture clicks and the work they trigger as spans, add the Interactions integration. - +### Configure Web Vitals -As of SDK version 10.0.0, First Input Delay (FID) is no longer reported. Google deprecated FID in favor of INP, which provides a more comprehensive measure of responsiveness. If you have alerts or dashboards based on FID, update them to use INP instead. + - +Configure which Web Vitals BrowserTracing collects. For example, to disable INP collection: +If you explicitly add `webVitalsIntegration()`, configure these options on that integration instead. See WebVitals for details and browser support requirements. + - +### Interaction to Next Paint (INP) + +BrowserTracing automatically captures [INP](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/#interaction-to-next-paint-inp) to measure responsiveness. Results appear in the [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) module. -Sample rate for INP spans, applied on top of `tracesSampleRate`. For example, `interactionsSampleRate: 0.5` with `tracesSampleRate: 0.1` results in 5% of interactions captured. + + +Enable or disable INP collection. Defaults to `true` in SDK 8 and later, and `false` in SDK 7.x. + +Deprecated in SDK version 11. Use `webVitals: { ignore: ["inp"] }` to disable INP. Explicitly adding `webVitalsIntegration()` takes precedence over this option. + + + + ## Advanced Options +These timeouts control pageload and navigation spans. + + + + +Configure timeouts for click-triggered work on the Interactions integration separately. + + + + Time in ms to wait before finishing a pageload/navigation span when no unfinished child spans remain. @@ -182,6 +202,20 @@ Enable/disable automatic `navigation` span creation on history changes. + + + + + +Start a navigation span when the page is restored from the back/forward cache. This starts a new trace for activity after the restore. It is independent of `instrumentNavigation`. + +Web Vitals for restored pages are collected by default in stream mode. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. See WebVitals for requirements. + + + + + + Enable/disable automatic spans for long tasks (main thread blocking > 50ms). @@ -250,21 +284,24 @@ Sentry.init({ - + + -Ignore spans created from `performance.mark()` and `performance.measure()`: +Use the UserTiming integration to capture `performance.mark()` and `performance.measure()` entries. To ignore entries by name: ```javascript Sentry.init({ integrations: [ - Sentry.browserTracingIntegration({ - ignorePerformanceApiSpans: ["myMeasurement", /myMark/], + Sentry.browserTracingIntegration(), + Sentry.userTimingIntegration({ + ignore: ["myMeasurement", /myMark/], }), ], }); ``` - + + diff --git a/docs/platforms/javascript/guides/nextjs/tracing/index.mdx b/docs/platforms/javascript/guides/nextjs/tracing/index.mdx index 802c9ced62d90..69e895b9905bf 100644 --- a/docs/platforms/javascript/guides/nextjs/tracing/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/tracing/index.mdx @@ -185,7 +185,7 @@ export async function submitForm(formData: FormData) { ## Web Vitals -The SDK automatically captures [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) on every page load. These metrics measure real user experience: +The SDK automatically captures [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) in the browser. These metrics measure real user experience: | Metric | What It Measures | Threshold (Good) | |--------|------------------|------------------| @@ -195,7 +195,9 @@ The SDK automatically captures [Web Vitals](/product/dashboards/sentry-dashboard | **FCP** | First Contentful Paint — initial render | ≤ 1s | | **TTFB** | Time to First Byte — server response | ≤ 100ms | -Web Vitals appear as measurements on page load transactions and feed into your [Performance Score](/product/dashboards/sentry-dashboards/frontend/web-vitals/#performance-score). See [Web Vitals Concepts](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/) for detailed explanations of each metric. +Web Vitals feed into your [Performance Score](/product/dashboards/sentry-dashboards/frontend/web-vitals/#performance-score). In the default stream mode, LCP, CLS, and INP are sent as Web Vital spans. + +To configure collection, see the WebVitals integration. For metric definitions and differences between SDK versions, see [Web Vitals Concepts](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/). ## Custom Instrumentation diff --git a/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx b/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx index a31ad37e5ed37..242fec95080cf 100644 --- a/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx +++ b/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx @@ -9,7 +9,11 @@ og_image: /og-images/product-insights-frontend-web-vitals-web-vitals-concepts.pn [Web Vitals](https://web.dev/vitals/) are a set of metrics defined by Google to measure render time, response time, and layout shift. Each data point provides insights about the overall [performance](/product/dashboards/sentry-dashboards/) of your application. -The in-browser Sentry SDKs collect web vitals information (where supported) and adds that information to frontend [transactions](/product/dashboards/sentry-dashboards/transaction-summary/). These web vitals are then summarized in the [Web Vitals dashboard](/product/dashboards/sentry-dashboards/frontend/web-vitals/) to give you a quick overview of how each page is performing for your users. +Sentry's browser SDKs collect supported Web Vitals and associate them with your application's traces. The [Web Vitals dashboard](/product/dashboards/sentry-dashboards/frontend/web-vitals/) summarizes these metrics to show how each page performs for your users. + +In JavaScript SDK version 11's default stream mode, LCP, CLS, and INP are sent as Web Vital spans. Earlier SDK versions and static mode can report vitals as measurements on pageload spans. In version 11, INP uses a Web Vital span in both modes. + +To configure collection, see the [WebVitals integration](/platforms/javascript/configuration/integrations/webvitals/). If your custom dashboards or alerts use INP measurements, see the [v11 migration guide](/platforms/javascript/migration/v10-to-v11/). ![Visualization of Web Vitals](../../img/diagram-transaction-vitals.png) @@ -24,7 +28,7 @@ Google considers Core Web Vitals to be the most important metrics for measuring ### Interaction to Next Paint (INP) -On March 12, 2024, Interaction to Next Paint (INP) replaced First Input Delay (FID) as a Core Web Vital. Prior to this, INP was an experimental metric that Sentry did not collect. To begin collecting INP measurements, make sure your JavaScript SDK version is [7.104.0](https://github.com/getsentry/sentry-javascript/releases/tag/7.104.0) or higher and that the option [`enableInp`](/platforms/javascript/tracing/instrumentation/automatic-instrumentation/#enableinp) is on (starting with version `8.0.0`, `enableInp` is enabled by default). +INP replaced First Input Delay (FID) as a Core Web Vital on March 12, 2024. Sentry supports INP starting with JavaScript SDK version 7.104.0. It is enabled by default with BrowserTracing in version 8 and later. In version 11, configure collection through the [WebVitals integration](/platforms/javascript/configuration/integrations/webvitals/). The older `enableInp` option is deprecated. [Interaction to Next Paint (INP)](https://web.dev/articles/inp) measures the time from when a user interacts with a page (through a click, tap, or keyboard input) to when the next paint (rendering of content on the screen) occurs. INP aims to assess how quickly users see a response from the website after taking an action, which is crucial for providing a smooth and responsive user experience. diff --git a/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx b/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx index 8da8a9aecd729..0545f0a4f3b2d 100644 --- a/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx +++ b/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx @@ -17,3 +17,5 @@ Sentry.init({ integrations: [Sentry.browserSessionIntegration({ lifecycle: "route" })], }); ``` + +See BrowserSession for lifecycle configuration and session health details. diff --git a/includes/migration/javascript-v11/browser-session-unhandled.mdx b/includes/migration/javascript-v11/browser-session-unhandled.mdx index 1827622d318bb..5ff4021d42066 100644 --- a/includes/migration/javascript-v11/browser-session-unhandled.mdx +++ b/includes/migration/javascript-v11/browser-session-unhandled.mdx @@ -10,3 +10,5 @@ order: 20 --- Sessions affected by an uncaught error are recorded as `unhandled` instead of `crashed`. If you track crash-free session rates or have alerts built on them, expect the rate to shift. + +See BrowserSession for session health details. diff --git a/includes/migration/javascript-v11/browser-user-timing.mdx b/includes/migration/javascript-v11/browser-user-timing.mdx index 45106aad2700e..6897a55acc1b9 100644 --- a/includes/migration/javascript-v11/browser-user-timing.mdx +++ b/includes/migration/javascript-v11/browser-user-timing.mdx @@ -29,3 +29,5 @@ Sentry.init({ ], }); ``` + +See UserTiming for configuration and CDN loading instructions. diff --git a/includes/migration/javascript-v11/browser-web-vital-options.mdx b/includes/migration/javascript-v11/browser-web-vital-options.mdx index f7b759a6e913a..2f4e48b7aaf20 100644 --- a/includes/migration/javascript-v11/browser-web-vital-options.mdx +++ b/includes/migration/javascript-v11/browser-web-vital-options.mdx @@ -1,6 +1,6 @@ --- id: browser-web-vital-options -title: "Standalone CLS and LCP span options were removed" +title: "Web Vitals moved to a dedicated integration" phase: code-changes category: removed-api severity: action-required @@ -9,6 +9,10 @@ platformCategory: browser order: 220 --- -The `_experiments.enableStandalone*Spans` options were removed. CLS and LCP are no longer configurable, and `browserTracingIntegration` no longer accepts an `_experiments` object at all. +The `_experiments.enableStandalone*Spans` options were removed, and `browserTracingIntegration` no longer accepts an `_experiments` object. BrowserTracing automatically adds `webVitalsIntegration` to collect Web Vitals. CLS and LCP are recorded as measurements on the pageload span, or as dedicated spans in stream mode. + +Configure collection through `browserTracingIntegration({ webVitals: { ... } })`. The `enableInp` option is deprecated. Use `webVitals: { ignore: ["inp"] }` to disable INP, or include `"cls"` or `"lcp"` in `ignore` to skip those vitals. If you explicitly add `webVitalsIntegration()`, its options take precedence. + +Soft-navigation vitals are enabled by default in stream mode on supporting browsers. Set `webVitals: { softNavigations: false }` to keep one set of vitals for the page lifetime. Back/forward-cache vitals are also enabled by default in stream mode when BrowserTracing's `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable collection for restores. See WebVitals for requirements. diff --git a/includes/migration/javascript-v11/inp-web-vital-span.mdx b/includes/migration/javascript-v11/inp-web-vital-span.mdx index 5e1eaaabe848e..b46f2b2b6d09c 100644 --- a/includes/migration/javascript-v11/inp-web-vital-span.mdx +++ b/includes/migration/javascript-v11/inp-web-vital-span.mdx @@ -9,4 +9,6 @@ platformCategory: browser order: 80 --- -INP is always sent as a web vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement (built-in dashboards do not need adjustments). +When collected, INP is always sent as a Web Vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement. Built-in dashboards do not need adjustments. + +See WebVitals for collection options and the attributes sent with each vital. diff --git a/includes/migration/javascript-v11/interaction-spans-integration.mdx b/includes/migration/javascript-v11/interaction-spans-integration.mdx index 2abf543870bde..2f814c16d7901 100644 --- a/includes/migration/javascript-v11/interaction-spans-integration.mdx +++ b/includes/migration/javascript-v11/interaction-spans-integration.mdx @@ -30,4 +30,4 @@ Sentry.init({ }); ``` -The `idleTimeout`, `finalTimeout`, and `childSpanTimeout` options of interaction spans are configured on `interactionsIntegration` now, with the same defaults as before. +Configure `idleTimeout`, `finalTimeout`, and `childSpanTimeout` for interaction spans on `interactionsIntegration`, with the same defaults as before. BrowserTracing's timeout options still control pageload and navigation spans. See Interactions for configuration and CDN loading instructions. diff --git a/includes/migration/javascript-v11/track-fetch-stream-performance.mdx b/includes/migration/javascript-v11/track-fetch-stream-performance.mdx index c2dd1eedf5538..167aecfba86c8 100644 --- a/includes/migration/javascript-v11/track-fetch-stream-performance.mdx +++ b/includes/migration/javascript-v11/track-fetch-stream-performance.mdx @@ -29,3 +29,5 @@ Sentry.init({ ], }); ``` + +See FetchStreamPerformance for supported response types and setup instructions. diff --git a/platform-includes/configuration/auto-session-tracking/javascript.mdx b/platform-includes/configuration/auto-session-tracking/javascript.mdx index 253272c211408..11fefd4cbc5a4 100644 --- a/platform-includes/configuration/auto-session-tracking/javascript.mdx +++ b/platform-includes/configuration/auto-session-tracking/javascript.mdx @@ -1,7 +1,8 @@ -By default, the JavaScript Browser SDKs are sending sessions. -We create a session for every page load. For single-page applications, we will create a new session for every navigation change (History API). +JavaScript Browser SDKs track sessions by default. A session starts on page load and continues across client-side navigations. A hard reload or navigation starts a new session. + +Before SDK version 11, the SDK started a new session on each client-side navigation by default. To configure this behavior, see BrowserSession lifecycle. To disable the default sessions handling, disable the `BrowserSession` integration: @@ -37,7 +38,18 @@ Sentry.init({ Sessions are marked as: -- `crashed` if an _unhandled error_ or _unhandled promise rejection_ bubbled up to the global handler. + + +- `unhandled` in the browser if an _unhandled error_ or _unhandled promise rejection_ bubbles up to the global handler. Before SDK version 11, browser sessions used `crashed` for these errors. + + + + + +- `crashed` on the server if an _unhandled error_ or _unhandled promise rejection_ bubbles up to the global handler. + + + - `errored` if the SDK captures an event that contains an exception (this includes manually captured errors). To receive data on user adoption, such as users crash free rate percentage, and the number of users that have adopted a specific release, set the user on the [`initialScope`](/platforms/javascript/configuration/options/#initial-scope) when initializing the SDK. diff --git a/platform-includes/configuration/integrations/javascript.astro.mdx b/platform-includes/configuration/integrations/javascript.astro.mdx index 5d44264f8c76d..a5eb483d43f1d 100644 --- a/platform-includes/configuration/integrations/javascript.astro.mdx +++ b/platform-includes/configuration/integrations/javascript.astro.mdx @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.gatsby.mdx b/platform-includes/configuration/integrations/javascript.gatsby.mdx index 5aff5b73147a2..bf11cd5d8784b 100644 --- a/platform-includes/configuration/integrations/javascript.gatsby.mdx +++ b/platform-includes/configuration/integrations/javascript.gatsby.mdx @@ -13,6 +13,10 @@ | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx index 9ce918e102f78..4e237ce3e233c 100644 --- a/platform-includes/configuration/integrations/javascript.mdx +++ b/platform-includes/configuration/integrations/javascript.mdx @@ -13,6 +13,10 @@ | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`elementTimingIntegration`](./elementtiming) | | | | | | | [`captureConsoleIntegration`](./captureconsole) | | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | diff --git a/platform-includes/configuration/integrations/javascript.nextjs.mdx b/platform-includes/configuration/integrations/javascript.nextjs.mdx index 58b03e0ad63ff..b80523d496b3a 100644 --- a/platform-includes/configuration/integrations/javascript.nextjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nextjs.mdx @@ -27,6 +27,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nuxt.mdx b/platform-includes/configuration/integrations/javascript.nuxt.mdx index 299722eb63186..3af9b312da31e 100644 --- a/platform-includes/configuration/integrations/javascript.nuxt.mdx +++ b/platform-includes/configuration/integrations/javascript.nuxt.mdx @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.remix.mdx b/platform-includes/configuration/integrations/javascript.remix.mdx index b7e2d2dc2a8ab..9d6c7c4c4e047 100644 --- a/platform-includes/configuration/integrations/javascript.remix.mdx +++ b/platform-includes/configuration/integrations/javascript.remix.mdx @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.solidstart.mdx b/platform-includes/configuration/integrations/javascript.solidstart.mdx index a33bc442497a4..873715155f310 100644 --- a/platform-includes/configuration/integrations/javascript.solidstart.mdx +++ b/platform-includes/configuration/integrations/javascript.solidstart.mdx @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.sveltekit.mdx b/platform-includes/configuration/integrations/javascript.sveltekit.mdx index 5f9b60c65be93..9028f20758da0 100644 --- a/platform-includes/configuration/integrations/javascript.sveltekit.mdx +++ b/platform-includes/configuration/integrations/javascript.sveltekit.mdx @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.vue.mdx b/platform-includes/configuration/integrations/javascript.vue.mdx index ecbd989aa0f01..ee901f3067045 100644 --- a/platform-includes/configuration/integrations/javascript.vue.mdx +++ b/platform-includes/configuration/integrations/javascript.vue.mdx @@ -14,6 +14,10 @@ | [`vueIntegration`](./vue) | ✓ | ✓ | ✓ | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.wasm.mdx b/platform-includes/configuration/integrations/javascript.wasm.mdx index ac3c8c7eab56d..b1c80277cfc54 100644 --- a/platform-includes/configuration/integrations/javascript.wasm.mdx +++ b/platform-includes/configuration/integrations/javascript.wasm.mdx @@ -13,6 +13,10 @@ | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/performance/enable-inp-example/javascript.mdx b/platform-includes/performance/enable-inp-example/javascript.mdx index 9182861cab98e..7c64af2750285 100644 --- a/platform-includes/performance/enable-inp-example/javascript.mdx +++ b/platform-includes/performance/enable-inp-example/javascript.mdx @@ -3,7 +3,9 @@ Sentry.init({ // ... integrations: [ Sentry.browserTracingIntegration({ - enableInp: true, + webVitals: { + ignore: ["inp"], + }, }), ], }); From f8405b02f72d7e52952d23f42944dabf3167e9c5 Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Tue, 22 Sep 2026 15:05:49 +0200 Subject: [PATCH 05/48] docs(javascript): Document OpenTelemetry interoperability in v11 (#19458) Document v11 OpenTelemetry support with two setup guides: capture OpenTelemetry API spans through Sentry, or connect an existing OpenTelemetry pipeline to Sentry. The OpenTelemetry Support landing page uses a PageGrid to explain when to choose each setup, its configuration, and how spans reach Sentry. Default Sentry tracing links to the existing tracing docs. Add a separate integration reference for `openTelemetryIntegration()` and `getOtlpTracesEndpoint()`. Preserve the v10 overview, two subpages, and setup examples as versioned docs, with links and snippet references that keep readers on v10. The current setup guides retain their existing URLs. Update HTTP and fetch propagation guidance for the separate tracing pipelines, and remove obsolete ESM loader troubleshooting from the installation guides. Fixes https://linear.app/getsentry/issue/SDK-1470 Fixes https://linear.app/getsentry/issue/SDK-1471 Fixes https://linear.app/getsentry/issue/SDK-1490 ## IS YOUR CHANGE URGENT? - [x] No deadline: Not urgent, can wait up to 1 week+ --- .../configuration/integrations/http.mdx | 2 +- .../configuration/integrations/nodefetch.mdx | 2 +- .../integrations/opentelemetry.mdx | 96 ++++++++ .../javascript/common/install/esm.mdx | 26 --- .../common/opentelemetry/custom-setup.mdx | 180 +++------------ .../opentelemetry/custom-setup__v10.x.mdx | 210 ++++++++++++++++++ .../javascript/common/opentelemetry/index.mdx | 7 +- .../common/opentelemetry/index__v10.x.mdx | 41 ++++ .../using-opentelemetry-apis.mdx | 131 ++--------- .../using-opentelemetry-apis__v10.x.mdx | 152 +++++++++++++ .../javascript/guides/nestjs/install/esm.mdx | 26 --- ...ript.bun.mdx => javascript.bun__v10.x.mdx} | 0 .../{javascript.mdx => javascript__v10.x.mdx} | 0 ...ript.bun.mdx => javascript.bun__v10.x.mdx} | 2 +- .../{javascript.mdx => javascript__v10.x.mdx} | 2 +- ...ript.bun.mdx => javascript.bun__v10.x.mdx} | 0 .../{javascript.mdx => javascript__v10.x.mdx} | 0 redirects.js | 11 + 18 files changed, 568 insertions(+), 320 deletions(-) create mode 100644 docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx create mode 100644 docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx create mode 100644 docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx create mode 100644 docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx rename platform-includes/performance/opentelemetry-setup/error-monitoring-only/{javascript.bun.mdx => javascript.bun__v10.x.mdx} (100%) rename platform-includes/performance/opentelemetry-setup/error-monitoring-only/{javascript.mdx => javascript__v10.x.mdx} (100%) rename platform-includes/performance/opentelemetry-setup/{javascript.bun.mdx => javascript.bun__v10.x.mdx} (95%) rename platform-includes/performance/opentelemetry-setup/{javascript.mdx => javascript__v10.x.mdx} (94%) rename platform-includes/performance/opentelemetry-setup/with-custom-sampler/{javascript.bun.mdx => javascript.bun__v10.x.mdx} (100%) rename platform-includes/performance/opentelemetry-setup/with-custom-sampler/{javascript.mdx => javascript__v10.x.mdx} (100%) diff --git a/docs/platforms/javascript/common/configuration/integrations/http.mdx b/docs/platforms/javascript/common/configuration/integrations/http.mdx index c3666472ad12d..31c73e77d9f6e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/http.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/http.mdx @@ -93,7 +93,7 @@ The callback function receives two arguments: _Type: `boolean`_ (Defaults to `true`) -Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing HTTP requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). This is useful when `skipOpenTelemetrySetup: true` is configured and your external OpenTelemetry setup already handles trace propagation, to avoid duplicate headers. +Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing HTTP requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). With `openTelemetryIntegration()` enabled and Sentry tracing off, your OpenTelemetry propagator already handles outgoing trace propagation. ### `ignoreOutgoingRequests` diff --git a/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx b/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx index e18f6fea19c0b..1314528f41519 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx @@ -61,7 +61,7 @@ If set to false, no breadcrumbs will be captured. _Type: `boolean`_ (Defaults to `true`) -Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing fetch requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). This is useful when `skipOpenTelemetrySetup: true` is configured and your external OpenTelemetry setup already handles trace propagation, to avoid duplicate headers. +Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing fetch requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). With `openTelemetryIntegration()` enabled and Sentry tracing off, your OpenTelemetry propagator already handles outgoing trace propagation. ### `ignoreOutgoingRequests` diff --git a/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx b/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx new file mode 100644 index 0000000000000..5c38402902538 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx @@ -0,0 +1,96 @@ +--- +title: OpenTelemetry +description: "Connect Sentry to an OpenTelemetry setup that owns tracing." +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +--- + + + +_Import name: `Sentry.openTelemetryIntegration`_ + +This integration is not enabled by default. Use it when OpenTelemetry owns tracing in your application and you want Sentry's errors, logs, metrics, and check-ins to land on the same traces. + +Everything Sentry sends that carries trace information is attached to the OpenTelemetry span that's active when it happens, so it shows up on the same trace as the spans your OpenTelemetry SDK exports. Outgoing request propagation is left to your OpenTelemetry propagator. + +An active Sentry span still takes precedence, so this only changes what happens when Sentry has no span of its own. If there is no active OpenTelemetry span, or its span context is invalid, Sentry uses its own trace context. + + + +This integration sends no spans. To get your OpenTelemetry spans into Sentry, point your own exporter at Sentry's OTLP endpoint with `getOtlpTracesEndpoint()`, as shown below. + + + +## Configure + +This integration runs on the server and takes no options. Leave Sentry tracing off so the two pipelines stay separate. `getOtlpTracesEndpoint()` turns your DSN into the URL and authentication headers of Sentry's OTLP endpoint: + +```javascript {filename: instrument.mjs} +import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; +import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"; +import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; +import * as Sentry from "___SDK_PACKAGE___"; + +const dsn = "___PUBLIC_DSN___"; +const endpoint = Sentry.getOtlpTracesEndpoint(dsn); + +if (!endpoint) { + throw new Error("Could not parse the Sentry DSN"); +} + +const provider = new NodeTracerProvider({ + spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter(endpoint))], +}); + +provider.register(); + +Sentry.init({ + dsn, + // Leave the OpenTelemetry setup to your own provider. + enableOpenTelemetrySetup: false, + // Leave tracesSampleRate and tracesSampler unset. OpenTelemetry owns spans. + integrations: [Sentry.openTelemetryIntegration()], +}); +``` + +If you already have a provider, add the exporter to that provider instead of registering a second one. Initialize OpenTelemetry before calling `Sentry.init()`. In frameworks with their own instrumentation entry point, initialize both there in that order. + +Set `enableOpenTelemetrySetup: false`. Leave `tracesSampleRate` and `tracesSampler` unset to keep Sentry tracing off. + +For sampling guidance, see the OpenTelemetry setup guide. + +## `getOtlpTracesEndpoint` + +`Sentry.getOtlpTracesEndpoint(dsn)` converts a Sentry DSN into configuration for an OpenTelemetry HTTP trace exporter. It takes a DSN string and returns an object with these fields: + +| Field | Type | Description | +| --------- | ------------------------ | ------------------------------------------------------------------- | +| `url` | `string` | The project's Sentry OTLP traces endpoint. | +| `headers` | `Record` | Authentication headers for the endpoint, including `X-Sentry-Auth`. | + +If the helper cannot parse the DSN, it returns `undefined`. The helper does not register a provider or send spans. + +Pass the result to `OTLPTraceExporter` and add it to your provider with a `BatchSpanProcessor`, as shown in the [configuration example](#configure). If you only want to associate Sentry errors with traces exported elsewhere, keep your existing exporter and omit this helper. diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index d222a843810b8..1e94c9aadb69c 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -52,29 +52,3 @@ on `--import` or `NODE_OPTIONS`, use the +Keep your own provider, context manager, propagator, instrumentation, and exporters when OpenTelemetry manages tracing. Add `Sentry.openTelemetryIntegration()` to associate Sentry errors, logs, metrics, and cron check-ins with the active OpenTelemetry span. -Use this guide when you already have a completely custom OpenTelemetry setup or when you intend to add a custom OpenTelemetry setup next to the Sentry SDK. +Set `enableOpenTelemetrySetup: false` and leave both `tracesSampleRate` and `tracesSampler` unset. This disables Sentry tracing and prevents duplicate spans for the same operations. Sentry's instrumentation still isolates requests and captures errors. -Setting `skipOpenTelemetrySetup: true` disables the Sentry SDK's automatic OpenTelemetry configuration, **requiring** you to perform the setup manually. For example, to ensure errors are correctly associated with their scope, you must add the `SentryContextManager` to your OpenTelemetry setup. You can find details on the required manual setup further down on this page. +Initialize your OpenTelemetry provider before calling `Sentry.init()`. -If you are looking to simply add individual OpenTelemetry instrumentation to your Sentry setup, you should read Adding Additional OpenTelemetry Instrumentation instead. +## Send OpenTelemetry Spans to Sentry - +Add an OTLP exporter to your existing provider. Install `@opentelemetry/exporter-trace-otlp-http` if you do not already use it. `Sentry.getOtlpTracesEndpoint()` supplies the endpoint URL and authentication headers for your DSN. - - +This example uses `NodeTracerProvider`. Add the same span processor to `spanProcessors` if you use `NodeSDK` instead. Keep your existing sampler, propagator, context manager, and instrumentation; do not register a second provider. -If you don't need the full `@sentry/node` SDK and want a simpler way to bridge your existing OpenTelemetry setup with Sentry, consider using lightweight mode with the OTLP integration instead. It requires significantly less manual wiring. +```javascript {filename: instrument.mjs} +import * as Sentry from "___SDK_PACKAGE___"; +import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; +import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"; +import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; - - +const dsn = "___PUBLIC_DSN___"; +const endpoint = Sentry.getOtlpTracesEndpoint(dsn); - +if (!endpoint) { + throw new Error("Could not parse the Sentry DSN"); +} -## Using Sentry for Error Monitoring Only - -If you have a custom OpenTelemetry setup and only want to use Sentry for error monitoring, you can skip adding the `SentrySpanProcessor`. You'll still need to add the `SentryContextManager`, `SentryPropagator`, and `SentrySampler` to your setup even if you don't want to send any tracing data to Sentry. Read on to learn why this is needed. - -In order for the Sentry SDK to work as expected, and for it to be in sync with OpenTelemetry, we need a few components to be in place. - -**Components needed for Sentry to work correctly:** - -- **SentryContextManager**: Ensures that the OpenTelemetry context is in sync with Sentry, for example to correctly isolate data between simultaneous requests. -- **SentrySampler**: Ensures that the Sentry `tracesSampleRate` is respected. Even if you don't use Sentry for tracing, you'll still need this in order for trace propagation to work as expected. Read [Using a Custom Sampler](./#using-a-custom-sampler) if you want to use a custom sampler. -- **SentryPropagator**: Ensures that trace propagation works correctly. -- [Required Instrumentation](./#required-instrumentation): Ensures that trace propagation works correctly. - -**Additional components needed to also use Sentry for tracing:** - -- **SentrySpanProcessor**: Ensures that spans are correctly sent to Sentry. - - - Trace propagation is needed for Sentry to automatically connect services - together. (For example, if you want to connect the frontend and backend, or - different backend services.) This makes it possible to see related errors - across services.{" "} - - Learn more about Trace Propagation. - - - -The following code snippet shows how to set up Sentry for error monitoring only: - - - -## Required Instrumentation - -By default, Sentry will register OpenTelemetry instrumentation to automatically capture spans for traces spanning incoming and outgoing HTTP requests, DB queries, and more. - -If tracing is not enabled (no `tracesSampleRate` is defined in the SDK configuration), only a minimal amount of OpenTelemetry instrumentation will be registered. This includes the following: - -{/* prettier-ignore-start */} - -- A Sentry-specific HTTP instrumentation that handles request isolation and trace propagation. This can work in parallel with [@opentelemetry/instrumentation-http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http), if you register it. -- [nativeNodeFetchIntegration](/platforms/javascript/guides/node/configuration/integrations/nodefetch/) registers [opentelemetry-instrumentation-fetch-node](https://www.npmjs.com/package/opentelemetry-instrumentation-fetch-node) which is needed for trace propagation. - -{/* prettier-ignore-end */} - - - - If tracing is not enabled, performance instrumentations will not be - registered but they will still be included in the bundle. If you want to - reduce the bundle size or used dependencies, you can also{" "} - - Set up Sentry without Performance Integrations - - - - -These are needed to make sure that trace propagation works correctly. - -If you want to add your own http/node-fetch instrumentation, you have to follow the following steps: - -### Custom HTTP Instrumentation - - - -You can add your own `@opentelemetry/instrumentation-http` instance in your OpenTelemetry setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`. You can also set `tracePropagation: false` to prevent Sentry from injecting trace headers, letting your OpenTelemetry setup handle propagation instead: - - - ```javascript - const sentryClient = Sentry.init({ - dsn: "___DSN___", - skipOpenTelemetrySetup: true, - integrations: [Sentry.httpIntegration({ spans: false, tracePropagation: false })], -}); - ``` - - - -```javascript - const sentryClient = Sentry.init({ - dsn: "___DSN___", - skipOpenTelemetrySetup: true, - integrations: (integrations) => - // Also filter out the BunServer integration to avoid emitting duplicated spans from Sentry AND your custom OTel instrumentation - integrations.filter((i) => i.name !== "BunServer") +const provider = new NodeTracerProvider({ + spanProcessors: [ + new BatchSpanProcessor(new OTLPTraceExporter(endpoint)), + // Keep any other span processors you already use. + ], }); -``` - - -It's important that `httpIntegration` is still registered this way to ensure that the Sentry SDK can correctly isolate requests, for example when capturing errors. -### Custom Node Fetch Instrumentation +provider.register(); -If tracing is disabled, the Node Fetch instrumentation will not emit any spans. In this scenario, it will only inject sentry-specific trace propagation headers. You are free to add your own Node Fetch instrumentation on top of this which may emit spans as you like. - -If your OpenTelemetry setup already handles trace propagation for fetch requests, you can set `tracePropagation: false` to prevent Sentry from injecting duplicate trace headers: - -```javascript -const sentryClient = Sentry.init({ - dsn: "___DSN___", - skipOpenTelemetrySetup: true, - integrations: [ - Sentry.nativeNodeFetchIntegration({ tracePropagation: false }), - ], +Sentry.init({ + dsn, + enableOpenTelemetrySetup: false, + // Leave tracesSampleRate and tracesSampler unset. OpenTelemetry owns tracing. + integrations: [Sentry.openTelemetryIntegration()], }); ``` -## Using a Custom Sampler - -While you can use your own sampler, we recommend that you use the `SentrySampler`. This will ensure that the correct subset of traces will be sent to Sentry, based on your `tracesSampleRate`. It will also ensure that all other Sentry features like trace propagation work as expected. If you do need to use your own sampler, make sure to wrap your `SamplingResult` with our `wrapSamplingDecision` method like in the example below: - - - - - -It is recommended registering your own ESM loader hooks when you have a complete custom OpenTelemetry setup, first and foremost because it makes the most sense architecturally. -You likely went through the effort to set up OpenTelemetry by itself and now you want to add Sentry to your application without messing with your OpenTelemetry setup. - -Additionally, there are a few pitfalls that can very simply be avoided by registering your own hooks: +## Use Sentry for Error Monitoring Only -- Registering loader hooks multiple times might result in duplicated spans being created. [More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961) -- OpenTelemetry instrumentation in ESM is very sensitive as to _when_ it is added relative to _when_ the loader hooks are registered. - The control over this should stay with the owner of the OpenTelemetry setup and not the Sentry SDK. +If your traces go elsewhere, keep your existing OpenTelemetry exporter and omit the Sentry OTLP exporter from the example above. The `Sentry.init()` configuration stays the same. `openTelemetryIntegration()` links Sentry errors to the active OpenTelemetry trace without sending spans to Sentry. - +## Configure Sampling - - - - Learn more about ESM installation methods. - - - +Configure sampling on your OpenTelemetry provider. Sentry's `tracesSampleRate` and `tracesSampler` do not control spans exported over OTLP. Use an OpenTelemetry sampler or your own implementation of its `Sampler` interface. diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx new file mode 100644 index 0000000000000..0499cec6813aa --- /dev/null +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx @@ -0,0 +1,210 @@ +--- +title: Using Your Existing OpenTelemetry Setup +description: "Learn how to use your existing custom OpenTelemetry setup with Sentry." +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +sidebar_order: 0 +--- + + + +Use this guide when you already have a completely custom OpenTelemetry setup or when you intend to add a custom OpenTelemetry setup next to the Sentry SDK. + +Setting `skipOpenTelemetrySetup: true` disables the Sentry SDK's automatic OpenTelemetry configuration, **requiring** you to perform the setup manually. For example, to ensure errors are correctly associated with their scope, you must add the `SentryContextManager` to your OpenTelemetry setup. You can find details on the required manual setup further down on this page. + +If you are looking to simply add individual OpenTelemetry instrumentation to your Sentry setup, you should read Adding Additional OpenTelemetry Instrumentation instead. + + + + + + +If you don't need the full `@sentry/node` SDK and want a simpler way to bridge your existing OpenTelemetry setup with Sentry, consider using lightweight mode with the OTLP integration instead. It requires significantly less manual wiring. + + + + + + + + + + + + +## Using Sentry for Error Monitoring Only + +If you have a custom OpenTelemetry setup and only want to use Sentry for error monitoring, you can skip adding the `SentrySpanProcessor`. You'll still need to add the `SentryContextManager`, `SentryPropagator`, and `SentrySampler` to your setup even if you don't want to send any tracing data to Sentry. Read on to learn why this is needed. + +In order for the Sentry SDK to work as expected, and for it to be in sync with OpenTelemetry, we need a few components to be in place. + +**Components needed for Sentry to work correctly:** + +- **SentryContextManager**: Ensures that the OpenTelemetry context is in sync with Sentry, for example to correctly isolate data between simultaneous requests. +- **SentrySampler**: Ensures that the Sentry `tracesSampleRate` is respected. Even if you don't use Sentry for tracing, you'll still need this in order for trace propagation to work as expected. Read [Using a Custom Sampler](#using-a-custom-sampler) if you want to use a custom sampler. +- **SentryPropagator**: Ensures that trace propagation works correctly. +- [Required Instrumentation](#required-instrumentation): Ensures that trace propagation works correctly. + +**Additional components needed to also use Sentry for tracing:** + +- **SentrySpanProcessor**: Ensures that spans are correctly sent to Sentry. + + + Trace propagation is needed for Sentry to automatically connect services + together. (For example, if you want to connect the frontend and backend, or + different backend services.) This makes it possible to see related errors + across services.{" "} + + Learn more about Trace Propagation. + + + +The following code snippet shows how to set up Sentry for error monitoring only: + + + + + + + + + +## Required Instrumentation + +By default, Sentry will register OpenTelemetry instrumentation to automatically capture spans for traces spanning incoming and outgoing HTTP requests, DB queries, and more. + +If tracing is not enabled (no `tracesSampleRate` is defined in the SDK configuration), only a minimal amount of OpenTelemetry instrumentation will be registered. This includes the following: + +{/* prettier-ignore-start */} + +- A Sentry-specific HTTP instrumentation that handles request isolation and trace propagation. This can work in parallel with [@opentelemetry/instrumentation-http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http), if you register it. +- [nativeNodeFetchIntegration](/platforms/javascript/guides/node/configuration/integrations/nodefetch/) registers [opentelemetry-instrumentation-fetch-node](https://www.npmjs.com/package/opentelemetry-instrumentation-fetch-node) which is needed for trace propagation. + +{/* prettier-ignore-end */} + + + + If tracing is not enabled, performance instrumentations will not be + registered but they will still be included in the bundle. If you want to + reduce the bundle size or used dependencies, you can also{" "} + + Set up Sentry without Performance Integrations + + + + +These are needed to make sure that trace propagation works correctly. + +If you want to add your own http/node-fetch instrumentation, you have to follow the following steps: + +### Custom HTTP Instrumentation + + + +You can add your own `@opentelemetry/instrumentation-http` instance in your OpenTelemetry setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`. You can also set `tracePropagation: false` to prevent Sentry from injecting trace headers, letting your OpenTelemetry setup handle propagation instead: + + + ```javascript + const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: [Sentry.httpIntegration({ spans: false, tracePropagation: false })], +}); + ``` + + + +```javascript + const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: (integrations) => + // Also filter out the BunServer integration to avoid emitting duplicated spans from Sentry AND your custom OTel instrumentation + integrations.filter((i) => i.name !== "BunServer") +}); +``` + + +It's important that `httpIntegration` is still registered this way to ensure that the Sentry SDK can correctly isolate requests, for example when capturing errors. + +### Custom Node Fetch Instrumentation + +If tracing is disabled, the Node Fetch instrumentation will not emit any spans. In this scenario, it will only inject sentry-specific trace propagation headers. You are free to add your own Node Fetch instrumentation on top of this which may emit spans as you like. + +If your OpenTelemetry setup already handles trace propagation for fetch requests, you can set `tracePropagation: false` to prevent Sentry from injecting duplicate trace headers: + +```javascript +const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: [ + Sentry.nativeNodeFetchIntegration({ tracePropagation: false }), + ], +}); +``` + +## Using a Custom Sampler + +While you can use your own sampler, we recommend that you use the `SentrySampler`. This will ensure that the correct subset of traces will be sent to Sentry, based on your `tracesSampleRate`. It will also ensure that all other Sentry features like trace propagation work as expected. If you do need to use your own sampler, make sure to wrap your `SamplingResult` with our `wrapSamplingDecision` method like in the example below: + + + + + + + + + + + +It is recommended registering your own ESM loader hooks when you have a complete custom OpenTelemetry setup, first and foremost because it makes the most sense architecturally. +You likely went through the effort to set up OpenTelemetry by itself and now you want to add Sentry to your application without messing with your OpenTelemetry setup. + +Additionally, there are a few pitfalls that can very simply be avoided by registering your own hooks: + +- Registering loader hooks multiple times might result in duplicated spans being created. [More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961) +- OpenTelemetry instrumentation in ESM is very sensitive as to _when_ it is added relative to _when_ the loader hooks are registered. + The control over this should stay with the owner of the OpenTelemetry setup and not the Sentry SDK. + + + + + + + Learn more about ESM installation methods. + + + diff --git a/docs/platforms/javascript/common/opentelemetry/index.mdx b/docs/platforms/javascript/common/opentelemetry/index.mdx index fbde8fe769b4c..9416efde7d57a 100644 --- a/docs/platforms/javascript/common/opentelemetry/index.mdx +++ b/docs/platforms/javascript/common/opentelemetry/index.mdx @@ -29,13 +29,10 @@ supported: - javascript.tanstackstart-react notSupported: - javascript -beta: true --- -The Sentry SDK uses [OpenTelemetry](https://opentelemetry.io/) under the hood. This means that any OpenTelemetry instrumentation that emits spans will automatically be picked up by Sentry without any further configuration. +The Sentry JavaScript SDK creates and sends spans without an OpenTelemetry pipeline. For the default setup, see Tracing. -To start capturing traces and spans, set up Tracing and Performance Monitoring with your Sentry SDK. If you don't use tracing, Sentry still connects to OpenTelemetry under the hood to ensure that context isolation and trace propagation works correctly. - -By default, Sentry will automatically set up OpenTelemetry for you, but you can also use your own OpenTelemetry setup. Read the guides below to learn how to use a custom OpenTelemetry setup or how to get the most out of the Sentry and OpenTelemetry integration. +If your application also uses OpenTelemetry, choose a setup based on which SDK manages tracing: diff --git a/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx new file mode 100644 index 0000000000000..57eb7542bc1b9 --- /dev/null +++ b/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx @@ -0,0 +1,41 @@ +--- +title: OpenTelemetry Support +description: "Learn how to use OpenTelemetry with Sentry." +sidebar_order: 14 +sidebar_section: configuration +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +beta: true +--- + +The Sentry SDK uses [OpenTelemetry](https://opentelemetry.io/) under the hood. This means that any OpenTelemetry instrumentation that emits spans will automatically be picked up by Sentry without any further configuration. + +To start capturing traces and spans, set up Tracing and Performance Monitoring with your Sentry SDK. If you don't use tracing, Sentry still connects to OpenTelemetry under the hood to ensure that context isolation and trace propagation works correctly. + +By default, Sentry will automatically set up OpenTelemetry for you, but you can also use your own OpenTelemetry setup. Read the guides below to learn how to use a custom OpenTelemetry setup or how to get the most out of the Sentry and OpenTelemetry integration. + +- Using Your Existing OpenTelemetry Setup +- Using OpenTelemetry APIs diff --git a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx index 40bc8d5179743..0a1db82c1b4f7 100644 --- a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx +++ b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx @@ -1,6 +1,7 @@ --- -title: Using OpenTelemetry APIs -description: "Learn how to use OpenTelemetry APIs with Sentry." +title: Capture Spans from OpenTelemetry APIs +description: "Let Sentry capture and send spans created by OpenTelemetry APIs." +sidebar_order: 0 supported: - javascript.nextjs - javascript.node @@ -27,127 +28,31 @@ supported: - javascript.tanstackstart-react notSupported: - javascript -sidebar_order: 1 --- -Sentry supports OpenTelemetry APIs out of the box. Any spans started using OpenTelemetry APIs will be automatically captured by Sentry, while any spans started using the Sentry SDK will be automatically propagated to OpenTelemetry. +To capture spans that your code or a library creates through `@opentelemetry/api`, set `enableOpenTelemetrySetup: true`. Sentry registers an OpenTelemetry-compatible tracer provider, context manager, and propagator. Spans created through `@opentelemetry/api` become native Sentry spans. Sentry's tracing configuration controls sampling and export. -## Adding Additional OpenTelemetry Instrumentation - -While the Sentry SDK includes some OpenTelemetry instrumentation out of the box, you may want to add additional instrumentation to your application. This can be done by registering the instrumentation through OpenTelemetry like the example below: - -```javascript {tabTitle: ESM} {12-13} -import * as Sentry from "@sentry/node"; -import { - GenericPoolInstrumentation, -} from "@opentelemetry/instrumentation-generic-pool"; +```javascript +import * as Sentry from "___SDK_PACKAGE___"; +import { trace } from "@opentelemetry/api"; Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample + dsn: "___PUBLIC_DSN___", + enableOpenTelemetrySetup: true, tracesSampleRate: 1.0, - - // Add additional OpenTelemetry instrumentation: - openTelemetryInstrumentations: [new GenericPoolInstrumentation()], -}); -``` -```javascript {tabTitle: CJS} {12-13} -const Sentry = require("@sentry/node"); -const { - GenericPoolInstrumentation, -} = require("@opentelemetry/instrumentation-generic-pool"); - -Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample - tracesSampleRate: 1.0, - - // Add additional OpenTelemetry instrumentation: - openTelemetryInstrumentations: [new GenericPoolInstrumentation()], -}); -``` - - - It is possible to add instrumentations via `registerInstrumentations()` from - `@opentelemetry/instrumentation`. However, with ESM (`import`/`export` syntax) - you need to be careful to do so before importing any modules that should be - instrumented. - -As a rule of thumb, `registerInstrumentations()` should be called right after, and in the same context as registering ESM Loaders. - - - -## Using an OpenTelemetry Tracer - -We recommend using `Sentry.startSpan()` and related APIs to create spans, but you can also create spans using native OpenTelemetry APIs. - -You can access the tracer Sentry uses via `client.tracer` and then create spans with OpenTelemetry APIs, as shown below: - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/node"; - -const tracer = Sentry.getClient()?.tracer; -// Now you can use native APIs on the tracer: -tracer.startActiveSpan("span name", () => { - // measure something -}); -``` -```javascript {tabTitle: CJS} -const Sentry = require("@sentry/node"); - -const tracer = Sentry.getClient()?.tracer; -// Now you can use native APIs on the tracer: -tracer.startActiveSpan("span name", () => { - // measure something }); -``` - -You can also use any other tracer. All OpenTelemetry spans will be picked up by Sentry automatically. - -## Modifying the default OpenTelemetry TracerProvider - -You can access the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/node"; - -const provider = Sentry.getClient()?.traceProvider; -``` -```javascript {tabTitle: CJS} -const Sentry = require("@sentry/node"); - -const provider = Sentry.getClient()?.traceProvider; -``` -## Adding Additional Span Processors +const tracer = trace.getTracer("my-app"); -You can add additional span processors to the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample - tracesSampleRate: 1.0, - - // Add additional OpenTelemetry SpanProcessors: - openTelemetrySpanProcessors: [new MySpanProcessor()], +tracer.startActiveSpan("process-order", (span) => { + try { + // Your synchronous work here. + } finally { + span.end(); + } }); ``` -```javascript {tabTitle: CJS} -const Sentry = require("@sentry/node"); -Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample - tracesSampleRate: 1.0, +Initialize Sentry before the application creates spans. This setup sends spans through Sentry's transport; it does not create an OTLP exporter. If your application already registers an OpenTelemetry provider, use your own OpenTelemetry pipeline instead. Sentry will not replace an existing provider. - // Add additional OpenTelemetry SpanProcessors: - openTelemetrySpanProcessors: [new MySpanProcessor()], -}); -``` +Most server SDKs leave `enableOpenTelemetrySetup` off by default. The `@sentry/nextjs` and `@sentry/sveltekit` SDKs enable it by default to capture spans emitted by those frameworks. diff --git a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx new file mode 100644 index 0000000000000..d114441401a19 --- /dev/null +++ b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx @@ -0,0 +1,152 @@ +--- +title: Using OpenTelemetry APIs +description: "Learn how to use OpenTelemetry APIs with Sentry." +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +sidebar_order: 1 +--- + +Sentry supports OpenTelemetry APIs out of the box. Any spans started using OpenTelemetry APIs will be automatically captured by Sentry, while any spans started using the Sentry SDK will be automatically propagated to OpenTelemetry. + +## Adding Additional OpenTelemetry Instrumentation + +While the Sentry SDK includes some OpenTelemetry instrumentation out of the box, you may want to add additional instrumentation to your application. This can be done by registering the instrumentation through OpenTelemetry like the example below: + +```javascript {tabTitle: ESM} {12-13} +import * as Sentry from "@sentry/node"; +import { + GenericPoolInstrumentation, +} from "@opentelemetry/instrumentation-generic-pool"; + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry instrumentation: + openTelemetryInstrumentations: [new GenericPoolInstrumentation()], +}); +``` +```javascript {tabTitle: CJS} {12-13} +const Sentry = require("@sentry/node"); +const { + GenericPoolInstrumentation, +} = require("@opentelemetry/instrumentation-generic-pool"); + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry instrumentation: + openTelemetryInstrumentations: [new GenericPoolInstrumentation()], +}); +``` + + + It is possible to add instrumentations via `registerInstrumentations()` from + `@opentelemetry/instrumentation`. However, with ESM (`import`/`export` syntax) + you need to be careful to do so before importing any modules that should be + instrumented. + +As a rule of thumb, `registerInstrumentations()` should be called right after, and in the same context as registering ESM Loaders. + + + +## Using an OpenTelemetry Tracer + +We recommend using `Sentry.startSpan()` and related APIs to create spans, but you can also create spans using native OpenTelemetry APIs. + +You can access the tracer Sentry uses via `client.tracer` and then create spans with OpenTelemetry APIs, as shown below: + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/node"; + +const tracer = Sentry.getClient()?.tracer; +// Now you can use native APIs on the tracer: +tracer.startActiveSpan("span name", () => { + // measure something +}); +``` +```javascript {tabTitle: CJS} +const Sentry = require("@sentry/node"); + +const tracer = Sentry.getClient()?.tracer; +// Now you can use native APIs on the tracer: +tracer.startActiveSpan("span name", () => { + // measure something +}); +``` + +You can also use any other tracer. All OpenTelemetry spans will be picked up by Sentry automatically. + +## Modifying the default OpenTelemetry TracerProvider + +You can access the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/node"; + +const provider = Sentry.getClient()?.traceProvider; +``` +```javascript {tabTitle: CJS} +const Sentry = require("@sentry/node"); + +const provider = Sentry.getClient()?.traceProvider; +``` + +## Adding Additional Span Processors + +You can add additional span processors to the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/node"; + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry SpanProcessors: + openTelemetrySpanProcessors: [new MySpanProcessor()], +}); +``` +```javascript {tabTitle: CJS} +const Sentry = require("@sentry/node"); + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry SpanProcessors: + openTelemetrySpanProcessors: [new MySpanProcessor()], +}); +``` diff --git a/docs/platforms/javascript/guides/nestjs/install/esm.mdx b/docs/platforms/javascript/guides/nestjs/install/esm.mdx index 9ba9ba454e9a0..fb036cb73ad7a 100644 --- a/docs/platforms/javascript/guides/nestjs/install/esm.mdx +++ b/docs/platforms/javascript/guides/nestjs/install/esm.mdx @@ -42,29 +42,3 @@ NODE_OPTIONS="--import ./instrument.mjs" npm run start ``` We do not support ESM in Node versions before 18.19.0. - -## Troubleshooting ESM Instrumentation - -By default, all packages are automatically wrapped by -[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to -aid instrumenting them. - -If `import-in-the-middle` encounters problems wrapping a package, you may see -syntax errors at runtime or logged errors in your console: - -```logs -SyntaxError: The requested module '...' does not provide an export named '...' -(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js' -``` - -To confirm that these errors are caused by `import-in-the-middle`, -disable it by setting `registerEsmLoaderHooks` to false. Note, this will also -disable tracing instrumentation: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} {4} -import * as Sentry from "@sentry/nestjs"; - -Sentry.init({ - registerEsmLoaderHooks: false, -}); -``` diff --git a/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun.mdx b/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun.mdx rename to platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun__v10.x.mdx diff --git a/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.mdx b/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.mdx rename to platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript__v10.x.mdx diff --git a/platform-includes/performance/opentelemetry-setup/javascript.bun.mdx b/platform-includes/performance/opentelemetry-setup/javascript.bun__v10.x.mdx similarity index 95% rename from platform-includes/performance/opentelemetry-setup/javascript.bun.mdx rename to platform-includes/performance/opentelemetry-setup/javascript.bun__v10.x.mdx index 4927978b8dd07..8a9c210fb0eba 100644 --- a/platform-includes/performance/opentelemetry-setup/javascript.bun.mdx +++ b/platform-includes/performance/opentelemetry-setup/javascript.bun__v10.x.mdx @@ -83,4 +83,4 @@ sdk.start(); validateOpenTelemetrySetup(); ``` -Make sure that all [Required OpenTelemetry Instrumentation](./#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. +Make sure that all [Required OpenTelemetry Instrumentation](#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. diff --git a/platform-includes/performance/opentelemetry-setup/javascript.mdx b/platform-includes/performance/opentelemetry-setup/javascript__v10.x.mdx similarity index 94% rename from platform-includes/performance/opentelemetry-setup/javascript.mdx rename to platform-includes/performance/opentelemetry-setup/javascript__v10.x.mdx index 8e89e864d6d5b..70515a91aa4d2 100644 --- a/platform-includes/performance/opentelemetry-setup/javascript.mdx +++ b/platform-includes/performance/opentelemetry-setup/javascript__v10.x.mdx @@ -75,4 +75,4 @@ sdk.start(); Sentry.validateOpenTelemetrySetup(); ``` -Make sure that all [Required OpenTelemetry Instrumentation](./#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. +Make sure that all [Required OpenTelemetry Instrumentation](#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. diff --git a/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun.mdx b/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun.mdx rename to platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun__v10.x.mdx diff --git a/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.mdx b/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.mdx rename to platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript__v10.x.mdx diff --git a/redirects.js b/redirects.js index ce4a3cae7c455..c886196053f4d 100644 --- a/redirects.js +++ b/redirects.js @@ -588,6 +588,17 @@ const developerDocsRedirects = [ /** @type {import('next/dist/lib/load-custom-routes').Redirect[]} */ const userDocsRedirects = [ + { + source: '/platforms/javascript/guides/:guide/opentelemetry/integration/', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/:guide/opentelemetry/integration.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/opentelemetry.md', + }, + // Guides → Get Started restructure { source: '/guides/', From 79bbd291f4814c0d55b75cb5b3fed805cb83cb35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 16:14:38 +0300 Subject: [PATCH 06/48] docs(js): Restructure the Node install methods for v11 (#19368) ## DESCRIBE YOUR PR closes SDK-1494 (kept the version v18 ranges as they ill be removed here: https://github.com/getsentry/sentry-docs/pull/19317/) Bring the Node install pages in line with the v11 install methods, and fix the ESM snippets that stop the app from starting. - Fix the extensionless `import "./instrument"` in the Express, Fastify, Hapi and Connect ESM tabs, in `install/esm-without-import.mdx` and in the NestJS ESM page. The config step creates `instrument.mjs`, and Node ESM does not probe extensions, so the app stopped with `ERR_MODULE_NOT_FOUND`. - Start the Koa ESM tab with `--import` instead. With the extension fixed the app starts, but `koa` is already loaded when `Sentry.init` runs, so every router and middleware span and every route name is lost. - Rewrite `install/late-initialization.mdx` around `node --import @sentry/node/import`. The page told readers to use `@sentry/node/preload`, which is no longer exported and fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Drop `SENTRY_PRELOAD_INTEGRATIONS` with it, and show a CommonJS entry point next to the ESM one, since `--import` covers both. - Rework `install/index.mdx` around the three v11 methods: `--import` your instrument file, a bundler plugin with a top-level import, and `--import` the SDK with a later `Sentry.init()`. Say that `--import` covers CommonJS as well, and that `--require` is gone. - Rewrite `install/esm-without-import.mdx` around the bundler plugin and the deferred entry point, and say why a top-level import alone is not equivalent to `--import`. - Remove the `registerEsmLoaderHooks` troubleshooting from `install/esm.mdx`. The option was removed and the SDK no longer depends on `import-in-the-middle`. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5 --- .../common/install/esm-without-import.mdx | 99 +++++++++++----- .../javascript/common/install/esm.mdx | 2 +- .../javascript/common/install/index.mdx | 37 ++++-- .../common/install/late-initialization.mdx | 107 ++++-------------- .../nestjs/install/esm-without-import.mdx | 2 +- .../getting-started-run/javascript.mdx | 4 +- .../javascript.connect.mdx | 2 +- .../javascript.express.mdx | 2 +- .../javascript.fastify.mdx | 2 +- .../getting-started-use/javascript.hapi.mdx | 2 +- .../getting-started-use/javascript.koa.mdx | 6 +- 11 files changed, 128 insertions(+), 137 deletions(-) diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx index a1a742bb750f5..1961f4821cfed 100644 --- a/docs/platforms/javascript/common/install/esm-without-import.mdx +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -17,23 +17,15 @@ supported: [installation methods](../). +When running your application in ESM mode, you'll most likely want to follow the ESM instructions. -When running your application in ESM mode, you will most likely want to follow the ESM instructions. However, if you can't use the `--import` command line option, you can either use [direct imports](#direct-imports) or [SEA bootstrap setup](#nodejs-single-executable-applications) if you are using a Node.js Single Executable Application (SEA). +If you can't pass the `--import` command line option, pick one of these instead: -## Direct Imports +- Use a [bundler plugin with a top-level import](#bundler-plugin-and-top-level-import) if you bundle your server code. +- Use a [deferred entry point](#deferred-entry-point) if you don't bundle it. +- Use the [SEA bootstrap setup](#nodejs-single-executable-applications) if you build a Node.js Single Executable Application. - - - -This installation method has the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module). - -As a result, the Sentry SDK will not capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. - -We recommend using this only if the `--import` flag is not an option for you. - - - -You need to create a file named `instrument.mjs` that imports and initializes Sentry: +All three need an `instrument.mjs` file that initializes Sentry: ```javascript {tabTitle:ESM} {filename: instrument.mjs} import * as Sentry from "@sentry/node"; @@ -48,18 +40,80 @@ Sentry.init({ }); ``` -You need to import the `instrument.mjs` file before importing any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application: +## Why a Top-Level Import Alone Isn't Enough + +ESM evaluates every `import` in a file before it runs the first line of that file. So even when `import "./instrument.mjs"` is written above your other imports, the modules below it are already loaded by the time `Sentry.init()` runs, and the SDK can no longer wrap them. + +What that costs depends on the library. Express, Fastify, Hapi and Hono register their instrumentation at runtime, so they still report spans and errors. Koa does not: it loses its router and middleware spans, its route names, and, without the deprecated `Sentry.setupKoaErrorHandler(app)` call, its error capture. + +The patterns below work around this. The bundler plugin instruments your dependencies at build time, so the order no longer matters. The deferred entry point loads your application only after `Sentry.init()` has run. + +## Bundler Plugin and Top-Level Import + +Instrument your dependencies at build time with the Sentry bundler plugin, then import `instrument.mjs` at the top of your entry point. Because the instrumentation is baked into the bundle, it no longer depends on `Sentry.init()` running before the imports. + +The plugin ships for Vite, Rollup, webpack and esbuild: + +```javascript {tabTitle:Vite} {filename: vite.config.mjs} +import { sentryVitePlugin } from "@sentry/node/vite"; + +export default { + plugins: [sentryVitePlugin()], +}; +``` + +```javascript {tabTitle:Rollup} {filename: rollup.config.mjs} +import { sentryRollupPlugin } from "@sentry/node/rollup"; + +export default { + plugins: [sentryRollupPlugin()], +}; +``` + +```javascript {tabTitle:webpack} {filename: webpack.config.mjs} +import { sentryWebpackPlugin } from "@sentry/node/webpack"; + +export default { + plugins: [sentryWebpackPlugin()], +}; +``` + +```javascript {tabTitle:esbuild} {filename: build.mjs} +import { sentryEsbuildPlugin } from "@sentry/node/esbuild"; + +await esbuild.build({ + plugins: [sentryEsbuildPlugin()], +}); +``` + +Then import your instrument file first: ```javascript {filename: app.mjs} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules -import http from "http"; +import express from "express"; // Your application code goes here ``` +## Deferred Entry Point + +Without a bundler, split the entry point in two. The static import runs `Sentry.init()`, and the dynamic `import()` loads your application afterwards, so your application's modules are wrapped: + +```javascript {filename: main.mjs} +import "./instrument.mjs"; + +await import("./app.mjs"); +``` + +Your application code stays in `app.mjs` and needs no changes. Start it as usual: + +```bash +node main.mjs +``` + ## Node.js Single Executable Applications Node.js Single Executable Applications (SEA) may not load your Sentry instrumentation early enough, so you need to package a small bootstrap file as the SEA main instead of packaging your app entrypoint directly. @@ -85,16 +139,7 @@ async function startApp() { startApp(); ``` -Keep your Sentry setup in `instrument.mjs`: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, -}); -``` +This is the deferred entry point pattern above, packaged for SEA. Keep your Sentry setup in `instrument.mjs`. Then configure SEA to use `sea-main.cjs` as its main script: diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index 1e94c9aadb69c..3a4aeb1862c05 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -34,7 +34,7 @@ Sentry.init({ }); ``` -Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`, which contains your `Sentry.init()` code: +Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.mjs`, which contains your `Sentry.init()` code: ```bash # Note: This is only available for Node v18.19.0 onwards. diff --git a/docs/platforms/javascript/common/install/index.mdx b/docs/platforms/javascript/common/install/index.mdx index 07508f115f535..4c48bc6df0a18 100644 --- a/docs/platforms/javascript/common/install/index.mdx +++ b/docs/platforms/javascript/common/install/index.mdx @@ -39,28 +39,41 @@ notSupported: ## How To Decide Which Installation Method To Use -Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. -CommonJS uses `require()` to load modules. Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. However, if your application is run in ESM mode, this will not work. In this case, you can follow the [ESM docs](./esm). +The SDK has to wrap the modules your application uses before your application imports them. How you arrange that is the only difference between the methods below. `--import` works for both ESM and CommonJS applications, so the module system your application uses no longer decides the method. -Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. In this case, you should follow the [CommonJS instructions](./commonjs). +### Load Your Instrument File With `--import` (Recommended) -### My application is in TypeScript +Put `Sentry.init()` in an instrument file and load it with the `--import` flag: -If you're using TypeScript, your application is likely compiled to CommonJS before running it. In this case, you should follow the [CommonJS instructions](./commonjs). +```bash +node --import ./instrument.mjs app.mjs +``` -### My application uses `require` +This runs `Sentry.init()` before any of your application's modules load, so every instrumented library is wrapped and every error during startup is captured. Use this unless one of the cases below applies to you. -If you are using `require()` in your application, you should follow the [CommonJS instructions](./commonjs). +`--import` works for CommonJS applications too, with an `instrument.js` file: -### My application uses `import` +```bash +node --import ./instrument.js app.js +``` -If you are using `import` in your application, your installation method depends on how your application is _run_. If you compile your application (e.g. into a `/dist` folder or similar) before running this, you need to check how the compiled code looks like. Is the compiled code using `require`? Then you should follow the [CommonJS instructions](./commonjs). If the compiled code is using `import`, you should follow the [ESM instructions](./esm). +Note that `--require` is no longer supported for initialization. See ESM (MJS) and CommonJS (CJS). -If you do not compile your code, you'll need to follow the [ESM instructions](./esm). +### Bundler Plugin and a Top-Level Import -### I don't need automatic spans/transactions +If you can't pass a flag to the Node.js binary, instrument your dependencies at build time with the Sentry bundler plugin and import `instrument.mjs` at the top of your entry file. See ESM without CLI Flag. -If you don't need spans emitted by OpenTelemetry instrumentation, you can use `@sentry/node-core` in [Lightweight Mode](./lightweight) without OpenTelemetry dependencies. You still get errors, logs, metrics, breadcrumbs, and more. This mode is experimental. +A top-level import on its own isn't equivalent to `--import`, because ESM evaluates every import in a file before it runs the first line of that file. That page explains what you lose and how to avoid it. + +### Load the SDK With `--import` and Initialize Later + +If you can't call `Sentry.init()` at startup, for example because you fetch your DSN from an external source, `--import` the SDK itself and call `Sentry.init()` at a later point: + +```bash +node --import @sentry/node/import main.mjs +``` + +See Late Initialization. diff --git a/docs/platforms/javascript/common/install/late-initialization.mdx b/docs/platforms/javascript/common/install/late-initialization.mdx index 1362f0af7741a..bea0c198f19bc 100644 --- a/docs/platforms/javascript/common/install/late-initialization.mdx +++ b/docs/platforms/javascript/common/install/late-initialization.mdx @@ -17,67 +17,30 @@ supported: [installation methods](../). -In order for auto-instrumentation to work, it is generally required to run `Sentry.init()` as early as possible, before anything else is imported in your application. +For auto-instrumentation to work, `Sentry.init()` normally has to run before anything else is imported in your application. -However, in some cases this may not be possible to do—for example, if you are fetching your DSN from an external source. In this case, you can use the `@sentry/node/preload` hook to ensure modules are wrapped early, which allows you to call `Sentry.init()` later at a time of your choosing. - - - We recommend to only use this method if strictly necessary. In most cases, it - is better to find a way to run `Sentry.init()` early in your application, in - order to ensure that no error can go unreported. - - -This initialization method is available starting in version **8.5.0**. - -## Late Initialization with CommonJS (CJS) - -In your CJS application, use the `@sentry/node/preload` hook with `--require` to ensure modules are wrapped early: +In some cases that isn't possible, for example when you fetch your DSN from an external source. For these cases, `--import` the SDK itself instead of your own instrument file. The SDK then wraps the modules your application imports, and you call `Sentry.init()` later: ```bash -node --require @sentry/node/preload app.js +node --import @sentry/node/import main.mjs ``` -Then, in your application you can call `Sentry.init()` at a later point: - -```javascript {filename: main.js} -const startApp = require("./app"); -const fetchDsn = require("./utils/fetchDsn"); -const Sentry = require("@sentry/node"); - -startApp(); - -const dsn = fetchDsn(); -Sentry.init({ - dsn, - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); - -// From now on, Sentry is initialized, -// but the app is still auto-instrumented -``` - -## Late Initialization with ESM - -In your ESM application, use the `@sentry/node/preload` hook with `--import` to ensure modules are wrapped early: +This works for CommonJS applications as well. `--require` is no longer supported, so use `--import` there too: ```bash -# Note: This is only available for Node v18.19.0 onwards. -node --import @sentry/node/preload app.js +node --import @sentry/node/import app.js ``` -Then, in your application you can call `Sentry.init()` at a later point: +With the flag in place, call `Sentry.init()` at the point of your choosing: -```javascript {filename: main.js} -import startApp from "./app"; -import fetchDsn from "./utils/fetchDsn"; +```javascript {filename: main.mjs} import * as Sentry from "@sentry/node"; +import startApp from "./app.mjs"; +import fetchDsn from "./utils/fetchDsn.mjs"; startApp(); -const dsn = fetchDsn(); +const dsn = await fetchDsn(); Sentry.init({ dsn, @@ -87,47 +50,19 @@ Sentry.init({ }); // From now on, Sentry is initialized, -// but the app is still auto-instrumented -``` - -## What does Preloading mean? - -Integrations that are preloaded ensure that the necessary modules are wrapped early, before they can be imported by your application. At this point, the modules are wrapped, but will not do anything—nothing will be emitted or captured from them. - -Once you call `Sentry.init()`, the wrapped modules will automatically start emitting performance data which will be sent to Sentry. - -## What is Preloaded? - -By default, all performance instrumentation is preloaded when using the `@sentry/node/preload` hook. - -You can optionally configure to only preload certain integrations by defining a `SENTRY_PRELOAD_INTEGRATIONS` environment variable. This variable should be a comma-separated list of integrations to preload. For example, to only preload the `Http` and `Express` integrations, you can set the environment variable as follows: - -```bash -SENTRY_PRELOAD_INTEGRATIONS="Http,Express" node --require @sentry/node/preload app.js +// and the app is still auto-instrumented ``` -You can pass the names of any of the following integrations: - -- `Http` -- `Express` -- `Connect` -- `Fastify` -- `Hapi` -- `Koa` -- `Nest` -- `Mongo` -- `Mongoose` -- `Mysql` -- `Mysql2` -- `Postgres` -- `Graphql` - -Note that it is not necessary to preload `NodeFetch`, this will always be instrumented. + + Use this method only if it's strictly necessary. Anything that happens before + `Sentry.init()` runs isn't captured, so an error thrown during startup goes + unreported. In most cases it's better to find a way to run `Sentry.init()` + early, as described in{" "} + ESM (MJS). + -## Debugging Preload +## What Wrapping Means -You can also define a `SENTRY_DEBUG` environment variable in order to get debug logs from the preload hook. This can be useful to understand what is happening during the preload process. +`--import @sentry/node/import` wraps the modules your application imports before your code runs. At that point the modules are wrapped but inactive: nothing is emitted or captured from them. -```bash -SENTRY_DEBUG=1 node --require @sentry/node/preload app.js -``` +Once you call `Sentry.init()`, the wrapped modules start emitting data to Sentry. diff --git a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx b/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx index 3c31674c680bb..c3c8100559235 100644 --- a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx +++ b/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx @@ -42,7 +42,7 @@ Sentry.init({ ```javascript {filename: main.ts} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import { NestFactory } from "@nestjs/core"; diff --git a/platform-includes/getting-started-run/javascript.mdx b/platform-includes/getting-started-run/javascript.mdx index 3b891ce87d7a1..912e582e22141 100644 --- a/platform-includes/getting-started-run/javascript.mdx +++ b/platform-includes/getting-started-run/javascript.mdx @@ -1,6 +1,6 @@ ```bash # If you are using CommonJS (CJS) -node --require ./instrument.js app.js +node --import ./instrument.js app.js # If you are using ECMAScript Modules (ESM) # Note: This is only available for Node v18.19.0 onwards. @@ -9,6 +9,6 @@ node --import ./instrument.mjs app.mjs -If you can't run node with `--require` or `--import`, import the Sentry Initialization file directly. +If you can't run node with `--import`, import the Sentry Initialization file directly. diff --git a/platform-includes/getting-started-use/javascript.connect.mdx b/platform-includes/getting-started-use/javascript.connect.mdx index 4d9ae89376dcb..9accba2961a23 100644 --- a/platform-includes/getting-started-use/javascript.connect.mdx +++ b/platform-includes/getting-started-use/javascript.connect.mdx @@ -17,7 +17,7 @@ app.listen(3030); ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import connect from "connect"; diff --git a/platform-includes/getting-started-use/javascript.express.mdx b/platform-includes/getting-started-use/javascript.express.mdx index 5e13b651c0bf3..b7760f4eda103 100644 --- a/platform-includes/getting-started-use/javascript.express.mdx +++ b/platform-includes/getting-started-use/javascript.express.mdx @@ -19,7 +19,7 @@ app.listen(3000); ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import express from "express"; diff --git a/platform-includes/getting-started-use/javascript.fastify.mdx b/platform-includes/getting-started-use/javascript.fastify.mdx index 2f9c72bf25bec..0c1b043afb911 100644 --- a/platform-includes/getting-started-use/javascript.fastify.mdx +++ b/platform-includes/getting-started-use/javascript.fastify.mdx @@ -17,7 +17,7 @@ app.listen({ port: 3030 }); ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import Fastify from "fastify"; diff --git a/platform-includes/getting-started-use/javascript.hapi.mdx b/platform-includes/getting-started-use/javascript.hapi.mdx index bfbdfbbe9deab..6dcf9f8ea060f 100644 --- a/platform-includes/getting-started-use/javascript.hapi.mdx +++ b/platform-includes/getting-started-use/javascript.hapi.mdx @@ -25,7 +25,7 @@ init(); ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import * as Sentry from "@sentry/node"; diff --git a/platform-includes/getting-started-use/javascript.koa.mdx b/platform-includes/getting-started-use/javascript.koa.mdx index 9f3e93bc84629..01745580954be 100644 --- a/platform-includes/getting-started-use/javascript.koa.mdx +++ b/platform-includes/getting-started-use/javascript.koa.mdx @@ -16,10 +16,8 @@ app.listen(3030); ``` ```javascript {tabTitle:ESM} -// Import this first! -import "./instrument"; - -// Now import other modules +// Start with `node --import ./instrument.mjs app.mjs`. A top-level +// import of the instrument file loses Koa's spans and route names. import Koa from "koa"; import * as Sentry from "@sentry/node"; From 0efd2ce6cb1c86c1b85b9bb6924695a4bbf094e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 16:15:06 +0300 Subject: [PATCH 07/48] docs(sveltekit): Import sentrySvelteKit from the vite subpath (#19394) ## DESCRIBE YOUR PR closes SDK-1485 `sentrySvelteKit` no longer lives on the `@sentry/sveltekit` entry, so every snippet that imported it from there fails the build with `SyntaxError: The requested module '@sentry/sveltekit/build/esm/index.server.js' does not provide an export named 'sentrySvelteKit'`. The plugin is exported only from `@sentry/sveltekit/vite`. Update all thirteen snippets on the current pages: - the three `vite.config` snippets in the getting-started include - the four in the source maps overview - the three in the source maps primer - the three on the build configuration page Also update the primer for the removed `sourceMapsUploadOptions`: its fields sit at the top level of the plugin options now, which the snippet already showed but the prose did not, and `url` became `sentryUrl`. The v8 and v10.7.0 manual setup pages keep the old import, since it was correct on those versions, and the migration entries keep it as their "Before" example. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5 --- .../guides/sveltekit/configuration/build/index.mdx | 6 +++--- .../getting-started-complete/javascript.sveltekit.mdx | 6 +++--- .../sourcemaps/overview/javascript.sveltekit.mdx | 8 ++++---- .../sourcemaps/upload/primer/javascript.sveltekit.mdx | 10 +++++----- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx b/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx index ad6089b21b8ff..8a4a553643366 100644 --- a/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx @@ -85,7 +85,7 @@ Set `autoInstrument` to `false` to disable auto-instrumentation of any `load` fu ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from '@sveltejs/kit/vite'; -import { sentrySvelteKit } from '@sentry/sveltekit'; +import { sentrySvelteKit } from '@sentry/sveltekit/vite'; export default { plugins: [ @@ -108,7 +108,7 @@ Set to `false` to disable auto-instrumentation of `load` functions inside `+page ```javascript {filename:vite.config.(js|ts)} {7-10} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -131,7 +131,7 @@ Set to `false` to disable auto-instrumentation of server-only `load` functions i ```javascript {filename:vite.config.(js|ts)} {7-10} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ diff --git a/platform-includes/getting-started-complete/javascript.sveltekit.mdx b/platform-includes/getting-started-complete/javascript.sveltekit.mdx index 8fc48c3b2cd35..77369e45d7452 100644 --- a/platform-includes/getting-started-complete/javascript.sveltekit.mdx +++ b/platform-includes/getting-started-complete/javascript.sveltekit.mdx @@ -362,7 +362,7 @@ Add the `sentrySvelteKit` plugin **before** `sveltekit` in your `vite.config.(js ```javascript {filename:vite.config.(js|ts)} {2,6} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; import { defineConfig } from "vite"; export default defineConfig({ @@ -400,7 +400,7 @@ To upload source maps for clear error stack traces, add your Sentry auth token, ```javascript {filename:vite.config.(js|ts)} {6-13} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -455,7 +455,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ diff --git a/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx b/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx index 840a7f50c5acf..745f393984a3b 100644 --- a/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx +++ b/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx @@ -38,7 +38,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ @@ -58,7 +58,7 @@ Configure source map behavior in your Vite config: ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ @@ -78,7 +78,7 @@ By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to confi ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ @@ -96,7 +96,7 @@ You can disable automatic source maps upload in your Vite config: ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ diff --git a/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx b/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx index 47372f4bfdbed..21d87031621b0 100644 --- a/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx +++ b/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx @@ -23,11 +23,11 @@ SENTRY_URL="https://your-sentry-instance.com" **Option 2** -You can also set your org and project slugs by passing a `sourceMapsUploadOptions` object to `sentrySvelteKit`, as seen in the example below. For a full list of available options, see the [Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#options). +You can also set your org and project slugs directly in the `sentrySvelteKit` options, as seen in the example below. For a full list of available options, see the [Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#options). ```javascript {filename:vite.config.(js|ts)} {6-12} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -36,7 +36,7 @@ export default { project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, // If you're self-hosting Sentry, also add your instance URL: - // url: "https://your-self-hosted-sentry.com/", + // sentryUrl: "https://your-self-hosted-sentry.com/", }), sveltekit(), ], @@ -60,7 +60,7 @@ By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to confi ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -79,7 +79,7 @@ You can disable automatic source maps upload in your Vite config: ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ From a9434b646e259cc80dcfa5f1f22c49cb367516c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 16:16:52 +0300 Subject: [PATCH 08/48] docs(js): Switch stream mode to be the default in v11 (#19464) ## DESCRIBE YOUR PR closes SDK-1495 Ten stream mode includes presented stream as opt-in and called `'static'` "(the default)". v11 inverts that: `packages/core/src/client.ts` normalizes with `options.traceLifecycle === 'static' ? 'static' : 'stream'`, so every value except an explicit `'static'` resolves to stream, and the migration guide calls stream mode "the new default". The page's prerequisites allow SDK `>=10.66.0`, where stream mode is real but opt-in, so keep the snippet and name the version it applies to: enabled by default in v11, set explicitly on older versions. Drop "(the default)" from the transaction mode line, and say that mode exists for backwards compatibility. Also add the missing comma after `tracesSampleRate: 0.2` in the Cloudflare Pages snippet, which did not parse. The browser and meta-framework client sections are untouched. Those enable stream mode with `spanStreamingIntegration()`, which is opt-in on every version. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5 --- .../performance/enable-stream-mode/javascript.bun.mdx | 4 ++-- .../enable-stream-mode/javascript.cloudflare.mdx | 10 +++++----- .../performance/enable-stream-mode/javascript.deno.mdx | 4 ++-- .../enable-stream-mode/javascript.elysia.mdx | 4 ++-- .../enable-stream-mode/javascript.gcp-functions.mdx | 4 ++-- .../performance/enable-stream-mode/javascript.hono.mdx | 4 ++-- .../enable-stream-mode/javascript.nestjs.mdx | 4 ++-- .../enable-stream-mode/javascript.nextjs.mdx | 4 ++-- .../enable-stream-mode/javascript.nitro.mdx | 4 ++-- .../performance/enable-stream-mode/javascript.node.mdx | 4 ++-- 10 files changed, 23 insertions(+), 23 deletions(-) diff --git a/platform-includes/performance/enable-stream-mode/javascript.bun.mdx b/platform-includes/performance/enable-stream-mode/javascript.bun.mdx index 50fcd0d395b0d..3b0ace37a99d4 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.bun.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.bun.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx b/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx index baaa88c96e41c..4fd10ed1d10a5 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx @@ -5,7 +5,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -16,7 +16,7 @@ import * as Sentry from "@sentry/cloudflare"; export const onRequest = [ Sentry.sentryPagesPlugin((context) => ({ dsn: "___PUBLIC_DSN___", - tracesSampleRate: 0.2 + tracesSampleRate: 0.2, // enables stream mode traceLifecycle: "stream", })), @@ -32,7 +32,7 @@ export const onRequest = [ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -44,7 +44,7 @@ export default Sentry.withSentry( (env: Env) => ({ dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, - // Enables stream mode + // enables stream mode traceLifecycle: "stream", }), { @@ -59,4 +59,4 @@ export default Sentry.withSentry( -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.deno.mdx b/platform-includes/performance/enable-stream-mode/javascript.deno.mdx index 297c972e1deaf..c20aa6d9137b8 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.deno.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.deno.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -21,4 +21,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx b/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx index dd0e571319c4b..5e042cd319f7b 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx b/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx index fc3c31c729469..cc2162172b45a 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.hono.mdx b/platform-includes/performance/enable-stream-mode/javascript.hono.mdx index 951546caad069..d60bc5ef99b21 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.hono.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.hono.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -48,4 +48,4 @@ app.use( -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx b/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx index 8faa6f11ac1b2..af1a4ef92631c 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx b/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx index 99ba2c2facc47..70b4ea075e854 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK in your server, client, and edge config files: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK in your server, client, and edge config files: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx b/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx index bf70f69d9b3cc..a421fc85e6f38 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.node.mdx b/platform-includes/performance/enable-stream-mode/javascript.node.mdx index 053c862d60073..f4bf41c9f9d6d 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.node.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.node.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -33,4 +33,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. From 386d2894d9924941000eb333d7dcc563706e6fe2 Mon Sep 17 00:00:00 2001 From: Francesco Gringl-Novy Date: Tue, 22 Sep 2026 15:19:33 +0200 Subject: [PATCH 09/48] docs(agent-tracing): Document AI integrations as auto-instrumented for v11 (#19547) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR For JS SDK v11, all gen-AI provider packages are auto-instrumented, so their Agent Tracing setup pages become standard integration reference pages, and the Agent Tracing page becomes a summary of what Sentry supports. - Moved `openai`, `anthropic`, `google-genai`, `langchain`, `langgraph`, and `vercelai` from `agent-tracing/*` sub-pages into `configuration/integrations/*`, rewritten as auto-enabled integrations (import name, how to add, options) with a "requires SDK v11+" note and `supportedCategories: [server, serverless]` - Added new integration pages: **Mistral AI**, **Groq**, **Together AI** (sourced from the SDK `server-utils` integrations) - Rewrote the Agent Tracing index: moved the instrumentation grid to the top, dropped "Getting Started" (now just "works out of the box"), completed the provider list; kept Tracking Conversations / Options / Manual Instrumentation / MCP. `flue` and `manual-instrumentation` remain as sub-pages - Repointed and extended the 14 per-platform integration tables (added langgraph/mistral/groq/together rows) - Reversed the old `integrations → agent-tracing` redirects and added `agent-tracing → integrations` redirects - Wired `mistral`/`groq` platform icons; removed Mastra/Eve from the Agent Tracing sidebar - Updated cross-references (product/agents, concepts, flue, nodejs-compat, manual-instrumentation include) Validation: `lint:ts`, `eslint`, `lint:redirect-chains` (no chains, no content links to redirect sources), and `prettier` all pass. > Note: `/brand-guidelines` and the `docs-review` skill were not run (managed skills aren't installed in this environment) — worth a pass before merge. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- .../key-terms/agent-tracing/index.mdx | 2 +- .../common/agent-tracing/anthropic.mdx | 161 ----- .../javascript/common/agent-tracing/flue.mdx | 2 +- .../common/agent-tracing/google-genai.mdx | 155 ----- .../javascript/common/agent-tracing/index.mdx | 83 +-- .../common/agent-tracing/langchain.mdx | 175 ----- .../common/agent-tracing/langgraph.mdx | 177 ----- .../common/agent-tracing/openai.mdx | 238 ------- .../common/agent-tracing/vercelai.mdx | 647 ------------------ .../configuration/integrations/anthropic.mdx | 79 +++ .../integrations/google-genai.mdx | 77 +++ .../configuration/integrations/groq.mdx | 74 ++ .../configuration/integrations/langchain.mdx | 83 +++ .../configuration/integrations/langgraph.mdx | 72 ++ .../configuration/integrations/mistral.mdx | 77 +++ .../configuration/integrations/openai.mdx | 74 ++ .../integrations/together-ai.mdx | 74 ++ .../configuration/integrations/vercelai.mdx | 85 +++ .../cloudflare/features/nodejs-compat.mdx | 4 +- docs/product/agents/naming.mdx | 6 +- docs/product/agents/privacy.mdx | 2 +- .../agent-tracing/manual-instrumentation.mdx | 62 +- .../integrations/javascript.astro.mdx | 14 +- .../integrations/javascript.aws-lambda.mdx | 14 +- .../integrations/javascript.bun.mdx | 14 +- .../integrations/javascript.connect.mdx | 14 +- .../integrations/javascript.fastify.mdx | 14 +- .../integrations/javascript.gcp-functions.mdx | 14 +- .../integrations/javascript.hapi.mdx | 14 +- .../integrations/javascript.nestjs.mdx | 14 +- .../integrations/javascript.nextjs.mdx | 16 +- .../integrations/javascript.node.mdx | 14 +- .../integrations/javascript.nuxt.mdx | 14 +- .../integrations/javascript.remix.mdx | 14 +- .../integrations/javascript.solidstart.mdx | 14 +- .../integrations/javascript.sveltekit.mdx | 14 +- redirects.js | 167 +++-- src/components/platformIcon.tsx | 15 + src/components/sidebar/platformSidebar.tsx | 40 +- 39 files changed, 1039 insertions(+), 1790 deletions(-) delete mode 100644 docs/platforms/javascript/common/agent-tracing/anthropic.mdx delete mode 100644 docs/platforms/javascript/common/agent-tracing/google-genai.mdx delete mode 100644 docs/platforms/javascript/common/agent-tracing/langchain.mdx delete mode 100644 docs/platforms/javascript/common/agent-tracing/langgraph.mdx delete mode 100644 docs/platforms/javascript/common/agent-tracing/openai.mdx delete mode 100644 docs/platforms/javascript/common/agent-tracing/vercelai.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/anthropic.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/google-genai.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/groq.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/langchain.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/langgraph.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/mistral.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/openai.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/together-ai.mdx create mode 100644 docs/platforms/javascript/common/configuration/integrations/vercelai.mdx diff --git a/docs/concepts/key-terms/agent-tracing/index.mdx b/docs/concepts/key-terms/agent-tracing/index.mdx index 1b5979876e81f..9b41e03737659 100644 --- a/docs/concepts/key-terms/agent-tracing/index.mdx +++ b/docs/concepts/key-terms/agent-tracing/index.mdx @@ -152,7 +152,7 @@ Click into a specific model for a detailed dashboard view, or scroll through the Depending on the data your agents handle, some of it may be sensitive and shouldn't be recorded in a span. Prompts and agent output aren't recorded by default in Sentry. This is an opt-in feature you can enable by setting `recordInputs`, `recordOutputs`, or both, to true in your Sentry SDK integration options. -[Here is an example from our JavaScript SDK using the Vercel AI SDK →](/platforms/javascript/guides/cloudflare/agent-tracing/vercelai/#record-inputs-and-outputs) +[Here is an example from our JavaScript SDK using the Vercel AI SDK →](/platforms/javascript/guides/cloudflare/configuration/integrations/vercelai/#options) You can explore agent tracing for your SDK here. diff --git a/docs/platforms/javascript/common/agent-tracing/anthropic.mdx b/docs/platforms/javascript/common/agent-tracing/anthropic.mdx deleted file mode 100644 index 52f5435bf37be..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/anthropic.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Anthropic -description: "Adds instrumentation for the Anthropic SDK." -sidebar_order: 22 -supported: - - javascript.node - - javascript.eve - - javascript.aws-lambda - - javascript.azure-functions - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.gcp-functions - - javascript.hapi - - javascript.hono - - javascript.koa - - javascript.nestjs - - javascript.nextjs - - javascript.nuxt - - javascript.solidstart - - javascript.sveltekit - - javascript.react-router - - javascript.remix - - javascript.astro - - javascript.bun - - javascript.tanstackstart-react - - javascript.cloudflare ---- - - - - For meta-framework applications running on both client and server, we recommend **setting up the integration manually** using the [`instrumentAnthropicAiClient` wrapper](#manual-instrumentation) to ensure consistent instrumentation across all runtimes. - - - - - - ## Automatic Instrumentation - - _Import name: `Sentry.anthropicAIIntegration`_ - - - - If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, you need to use **[Manual Instrumentation](#manual-instrumentation)** to explicitly wrap your AI client instance instead. - - - - The `anthropicAIIntegration` adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions. - - In Node.js runtimes, this integration is enabled by default and automatically captures spans for Anthropic SDK calls (requires Sentry SDK version `10.28.0` or higher). - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - - - - ## Manual Instrumentation - - _Import name: `Sentry.instrumentAnthropicAiClient`_ - - The `instrumentAnthropicAiClient` helper adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions with configurable input/output recording. You need to manually wrap your Anthropic client instance with this helper. - - See the example below: - - ```javascript - import Anthropic from "@anthropic-ai/sdk"; - - const anthropic = new Anthropic({ - apiKey: "your-api-key", // Warning: API key will be exposed in browser! -}); - - const client = Sentry.instrumentAnthropicAiClient(anthropic, { - recordInputs: true, - recordOutputs: true, -}); - - // Use the wrapped client instead of the original anthropic instance - const response = await client.messages.create({ - model: "claude-3-5-sonnet-20241022", - max_tokens: 1024, - messages: [{ role: "user", content: "Hello!" }], -}); - ``` - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - -## Configuration - -### Options - -The following options control what data is captured from Anthropic SDK calls: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to Anthropic SDK calls (such as prompts and messages). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ - -Records outputs from Anthropic SDK calls (such as generated text and responses). - -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -**Usage** - - - - Using the `anthropicAIIntegration` integration for **automatic instrumentation**: - - ```javascript - Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work - tracesSampleRate: 1.0, - integrations: [ - Sentry.anthropicAIIntegration({ - // your options here -}), - ], -}); - ``` - - - - - - Using the `instrumentAnthropicAiClient` wrapper for **manual instrumentation**: - - ```javascript - const client = Sentry.instrumentAnthropicAiClient(anthropic, { - // your options here -}); - ``` - - - -## Supported Operations - -By default, tracing support is added to the following Anthropic SDK calls: - -- `messages.create()` - Create messages with Claude models -- `messages.stream()` - Stream messages with Claude models -- `messages.countTokens()` - Count tokens for messages -- `models.get()` - Get model information -- `completions.create()` - Create completions (legacy) -- `models.retrieve()` - Retrieve model details -- `beta.messages.create()` - Beta messages API - -Streaming and non-streaming requests are automatically detected and handled appropriately. - -## Supported Versions - -- `@anthropic-ai/sdk`: `>=0.19.2 <1.0.0` diff --git a/docs/platforms/javascript/common/agent-tracing/flue.mdx b/docs/platforms/javascript/common/agent-tracing/flue.mdx index db903967a4e56..daf0370406d4b 100644 --- a/docs/platforms/javascript/common/agent-tracing/flue.mdx +++ b/docs/platforms/javascript/common/agent-tracing/flue.mdx @@ -214,7 +214,7 @@ Also confirm that a wrapped agent delivers spans, logs, and issues from `workerd ## Troubleshooting - **Logs and issues arrive but no traces.** `SENTRY_TRACES_SAMPLE_RATE` defaults to `0`. Set it above `0`. -- **Token and cost values are doubled.** Don't add a second AI tracing integration such as the Vercel AI integration or Anthropic integration. The blueprint removes them on purpose because Flue already emits the model spans. +- **Token and cost values are doubled.** Don't add a second AI tracing integration such as the Vercel AI integration or Anthropic integration. The blueprint removes them on purpose because Flue already emits the model spans. - **A tool error did not create an issue.** Only terminal operation and submission failures create issues. A recovered tool error stays on the trace as diagnostic context. ## Supported Versions diff --git a/docs/platforms/javascript/common/agent-tracing/google-genai.mdx b/docs/platforms/javascript/common/agent-tracing/google-genai.mdx deleted file mode 100644 index 1f4b5f8bb4d3a..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/google-genai.mdx +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Google Gen AI -description: "Adds instrumentation for Google Gen AI SDK." -sidebar_order: 23 -supported: - - javascript.node - - javascript.eve - - javascript.aws-lambda - - javascript.azure-functions - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.gcp-functions - - javascript.hapi - - javascript.hono - - javascript.koa - - javascript.nestjs - - javascript.nextjs - - javascript.nuxt - - javascript.solidstart - - javascript.sveltekit - - javascript.react-router - - javascript.remix - - javascript.astro - - javascript.bun - - javascript.tanstackstart-react - - javascript.cloudflare ---- - - - - For meta-framework applications running on both client and server, we recommend **setting up the integration manually** using the [`instrumentGoogleGenAIClient` wrapper](#manual-instrumentation) to ensure consistent instrumentation across all runtimes. - - - - - - ## Automatic Instrumentation - - _Import name: `Sentry.googleGenAIIntegration`_ - - - - If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, you need to use **[Manual Instrumentation](#manual-instrumentation)** to explicitly wrap your AI client instance instead. - - - - The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions. - - In Node.js runtimes, this integration is enabled by default and automatically captures spans for Google Gen AI SDK calls (requires Sentry SDK version `10.28.0` or higher). - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - - - - ## Manual Instrumentation - - _Import name: `Sentry.instrumentGoogleGenAIClient`_ - - The `instrumentGoogleGenAIClient` helper adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions with configurable input/output recording. You need to manually wrap your Google Gen AI client instance with this helper. - - See example below: - - ```javascript - import { GoogleGenAI } from "@google/genai"; - - const genAI = new GoogleGenAI({ - apiKey: "your-api-key", // Warning: API key will be exposed in browser! - }); - - const client = Sentry.instrumentGoogleGenAIClient(genAI, { - recordInputs: true, - recordOutputs: true, - }); - - // Use the wrapped client instead of the original genAI instance - const result = await client.models.generateContent("Hello!"); - ``` - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - -## Configuration - -### Options - -The following options control what data is captured from Google Gen AI SDK calls: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to Google Gen AI SDK calls (such as prompts and messages). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ - -Records outputs from Google Gen AI SDK calls (such as generated text and responses). - -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -**Usage** - - - -Using the `googleGenAIIntegration` integration for **automatic instrumentation**: - -```javascript -Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work - tracesSampleRate: 1.0, - integrations: [ - Sentry.googleGenAIIntegration({ - // your options here - }), - ], -}); -``` - - - - - -Using the `instrumentGoogleGenAIClient` wrapper for **manual instrumentation**: - -```javascript -const client = Sentry.instrumentGoogleGenAIClient(genAI, { - // your options here -}); -``` - - - -## Supported Operations - -By default, tracing support is added to the following Google Gen AI SDK calls: - -- `models.generateContent()` - Generate content with a given model -- `models.generateContentStream()` - Stream content generation with a given model -- `chats.create()` - Create chat sessions -- `sendMessage()` - Send messages in chat sessions -- `sendMessageStream()` - Stream messages in chat sessions - -Streaming and non-streaming requests are automatically detected and handled appropriately. - -## Supported Versions - -- `@google/genai`: `>=0.10.0 <2` diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index 2b3dc566ecb3b..ba7a87adcbcc7 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -39,52 +39,9 @@ With Sentry Agent Tracing, you can -## Getting Started +## Supported Instrumentation -Enable tracing and pass `dataCollection` so generative AI content follows the SDK defaults (including prompts and responses when left unconfigured). - -`dataCollection: {}` also opts into other **permissive** defaults (bodies, cookies, user info, and more). Tighten via `dataCollection`. - - - -```javascript -import * as Sentry from "___SDK_PACKAGE___"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - dataCollection: {}, -}); -``` - - - - - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - dataCollection: {}, - }), - { - async fetch(request, env, ctx) { - // your worker - }, - } -); -``` - -Durable Objects / Agents SDK: use `instrumentDurableObjectWithSentry` with the same options. - - - -## Instrumentation - -Pick your AI stack. Some libraries auto-instrument; others need a short setup — each page has the details. +As of SDK version `11.0.0`, Sentry auto-instruments the most popular AI SDKs and frameworks out of the box — no manual setup is required. Just enable tracing, then pick your AI stack below. Each integration page has the details. - - For meta-framework applications running on both client and server, we recommend **setting up the integration manually** using the [`createLangChainCallbackHandler` wrapper](#manual-instrumentation) to ensure consistent instrumentation across all runtimes. - - - - - - ## Automatic Instrumentation - - _Import name: `Sentry.langChainIntegration`_ - - - - If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, you need to use **[Manual Instrumentation](#manual-instrumentation)** to explicitly wrap your AI client instance instead. - - - - The `langChainIntegration` adds instrumentation for [`langchain`](https://www.npmjs.com/package/langchain) to capture spans by automatically wrapping LangChain operations and recording agent interactions with configurable input/output recording. - - In Node.js runtimes, this integration is enabled by default and automatically captures spans for LangChain SDK calls (requires Sentry SDK version `10.28.0` or higher). - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - - - - ## Manual Instrumentation - - _Import name: `Sentry.createLangChainCallbackHandler`_ - - The `createLangChainCallbackHandler` helper adds instrumentation for [`langchain`](https://www.npmjs.com/package/langchain) to capture spans by creating a callback handler that wraps LangChain operations and records agent interactions with configurable input/output recording. You need to manually create and pass this callback handler to your LangChain operations. - - See example below: - - ```javascript - import { ChatAnthropic } from "@langchain/anthropic"; - - // Create a LangChain callback handler - const callbackHandler = Sentry.createLangChainCallbackHandler({ - recordInputs: true, - recordOutputs: true, - }); - - // Use with chat models - const model = new ChatAnthropic({ - model: "claude-3-5-sonnet-20241022", - apiKey: "your-api-key", // Warning: API key will be exposed in browser! - }); - - await model.invoke("Tell me a joke", { - callbacks: [callbackHandler], - }); - ``` - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - -## Configuration - -### Options - -The following options control what data is captured from LangChain operations: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to LangChain operations (such as prompts and messages). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ - -Records outputs from LangChain operations (such as generated text and responses). - -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -**Usage** - - - -Using the `langChainIntegration` integration for **automatic instrumentation**: - -```javascript -Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work - tracesSampleRate: 1.0, - integrations: [ - Sentry.langChainIntegration({ - // your options here - }), - ], -}); -``` - - - - - -Using the `createLangChainCallbackHandler` wrapper for **manual instrumentation**: - -```javascript -const callbackHandler = Sentry.createLangChainCallbackHandler({ - // your options here -}); -``` - - - -## Supported Operations - -By default, tracing support is added to the following LangChain SDK calls: - -- **Chat model invocations** - Captures spans for chat model calls -- **LLM invocations** - Captures spans for LLM pipeline executions -- **Chain executions** - Captures spans for chain invocations -- **Tool executions** - Captures spans for tool calls - -### Runnables - -The integration automatically instruments the following LangChain runnable methods: - -- `invoke()` - Single execution -- `stream()` - Streaming execution -- `batch()` - Batch execution - -### Providers - -The automatic instrumentation supports the following LangChain provider packages: - -- `@langchain/anthropic` -- `@langchain/openai` -- `@langchain/google-genai` -- `@langchain/mistralai` -- `@langchain/google-vertexai` -- `@langchain/groq` - -## Supported Versions - -- `langchain`: `>=0.1.0 <2.0.0` diff --git a/docs/platforms/javascript/common/agent-tracing/langgraph.mdx b/docs/platforms/javascript/common/agent-tracing/langgraph.mdx deleted file mode 100644 index d624bf14c23f4..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/langgraph.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: LangGraph -description: "Adds instrumentation for the LangGraph SDK." -sidebar_order: 25 -supported: - - javascript.node - - javascript.eve - - javascript.aws-lambda - - javascript.azure-functions - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.gcp-functions - - javascript.hapi - - javascript.hono - - javascript.koa - - javascript.nestjs - - javascript.nextjs - - javascript.nuxt - - javascript.solidstart - - javascript.sveltekit - - javascript.react-router - - javascript.remix - - javascript.astro - - javascript.bun - - javascript.tanstackstart-react - - javascript.cloudflare ---- - - - - For meta-framework applications running on both client and server, we recommend **setting up the integration manually** using the [`instrumentLangGraph` wrapper](#manual-instrumentation) to ensure consistent instrumentation across all runtimes. - - - - - - ## Automatic Instrumentation - - _Import name: `Sentry.langGraphIntegration`_ - - - - If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, you need to use **[Manual Instrumentation](#manual-instrumentation)** to explicitly wrap your AI client instance instead. - - - - The `langGraphIntegration` adds instrumentation for [`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph) to capture spans by automatically wrapping LangGraph operations and recording agent interactions including agent invocations, graph executions, and node operations. - - In Node.js runtimes, this integration is enabled by default and automatically captures spans for LangGraph SDK calls (requires Sentry SDK version `10.28.0` or higher). - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - - - - ## Manual Instrumentation - - _Import name: `Sentry.instrumentLangGraph`_ - - The `instrumentLangGraph` helper adds instrumentation for [`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph) to capture spans by wrapping a `StateGraph` before compilation and recording agent interactions with configurable input/output recording. You need to call this helper on the graph **before** calling `.compile()`. - - See example below: - - ```javascript - import { ChatOpenAI } from "@langchain/openai"; - import { StateGraph, MessagesAnnotation, START, END } from '@langchain/langgraph'; - import { SystemMessage, HumanMessage } from '@langchain/core/messages'; - - // Create LLM call - const llm = new ChatOpenAI({ - modelName: "gpt-4o", - apiKey: "your-api-key", // Warning: API key will be exposed in browser! - }); - - async function callLLM(state) { - const response = await llm.invoke(state.messages); - - return { - messages: [...state.messages, response], - }; - } - - // Create the agent - const agent = new StateGraph(MessagesAnnotation) - .addNode('agent', callLLM) - .addEdge(START, 'agent') - .addEdge('agent', END); - - // Instrument the graph before compiling - Sentry.instrumentLangGraph(agent, { - recordInputs: true, - recordOutputs: true, - }); - - const graph = agent.compile({ name: 'my_agent' }); - - // Invoke the agent - const result = await graph.invoke({ - messages: [ - new SystemMessage("You are a helpful assistant."), - new HumanMessage("Hello!"), - ], - }); - ``` - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - -## Configuration - -### Options - -The following options control what data is captured from LangGraph operations: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to LangGraph operations (such as messages and state data passed to the graph). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ - -Records outputs from LangGraph operations (such as generated responses, agent outputs, and final state). - -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -**Usage** - - - -Using the `langGraphIntegration` integration for **automatic instrumentation**: - -```javascript -Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work - tracesSampleRate: 1.0, - integrations: [ - Sentry.langGraphIntegration({ - // your options here - }), - ], -}); -``` - - - - - -Using the `instrumentLangGraph` wrapper for **manual instrumentation**: - -```javascript -Sentry.instrumentLangGraph(graph, { - // your options here -}); -``` - - - -## Supported Operations - -By default, tracing support is added to the following LangGraph SDK calls: - -- **Agent Creation** (`gen_ai.create_agent`) - Captures spans when compiling a StateGraph into an executable agent -- **Agent Invocation** (`gen_ai.invoke_agent`) - Captures spans for agent execution via `invoke()` - - -## Supported Versions - -- `@langchain/langgraph`: `>=0.2.0 <2.0.0` diff --git a/docs/platforms/javascript/common/agent-tracing/openai.mdx b/docs/platforms/javascript/common/agent-tracing/openai.mdx deleted file mode 100644 index 4f7dcea270c05..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/openai.mdx +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: OpenAI -description: "Adds instrumentation for the OpenAI SDK." -sidebar_order: 21 -supported: - - javascript.node - - javascript.eve - - javascript.aws-lambda - - javascript.azure-functions - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.gcp-functions - - javascript.hapi - - javascript.hono - - javascript.koa - - javascript.nestjs - - javascript.nextjs - - javascript.nuxt - - javascript.solidstart - - javascript.sveltekit - - javascript.react-router - - javascript.remix - - javascript.astro - - javascript.bun - - javascript.tanstackstart-react - - javascript.cloudflare ---- - - - - For meta-framework applications running on both client and server, we recommend using the [`instrumentOpenAiClient` wrapper](#instrument-the-client) to ensure consistent instrumentation across all runtimes. - - - - - - ## Automatic Instrumentation - - _Import name: `Sentry.openAIIntegration`_ - - - - If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, **[wrap the client](#instrument-the-client)** with `instrumentOpenAiClient` instead. - - - - The `openAIIntegration` adds instrumentation for the [`openai`](https://www.npmjs.com/package/openai) SDK to capture spans by wrapping OpenAI SDK calls and recording LLM interactions. - - In Node.js runtimes, this integration is enabled by default and automatically captures spans for OpenAI SDK calls (requires Sentry SDK version `10.28.0` or higher). - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - - - - ## Instrument the Client - - _Import name: `Sentry.instrumentOpenAiClient`_ - - The `instrumentOpenAiClient` helper instruments the [`openai`](https://www.npmjs.com/package/openai) SDK by wrapping your client instance and recording LLM interactions with configurable input/output capture. - - - - On Cloudflare Workers, enable tracing on the worker (for example with `Sentry.withSentry` and `tracesSampleRate`), then wrap every OpenAI client you use. Tracing alone is not enough — unwrapped clients produce no `gen_ai.*` spans. - - ```javascript - import * as Sentry from "@sentry/cloudflare"; - import OpenAI from "openai"; - - export default Sentry.withSentry( - (env) => ({ - dsn: env.SENTRY_DSN, - tracesSampleRate: 1.0, - }), - { - async fetch(request, env) { - const openai = new OpenAI({ - apiKey: env.OPENAI_API_KEY, - }); - - const client = Sentry.instrumentOpenAiClient(openai, { - recordInputs: true, - recordOutputs: true, - }); - - const response = await client.chat.completions.create({ - model: "gpt-4o-mini", - messages: [{ role: "user", content: "Hello!" }], - }); - - return Response.json(response); - }, - }, - ); - ``` - - If you call OpenAI from a Durable Object over RPC, set `rpcTracePropagationBindings` on both sides. On the Worker, list the Durable Object's binding. On the Durable Object, set the option to an empty array. Wrap the Durable Object with `instrumentDurableObjectWithSentry`. See RPC Trace Propagation. - - For multi-turn Conversations and the User column, see Tracking Conversations (`setConversationId` / `setUser`). - - - - - - See example below: - - ```javascript - import OpenAI from "openai"; - - const openai = new OpenAI({ - // Warning: API key will be exposed in browser! - apiKey: "your-api-key", - }); - - const client = Sentry.instrumentOpenAiClient(openai, { - recordInputs: true, - recordOutputs: true, - }); - - // Use the wrapped client instead of the original openai instance - const response = await client.chat.completions.create({ - model: "gpt-4o", - messages: [{ role: "user", content: "Hello!" }], - }); - ``` - - - - To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - - - -## Configuration - -### Options - -The following options control what data is captured from OpenAI SDK calls: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to OpenAI SDK calls (such as prompts and messages). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ - -Records outputs from OpenAI SDK calls (such as generated text and responses). - -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -**Usage** - - - -Using the `openAIIntegration` integration for **automatic instrumentation**: - -```javascript -Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work - tracesSampleRate: 1.0, - integrations: [ - Sentry.openAIIntegration({ - // your options here - }), - ], -}); -``` - - - - - -Using the `instrumentOpenAiClient` wrapper: - -```javascript -const client = Sentry.instrumentOpenAiClient(openai, { - // your options here -}); -``` - - - -## Supported Operations - -By default, tracing support is added to the following OpenAI SDK calls: - -- `chat.completions.create()` - Chat completion requests -- `responses.create()` - Response SDK requests - -Streaming and non-streaming requests are automatically detected and handled appropriately. - -Both APIs produce the same span type in Sentry: op `gen_ai.chat`, name like `chat `. There is no separate `gen_ai.responses` span — `responses.create()` is still a model chat request under the hood, so it uses the standard chat operation. - -Instrumented calls record model, token usage, latency, and (when enabled) inputs/outputs on the LLM span. If you pass `tools` to the request, Sentry stores the tool definitions on the span and records any tool calls the model returns as span attributes. - -### Tool execution spans - -The OpenAI SDK does **not** run your tools — your application does, after the model returns `tool_calls`. Because of that, `instrumentOpenAiClient` / `openAIIntegration` do **not** create `gen_ai.execute_tool` spans for local tool handlers. - - - -To get the full agent tree (`gen_ai.invoke_agent` → `gen_ai.chat` + `gen_ai.execute_tool`), wrap your tool loop with manual instrumentation. - - - - - -To get the full agent tree (`gen_ai.invoke_agent` → `gen_ai.chat` + `gen_ai.execute_tool`), wrap your tool loop with manual instrumentation. - - - -### Streaming token usage - - - -When using OpenAI's streaming API, you must also pass `stream_options: { include_usage: true }` to receive token usage data. Without this option, OpenAI does not include `prompt_tokens` or `completion_tokens` in streamed responses, and Sentry will be unable to capture `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` on the resulting span. This is an OpenAI API behavior, not a Sentry limitation. See [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create). - - - -```javascript -const stream = await client.chat.completions.create({ - model: "gpt-4o-mini", - messages: [{ role: "user", content: "Hello!" }], - stream: true, - stream_options: { include_usage: true }, -}); -``` - -## Supported Versions - -- `openai`: `>=4.0.0 <7` diff --git a/docs/platforms/javascript/common/agent-tracing/vercelai.mdx b/docs/platforms/javascript/common/agent-tracing/vercelai.mdx deleted file mode 100644 index e9fcdfda98cfc..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/vercelai.mdx +++ /dev/null @@ -1,647 +0,0 @@ ---- -title: Vercel AI -description: "Adds instrumentation for Vercel AI SDK." -sidebar_order: 20 -supported: - - javascript.node - - javascript.eve - - javascript.aws-lambda - - javascript.azure-functions - - javascript.bun - - javascript.cloudflare - - javascript.connect - - javascript.deno - - javascript.effect - - javascript.elysia - - javascript.express - - javascript.fastify - - javascript.firebase - - javascript.gcp-functions - - javascript.hapi - - javascript.hono - - javascript.koa - - javascript.nestjs - - javascript.nitro - - javascript.astro - - javascript.nextjs - - javascript.nuxt - - javascript.react-router - - javascript.remix - - javascript.solidstart - - javascript.sveltekit - - javascript.tanstackstart-react ---- - -_Import name: `Sentry.vercelAIIntegration`_ - -The `vercelAIIntegration` adds instrumentation for the [`ai`](https://www.npmjs.com/package/ai) SDK by Vercel to capture spans using the [AI SDK's built-in telemetry](https://sdk.vercel.ai/docs/ai-sdk-core/telemetry). - - - -Don't use the AI SDK's `registerTelemetry` API (AI SDK v7 and above) together with this integration. `vercelAIIntegration` already instruments the AI SDK, so registering telemetry separately produces duplicate spans. - - - - - -## Runtime Differences - - - -Next.js runs your server code in two runtimes. In both, you must pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). - -Everything else depends on which runtime you're in: - -| | Node runtime | Edge runtime | -| ------------------------- | ----------------------- | ----------------------------------- | -| Enabled by default | Yes | No — add it to `sentry.edge.config` | -| Record inputs and outputs | Integration or per call | Per call only | -| `force` | Available | Not available — always active | -| AI SDK v7 | Supported | Not supported | - - - - - -Cloudflare Workers can't load OpenTelemetry instrumentation. On both entrypoints, Sentry reads the spans the AI SDK emits on its own instead of patching your call sites, so you must pass `experimental_telemetry` on every call. The `@sentry/cloudflare/nodejs_compat` entrypoint adds the Node.js APIs the AI SDK v7 telemetry channel needs. - -Your entrypoint decides the rest: - -| | `@sentry/cloudflare` | `@sentry/cloudflare/nodejs_compat` | -| ---------------------------- | -------------------- | ---------------------------------- | -| Record inputs and outputs | Per call only | Integration or per call | -| AI SDK v7 | Not supported | Supported | -| Minimum Sentry SDK | `10.6.0` | `10.64.0` | -| Minimum `compatibility_date` | `2024-09-23` | `2026-02-19` | - - - - - -## Setup - - - -The integration is enabled by default and captures spans for all `ai` function calls. No setup code is needed beyond enabling tracing: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, -}); -``` - -Prompts and completions are not captured until you opt in. See [Record inputs and outputs](#record-inputs-and-outputs). - - - - - -### Node Runtime - -The integration is enabled by default: - -```javascript {filename:sentry.server.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, -}); -``` - -### Edge Runtime - -The integration is not enabled by default. Add it yourself: - -```javascript {filename:sentry.edge.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], -}); -``` - -In both runtimes, adding the integration is not enough on its own. You must also pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). - -If your spans have raw names like `ai.toolCall`, see [Troubleshooting](#troubleshooting). - - - - - -The integration is not enabled by default. Add it yourself: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], -}); -``` - -Deno can't load OpenTelemetry instrumentation, so Sentry can't patch your call sites. Adding the integration is not enough on its own — you must also pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). - - - - - -### AI SDK v7 - -Use the `@sentry/cloudflare/nodejs_compat` entrypoint and enable the Wrangler `nodejs_compat` flag: - -```javascript -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - -```jsonc {filename:wrangler.jsonc} -{ - "compatibility_date": "2026-02-19", - "compatibility_flags": ["nodejs_compat"], -} -``` - - - -AI SDK v7 only emits telemetry when `compatibility_date` is `2026-02-19` or later, and Wrangler is `4.67.0` or later. With an earlier date you get no AI spans and no error message. - - - -### AI SDK v6 and Below - -Import `@sentry/cloudflare` instead: - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - -On both entrypoints, adding the integration is not enough on its own. Cloudflare can't patch your call sites, so you must also pass `experimental_telemetry` on every call — including on `nodejs_compat`. See [Turn on telemetry](#turn-on-telemetry). - - - -## Record Inputs and Outputs - -Prompts and completions are not captured by default, because they usually contain user data. Turn recording on with `recordInputs` and `recordOutputs`. - -Sentry resolves both settings in this order, and stops at the first one that is set: - -1. The integration option — applies to every call. -2. The call's `experimental_telemetry` — applies to that call. -3. `dataCollection.genAI` — applies to every call. - -The integration option wins over the call, not the other way around. If you set `recordInputs: false` on the integration, no call site can turn it back on. - - - -Set the options on the integration to cover every call. Re-adding the integration replaces the default instance and configures it: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - Sentry.vercelAIIntegration({ - recordInputs: true, - recordOutputs: true, - }), - ], -}); -``` - -To record only some calls, leave the integration options unset and set them per call instead: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - -Set the options on the integration to cover every call (Node runtime only). Re-adding the integration replaces the default instance and configures it: - -```javascript {filename:sentry.server.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - Sentry.vercelAIIntegration({ - recordInputs: true, - recordOutputs: true, - }), - ], -}); -``` - - - -The Edge runtime ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. - - - -Or set them per call, which works in both runtimes: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - isEnabled: true, - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - -### `@sentry/cloudflare/nodejs_compat` - -Set the options on the integration to cover every call: - -```javascript -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - Sentry.vercelAIIntegration({ - recordInputs: true, - recordOutputs: true, - }), - ], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - -### `@sentry/cloudflare` - - - -The default entrypoint ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. - - - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - isEnabled: true, - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - - - -Deno ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. - - - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - isEnabled: true, - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - -`dataCollection: {}` also turns recording on, but it opts you into the SDK's permissive defaults for every other category too: user identity, cookies, headers, HTTP bodies, query parameters, and stack-frame locals. Prefer the integration and per-call options above unless you want all of it. See `dataCollection`. - - - -## Configure individual calls - -Every instrumented `ai` function takes an `experimental_telemetry` object. Use it to control one call instead of all of them. For the full list of fields, see the [AI SDK telemetry metadata docs](https://sdk.vercel.ai/docs/ai-sdk-core/telemetry#telemetry-metadata). - - - -### Turn on Telemetry - - - -Required in both the Node and Edge runtimes. - - - -Set `isEnabled` to `true` on every instrumented call. Without it, the AI SDK emits no spans and Sentry has nothing to capture: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { isEnabled: true }, -}); -``` - -For `ToolLoopAgent`, set it on the constructor instead. See [ToolLoopAgent](#toolloopagent). - - - -### Skip a Call - -To capture no span for one call, set `isEnabled` to `false`: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { isEnabled: false }, -}); -``` - -### Identify Your Call Sites - -Spans carry the AI SDK function name, not yours, so a trace with several `generateText` calls is hard to read. Set `functionId` to label the call site. It appears on the span as `gen_ai.function_id`: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - functionId: "summarize-ticket", - }, -}); -``` - -### ToolLoopAgent - -The integration captures spans for the [`ToolLoopAgent`](https://ai-sdk.dev/docs/agents/overview#toolloopagent-class) class. Each call to `generate()` or `stream()` creates an agent span, with the individual LLM requests and tool executions as child spans. - -`ToolLoopAgent` takes its telemetry settings on the constructor, not on `generate()` or `stream()`: - - - -```javascript -const agent = new ToolLoopAgent({ - model: openai("gpt-4o"), - tools: { - /* ... */ - }, - experimental_telemetry: { - functionId: "weather-agent", - }, -}); - -const result = await agent.generate({ - prompt: "What is the weather in San Francisco?", -}); -``` - -Spans are captured without the `experimental_telemetry` block. Pass it only to set `functionId` or the recording options. - - - - - -```javascript -const agent = new ToolLoopAgent({ - model: openai("gpt-4o"), - tools: { - /* ... */ - }, - experimental_telemetry: { - isEnabled: true, - functionId: "weather-agent", - }, -}); - -const result = await agent.generate({ - prompt: "What is the weather in San Francisco?", -}); -``` - - - -## Options - - - -Pass these to `Sentry.vercelAIIntegration()`. The Edge runtime accepts `enableTruncation` only. - - - - - -Pass these to `Sentry.vercelAIIntegration()`. The default `@sentry/cloudflare` entrypoint accepts `enableTruncation` only; `nodejs_compat` also accepts `recordInputs` and `recordOutputs`. Neither has module detection to override, so `force` does not apply. - - - - - -Pass these to `Sentry.vercelAIIntegration()`. Deno accepts `enableTruncation` only. It has no module detection to override, so `force` does not apply. - - - -### `enableTruncation` - -_Type: `boolean`_ - -Truncates recorded input messages so large payloads stay within span size limits. Affects inputs only, not outputs. - -Defaults to `true`. - - - -```javascript -Sentry.init({ - integrations: [Sentry.vercelAIIntegration({ enableTruncation: false })], -}); -``` - - - - - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - integrations: [Sentry.vercelAIIntegration({ enableTruncation: false })], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - - - - - -### `force` - -_Type: `boolean`_ - -Registers the integration's span processors even when the `ai` module can't be detected. Set this when your build bundles `ai`, which defeats module detection. See [Troubleshooting](#troubleshooting). - -Defaults to `false`. - -```javascript -Sentry.init({ - integrations: [Sentry.vercelAIIntegration({ force: true })], -}); -``` - - - -`force` only registers the span processors. You still need `experimental_telemetry` on every call. Not available in the Edge runtime, where the integration is always active once you add it. - - - - - -### `recordInputs` - -_Type: `boolean`_ - -Records inputs to the `ai` function call. See [Record inputs and outputs](#record-inputs-and-outputs) for the full resolution order and the per-call alternative. - -### `recordOutputs` - -_Type: `boolean`_ - -Records outputs from the `ai` function call. See [Record inputs and outputs](#record-inputs-and-outputs) for the full resolution order and the per-call alternative. - -## Supported Operations - - - -Spans are captured for these `ai` functions: - - - - - -Spans are captured for these `ai` functions. Pass `experimental_telemetry` to each one, as described in [Turn on telemetry](#turn-on-telemetry): - - - -- `generateText()` -- `streamText()` -- `generateObject()` -- `streamObject()` -- `embed()` -- `embedMany()` -- `rerank()` - -Plus `generate()` and `stream()` on [`ToolLoopAgent`](#toolloopagent). - -## Supported Versions - -- `ai`: `>=3.0.0 <=7` - - - -- Sentry SDK: `10.6.0`+ - - - - - -- Sentry SDK: `10.6.0`+ -- Edge runtime: `ai` v7 is not supported. Use v6 or below, or run the call in the Node runtime. - - - - - -- Sentry SDK: `10.12.0`+ - - - - - -- Sentry SDK: `10.6.0`+ with `@sentry/cloudflare` -- Sentry SDK: `10.64.0`+ with `@sentry/cloudflare/nodejs_compat`, required for `ai` v7 - - - -## Troubleshooting - - - - - -Raw names mean the AI SDK's telemetry is already on and emitting spans — Sentry's span processors just aren't registered to rename them. Add `force: true`: - -```javascript {filename:sentry.server.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - integrations: [Sentry.vercelAIIntegration({ force: true })], -}); -``` - -Keep `experimental_telemetry` on your calls. It's what produces the spans in the first place, so `force: true` without it leaves you with no AI spans at all. If only some of your spans have raw names, the remaining call sites are missing it: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { isEnabled: true }, -}); -``` - - - - - - - -Recording is off unless you turn it on. Check, in order: - -1. `recordInputs` and `recordOutputs` are set. See [Record inputs and outputs](#record-inputs-and-outputs). -2. You set them in a place the runtime reads. Some runtimes ignore the integration options and take them per call only. -3. No integration option is overriding your per-call value. The integration option wins. - - diff --git a/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx new file mode 100644 index 0000000000000..cc7fb6ce54fb1 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx @@ -0,0 +1,79 @@ +--- +title: Anthropic +description: "Adds instrumentation for the Anthropic SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.anthropicAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `anthropicAIIntegration` adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.anthropicAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Anthropic SDK calls: + +- `messages.create()` - Create messages with Claude models +- `messages.stream()` - Stream messages with Claude models +- `messages.countTokens()` - Count tokens for messages +- `models.get()` - Get model information +- `completions.create()` - Create completions (legacy) +- `models.retrieve()` - Retrieve model details +- `beta.messages.create()` - Beta messages API + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `@anthropic-ai/sdk`: `>=0.19.2 <1.0.0` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Anthropic SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Anthropic SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.anthropicAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx new file mode 100644 index 0000000000000..9cbf727ed774f --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx @@ -0,0 +1,77 @@ +--- +title: Google Gen AI +description: "Adds instrumentation for the Google Gen AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.googleGenAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.googleGenAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Google Gen AI SDK calls: + +- `models.generateContent()` - Generate content with a given model +- `models.generateContentStream()` - Stream content generation with a given model +- `chats.create()` - Create chat sessions +- `sendMessage()` - Send messages in chat sessions +- `sendMessageStream()` - Stream messages in chat sessions + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `@google/genai`: `>=0.10.0 <=2` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Google Gen AI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Google Gen AI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.googleGenAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/groq.mdx b/docs/platforms/javascript/common/configuration/integrations/groq.mdx new file mode 100644 index 0000000000000..b6a142dab30bd --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/groq.mdx @@ -0,0 +1,74 @@ +--- +title: Groq +description: "Adds instrumentation for the Groq SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. + + + +_Import name: `Sentry.groqIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `groqIntegration` adds instrumentation for the [`groq-sdk`](https://www.npmjs.com/package/groq-sdk) to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. Groq speaks the OpenAI wire format, so it reuses the same span and streaming logic as the OpenAI integration. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.groqIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Groq SDK calls: + +- `chat.completions.create()` - Chat completion requests +- `embeddings.create()` - Embedding requests + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `groq-sdk`: `>=0.3.0 <2` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Groq SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Groq SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.groqIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/langchain.mdx b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx new file mode 100644 index 0000000000000..a57f58e4a8dfb --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx @@ -0,0 +1,83 @@ +--- +title: LangChain +description: "Adds instrumentation for LangChain. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.langChainIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `langChainIntegration` adds instrumentation for [`langchain`](https://www.npmjs.com/package/langchain) to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.langChainIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following LangChain operations: + +- **Chat model invocations** - Captures spans for chat model calls +- **LLM invocations** - Captures spans for LLM pipeline executions +- **Chain executions** - Captures spans for chain invocations +- **Tool executions** - Captures spans for tool calls + +The integration automatically instruments the `invoke()`, `stream()`, and `batch()` runnable methods, across the following LangChain provider packages: + +- `@langchain/anthropic` +- `@langchain/openai` +- `@langchain/google-genai` +- `@langchain/mistralai` +- `@langchain/google-vertexai` +- `@langchain/groq` + +## Supported Versions + +- `langchain`: `>=0.1.0 <2.0.0` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to LangChain operations (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from LangChain operations (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.langChainIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx new file mode 100644 index 0000000000000..cd1e54bd52660 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx @@ -0,0 +1,72 @@ +--- +title: LangGraph +description: "Adds instrumentation for the LangGraph SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.langGraphIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `langGraphIntegration` adds instrumentation for [`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph) to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.langGraphIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following LangGraph operations: + +- **Agent Creation** (`gen_ai.create_agent`) - Captures spans when compiling a StateGraph into an executable agent +- **Agent Invocation** (`gen_ai.invoke_agent`) - Captures spans for agent execution via `invoke()` + +## Supported Versions + +- `@langchain/langgraph`: `>=0.2.0 <2.0.0` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to LangGraph operations (such as messages and state data passed to the graph). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from LangGraph operations (such as generated responses, agent outputs, and final state). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.langGraphIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/mistral.mdx b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx new file mode 100644 index 0000000000000..198678d4df294 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx @@ -0,0 +1,77 @@ +--- +title: Mistral AI +description: "Adds instrumentation for the Mistral AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. + + + +_Import name: `Sentry.mistralAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `mistralAIIntegration` adds instrumentation for the [`@mistralai/mistralai`](https://www.npmjs.com/package/@mistralai/mistralai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.mistralAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Mistral AI SDK calls: + +- `chat.complete()` / `chat.parse()` - Chat completion requests +- `chat.stream()` / `chat.parseStream()` - Streaming chat completions +- `embeddings.create()` - Embedding requests +- `agents.complete()` - Agent completion requests +- `agents.stream()` - Streaming agent completions + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `@mistralai/mistralai`: `>=2.0.0 <3` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Mistral AI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Mistral AI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.mistralAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/openai.mdx b/docs/platforms/javascript/common/configuration/integrations/openai.mdx new file mode 100644 index 0000000000000..24671db7850d7 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/openai.mdx @@ -0,0 +1,74 @@ +--- +title: OpenAI +description: "Adds instrumentation for the OpenAI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.openAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `openAIIntegration` adds instrumentation for the [`openai`](https://www.npmjs.com/package/openai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.openAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following OpenAI SDK calls: + +- `chat.completions.create()` - Chat completion requests +- `responses.create()` - Response SDK requests + +Streaming and non-streaming requests are automatically detected and handled appropriately. Both APIs produce the same span type: op `gen_ai.chat`, name like `chat `. + +## Supported Versions + +- `openai`: `>=4.0.0 <7` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to OpenAI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from OpenAI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.openAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx b/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx new file mode 100644 index 0000000000000..bd1a7636baf1c --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx @@ -0,0 +1,74 @@ +--- +title: Together AI +description: "Adds instrumentation for the Together AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. + + + +_Import name: `Sentry.togetherAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `togetherAIIntegration` adds instrumentation for the [`together-ai`](https://www.npmjs.com/package/together-ai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. Together AI speaks the OpenAI wire format, so it reuses the same span and streaming logic as the OpenAI integration. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.togetherAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Together AI SDK calls: + +- `chat.completions.create()` - Chat completion requests +- `embeddings.create()` - Embedding requests + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `together-ai`: `>=0.6.0 <1` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Together AI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Together AI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.togetherAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx new file mode 100644 index 0000000000000..0fde1e1a9fcb2 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx @@ -0,0 +1,85 @@ +--- +title: Vercel AI +description: "Adds instrumentation for the Vercel AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.vercelAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `vercelAIIntegration` adds instrumentation for the [`ai`](https://www.npmjs.com/package/ai) SDK by Vercel to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.vercelAIIntegration()], +}); +``` + + + +Don't use the AI SDK's `registerTelemetry` API (AI SDK v7 and above) together with this integration. `vercelAIIntegration` already instruments the AI SDK, so registering telemetry separately produces duplicate spans. + + + +## Supported Operations + +By default, tracing support is added to the following `ai` functions: + +- `generateText()` +- `streamText()` +- `generateObject()` +- `streamObject()` +- `embed()` +- `embedMany()` +- `rerank()` + +Plus `generate()` and `stream()` on [`ToolLoopAgent`](https://ai-sdk.dev/docs/agents/overview#toolloopagent-class). + +## Supported Versions + +- `ai`: `>=3.0.0 <=7` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to `ai` function calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from `ai` function calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.vercelAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx b/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx index 79193891a005a..44d85ea68781e 100644 --- a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx +++ b/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx @@ -16,7 +16,7 @@ The `@sentry/cloudflare/nodejs_compat` entrypoint requires SDK version `10.64.0` The `/nodejs_compat` entrypoint enables Node.js-only integrations and features on Cloudflare, including: - The `prismaIntegration` for tracing Prisma ORM queries. -- Vercel AI SDK v7 support for the `vercelAIIntegration`. +- Vercel AI SDK v7 support for the `vercelAIIntegration`. ## Usage @@ -45,6 +45,6 @@ compatibility_flags = ["nodejs_compat"] -We recommend that you also keep `compatibility_date` and Wrangler up to date. Some instrumentation depends on Node.js APIs that Cloudflare only exposes from a given compatibility date on, and an older date can turn that instrumentation off without an error message. The Vercel AI integration, for example, needs `2026-02-19` or later. +We recommend that you also keep `compatibility_date` and Wrangler up to date. Some instrumentation depends on Node.js APIs that Cloudflare only exposes from a given compatibility date on, and an older date can turn that instrumentation off without an error message. The Vercel AI integration, for example, needs `2026-02-19` or later. diff --git a/docs/product/agents/naming.mdx b/docs/product/agents/naming.mdx index 22cb2a290e958..45a6f05a83fb3 100644 --- a/docs/product/agents/naming.mdx +++ b/docs/product/agents/naming.mdx @@ -149,7 +149,7 @@ const agent = new ToolLoopAgent({ Vercel AI SDK integration docs @@ -180,7 +180,7 @@ const agent = createReactAgent({ LangGraph integration docs @@ -201,7 +201,7 @@ const agent = createAgent({ LangChain integration docs diff --git a/docs/product/agents/privacy.mdx b/docs/product/agents/privacy.mdx index 9d57c79356bba..f3b83d4228d3f 100644 --- a/docs/product/agents/privacy.mdx +++ b/docs/product/agents/privacy.mdx @@ -21,7 +21,7 @@ By default, Sentry agent integrations respect your [SDK's PII settings](/platfor - `sendDefaultPii: false` - Only metadata like model names, token counts, tool names, and execution times are collected - `sendDefaultPii: true` - Full inputs, outputs, prompts, and responses from AI models and tools are captured. -You can override this by configuring it on a function call level. For more details see [Configuration](/platforms/javascript/guides/nextjs/agent-tracing/vercelai/#configuration). +You can override this per integration with `recordInputs` and `recordOutputs`. For more details see [Options](/platforms/javascript/guides/nextjs/configuration/integrations/vercelai/#options). ## Server side PII Scrubbing diff --git a/includes/agent-tracing/manual-instrumentation.mdx b/includes/agent-tracing/manual-instrumentation.mdx index acd900f4da21e..7264f3f952eb5 100644 --- a/includes/agent-tracing/manual-instrumentation.mdx +++ b/includes/agent-tracing/manual-instrumentation.mdx @@ -12,11 +12,42 @@ For supported AI libraries, Sentry provides manual instrumentation helpers that @@ -26,17 +57,21 @@ For supported AI libraries, Sentry provides manual instrumentation helpers that -Each integration page includes a manual-instrumentation example with options like `recordInputs` and `recordOutputs`. +Each integration page documents its options, like `recordInputs` and `recordOutputs`. @@ -113,9 +148,7 @@ This span represents a request to an LLM model or service that generates a respo const messages = [ { role: "user", parts: [{ type: "text", content: "Tell me a joke" }] }, ]; -const tools = [ - { name: "get_weather", description: "Get weather for a city" }, -]; +const tools = [{ name: "get_weather", description: "Get weather for a city" }]; await Sentry.startSpan( { @@ -367,7 +400,6 @@ When the model streams tokens, keep the span open until the stream finishes (inc Use `Sentry.startInactiveSpan` if the span outlives the function that starts the stream, and `Sentry.withActiveSpan` when work within the stream needs the model span as its parent. End the span when the stream completes or fails. See Streamed Spans for span lifecycle patterns. - Sentry derives [model cost](/product/agents/costs/) from the model name and token counts. You do not need to set `gen_ai.cost.*` attributes. Pass the raw provider model string unchanged so pricing can resolve. If your provider reports costs or you use custom pricing, see [Send Custom Costs](/product/agents/costs/#send-custom-costs). diff --git a/platform-includes/configuration/integrations/javascript.astro.mdx b/platform-includes/configuration/integrations/javascript.astro.mdx index a5eb483d43f1d..e3e03d1f5ad15 100644 --- a/platform-includes/configuration/integrations/javascript.astro.mdx +++ b/platform-includes/configuration/integrations/javascript.astro.mdx @@ -75,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -85,10 +85,14 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx index d9faf15d2a6ca..7e73c81d7c8b5 100644 --- a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx +++ b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx @@ -17,11 +17,15 @@ | [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | | [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`amqplibIntegration`](./amqplib) | | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.bun.mdx b/platform-includes/configuration/integrations/javascript.bun.mdx index 9a05e62814063..155bb4785746d 100644 --- a/platform-includes/configuration/integrations/javascript.bun.mdx +++ b/platform-includes/configuration/integrations/javascript.bun.mdx @@ -29,11 +29,15 @@ | [`requestDataIntegration`](./requestdata) | ✓ | | ✓ | | | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`bunRuntimeMetricsIntegration`](./bunruntimemetrics) | | | | ✓ | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.connect.mdx b/platform-includes/configuration/integrations/javascript.connect.mdx index b2ce33a4e7010..42eb281c61039 100644 --- a/platform-includes/configuration/integrations/javascript.connect.mdx +++ b/platform-includes/configuration/integrations/javascript.connect.mdx @@ -30,11 +30,15 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`rewriteFramesIntegration`](./rewriteframes) | ✓ | ✓ | | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.fastify.mdx b/platform-includes/configuration/integrations/javascript.fastify.mdx index 807d522390215..53ebfaeb7586b 100644 --- a/platform-includes/configuration/integrations/javascript.fastify.mdx +++ b/platform-includes/configuration/integrations/javascript.fastify.mdx @@ -29,11 +29,15 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx index 61e464d853018..743486427721e 100644 --- a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx +++ b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx @@ -17,11 +17,15 @@ | [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | | [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`amqplibIntegration`](./amqplib) | | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.hapi.mdx b/platform-includes/configuration/integrations/javascript.hapi.mdx index 7ed14e4ceef24..1d6cb46f7eced 100644 --- a/platform-includes/configuration/integrations/javascript.hapi.mdx +++ b/platform-includes/configuration/integrations/javascript.hapi.mdx @@ -30,11 +30,15 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nestjs.mdx b/platform-includes/configuration/integrations/javascript.nestjs.mdx index 00b3a8bf1614c..716a03b6c49a8 100644 --- a/platform-includes/configuration/integrations/javascript.nestjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nestjs.mdx @@ -30,7 +30,7 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | @@ -44,9 +44,13 @@ | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nextjs.mdx b/platform-includes/configuration/integrations/javascript.nextjs.mdx index b80523d496b3a..a47472bcebea6 100644 --- a/platform-includes/configuration/integrations/javascript.nextjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nextjs.mdx @@ -91,11 +91,15 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | ✓ | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | @@ -104,4 +108,4 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`winterCGFetchIntegration`](./wintercgfetch) | ✓ | | ✓ | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.node.mdx b/platform-includes/configuration/integrations/javascript.node.mdx index 5973f59e60b12..4ac15382fcb4f 100644 --- a/platform-includes/configuration/integrations/javascript.node.mdx +++ b/platform-includes/configuration/integrations/javascript.node.mdx @@ -38,15 +38,19 @@ | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | | [`redisIntegration`](./redis) | ✓ | | ✓ | | | [`requestDataIntegration`](./requestdata) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nuxt.mdx b/platform-includes/configuration/integrations/javascript.nuxt.mdx index 3af9b312da31e..996534294613b 100644 --- a/platform-includes/configuration/integrations/javascript.nuxt.mdx +++ b/platform-includes/configuration/integrations/javascript.nuxt.mdx @@ -75,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -85,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.remix.mdx b/platform-includes/configuration/integrations/javascript.remix.mdx index 9d6c7c4c4e047..ed4fd65bbda59 100644 --- a/platform-includes/configuration/integrations/javascript.remix.mdx +++ b/platform-includes/configuration/integrations/javascript.remix.mdx @@ -75,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -85,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.solidstart.mdx b/platform-includes/configuration/integrations/javascript.solidstart.mdx index 873715155f310..f2b3275ad0222 100644 --- a/platform-includes/configuration/integrations/javascript.solidstart.mdx +++ b/platform-includes/configuration/integrations/javascript.solidstart.mdx @@ -75,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -85,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.sveltekit.mdx b/platform-includes/configuration/integrations/javascript.sveltekit.mdx index 9028f20758da0..5bee23bd43e17 100644 --- a/platform-includes/configuration/integrations/javascript.sveltekit.mdx +++ b/platform-includes/configuration/integrations/javascript.sveltekit.mdx @@ -74,7 +74,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -85,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/redirects.js b/redirects.js index c886196053f4d..eb2eae9d370a8 100644 --- a/redirects.js +++ b/redirects.js @@ -2432,6 +2432,123 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/:guide/agent-tracing/eve/:path*', destination: '/platforms/javascript/guides/eve/', }, + // AI provider setup pages moved from agent-tracing to configuration/integrations + { + source: '/platforms/javascript/agent-tracing/openai.md', + destination: '/platforms/javascript/guides/node/configuration/integrations/openai.md', + }, + { + source: '/platforms/javascript/agent-tracing/openai/:path*', + destination: '/platforms/javascript/guides/node/configuration/integrations/openai/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/openai.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/openai.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/openai/:path*', + destination: '/platforms/javascript/guides/:guide/configuration/integrations/openai/', + }, + { + source: '/platforms/javascript/agent-tracing/anthropic.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/anthropic.md', + }, + { + source: '/platforms/javascript/agent-tracing/anthropic/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/anthropic/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/anthropic.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/anthropic.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/anthropic/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/anthropic/', + }, + { + source: '/platforms/javascript/agent-tracing/google-genai.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/google-genai.md', + }, + { + source: '/platforms/javascript/agent-tracing/google-genai/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/google-genai/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/google-genai.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/google-genai.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/google-genai/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/google-genai/', + }, + { + source: '/platforms/javascript/agent-tracing/langchain.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langchain.md', + }, + { + source: '/platforms/javascript/agent-tracing/langchain/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langchain/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langchain.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langchain.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langchain/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langchain/', + }, + { + source: '/platforms/javascript/agent-tracing/langgraph.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langgraph.md', + }, + { + source: '/platforms/javascript/agent-tracing/langgraph/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langgraph/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langgraph.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langgraph.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langgraph/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langgraph/', + }, + { + source: '/platforms/javascript/agent-tracing/vercelai.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/vercelai.md', + }, + { + source: '/platforms/javascript/agent-tracing/vercelai/:path*', + destination: '/platforms/javascript/guides/node/configuration/integrations/vercelai/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/vercelai.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/vercelai.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/vercelai/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/vercelai/', + }, // Browser and mobile Agent Tracing pages now point to the Node.js guides. { source: '/platforms/javascript/agent-tracing.md', @@ -2533,56 +2650,6 @@ const userDocsRedirects = [ source: '/platforms/python/integrations/pydantic-ai/:path*', destination: '/platforms/python/agent-tracing/pydantic-ai/:path*', }, - // AI library setup pages moved from configuration/integrations to agent-tracing - { - source: '/platforms/javascript/configuration/integrations/vercelai/', - destination: '/platforms/javascript/agent-tracing/vercelai/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/vercelai/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/vercelai/', - }, - { - source: '/platforms/javascript/configuration/integrations/openai/', - destination: '/platforms/javascript/agent-tracing/openai/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/openai/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/openai/', - }, - { - source: '/platforms/javascript/configuration/integrations/anthropic/', - destination: '/platforms/javascript/agent-tracing/anthropic/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/anthropic/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/anthropic/', - }, - { - source: '/platforms/javascript/configuration/integrations/google-genai/', - destination: '/platforms/javascript/agent-tracing/google-genai/', - }, - { - source: - '/platforms/javascript/guides/:guide/configuration/integrations/google-genai/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/google-genai/', - }, - { - source: '/platforms/javascript/configuration/integrations/langchain/', - destination: '/platforms/javascript/agent-tracing/langchain/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/langchain/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/langchain/', - }, - { - source: '/platforms/javascript/configuration/integrations/langgraph/', - destination: '/platforms/javascript/agent-tracing/langgraph/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/langgraph/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/langgraph/', - }, // agent-tracing-browser merged into agent-tracing { source: '/platforms/javascript/agent-tracing-browser/', diff --git a/src/components/platformIcon.tsx b/src/components/platformIcon.tsx index 440248389f4fb..bccc78bb1eef1 100644 --- a/src/components/platformIcon.tsx +++ b/src/components/platformIcon.tsx @@ -68,6 +68,7 @@ import GodotSVG from 'platformicons/svg/godot.svg'; import GoogleSVG from 'platformicons/svg/google.svg'; import GrapheneSVG from 'platformicons/svg/graphene.svg'; import GraphqlSVG from 'platformicons/svg/graphql.svg'; +import GroqSVG from 'platformicons/svg/groq.svg'; import GrpcSVG from 'platformicons/svg/grpc.svg'; import HapiSVG from 'platformicons/svg/hapi.svg'; import HonoSVG from 'platformicons/svg/hono.svg'; @@ -92,6 +93,7 @@ import LoguruSVG from 'platformicons/svg/loguru.svg'; import MastraSVG from 'platformicons/svg/mastra.svg'; import MauiSVG from 'platformicons/svg/maui.svg'; import McpSVG from 'platformicons/svg/mcp.svg'; +import MistralSVG from 'platformicons/svg/mistral.svg'; import MongodbSVG from 'platformicons/svg/mongodb.svg'; import NativecSVG from 'platformicons/svg/nativec.svg'; import NestjsSVG from 'platformicons/svg/nestjs.svg'; @@ -223,6 +225,7 @@ import GodotSVGLarge from 'platformicons/svg_80x80/godot.svg'; import GoogleSVGLarge from 'platformicons/svg_80x80/google.svg'; import GrapheneSVGLarge from 'platformicons/svg_80x80/graphene.svg'; import GraphqlSVGLarge from 'platformicons/svg_80x80/graphql.svg'; +import GroqSVGLarge from 'platformicons/svg_80x80/groq.svg'; import GrpcSVGLarge from 'platformicons/svg_80x80/grpc.svg'; import HapiSVGLarge from 'platformicons/svg_80x80/hapi.svg'; import HonoSVGLarge from 'platformicons/svg_80x80/hono.svg'; @@ -247,6 +250,7 @@ import LoguruSVGLarge from 'platformicons/svg_80x80/loguru.svg'; import MastraSVGLarge from 'platformicons/svg_80x80/mastra.svg'; import MauiSVGLarge from 'platformicons/svg_80x80/maui.svg'; import McpSVGLarge from 'platformicons/svg_80x80/mcp.svg'; +import MistralSVGLarge from 'platformicons/svg_80x80/mistral.svg'; import MongodbSVGLarge from 'platformicons/svg_80x80/mongodb.svg'; import NativecSVGLarge from 'platformicons/svg_80x80/nativec.svg'; import NestjsSVGLarge from 'platformicons/svg_80x80/nestjs.svg'; @@ -676,6 +680,14 @@ const formatToSVG = { sm: LanggraphSVG, lg: LanggraphSVGLarge, }, + groq: { + sm: GroqSVG, + lg: GroqSVGLarge, + }, + mistral: { + sm: MistralSVG, + lg: MistralSVGLarge, + }, laravel: { sm: LaravelSVG, lg: LaravelSVGLarge, @@ -1003,6 +1015,9 @@ export const PLATFORM_TO_ICON = { git: 'git', go: 'go', 'google-genai': 'gemini', + groq: 'groq', + mistral: 'mistral', + 'together-ai': 'default', 'go-echo': 'echo', 'go-fasthttp': 'fasthttp', 'go-fiber': 'fiber', diff --git a/src/components/sidebar/platformSidebar.tsx b/src/components/sidebar/platformSidebar.tsx index 27c660d7c1437..8f6ca1b738fd0 100644 --- a/src/components/sidebar/platformSidebar.tsx +++ b/src/components/sidebar/platformSidebar.tsx @@ -23,19 +23,6 @@ const AGENT_TRACING_ALIAS_PATH_OVERRIDES: Record> const UNALIASED_AGENT_TRACING_PAGES = new Set(['manual-instrumentation']); const CLOUDFLARE_AGENT_TRACING_PAGE_SLUGS = ['agents-sdk', 'workers-ai']; -// Standalone JavaScript guides that own their Agent Tracing setup. They're -// surfaced in every JavaScript Agent Tracing sidebar as link-only entries that -// navigate to the dedicated guide instead of a page under the current guide. -const STANDALONE_AGENT_TRACING_GUIDES: { - guide: string; - sidebar_order: number; - slug: string; - title: string; -}[] = [ - {guide: 'mastra', slug: 'mastra', title: 'Mastra', sidebar_order: 26}, - {guide: 'eve', slug: 'eve', title: 'Eve', sidebar_order: 27}, -]; - export function PlatformSidebar({ rootNode, platformName, @@ -139,31 +126,10 @@ export function PlatformSidebar({ }; }).filter(alias => alias !== undefined); - // Surface the standalone Mastra and Eve guides from every JavaScript Agent - // Tracing sidebar. Their links navigate to the dedicated guide instead of - // creating an Agent Tracing page under the current guide. - const standaloneGuideAgentTracingAliases = - platformName !== 'javascript' || !agentTracingNode - ? [] - : STANDALONE_AGENT_TRACING_GUIDES.filter( - guideData => guideData.guide !== guideName - ).map(guideData => ({ - context: { - platform: {platformName}, - title: guideData.title, - sidebar_order: guideData.sidebar_order, - href: `/platforms/javascript/guides/${guideData.guide}/`, - }, - path: `/${pathRoot}/agent-tracing/${guideData.slug}/`, - })); - const tree = toTree( - [ - ...nodes, - ...agentTracingAliases, - ...cloudflareAgentTracingAliases, - ...standaloneGuideAgentTracingAliases, - ].filter(n => !!n.context) + [...nodes, ...agentTracingAliases, ...cloudflareAgentTracingAliases].filter( + n => !!n.context + ) ); // Use "Getting Started" for Next.js, default title for other platforms From e436f565c6342a8dc49830912b81c66cb0a77aa9 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:20:28 +0200 Subject: [PATCH 10/48] docs(remix): Update form data collection for v11 (#19434) Fixes https://linear.app/getsentry/issue/SDK-1487/update-remix-form-data-collection-docs-for-v11 --- .../common/data-management/data-collected/index.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index 8945a902a7a2f..f21526626d8e8 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -98,7 +98,11 @@ Without `dataCollection` (and with `sendDefaultPii` unset or `false`), Sentry on - When `dataCollection` is used, HTTP body collection is enabled by default, so Form Data can be sent with `captureActionFormDataKeys` in the Remix server-side configuration. When not using `dataCollection`, this requires the deprecated `sendDefaultPii: true`. + Remix action form data is captured when `dataCollection.httpBodies` includes `"incomingRequest"`, which is the default. All form fields are captured, and values with a sensitive-looking field name (like `password` or `token`) are replaced with `[Filtered]`. + + To capture only specific fields, set `captureActionFormDataKeys` in the Remix server-side configuration. This option works on its own and doesn't require `dataCollection.httpBodies` to include `"incomingRequest"`. To stop capturing form data, remove `captureActionFormDataKeys` and exclude `"incomingRequest"` from `dataCollection.httpBodies`. + + Captured fields are sent as `remix.action_form_data.` span attributes. Before version 11, the Node.js SDK sent them as `formData.`, so update any dashboards, alerts, or saved searches that query the old attribute names. From 73beac7366d583f59997cbdfbfa61eab00460915 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:23:35 +0200 Subject: [PATCH 11/48] docs(react-router): Update framework guides for v11 (#19366) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Updates the React Router Framework docs for SDK v11: state the new 7.15 framework-mode minimum, drop the beta warnings, only describe the instrumentation API for server-side tracing, and fix the snippets that no longer build against v11. - Change the stated support in the page descriptions from "v7+" to "v7.15+" - Add a `getting-started-prerequisites` include for React Router that lists the `7.15.0` minimum (framework mode) - Drop the feature-scoped "React Router 7.15+" notes around the `instrumentations` export, since 7.15 is now the baseline - Remove the "This SDK is currently in beta" alerts from the getting started and manual setup pages - Import `sentryReactRouter`, `SentryReactRouterBuildOptions`, and `sentryOnBuildEnd` from `@sentry/react-router/vite` on the manual setup and Hydrogen pages - Fix the `entry.server.tsx` snippet to import `../instrument.server` (the file lives in the project root, the entry in `app/`) - Move the misplaced `+` diff marker in the `react-router.config.ts` snippet so it no longer renders as a unary plus The removed `wrapServerLoader` / `wrapServerAction` wrappers are already covered by the v10-to-v11 migration guide and aren't referenced anywhere else in the docs. Supersedes #19314. > **⚠️ Do not merge until v11 is released as stable.** Fixes https://linear.app/getsentry/issue/SDK-1466/update-react-router-minimum-version-to-715-in-docs Fixes https://linear.app/getsentry/issue/SDK-1486/update-react-router-vite-plugin-imports-for-v11-in-docs Fixes https://linear.app/getsentry/issue/SDK-1516/react-router-getting-started-manual-setup ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01833WEY4kqAQNfbtu9Z8JLr --------- Co-authored-by: Claude Fable 5.1 --- .../frameworks/hydrogen-react-router.mdx | 2 +- .../javascript/guides/react-router/index.mdx | 9 +------- .../guides/react-router/manual-setup.mdx | 23 +++++++------------ .../javascript.react-router.mdx | 7 ++++++ 4 files changed, 17 insertions(+), 24 deletions(-) create mode 100644 platform-includes/getting-started-prerequisites/javascript.react-router.mdx diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx index 7e81d4baf69ba..7d3564242446d 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx @@ -307,7 +307,7 @@ import { reactRouter } from "@react-router/dev/vite"; import { hydrogen } from "@shopify/hydrogen/vite"; import { oxygen } from "@shopify/mini-oxygen/vite"; import { defineConfig } from "vite"; -import { sentryReactRouter } from "@sentry/react-router"; +import { sentryReactRouter } from "@sentry/react-router/vite"; export default defineConfig((config) => ({ plugins: [ diff --git a/docs/platforms/javascript/guides/react-router/index.mdx b/docs/platforms/javascript/guides/react-router/index.mdx index e9e9c5775851a..42544d7303ed5 100644 --- a/docs/platforms/javascript/guides/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react-router/index.mdx @@ -1,6 +1,6 @@ --- title: React Router Framework -description: Learn how to set up and configure Sentry in your React Router application (v7+) using the installation wizard, capture your first errors, and view them in Sentry. +description: Learn how to set up and configure Sentry in your React Router application (v7.15+) using the installation wizard, capture your first errors, and view them in Sentry. sdk: sentry.javascript.react-router categories: - browser @@ -12,13 +12,6 @@ categories: platformName="React Router" /> - - This SDK is currently in **beta**. Beta features are still in progress and may - have bugs. Please reach out on - [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if - you have any feedback or concerns. - - If you're using React Router in data or declarative mode, follow the instructions in our [React guide for v7](/platforms/javascript/guides/react/features/react-router/v7) or [v8](/platforms/javascript/guides/react/features/react-router/v8). diff --git a/docs/platforms/javascript/guides/react-router/manual-setup.mdx b/docs/platforms/javascript/guides/react-router/manual-setup.mdx index 1d962a45d25b2..06e808cb7b486 100644 --- a/docs/platforms/javascript/guides/react-router/manual-setup.mdx +++ b/docs/platforms/javascript/guides/react-router/manual-setup.mdx @@ -1,16 +1,9 @@ --- title: "Manual Setup" sidebar_order: 1 -description: "Learn how to manually set up Sentry in your React Router app (v7+) and capture your first errors." +description: "Learn how to manually set up Sentry in your React Router app (v7.15+) and capture your first errors." --- - - This SDK is currently in **beta**. Beta features are still in progress and may - have bugs. Please reach out on - [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if - you have any feedback or concerns. - - @@ -190,7 +183,7 @@ Sentry's OpenTelemetry-based auto-instrumentation (loaded through `instrument.se - **Node 20:** Version \<20.19 - **Node 22:** Version \<22.12 -This restriction **doesn't** affect tracing for loaders, actions, middleware, and request handlers. Those are instrumented through React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (the `instrumentations` export shown below, React Router 7.15+), which works on all Node versions. +This restriction **doesn't** affect tracing for loaders, actions, middleware, and request handlers. Those are instrumented through React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (the `instrumentations` export shown below), which works on all Node versions. On unsupported Node versions, you'll only lose auto-instrumentation for lower-level operations such as outgoing HTTP requests and database queries. @@ -244,7 +237,7 @@ Sentry.init({ Next, replace the default `handleRequest` and `handleError` functions in your `entry.server.tsx` file with Sentry's wrapped versions, and export `instrumentations` to enable automatic tracing. -Exporting `instrumentations` uses React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (React Router 7.15+) to automatically create spans for all loaders, actions, middleware, and request handlers — no need to wrap them individually. +Exporting `instrumentations` uses React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) to automatically create spans for all loaders, actions, middleware, and request handlers — no need to wrap them individually. @@ -269,7 +262,7 @@ Exporting `instrumentations` uses React Router's [instrumentation API](https://r +}); +// Automatically instruments all server loaders, actions, middleware, -+// and request handlers. Requires React Router 7.15+. ++// and request handlers. +export const instrumentations = [Sentry.createSentryServerInstrumentation()]; // ... rest of your server entry @@ -420,7 +413,7 @@ If you're deploying to platforms where you can't set the `NODE_OPTIONS` flag, im ```tsx {diff} {filename: entry.server.tsx} -+import './instrument.server'; ++import '../instrument.server'; import * as Sentry from '@sentry/react-router'; import { createReadableStreamFromReadable } from '@react-router/node'; import { renderToPipeableStream } from 'react-dom/server'; @@ -452,7 +445,7 @@ First, update `vite.config.ts` to include the `sentryReactRouter` plugin, making ```typescript {filename: vite.config.ts} {diff} import { reactRouter } from '@react-router/dev/vite'; -import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router'; +import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router/vite'; import { defineConfig } from 'vite'; const sentryConfig: SentryReactRouterBuildOptions = { @@ -506,14 +499,14 @@ Next, include the `sentryOnBuildEnd` hook in `react-router.config.ts`: ```typescript {filename: react-router.config.ts} {diff} import type { Config } from "@react-router/dev/config"; -import { sentryOnBuildEnd } from "@sentry/react-router"; +import { sentryOnBuildEnd } from "@sentry/react-router/vite"; export default { ssr: true, buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => { // ... // Call this at the end of the hook - +(await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest })); ++ await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest }); }, } satisfies Config; ``` diff --git a/platform-includes/getting-started-prerequisites/javascript.react-router.mdx b/platform-includes/getting-started-prerequisites/javascript.react-router.mdx new file mode 100644 index 0000000000000..5de5e376f5010 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.react-router.mdx @@ -0,0 +1,7 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- React Router version `7.15.0` or above (framework mode) From 83767bdbbf01434728ad5edfbe81462dac39bc22 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:25:08 +0200 Subject: [PATCH 12/48] docs(js): Update metrics docs for v11 (#19396) Removes `enableMetrics` from the JS metrics docs and documents the `*.logs.metrics` CDN bundle requirement for v11. Closes https://linear.app/getsentry/issue/SDK-1477/update-metrics-docs-for-v11 --- .../javascript/common/configuration/options.mdx | 7 ------- platform-includes/metrics/options/javascript.mdx | 11 ++++++++--- platform-includes/metrics/requirements/javascript.mdx | 6 ++++++ platform-includes/metrics/usage/javascript.mdx | 2 +- 4 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index ce8b3a26fe7cc..ddce8c8726c52 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -815,13 +815,6 @@ This function is called with a log object, and can return a modified log object, are set. - - -Set this option to `false` to disable metric capturing in Sentry (enabled by default). -Only when this option is enabled will the `metrics` APIs actually send metrics to Sentry. - - - This function is called with a metric object, and can return a modified metric object, or `null` to skip sending this metric to Sentry. diff --git a/platform-includes/metrics/options/javascript.mdx b/platform-includes/metrics/options/javascript.mdx index 08c7a4247bed3..2f34ab3ee2b8a 100644 --- a/platform-includes/metrics/options/javascript.mdx +++ b/platform-includes/metrics/options/javascript.mdx @@ -37,7 +37,12 @@ Sentry.init({ ### Disable Metrics -Set `enableMetrics: false` to disable metrics collection entirely. +Metrics are only captured when you call `Sentry.metrics.*`, so there is no option to turn them on or off. To stop sending metrics without removing those calls, return `null` from `beforeSendMetric`. + + + On SDK versions below `11.0.0`, set `enableMetrics: false` in your + `Sentry.init` to disable metrics instead. + ### Flush Metrics @@ -47,10 +52,10 @@ Metrics are buffered and sent periodically. Use this snippet to flush immediatel ```javascript -// Disable metrics +// Drop all metrics Sentry.init({ dsn: "___PUBLIC_DSN___", - enableMetrics: false, + beforeSendMetric: () => null, }); // Flush all pending metrics diff --git a/platform-includes/metrics/requirements/javascript.mdx b/platform-includes/metrics/requirements/javascript.mdx index a7404ef7f43db..f15b9be3c6c56 100644 --- a/platform-includes/metrics/requirements/javascript.mdx +++ b/platform-includes/metrics/requirements/javascript.mdx @@ -1,3 +1,9 @@ Metrics are supported in all Sentry JavaScript SDKs version `10.25.0` and above. Make sure you have the SDK set up before proceeding. + + + +Metrics are also supported via [CDN bundles and the Loader Script](/platforms/javascript/install/loader/). Use a bundle that includes metrics, such as `bundle.logs.metrics.min.js`. On other bundles, `Sentry.metrics.*` calls are a no-op that only warns when `debug` is enabled. + + diff --git a/platform-includes/metrics/usage/javascript.mdx b/platform-includes/metrics/usage/javascript.mdx index 2743757f8af70..a70fa09f78a87 100644 --- a/platform-includes/metrics/usage/javascript.mdx +++ b/platform-includes/metrics/usage/javascript.mdx @@ -10,7 +10,7 @@ | `gauge` | Current values (queue depth, connections) | | `distribution` | Value ranges (response times, payload sizes) | -No setup required beyond SDK initialization. +No setup required beyond SDK initialization. Metrics are captured whenever you call `Sentry.metrics.*`. From 2a0bc8909bc1c049eec0a5c9be49a7ca377cb842 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:26:16 +0200 Subject: [PATCH 13/48] docs(fastify): Fix imports in error handler snippet (#19426) Rewrites the Fastify error handler page for v11. `setupFastifyErrorHandler` is a deprecated no-op in v11, so the page now documents only the happy path: errors are captured by `fastifyIntegration`, which is enabled by default, and `shouldHandleError` is configured on the integration. This also removes the old snippet's import of `@sentry/fastify`, a package that does not exist. Closes https://linear.app/getsentry/issue/SDK-1496/fastify-getting-started-manual-setup --------- Co-authored-by: Claude Opus 5 --- .../guides/fastify/features/error-handler.mdx | 40 ++++++++----------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/docs/platforms/javascript/guides/fastify/features/error-handler.mdx b/docs/platforms/javascript/guides/fastify/features/error-handler.mdx index af18d44139e9d..43e3c0f8cf935 100644 --- a/docs/platforms/javascript/guides/fastify/features/error-handler.mdx +++ b/docs/platforms/javascript/guides/fastify/features/error-handler.mdx @@ -1,34 +1,36 @@ --- title: Fastify Error Handler -description: "Learn about Sentry's Fastify SDK Error Handler and how to configure it." +description: "Learn how Sentry's Fastify integration captures errors and how to configure it." --- -The Fastify error handler integration automatically captures errors in your Fastify application and sends them to Sentry. By default, it captures all errors with status codes 5xx and above, as well as errors with status codes 2xx and below. +The `fastifyIntegration` captures errors in your Fastify application and sends them to Sentry. It's enabled by default, so you only need to add it to your `Sentry.init` call to configure it. + +By default, errors with status codes 5xx and above, as well as errors with status codes 2xx and below, are captured. Errors with 3xx and 4xx status codes aren't sent to Sentry. ## Configuration -You can configure the error handler using the `setupFastifyErrorHandler` function: +To control which errors are captured, pass `shouldHandleError` to `Sentry.fastifyIntegration`: ```javascript import * as Sentry from "@sentry/node"; -import { setupFastifyErrorHandler } from "@sentry/fastify"; - -const app = fastify(); -// Initialize Sentry Sentry.init({ dsn: "your-dsn", + integrations: [ + Sentry.fastifyIntegration({ + shouldHandleError(error, request, reply) { + return reply.statusCode >= 500; + }, + }), + ], }); - -// Setup the error handler -setupFastifyErrorHandler(app); ``` ## Options -The `setupFastifyErrorHandler` function accepts an optional options object that can be used to customize the error handler. +`Sentry.fastifyIntegration` accepts the following options: -- `shouldHandleError` _version 9.9.0+_ +- `shouldHandleError` A function that determines whether an error should be captured. @@ -40,24 +42,16 @@ declare function shouldHandleError( ): boolean; ``` -```javascript -setupFastifyErrorHandler(app, { - shouldHandleError(error, request, reply) { - return reply.statusCode >= 500 || reply.statusCode <= 399; - }, -}); -``` - If using TypeScript, you can cast the request and reply to get full type safety. ```typescript -import { FastifyRequest, FastifyReply } from "fastify"; +import type { FastifyRequest, FastifyReply } from "fastify"; -setupFastifyErrorHandler(app, { +Sentry.fastifyIntegration({ shouldHandleError(error, minimalRequest, minimalReply) { const request = minimalRequest as FastifyRequest; const reply = minimalReply as FastifyReply; - return reply.statusCode >= 500 || reply.statusCode <= 399; + return reply.statusCode >= 500; }, }); ``` From 0bd21d5eff04202dcc480cf889ce044366b1a36b Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:26:32 +0200 Subject: [PATCH 14/48] docs(remix): Fix manual setup and document Cloudflare Workers for v11 (#19425) Fixes the Remix manual setup and the Remix on Cloudflare page for v11. The handleError and Vite snippets no longer break the build, the Cloudflare branch now documents a working Workers setup (`withSentry` + `instrumentBuild`, `handleError` from `@sentry/remix/cloudflare`, `sentryCloudflareVitePlugin`), and v10-only bits like `--require` are gone. It also updates the Cloudflare Vite plugin page to the shipped top-level `buildTimeInstrumentation` and `autoInstrumentation` options, and adds a request isolation warning for `wrapRequestHandler` to both Hydrogen pages. Closes https://linear.app/getsentry/issue/SDK-1512/remix-getting-started-manual-setup --- .../frameworks/hydrogen-react-router.mdx | 6 + .../cloudflare/frameworks/hydrogen-remix.mdx | 6 + .../guides/cloudflare/frameworks/remix.mdx | 10 +- .../javascript/guides/cloudflare/index.mdx | 11 +- .../guides/cloudflare/install/vite-plugin.mdx | 21 +- .../guides/cloudflare/install/wrangler.mdx | 2 +- .../javascript.remix.mdx | 234 ++++++++++++++++-- .../sourcemaps/overview/javascript.remix.mdx | 57 ++--- 8 files changed, 259 insertions(+), 88 deletions(-) diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx index 7d3564242446d..78589df78ec27 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx @@ -180,6 +180,12 @@ On Shopify Oxygen, never import anything directly from `@sentry/cloudflare`. Onl + + +`wrapRequestHandler` doesn't isolate requests from each other. Scope data you set during a request, for example with `setTag` or `setUser`, can show up on events from other concurrent or later requests in the same isolate. Use `wrapRequestHandler` only on runtimes that can't enable `nodejs_compat`, such as Shopify Oxygen. On Cloudflare Workers, wrap your handler with `Sentry.withSentry()` instead, as described in the [Cloudflare guide](/platforms/javascript/guides/cloudflare/). + + + diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx index 0ae565165243d..0bc2d4d382e54 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx @@ -37,6 +37,12 @@ On Shopify Oxygen, never import anything directly from `@sentry/cloudflare`. Onl + + +`wrapRequestHandler` doesn't isolate requests from each other. Scope data you set during a request, for example with `setTag` or `setUser`, can show up on events from other concurrent or later requests in the same isolate. Use `wrapRequestHandler` only on runtimes that can't enable `nodejs_compat`, such as Shopify Oxygen. For Remix on Cloudflare Workers, follow the [Remix on Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/remix/) instead. + + + ```ts {filename:server.ts} import { wrapRequestHandler } from "@sentry/cloudflare/request"; import { instrumentBuild } from "@sentry/remix/cloudflare"; diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx index e67065e7a1fcc..87b9c85bf2122 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx @@ -31,21 +31,23 @@ Choose the features you want to configure, and this guide will show you how: -Run the command for your preferred package manager to add the Sentry SDK to your application: +Run the command for your preferred package manager to add the Sentry Remix and Cloudflare SDKs to your application. + +With npm, add `--legacy-peer-deps`: `@remix-run/cloudflare` requires `@cloudflare/workers-types` version 4, while Wrangler 4 requires version 5. ```bash {tabTitle:npm} -npm install @sentry/remix --save +npm install @sentry/remix @sentry/cloudflare --save --legacy-peer-deps ``` ```bash {tabTitle:yarn} -yarn add @sentry/remix +yarn add @sentry/remix @sentry/cloudflare ``` ```bash {tabTitle:pnpm} -pnpm add @sentry/remix +pnpm add @sentry/remix @sentry/cloudflare ``` diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index ee86267841af2..1ca6aba3bf96a 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -81,9 +81,9 @@ Not using Vite? See the Wrangler setup -Add the Sentry plugin to your existing `vite.config.ts`, next to `cloudflare()`. Both behaviors are experimental in this version, so turn them on explicitly. +Add the Sentry plugin to your existing `vite.config.ts`, next to `cloudflare()`. Both of its behaviors are on by default. -`autoInstrumentation` wraps your Worker entry, and any Durable Object, Workflow or Agents SDK class in your wrangler config, at build time, so you don't have to call `Sentry.withSentry()` yourself. `useDiagnosticsChannelInjection` instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime, where the SDK can't patch them at runtime. +`autoInstrumentation` wraps your Worker entry, and any Durable Object, Workflow or Agents SDK class in your wrangler config, at build time, so you don't have to call `Sentry.withSentry()` yourself. `buildTimeInstrumentation` instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime, where the SDK can't patch them at runtime. To see its options, which packages it instruments, and how to opt out of either behavior, see Vite Plugin. @@ -98,12 +98,7 @@ To see its options, which packages it instruments, and how to opt out of either export default defineConfig({ plugins: [ cloudflare(), -+ sentryCloudflareVitePlugin({ -+ _experimental: { -+ autoInstrumentation: true, -+ useDiagnosticsChannelInjection: true, -+ }, -+ }), ++ sentryCloudflareVitePlugin(), ], }); ``` diff --git a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx index f6dbe06fcc132..8007e7ff0208c 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx @@ -15,7 +15,7 @@ The Sentry Cloudflare Vite plugin (`sentryCloudflareVitePlugin`) instruments you 1. **Instrument bundled dependencies**: instruments supported packages in your bundle, such as database clients and AI SDKs, giving you more traces out of the box. 2. **Auto-instrument your Worker entry**: wraps your default export with `Sentry.withSentry()`, and Durable Object, Workflow, and Agents SDK classes with the matching `instrument*WithSentry` helper at build time, so you don't need to modify your code. -Both are opt-in while the plugin is experimental. Turn them on with [`_experimental.useDiagnosticsChannelInjection`](#_experimentalusediagnosticschannelinjection) and [`_experimental.autoInstrumentation`](#_experimentalautoinstrumentation). +Both are on by default. Turn either off with [`buildTimeInstrumentation`](#buildtimeinstrumentation) and [`autoInstrumentation`](#autoinstrumentation). The quick start covers adding the plugin and creating `instrument.server.ts`. This page documents what it instruments, its @@ -25,7 +25,7 @@ options, and the details that matter once it's running. The plugin reads your wrangler config (probing `wrangler.json`, `wrangler.jsonc`, and `wrangler.toml` at the Vite root, or the file set with [`wranglerConfigPath`](#wranglerconfigpath)) to find the entry point, Durable Objects, workflows, and Agents SDK classes. It wraps Agents SDK classes (`Agent`, `AIChatAgent`, `McpAgent`) with `instrumentAgentWithSentry`, which also gives them automatic conversation IDs (see Cloudflare Agents SDK). -Any entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, leave `_experimental.autoInstrumentation` off and follow the Wrangler setup. +Any entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, set `autoInstrumentation: false` and follow the Wrangler setup. With auto-instrumentation, you can optionally provide Sentry options via a co-located `instrument.server.*` file (`.ts`, `.mts`, `.js`, `.mjs`, or `.cjs`) next to your Worker entry. The plugin resolves this location from `main` in your wrangler config. For example, if `main` is `src/worker/index.ts`, place the file at `src/worker/instrument.server.ts`, not at the project root. Use `defineCloudflareOptions` for full type-checking: @@ -79,9 +79,6 @@ export default defineConfig({ cloudflare({ configPath: "./wrangler.agent.jsonc" }), sentryCloudflareVitePlugin({ wranglerConfigPath: "./wrangler.agent.jsonc", - _experimental: { - autoInstrumentation: true, - }, }), ], }); @@ -89,23 +86,17 @@ export default defineConfig({ - + -Experimental options that may change or be removed without notice. - - - - - -Build-time instrumentation of supported dependencies. The plugin injects `diagnostics_channel.tracingChannel` calls into the bundled packages, and next to each one a snippet that registers the matching Sentry channel subscriber, which the SDK picks up in `Sentry.withSentry()`. This is how those packages get traced in the Workers runtime, where the SDK can't monkey-patch them. Both `vite build` and `vite dev` are instrumented. +Build-time instrumentation of supported dependencies. The plugin injects `diagnostics_channel.tracingChannel` calls into the bundled packages, and next to each one a snippet that registers the matching Sentry channel subscriber, which the SDK picks up in `Sentry.withSentry()`. This is how those packages get traced in the Workers runtime, where the SDK can't monkey-patch them. Both `vite build` and `vite dev` are instrumented. Set to `false` to opt out. A package is only instrumented if it's actually bundled. A dependency you mark as external is resolved at runtime and never passes through the build, so it stays untraced. - + -Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry` (SDK version 10.69.0 or higher). Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). +Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry` (SDK version 10.69.0 or higher). Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). Set to `false` to opt out. diff --git a/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx b/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx index 2ff396ccfc0aa..120d277af1319 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx @@ -17,7 +17,7 @@ Everything else is the same: install, Wrangler configuration, source maps, and t `withSentry` gives you the same errors and request traces as the plugin. What a plain Wrangler build can't do is instrument your bundled dependencies. -The Workers runtime doesn't let the SDK patch modules at runtime, so packages like database and AI clients are only traced when something rewrites them during the build. That's what the Vite plugin's `_experimental.useDiagnosticsChannelInjection` does. Without it, spans from those packages are missing, and you only get the spans the SDK creates itself. +The Workers runtime doesn't let the SDK patch modules at runtime, so packages like database and AI clients are only traced when something rewrites them during the build. That's what the Vite plugin's `buildTimeInstrumentation` does. Without it, spans from those packages are missing, and you only get the spans the SDK creates itself. You also have to keep the wrapper in your code, and list your RPC trace propagation bindings by hand, because a plain build can't derive them. See RPC Trace Propagation. diff --git a/platform-includes/getting-started-complete/javascript.remix.mdx b/platform-includes/getting-started-complete/javascript.remix.mdx index 373689d8ec566..5bda03ffc0b23 100644 --- a/platform-includes/getting-started-complete/javascript.remix.mdx +++ b/platform-includes/getting-started-complete/javascript.remix.mdx @@ -186,8 +186,8 @@ Sentry.init({ profileSessionSampleRate: 1.0, // ___PRODUCT_OPTION_END___ profiling - // Optionally capture action formData attributes with errors. - // This requires `sendDefaultPii` set to true as well. + // Optionally limit which action formData fields are captured. + // Without this option, all fields are captured. captureActionFormDataKeys: { key_x: true, key_y: true, @@ -208,8 +208,6 @@ Then run your Remix server using the `--import` command line option and point it ```bash NODE_OPTIONS='--import=./instrument.server.mjs' remix-serve build -# or -NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build ``` @@ -227,10 +225,9 @@ If you use the Express server instead of the built-in Remix server, you can impo -```typescript {filename: server.(mjs|cjs)} +```typescript {filename: server.mjs} // import the Sentry instrumentation file before anything else. import "./instrument.server.mjs"; -// alternatively `require('./instrument.server.cjs')` // ... @@ -253,6 +250,59 @@ const app = express(); +Create a Worker entry file, for example `server.ts` in your project's root folder, and set it as `main` in your wrangler config. + +In this file, instrument your Remix server build with `instrumentBuild` from `@sentry/remix/cloudflare`, pass it to `createRequestHandler`, and wrap the exported handler with `Sentry.withSentry()` from `@sentry/cloudflare`. `withSentry` isolates each request, so scope data like tags and users stays on the request that set it. + + + +Don't also wrap `createRequestHandler` with `makeWrappedCreateRequestHandler`. Combined with `withSentry`, it reports every request twice, as two `http.server` transactions in two different traces. + + + + + + +```typescript {filename:server.ts} +import { createRequestHandler } from "@remix-run/cloudflare"; +import * as Sentry from "@sentry/cloudflare"; +import { instrumentBuild } from "@sentry/remix/cloudflare"; +// The server build produced by `remix vite:build` +import * as remixBuild from "./build/server/index.js"; + +const handleRequest = createRequestHandler(instrumentBuild(remixBuild)); + +export default Sentry.withSentry( + (env) => ({ + dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + }), + { + async fetch(request, env, ctx) { + return handleRequest(request, { env, ctx }); + }, + } +); +``` + + + + + + + + + + + @@ -276,8 +326,8 @@ export const onRequest = [ tracesSampleRate: 1.0, // ___PRODUCT_OPTION_END___ performance - // Optionally capture action formData attributes with errors. - // This requires `sendDefaultPii` set to true as well. + // Optionally limit which action formData fields are captured. + // Without this option, all fields are captured. captureActionFormDataKeys: { key_x: true, key_y: true, @@ -291,15 +341,22 @@ export const onRequest = [ + + ### Capture Server-Side Errors + + -To automatically capture server-side errors, instrument the [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function in your server entry point (`entry.server.tsx`). You can wrap your custom error handler with `wrapHandleErrorWithSentry` or directly use `sentryHandleError`: +To automatically capture server-side errors, export a [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function from your server entry point (`entry.server.tsx`). Choose one of the two options: + +- Wrap your custom error handler with `wrapHandleErrorWithSentry`. +- Use `sentryHandleError` directly if you don't have a custom error handler. @@ -310,7 +367,7 @@ Sentry's Remix SDK automatically records your [`action`](https://remix.run/docs/ -```typescript {filename: entry.server.tsx} +```typescript {tabTitle:Custom Error Handler} {filename: entry.server.tsx} import * as Sentry from "@sentry/remix"; export const handleError = Sentry.wrapHandleErrorWithSentry( @@ -318,8 +375,11 @@ export const handleError = Sentry.wrapHandleErrorWithSentry( // Custom handleError implementation } ); +``` + +```typescript {tabTitle:Default Error Handler} {filename: entry.server.tsx} +import * as Sentry from "@sentry/remix"; -// Alternative: Use the Sentry utility function if you don't need to wrap a custom function export const handleError = Sentry.sentryHandleError; ``` @@ -327,6 +387,37 @@ export const handleError = Sentry.sentryHandleError; + + + + + + + + +To automatically capture server-side errors, export `sentryHandleError` as the [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function from your server entry point (`entry.server.tsx`). Without this export, Remix handles errors thrown in loaders and actions itself, and Sentry doesn't receive them. + + + +Import from `@sentry/remix/cloudflare`, not from `@sentry/remix`. In a Cloudflare server build, `sentryHandleError` from `@sentry/remix` is `undefined`, and no errors are captured. + + + + + + +```typescript {filename: entry.server.tsx} +import { sentryHandleError } from "@sentry/remix/cloudflare"; + +export const handleError = sentryHandleError; +``` + + + + + + + ### Configure Cloudflare for Sentry @@ -338,13 +429,116 @@ export const handleError = Sentry.sentryHandleError; +### Configure Vite + + + + + + + +Add `sentryRemixVitePlugin` from `@sentry/remix/vite` to your `vite.config.ts`. The plugin: + +- Parameterizes client-side transaction names with your route patterns, for example `/users/:id`. +- Instruments supported server-side dependencies, such as database clients, at build time. + + + +You can skip this step. Client-side transaction names then use the URL instead of the route pattern. + + + + + + +```typescript {filename:vite.config.ts} {2, 10} +import { vitePlugin as remix } from "@remix-run/dev"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + remix({ + // ... your Remix plugin options + }), + sentryRemixVitePlugin(), + ], +}); +``` + + + + + + + + + + + + + +Add two Sentry plugins to your `vite.config.ts`, next to the Remix plugin: + +- `sentryRemixVitePlugin` from `@sentry/remix/vite` parameterizes transaction names with your route patterns, for example `/users/:id`. +- `sentryCloudflareVitePlugin` from `@sentry/cloudflare/vite` instruments supported bundled dependencies at build time, so you get spans for database clients like `mysql`. Without it, database calls produce no spans and no warning. + +Set `ssr.target` to `webworker` and bundle the Sentry packages and any database client you want traced with `ssr.noExternal`. Setting `noExternal: true` bundles every dependency, which works too. + + + + +```typescript {filename:vite.config.ts} {2-3, 11-12, 14-17} +import { vitePlugin as remix } from "@remix-run/dev"; +import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + remix({ + // ... your Remix plugin options + }), + sentryRemixVitePlugin(), + sentryCloudflareVitePlugin(), + ], + ssr: { + target: "webworker", + noExternal: ["mysql", /^@sentry\//, "@opentelemetry/api"], + }, +}); +``` + + + + + + + +Build your app with `remix vite:build`. Under Vite 6, a plain `vite build` only builds the client and skips `build/server`, without an error. + + + + +```bash +npx remix vite:build +``` + + + + + + + ### Add Readable Stack Traces With Source Maps (Optional) -To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your `vite.config.ts` file: +To upload source maps for clear error stack traces, pass your Sentry organization, project, and auth token to `sentryRemixVitePlugin` from the previous step. It injects debug IDs, uploads the source maps during your production build, and deletes them from your build output afterwards. + +The plugin also turns on hidden source maps for you, unless you set `build.sourcemap` yourself. @@ -356,30 +550,26 @@ alternative setup options. -```javascript {filename:vite.config.ts} {3, 10-17,20-23} -import { defineConfig } from "vite"; +```javascript {filename:vite.config.ts} {10-16} import { vitePlugin as remix } from "@remix-run/dev"; -import { sentryVitePlugin } from "@sentry/vite-plugin"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; export default defineConfig({ plugins: [ remix({ // ... your Remix plugin options }), - sentryVitePlugin({ - // If you use .sentryclirc or environment variables, + sentryRemixVitePlugin({ + // If you use environment variables, // you don't need to specify these options org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", // store your auth token in an environment variable authToken: process.env.SENTRY_AUTH_TOKEN, }), + // ... other plugins ], - - build: { - sourcemap: "hidden", - // ... rest of your Vite build options - }, }); ``` diff --git a/platform-includes/sourcemaps/overview/javascript.remix.mdx b/platform-includes/sourcemaps/overview/javascript.remix.mdx index 40b741b58836f..44817187e006e 100644 --- a/platform-includes/sourcemaps/overview/javascript.remix.mdx +++ b/platform-includes/sourcemaps/overview/javascript.remix.mdx @@ -9,66 +9,47 @@ If you installed the SDK manually or the wizard failed, follow the steps below t Starting from version 2.2.0, Remix supports [Vite](https://vitejs.dev/) as a build tool, and from Remix version 2.7.0 it's stable and the recommended way to build your application. -If you use Vite to build your project, you can use the [Vite plugin](/platforms/javascript/sourcemaps/uploading/vite/) to upload source maps to Sentry. +If you use Vite to build your project, `sentryRemixVitePlugin` uploads your source maps to Sentry. It ships with `@sentry/remix`, so there's no extra package to install. -First, install the plugin if you haven't already done so: - -```bash {tabTitle:npm} -npm install @sentry/vite-plugin --save-dev -``` - -```bash {tabTitle:yarn} -yarn add @sentry/vite-plugin --dev -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/vite-plugin --save-dev -``` - -Then, add the plugin to your Vite configuration: +Add your Sentry organization, project, and auth token to the plugin in your Vite configuration: ```typescript {filename:vite.config.ts} -import { defineConfig } from "vite"; import { vitePlugin as remix } from "@remix-run/dev"; -import { sentryVitePlugin } from "@sentry/vite-plugin"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; export default defineConfig({ plugins: [ remix({ // ... your Remix plugin options }), - sentryVitePlugin({ - // If you use .sentryclirc or environment variables, - // you don't need to specify these options - authToken: "___SENTRY_AUTH_TOKEN___", + sentryRemixVitePlugin({ + // If you use environment variables, you don't need to specify these options + authToken: process.env.SENTRY_AUTH_TOKEN, org: "___SENTRY_ORG_SLUG___", project: "___SENTRY_PROJECT_SLUG___", - - sourcemaps: { - // As you're enabling client source maps, you probably want to delete them after they're uploaded to Sentry. - // Set the appropriate glob pattern for your output folder - some glob examples below: - filesToDeleteAfterUpload: ["./**/*.map", ".*/**/public/**/*.map", "./dist/**/client/**/*.map"] - } }), ], - build: { - sourcemap: "hidden", // Source map generation must be turned on ("hidden", true, etc.) - // ... rest of your Vite build options - }, // ... rest of your Vite config }); ``` +The plugin reads `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` from your environment, so you can leave the options out and set those instead. + +During a production build, the plugin injects debug IDs, uploads the source maps, and then deletes the `.map` files it generated from your build output. It skips uploading in development, so `vite dev` doesn't create a new set of artifacts on every restart. + +If you don't set `build.sourcemap` yourself, the plugin turns on hidden source maps. If you do set it, the plugin keeps your setting and leaves your source maps in place, so you control whether they're deleted with `sourcemaps.filesToDeleteAfterUpload`. + - Generating source maps **may expose them to the public**, potentially causing your - source code to be leaked. You can prevent this by configuring your server to deny access to `.js.map` files, or by - using [Sentry Vite Plugin's - `sourcemaps.filesToDeleteAfterUpload`](https://www.npmjs.com/package/@sentry/vite-plugin#sourcemapsfilestodeleteafterupload) - option to delete source maps after they've been uploaded to Sentry. + Generating source maps **may expose them to the public**, potentially causing + your source code to be leaked. If you turn on source maps yourself, prevent + this by configuring your server to deny access to `.js.map` files, or by + setting `sourcemaps.filesToDeleteAfterUpload` to delete them after they've + been uploaded to Sentry. -To see the full list of options, refer to the [Vite plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin). +To turn uploading off, set `sourcemaps.disable` to `true`. To keep the debug IDs and upload the maps yourself, set it to `'disable-upload'`. ### Using `npx @sentry/remix --upload-sourcemaps` From d4390974dc404cbb507a4a86abdb4f57db35b4cb Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:26:55 +0200 Subject: [PATCH 15/48] docs(js): Replace legacy profiling options with session-based API (#19427) The legacy `profilesSampleRate`/`profilesSampler` options were removed in favor of session-based profiling. This updates the Firebase and Hono guides to use `profileSessionSampleRate` with `profileLifecycle: "trace"` (Firebase was also missing `nodeProfilingIntegration()`), and removes the deprecated `profilesSampleRate` entries from the JavaScript options reference. Closes https://linear.app/getsentry/issue/SDK-1489/fix-remaining-legacy-profiling-options-in-docs --- .../common/configuration/options.mdx | 16 ---------------- .../javascript/guides/firebase/index.mdx | 19 ++++++++++++++++--- .../javascript/guides/hono/index.mdx | 4 +++- 3 files changed, 19 insertions(+), 20 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index ddce8c8726c52..6cb07ab8a777d 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -861,14 +861,6 @@ Determines how profiling sessions are controlled. It has two modes: - - -**Deprecated:** Use `profileSessionSampleRate` instead to configure continuous profiling from version `7.4.0` onwards. - -A number between `0` and `1`, controlling the percentage chance a given sampled transaction will be profiled. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. This is relative to the tracing sample rate - e.g. `0.5` means 50% of sampled transactions will be profiled. - - - @@ -900,14 +892,6 @@ Determines how profiling sessions are controlled. It has two modes: - - -**Deprecated:** Use `profileSessionSampleRate` instead to configure continuous profiling from version 10.27.0 onwards. - -A number between `0` and `1`, controlling the percentage chance a given sampled transaction will be profiled. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. This is relative to the tracing sample rate - e.g. `0.5` means 50% of sampled transactions will be profiled. - - - diff --git a/docs/platforms/javascript/guides/firebase/index.mdx b/docs/platforms/javascript/guides/firebase/index.mdx index f34b8fadbc14d..3db1029ac534b 100644 --- a/docs/platforms/javascript/guides/firebase/index.mdx +++ b/docs/platforms/javascript/guides/firebase/index.mdx @@ -96,10 +96,20 @@ Create an initialization file (for example, `instrument.js`) that imports and in ```javascript {filename:instrument.js} const Sentry = require("@sentry/node"); +// ___PRODUCT_OPTION_START___ profiling +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); +// ___PRODUCT_OPTION_END___ profiling Sentry.init({ dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ profiling + + integrations: [ + // Add our Profiling integration + nodeProfilingIntegration(), + ], + // ___PRODUCT_OPTION_END___ profiling // ___PRODUCT_OPTION_START___ performance // Add Tracing by setting tracesSampleRate @@ -111,9 +121,12 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ performance // ___PRODUCT_OPTION_START___ profiling - // Set profilesSampleRate to 1.0 to profile 100% of sampled transactions. - // This is relative to tracesSampleRate - profilesSampleRate: 1.0, + // Enable profiling for a percentage of sessions + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate + profileSessionSampleRate: 1.0, + // Profile automatically while there's an active sampled span + profileLifecycle: "trace", // ___PRODUCT_OPTION_END___ profiling }); ``` diff --git a/docs/platforms/javascript/guides/hono/index.mdx b/docs/platforms/javascript/guides/hono/index.mdx index e8c0afc71400a..a76d157297271 100644 --- a/docs/platforms/javascript/guides/hono/index.mdx +++ b/docs/platforms/javascript/guides/hono/index.mdx @@ -188,10 +188,12 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ performance // ___PRODUCT_OPTION_START___ profiling - // Set profilesSampleRate relative to tracesSampleRate + // Enable profiling for a percentage of sessions // Learn more at // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate profileSessionSampleRate: 1.0, + // Profile automatically while there's an active sampled span + profileLifecycle: "trace", // ___PRODUCT_OPTION_END___ profiling }); ``` From 859d90b4c5698f4b59f4c73d2993c2eddbffd6d8 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 15:28:30 +0200 Subject: [PATCH 16/48] docs(astro): update minimum Astro version to 4 (#19315) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Set the Astro minimum to 4.0.0 for v11 and drop the now-moot `3.5.2` version qualifiers from the server-instrumentation notes. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) Co-authored-by: Andrei Borza --- docs/platforms/javascript/common/configuration/apis.mdx | 6 +++--- .../tracing/instrumentation/automatic-instrumentation.mdx | 2 +- docs/platforms/javascript/guides/astro/index.mdx | 2 +- .../getting-started-complete/javascript.astro.mdx | 6 ------ 4 files changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/apis.mdx b/docs/platforms/javascript/common/configuration/apis.mdx index bc4bd902ca6c3..3f3c47c563738 100644 --- a/docs/platforms/javascript/common/configuration/apis.mdx +++ b/docs/platforms/javascript/common/configuration/apis.mdx @@ -1461,9 +1461,9 @@ export const GET = wrapServerRouteWithSentry(async () => { ## Server Request Instrumentation -Astro server requests are automatically instrumented starting from Astro version `3.5.2`. +Astro server requests are automatically instrumented. -If you're below Astro version `3.5.2` or want to customize instrumentation, you can use `Sentry.handleRequest()` as an Astro middleware. +If you want to customize instrumentation, you can use `Sentry.handleRequest()` as an Astro middleware. -If you're using Astro version `>=3.5.2`, you must disable automatic instrumentation before adding this middleware manually. +You must disable automatic instrumentation before adding this middleware manually. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx index d1d6d46ae49b3..7b17dd9cfd265 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx @@ -42,7 +42,7 @@ Once you enable tracing, the SDK automatically captures performance data without ## Disable Automatic Instrumentation -For Astro version `3.5.2` and up, you can optionally disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: +You can optionally disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: ```javascript {filename:astro.config.mjs} import { defineConfig } from "astro/config"; diff --git a/docs/platforms/javascript/guides/astro/index.mdx b/docs/platforms/javascript/guides/astro/index.mdx index 5a6569da961e8..79f9f86d22fd2 100644 --- a/docs/platforms/javascript/guides/astro/index.mdx +++ b/docs/platforms/javascript/guides/astro/index.mdx @@ -13,7 +13,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- Astro `3.0.0` or above +- Astro `4.0.0` or above - If you're using Astro's Netlify adapter (`@astrojs/netlify`), you need version `5.0.0` or above diff --git a/platform-includes/getting-started-complete/javascript.astro.mdx b/platform-includes/getting-started-complete/javascript.astro.mdx index 64031453f1e2d..6e359cabaf134 100644 --- a/platform-includes/getting-started-complete/javascript.astro.mdx +++ b/platform-includes/getting-started-complete/javascript.astro.mdx @@ -296,12 +296,6 @@ export default defineConfig({ Create a `sentry.server.config.(ts|js)` file in the root of your project. In this file, import and initialize Sentry for the server: - - -For Astro versions below `3.5.2`, you need to manually add server instrumentation via the Sentry middleware as explained on our APIs page. - - - From e272f47c3c53a80a26c7c69d00ba60c3798059a6 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:30:26 +0200 Subject: [PATCH 17/48] docs(javascript): Note that tags and extra don't apply to streamed spans (#19549) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR With span streaming enabled, spans only carry attributes, so scope tags and extra (`setTag`, `setTags`, `setExtra`, `setExtras`) no longer reach any span. They still apply to errors, and in transaction mode (`traceLifecycle: "static"`) they keep landing on the transaction. This adds a note about that to the three JavaScript enriching-events pages where readers set that data, and points them to `setAttribute`/`setAttributes` for anything that should be searchable on spans. - `enriching-events/tags/` — extend the existing "not applied to logs or metrics" warning to cover spans - `enriching-events/scopes/` — callout after the "How Scope Data is Applied to Events" example - `enriching-events/attributes/` — callout in the intro, noting attributes keep their type Refs SDK-1474 --------- Co-authored-by: Claude Opus 5 Co-authored-by: Lukas Stracke --- .../common/enriching-events/attributes/index.mdx | 6 ++++++ .../javascript/common/enriching-events/scopes/index.mdx | 8 ++++++++ .../javascript/common/enriching-events/tags/index.mdx | 6 +++++- 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/attributes/index.mdx b/docs/platforms/javascript/common/enriching-events/attributes/index.mdx index 41edd64e15be8..5ad9c71493437 100644 --- a/docs/platforms/javascript/common/enriching-events/attributes/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/attributes/index.mdx @@ -11,6 +11,12 @@ Unlike [tags](../tags/), which only accept `string` values, attributes support ` Common uses include subscription tier, feature flags, or any business context that helps you filter and query your telemetry. Check out [Sending Span Metrics](../../tracing/span-metrics/) for an example of how to use attributes to enrich your spans. + + +Use attributes for any data you want to search on spans. Streamed spans only carry attributes, so tags and extra (`Sentry.setTag()`, `Sentry.setExtra()`, and similar) aren't added to any span. They still apply to errors, so you don't need to remove them. Unlike tags, attributes keep their type, so you don't need to convert numbers and booleans to strings. + + + Setting attributes will bind them to the [isolation scope](../scopes/#isolation-scope). This ensures they'll automatically be included on future telemetry for the current request or page view: ```javascript diff --git a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx index 225af428a63fc..58441d6a711b2 100644 --- a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx @@ -104,6 +104,14 @@ Sentry.captureException(new Error("my error")); // { shared: 'current', global: 'data', isolation: 'data', current: 'data' } ``` + + +With span streaming enabled, spans only carry attributes. Tags and extra set on any scope (for example, with `setTag()`, `setTags()`, `setExtra()`, or `setExtras()`) aren't applied to spans. They still apply to errors, so you don't need to remove them. In transaction mode (`traceLifecycle: "static"`), they're still added to the transaction. + +To make data searchable on spans, set it with `setAttribute()` or `setAttributes()`, which also applies it to logs and metrics. See Attributes. + + + ## Configuring the Scope In most cases, you should use top-level methods like `Sentry.setTag()` directly, which will set the data on the isolation scope, ensuring it is applied to all events related to the current request/process. diff --git a/docs/platforms/javascript/common/enriching-events/tags/index.mdx b/docs/platforms/javascript/common/enriching-events/tags/index.mdx index 14c1e158ddcd8..0d8f2803c0b1d 100644 --- a/docs/platforms/javascript/common/enriching-events/tags/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/tags/index.mdx @@ -8,7 +8,11 @@ description: "Tags in Sentry's JavaScript SDK power UI features such as filters We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the number of distinct tags and can assist you in determining hotspots for various issues. - Tags are **not** applied to logs or metrics. If you're using SDK version `10.61.0` or above and want to attach context to logs or metrics, use Attributes instead. + +Tags are **not** applied to logs, metrics, or spans when span streaming is enabled. Tags still apply to errors, and in transaction mode (`traceLifecycle: "static"`) they're still added to the transaction. + +If you're using SDK version `10.61.0` or above and want data to be searchable on spans, logs, or metrics, use Attributes instead. + _Tag keys_ have a maximum length of 200 characters and can contain only letters (`a-zA-Z`), numbers (`0-9`), underscores (`_`), periods (`.`), colons (`:`), and dashes (`-`). From 718008ccef466d319444ad177825901c38d2f82a Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:35:58 +0200 Subject: [PATCH 18/48] docs(js): Remove deprecated framework error handler setup calls (#19428) closes https://linear.app/getsentry/issue/SDK-1482/document-automatic-framework-error-capture-expressfastifykoahapi-in --- .../javascript.express.mdx | 10 --------- .../javascript.fastify.mdx | 6 ----- .../javascript.koa.mdx | 6 ----- .../javascript.express.mdx | 22 +++++++++++++++++++ .../javascript.fastify.mdx | 3 +++ .../javascript.hapi.mdx | 3 +++ .../javascript.hono.mdx | 2 +- .../javascript.koa.mdx | 3 +++ .../javascript.express.mdx | 10 --------- .../javascript.fastify.mdx | 6 ----- .../getting-started-use/javascript.hapi.mdx | 6 ----- .../getting-started-use/javascript.koa.mdx | 6 ----- 12 files changed, 32 insertions(+), 51 deletions(-) create mode 100644 platform-includes/getting-started-capture-errors/javascript.express.mdx create mode 100644 platform-includes/getting-started-capture-errors/javascript.fastify.mdx create mode 100644 platform-includes/getting-started-capture-errors/javascript.hapi.mdx create mode 100644 platform-includes/getting-started-capture-errors/javascript.koa.mdx diff --git a/platform-includes/getting-started-add-top-level-import/javascript.express.mdx b/platform-includes/getting-started-add-top-level-import/javascript.express.mdx index 4843de736705e..3747f6fd492f5 100644 --- a/platform-includes/getting-started-add-top-level-import/javascript.express.mdx +++ b/platform-includes/getting-started-add-top-level-import/javascript.express.mdx @@ -3,15 +3,10 @@ require('./instrument.js') const express = require("express"); -const Sentry = require("@sentry/node"); const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` @@ -20,14 +15,9 @@ app.listen(3000); import './instrument.js' import express from "express"; -import * as Sentry from "@sentry/node"; const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` diff --git a/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx b/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx index c588a37961fe7..d10287bc4e075 100644 --- a/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx +++ b/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx @@ -3,11 +3,8 @@ require('./instrument.js') const Fastify = require("fastify"); -const Sentry = require("@sentry/node"); const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); @@ -18,11 +15,8 @@ app.listen({ port: 3030 }); import './instrument.js' import Fastify from "fastify"; -import * as Sentry from "@sentry/node"; const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); diff --git a/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx b/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx index 2d050160d4794..cba9dc32f4745 100644 --- a/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx +++ b/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx @@ -4,13 +4,10 @@ require('./instrument.js') const Koa = require('koa'); const Router = require('@koa/router'); -const Sentry = require("@sentry/node"); const router = new Router(); const app = new Koa(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.listen(3030); @@ -22,13 +19,10 @@ import './instrument.js' import Koa from 'koa'; import Router from '@koa/router'; -import * as Sentry from "@sentry/node"; const router = new Router(); const app = new Koa(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.listen(3030) diff --git a/platform-includes/getting-started-capture-errors/javascript.express.mdx b/platform-includes/getting-started-capture-errors/javascript.express.mdx new file mode 100644 index 0000000000000..9d86eeb45f304 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.express.mdx @@ -0,0 +1,22 @@ +### Report Unhandled Exceptions + +`expressIntegration` captures errors from your routes and middleware automatically, so you don't need to register a Sentry error handler. Errors with a 3xx or 4xx status code are skipped, since they're usually expected redirects or client errors. + +To change which errors are captured, pass a `shouldHandleError` callback to `expressIntegration()`. Return `true` to capture an error or `false` to skip it: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.expressIntegration({ + shouldHandleError(error) { + const status = Number(error.status ?? error.statusCode ?? 500); + // Capture 401/403 in addition to the default 5xx errors + return status === 401 || status === 403 || status >= 500; + }, + }), + ], +}); +``` + +If you capture errors yourself in your own error-handling middleware, set `shouldHandleError: false` to avoid duplicate events. diff --git a/platform-includes/getting-started-capture-errors/javascript.fastify.mdx b/platform-includes/getting-started-capture-errors/javascript.fastify.mdx new file mode 100644 index 0000000000000..f8b66c63d354f --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.fastify.mdx @@ -0,0 +1,3 @@ +### Report Unhandled Exceptions + +`fastifyIntegration` captures errors from your routes and hooks automatically, so you don't need to register a Sentry error handler. Errors with a 3xx or 4xx status code are skipped. To change which errors are captured, use the `shouldHandleError` option. diff --git a/platform-includes/getting-started-capture-errors/javascript.hapi.mdx b/platform-includes/getting-started-capture-errors/javascript.hapi.mdx new file mode 100644 index 0000000000000..d70bebcfdb131 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.hapi.mdx @@ -0,0 +1,3 @@ +### Report Unhandled Exceptions + +`hapiIntegration` registers an error handler when your Hapi server starts, so errors are captured automatically. No additional configuration is needed. diff --git a/platform-includes/getting-started-capture-errors/javascript.hono.mdx b/platform-includes/getting-started-capture-errors/javascript.hono.mdx index 806df42b477ef..1ea3d3dfb14a9 100644 --- a/platform-includes/getting-started-capture-errors/javascript.hono.mdx +++ b/platform-includes/getting-started-capture-errors/javascript.hono.mdx @@ -1,3 +1,3 @@ ### Report Unhandled Exceptions -By default, Sentry captures exceptions from Hono's `onError` handler. Errors with a 3xx or 4xx status code are excluded. You can customize this behavior through the `honoIntegration`'s `shouldHandleError` option. +By default, Sentry captures exceptions from Hono's `onError` handler. Errors with a 3xx or 4xx status code are excluded. You can customize this behavior through the `sentry()` middleware's `shouldHandleError` option. diff --git a/platform-includes/getting-started-capture-errors/javascript.koa.mdx b/platform-includes/getting-started-capture-errors/javascript.koa.mdx new file mode 100644 index 0000000000000..948fcf206fe18 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.koa.mdx @@ -0,0 +1,3 @@ +### Report Unhandled Exceptions + +`koaIntegration` registers an error handler when your Koa app starts, so errors are captured automatically. No additional configuration is needed. diff --git a/platform-includes/getting-started-use/javascript.express.mdx b/platform-includes/getting-started-use/javascript.express.mdx index b7760f4eda103..e738883598f50 100644 --- a/platform-includes/getting-started-use/javascript.express.mdx +++ b/platform-includes/getting-started-use/javascript.express.mdx @@ -4,16 +4,11 @@ require("./instrument"); // Now require other modules const express = require("express"); -const Sentry = require("@sentry/node"); const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` @@ -23,15 +18,10 @@ import "./instrument.mjs"; // Now import other modules import express from "express"; -import * as Sentry from "@sentry/node"; const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` diff --git a/platform-includes/getting-started-use/javascript.fastify.mdx b/platform-includes/getting-started-use/javascript.fastify.mdx index 0c1b043afb911..a7e5092519192 100644 --- a/platform-includes/getting-started-use/javascript.fastify.mdx +++ b/platform-includes/getting-started-use/javascript.fastify.mdx @@ -4,12 +4,9 @@ require("./instrument"); // Now require other modules const Fastify = require("fastify"); -const Sentry = require("@sentry/node"); const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); @@ -21,12 +18,9 @@ import "./instrument.mjs"; // Now import other modules import Fastify from "fastify"; -import * as Sentry from "@sentry/node"; const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); diff --git a/platform-includes/getting-started-use/javascript.hapi.mdx b/platform-includes/getting-started-use/javascript.hapi.mdx index 6dcf9f8ea060f..652945b1f78cb 100644 --- a/platform-includes/getting-started-use/javascript.hapi.mdx +++ b/platform-includes/getting-started-use/javascript.hapi.mdx @@ -3,7 +3,6 @@ require("./instrument"); // Now require other modules -const Sentry = require("@sentry/node"); const Hapi = require('@hapi/hapi'); const init = async () => { @@ -14,8 +13,6 @@ const init = async () => { // All your routes etc. - await Sentry.setupHapiErrorHandler(server); - await server.start(); console.log('Server running on %s', server.info.uri); }; @@ -28,7 +25,6 @@ init(); import "./instrument.mjs"; // Now import other modules -import * as Sentry from "@sentry/node"; import Hapi from "@hapi/hapi"; const init = async () => { @@ -39,8 +35,6 @@ const init = async () => { // All your routes etc. - await Sentry.setupHapiErrorHandler(server); - await server.start(); }; diff --git a/platform-includes/getting-started-use/javascript.koa.mdx b/platform-includes/getting-started-use/javascript.koa.mdx index 01745580954be..7454bcb25b8f6 100644 --- a/platform-includes/getting-started-use/javascript.koa.mdx +++ b/platform-includes/getting-started-use/javascript.koa.mdx @@ -4,12 +4,9 @@ require("./instrument"); // Now require other modules const Koa = require("koa"); -const Sentry = require("@sentry/node"); const app = new Koa(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.listen(3030); @@ -19,12 +16,9 @@ app.listen(3030); // Start with `node --import ./instrument.mjs app.mjs`. A top-level // import of the instrument file loses Koa's spans and route names. import Koa from "koa"; -import * as Sentry from "@sentry/node"; const app = new Koa(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.listen(3030); From 99008507e9114b3041f701d590cc0788b10d9e4a Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 15:37:25 +0200 Subject: [PATCH 19/48] docs(node): update minimum Node.js version to 20.19.0 (#19317) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Set the Node.js minimum to 20.19.0 for v11 across the docs: reword the prerequisites with the full supported range, drop the now-moot "only available for Node v18.19.0 onwards" ESM notes (the minimum already guarantees them), and bump the stale Node-18 minimums on the Nitro and Elysia guides. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- docs/platforms/javascript/common/install/esm.mdx | 3 --- docs/platforms/javascript/guides/elysia/index.mdx | 2 +- .../javascript/guides/nestjs/install/esm.mdx | 3 --- docs/platforms/javascript/guides/nitro/index.mdx | 2 +- platform-includes/getting-started-node/javascript.mdx | 1 - .../getting-started-prerequisites/javascript.node.mdx | 11 +---------- platform-includes/getting-started-run/javascript.mdx | 1 - 7 files changed, 3 insertions(+), 20 deletions(-) diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index 3a4aeb1862c05..e09572b1064ee 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -37,7 +37,6 @@ Sentry.init({ Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.mjs`, which contains your `Sentry.init()` code: ```bash -# Note: This is only available for Node v18.19.0 onwards. node --import ./instrument.mjs app.mjs ``` @@ -50,5 +49,3 @@ NODE_OPTIONS="--import ./instrument.mjs" npm run start If you're building a Node.js Single Executable Application (SEA) and can't rely on `--import` or `NODE_OPTIONS`, use the SEA bootstrap setup instead. - -We do not support ESM in Node versions before 18.19.0. diff --git a/docs/platforms/javascript/guides/elysia/index.mdx b/docs/platforms/javascript/guides/elysia/index.mdx index 06181b77ddab6..a55c7dd5cb74e 100644 --- a/docs/platforms/javascript/guides/elysia/index.mdx +++ b/docs/platforms/javascript/guides/elysia/index.mdx @@ -21,7 +21,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - An Elysia application (`v1.4.0+`) -- Bun or Node.js 18+ (with [@elysiajs/node](https://elysiajs.com/integrations/node) adapter) +- Bun or Node.js 20.19.0+ (with [@elysiajs/node](https://elysiajs.com/integrations/node) adapter) diff --git a/docs/platforms/javascript/guides/nestjs/install/esm.mdx b/docs/platforms/javascript/guides/nestjs/install/esm.mdx index fb036cb73ad7a..c43f28f39d153 100644 --- a/docs/platforms/javascript/guides/nestjs/install/esm.mdx +++ b/docs/platforms/javascript/guides/nestjs/install/esm.mdx @@ -31,7 +31,6 @@ Sentry.init({ **Step 2:** Adjust your application's start command to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter: ```bash -# Note: This is only available for Node v18.19.0 onwards. "start": "--import ./instrument.mjs nest start" ``` @@ -40,5 +39,3 @@ If you can't pass the `--import` flag to the Node.js binary, you can alternative ```bash NODE_OPTIONS="--import ./instrument.mjs" npm run start ``` - -We do not support ESM in Node versions before 18.19.0. diff --git a/docs/platforms/javascript/guides/nitro/index.mdx b/docs/platforms/javascript/guides/nitro/index.mdx index 50c232c5ac87b..52c8d5cbeb921 100644 --- a/docs/platforms/javascript/guides/nitro/index.mdx +++ b/docs/platforms/javascript/guides/nitro/index.mdx @@ -20,7 +20,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - A Nitro application (`3.0.260415-beta` or newer) -- Node.js 18.19.0+ +- Node.js 20.19.0+ diff --git a/platform-includes/getting-started-node/javascript.mdx b/platform-includes/getting-started-node/javascript.mdx index f3feb0922de7d..8b543151099ca 100644 --- a/platform-includes/getting-started-node/javascript.mdx +++ b/platform-includes/getting-started-node/javascript.mdx @@ -91,7 +91,6 @@ When running your application in ESM mode, use the [--import](https://nodejs.org ```bash -# Note: This is only available for Node v18.19.0 onwards. node --import ./instrument.mjs app.mjs ``` diff --git a/platform-includes/getting-started-prerequisites/javascript.node.mdx b/platform-includes/getting-started-prerequisites/javascript.node.mdx index 76c8644590648..921938957f024 100644 --- a/platform-includes/getting-started-prerequisites/javascript.node.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.node.mdx @@ -4,13 +4,4 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- Node version `18.0.0` or above (>= `19.9.0` or `18.19.0` recommended) - - - The required Node version will increase in the next major release of the SDK (v11) to support features that rely on [`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). - - - We strongly recommend upgrading to at least Node `18.19.0` or `19.9.0` to get the best support. - - While we may add features relying on `TracingChannel` in v10.x releases, they will have backwards compatibility for older Node versions. - - See the following [issue on GitHub](https://github.com/getsentry/sentry-javascript/issues/17585) for more details. - +- Node version `20.19.0` or above. Node.js 22 needs `22.12` or higher, while Node.js 23 needs `23.2` or higher (`>=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0`). diff --git a/platform-includes/getting-started-run/javascript.mdx b/platform-includes/getting-started-run/javascript.mdx index 912e582e22141..f9859c4ffc7e7 100644 --- a/platform-includes/getting-started-run/javascript.mdx +++ b/platform-includes/getting-started-run/javascript.mdx @@ -3,7 +3,6 @@ node --import ./instrument.js app.js # If you are using ECMAScript Modules (ESM) -# Note: This is only available for Node v18.19.0 onwards. node --import ./instrument.mjs app.mjs ``` From 0d11a140c9cd2845db9765c1855ad7a6a00b2b27 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:38:20 +0200 Subject: [PATCH 20/48] docs(js): Rename InboundFilters integration to EventFilters (#19431) Renames the JS `InboundFilters` integration page to `EventFilters` for v11, adds redirects from the old URLs, and updates the integration tables and examples. Closes https://linear.app/getsentry/issue/SDK-1481/rename-the-inboundfilters-integration-to-eventfilters-in-docs --- .../{inboundfilters.mdx => eventfilters.mdx} | 10 ++++++++-- .../javascript/common/configuration/tree-shaking.mdx | 2 +- .../guides/capacitor/migration/v2-to-v3/index.mdx | 2 +- docs/pricing/quotas/manage-event-stream-guide.mdx | 4 ++-- .../configuration/integrations/javascript.astro.mdx | 2 +- .../integrations/javascript.aws-lambda.mdx | 2 +- .../configuration/integrations/javascript.bun.mdx | 2 +- .../integrations/javascript.capacitor.mdx | 2 +- .../integrations/javascript.cloudflare.mdx | 2 +- .../configuration/integrations/javascript.connect.mdx | 2 +- .../configuration/integrations/javascript.cordova.mdx | 2 +- .../configuration/integrations/javascript.deno.mdx | 2 +- .../configuration/integrations/javascript.fastify.mdx | 2 +- .../configuration/integrations/javascript.gatsby.mdx | 2 +- .../integrations/javascript.gcp-functions.mdx | 2 +- .../configuration/integrations/javascript.hapi.mdx | 2 +- .../configuration/integrations/javascript.mdx | 2 +- .../configuration/integrations/javascript.nestjs.mdx | 2 +- .../configuration/integrations/javascript.nextjs.mdx | 2 +- .../configuration/integrations/javascript.node.mdx | 2 +- .../configuration/integrations/javascript.nuxt.mdx | 2 +- .../configuration/integrations/javascript.remix.mdx | 2 +- .../integrations/javascript.solidstart.mdx | 2 +- .../integrations/javascript.sveltekit.mdx | 2 +- .../configuration/integrations/javascript.vue.mdx | 2 +- .../configuration/integrations/javascript.wasm.mdx | 2 +- redirects.js | 9 +++++++++ 27 files changed, 43 insertions(+), 28 deletions(-) rename docs/platforms/javascript/common/configuration/integrations/{inboundfilters.mdx => eventfilters.mdx} (86%) diff --git a/docs/platforms/javascript/common/configuration/integrations/inboundfilters.mdx b/docs/platforms/javascript/common/configuration/integrations/eventfilters.mdx similarity index 86% rename from docs/platforms/javascript/common/configuration/integrations/inboundfilters.mdx rename to docs/platforms/javascript/common/configuration/integrations/eventfilters.mdx index efabcf626d75c..83b29752ed011 100644 --- a/docs/platforms/javascript/common/configuration/integrations/inboundfilters.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/eventfilters.mdx @@ -1,9 +1,15 @@ --- -title: InboundFilters +title: EventFilters description: "Allows you to ignore specific errors based on the type, message, or URLs in a given exception. (default)" --- -_Import name: `Sentry.inboundFiltersIntegration`_ +_Import name: `Sentry.eventFiltersIntegration`_ + + + +In SDK versions before 11, this integration was called `InboundFilters` and exported as `inboundFiltersIntegration`. + + This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). diff --git a/docs/platforms/javascript/common/configuration/tree-shaking.mdx b/docs/platforms/javascript/common/configuration/tree-shaking.mdx index e3d50897086c4..c9ef7dde31bf3 100644 --- a/docs/platforms/javascript/common/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/common/configuration/tree-shaking.mdx @@ -296,7 +296,7 @@ Sentry.initWithoutDefaultIntegrations({ Sentry.httpIntegration(), Sentry.consoleIntegration(), Sentry.dedupeIntegration(), - Sentry.inboundFiltersIntegration(), + Sentry.eventFiltersIntegration(), ], }); ``` diff --git a/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx b/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx index 6b229a8142545..6b78e89219c1a 100644 --- a/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx +++ b/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx @@ -115,7 +115,7 @@ This version restores several integrations that were previously missing and adds | `dedupeIntegration` | ✓ | ✓ | | | | | `functionToStringIntegration` | ✓ | | | | | | `globalHandlersIntegration` | ✓ | ✓ | | | | -| `inboundFiltersIntegration` | ✓ | ✓ | | | | +| `inboundFiltersIntegration` | ✓ | ✓ | | | | | `linkedErrorsIntegration` | ✓ | ✓ | | | | | `spotlightIntegration` | | | | | | diff --git a/docs/pricing/quotas/manage-event-stream-guide.mdx b/docs/pricing/quotas/manage-event-stream-guide.mdx index a7068fe3d4025..52622bdce00b8 100644 --- a/docs/pricing/quotas/manage-event-stream-guide.mdx +++ b/docs/pricing/quotas/manage-event-stream-guide.mdx @@ -210,9 +210,9 @@ The Sentry SDKs have several configuration options that can be used to filter un ### JavaScript -The JavaScript SDK includes multiple integrations: functional plugins that you can configure, enable, or disable. Learn more in [JavaScript SDK Integrations](/platforms/javascript/configuration/integrations/). Several integrations allow you to configure the types of events you want Sentry to monitor; two of them, InboundFilters and GlobalHandlers are explained below: +The JavaScript SDK includes multiple integrations: functional plugins that you can configure, enable, or disable. Learn more in [JavaScript SDK Integrations](/platforms/javascript/configuration/integrations/). Several integrations allow you to configure the types of events you want Sentry to monitor; two of them, EventFilters and GlobalHandlers are explained below: -#### InboundFilters +#### EventFilters The integration is enabled by default and adds the following configuration options to the SDK: diff --git a/platform-includes/configuration/integrations/javascript.astro.mdx b/platform-includes/configuration/integrations/javascript.astro.mdx index e3e03d1f5ad15..305ea4bd3cbee 100644 --- a/platform-includes/configuration/integrations/javascript.astro.mdx +++ b/platform-includes/configuration/integrations/javascript.astro.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx index 7e73c81d7c8b5..daf01fb6677d3 100644 --- a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx +++ b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx @@ -7,9 +7,9 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`modulesIntegration`](./modules) | ✓ | | | ✓ | | [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.bun.mdx b/platform-includes/configuration/integrations/javascript.bun.mdx index 155bb4785746d..30c3ec00901c1 100644 --- a/platform-includes/configuration/integrations/javascript.bun.mdx +++ b/platform-includes/configuration/integrations/javascript.bun.mdx @@ -7,11 +7,11 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.capacitor.mdx b/platform-includes/configuration/integrations/javascript.capacitor.mdx index dde93c2b4c7d0..bf592b4487b67 100644 --- a/platform-includes/configuration/integrations/javascript.capacitor.mdx +++ b/platform-includes/configuration/integrations/javascript.capacitor.mdx @@ -5,10 +5,10 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.cloudflare.mdx b/platform-includes/configuration/integrations/javascript.cloudflare.mdx index deddfb8faa9f7..1a117d34ac0ce 100644 --- a/platform-includes/configuration/integrations/javascript.cloudflare.mdx +++ b/platform-includes/configuration/integrations/javascript.cloudflare.mdx @@ -3,9 +3,9 @@ | | **Auto Enabled** | **Errors** | **Tracing** | **Cron** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`fetchIntegration`](./fetchIntegration) | ✓ | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`requestDataIntegration`](./requestdata) | ✓ | | | | ✓ | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.connect.mdx b/platform-includes/configuration/integrations/javascript.connect.mdx index 42eb281c61039..50e06fb7aea44 100644 --- a/platform-includes/configuration/integrations/javascript.connect.mdx +++ b/platform-includes/configuration/integrations/javascript.connect.mdx @@ -7,11 +7,11 @@ | [`connectIntegration`](./connect) | ✓ | | ✓ | | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.cordova.mdx b/platform-includes/configuration/integrations/javascript.cordova.mdx index b018d5a58ec4a..d02c879125bb8 100644 --- a/platform-includes/configuration/integrations/javascript.cordova.mdx +++ b/platform-includes/configuration/integrations/javascript.cordova.mdx @@ -5,10 +5,10 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.deno.mdx b/platform-includes/configuration/integrations/javascript.deno.mdx index 4aab5d17afbf3..84dca4a8f822b 100644 --- a/platform-includes/configuration/integrations/javascript.deno.mdx +++ b/platform-includes/configuration/integrations/javascript.deno.mdx @@ -6,9 +6,9 @@ | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`denoContextIntegration`](./denocontext) | ✓ | | | | ✓ | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`denoCronIntegration`](./denocron) | | | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.fastify.mdx b/platform-includes/configuration/integrations/javascript.fastify.mdx index 53ebfaeb7586b..c928ec5d0d60d 100644 --- a/platform-includes/configuration/integrations/javascript.fastify.mdx +++ b/platform-includes/configuration/integrations/javascript.fastify.mdx @@ -5,12 +5,12 @@ | [`amqplibIntegration`](./amqplib) | ✓ | | ✓ | | | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`fastifyIntegration`](./fastify) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.gatsby.mdx b/platform-includes/configuration/integrations/javascript.gatsby.mdx index bf11cd5d8784b..7113f03720a84 100644 --- a/platform-includes/configuration/integrations/javascript.gatsby.mdx +++ b/platform-includes/configuration/integrations/javascript.gatsby.mdx @@ -5,10 +5,10 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx index 743486427721e..5914b98376820 100644 --- a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx +++ b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx @@ -5,11 +5,11 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`googleCloudGrpcIntegration`](./googlecloudgrpc) | ✓ | | ✓ | | | [`googleCloudHttpIntegration`](./googlecloudhttp) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`modulesIntegration`](./modules) | ✓ | | | ✓ | | [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.hapi.mdx b/platform-includes/configuration/integrations/javascript.hapi.mdx index 1d6cb46f7eced..40090a1bf4908 100644 --- a/platform-includes/configuration/integrations/javascript.hapi.mdx +++ b/platform-includes/configuration/integrations/javascript.hapi.mdx @@ -6,12 +6,12 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`hapiIntegration`](./hapi) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx index 4e237ce3e233c..45b1a65767256 100644 --- a/platform-includes/configuration/integrations/javascript.mdx +++ b/platform-includes/configuration/integrations/javascript.mdx @@ -6,10 +6,10 @@ | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.nestjs.mdx b/platform-includes/configuration/integrations/javascript.nestjs.mdx index 716a03b6c49a8..1c0a32c016555 100644 --- a/platform-includes/configuration/integrations/javascript.nestjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nestjs.mdx @@ -6,11 +6,11 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.nextjs.mdx b/platform-includes/configuration/integrations/javascript.nextjs.mdx index a47472bcebea6..e5fbd3eb908cd 100644 --- a/platform-includes/configuration/integrations/javascript.nextjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nextjs.mdx @@ -12,8 +12,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.node.mdx b/platform-includes/configuration/integrations/javascript.node.mdx index 4ac15382fcb4f..489437d96bed0 100644 --- a/platform-includes/configuration/integrations/javascript.node.mdx +++ b/platform-includes/configuration/integrations/javascript.node.mdx @@ -11,13 +11,13 @@ | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dataloaderIntegration`](./dataloader) | | | ✓ | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | | [`fsIntegration`](./fs) | | | ✓ | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nuxt.mdx b/platform-includes/configuration/integrations/javascript.nuxt.mdx index 996534294613b..45e809cc438e3 100644 --- a/platform-includes/configuration/integrations/javascript.nuxt.mdx +++ b/platform-includes/configuration/integrations/javascript.nuxt.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.remix.mdx b/platform-includes/configuration/integrations/javascript.remix.mdx index ed4fd65bbda59..0a099873775dd 100644 --- a/platform-includes/configuration/integrations/javascript.remix.mdx +++ b/platform-includes/configuration/integrations/javascript.remix.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.solidstart.mdx b/platform-includes/configuration/integrations/javascript.solidstart.mdx index f2b3275ad0222..a71907c8ea8f8 100644 --- a/platform-includes/configuration/integrations/javascript.solidstart.mdx +++ b/platform-includes/configuration/integrations/javascript.solidstart.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.sveltekit.mdx b/platform-includes/configuration/integrations/javascript.sveltekit.mdx index 5bee23bd43e17..031724444dab9 100644 --- a/platform-includes/configuration/integrations/javascript.sveltekit.mdx +++ b/platform-includes/configuration/integrations/javascript.sveltekit.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.vue.mdx b/platform-includes/configuration/integrations/javascript.vue.mdx index ee901f3067045..9b84a9e305c6d 100644 --- a/platform-includes/configuration/integrations/javascript.vue.mdx +++ b/platform-includes/configuration/integrations/javascript.vue.mdx @@ -6,10 +6,10 @@ | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`vueIntegration`](./vue) | ✓ | ✓ | ✓ | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.wasm.mdx b/platform-includes/configuration/integrations/javascript.wasm.mdx index b1c80277cfc54..ff99e1a54df39 100644 --- a/platform-includes/configuration/integrations/javascript.wasm.mdx +++ b/platform-includes/configuration/integrations/javascript.wasm.mdx @@ -5,10 +5,10 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | diff --git a/redirects.js b/redirects.js index eb2eae9d370a8..7fe89bbd4ca15 100644 --- a/redirects.js +++ b/redirects.js @@ -2650,6 +2650,15 @@ const userDocsRedirects = [ source: '/platforms/python/integrations/pydantic-ai/:path*', destination: '/platforms/python/agent-tracing/pydantic-ai/:path*', }, + // InboundFilters integration was renamed to EventFilters in SDK v11 + { + source: '/platforms/javascript/configuration/integrations/inboundfilters/', + destination: '/platforms/javascript/configuration/integrations/eventfilters/', + }, + { + source: '/platforms/javascript/guides/:guide/configuration/integrations/inboundfilters/', + destination: '/platforms/javascript/guides/:guide/configuration/integrations/eventfilters/', + }, // agent-tracing-browser merged into agent-tracing { source: '/platforms/javascript/agent-tracing-browser/', From bd02b21b642239f893360dbf7fee8c85ba2b382a Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:38:45 +0200 Subject: [PATCH 21/48] docs(javascript): Apply httpIntegration option renames (#19548) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Docs still described `httpIntegration` options that v11 renamed or removed. - Rename: `trackIncomingRequestsAsSessions` → `sessions`, `maxIncomingRequestBodySize` → `maxRequestBodySize`, `ignoreIncomingRequestBody` → `ignoreRequestBody`, `dropSpansForIncomingRequestStatusCodes` → `ignoreStatusCodes`, `incomingRequestSpanHook` → `onSpanCreated` - Flag `ignoreStatusCodes` as deprecated and `traceLifecycle: 'static'` only - Replace the removed `instrumentation` hooks with `onSpanCreated` / `outgoingRequestHook`, and document the two other outgoing hooks - Fix three pre-existing errors found while verifying against the SDK source: the `spans` default, `ignoreOutgoingRequests` trace headers, and the intro Fixes SDK-1476 --------- Co-authored-by: Claude Opus 5 --- .../configuration/integrations/http.mdx | 72 +++++++++++++------ .../data-management/data-collected/index.mdx | 2 +- .../auto-session-tracking/javascript.mdx | 4 +- .../auto-session-tracking/javascript.node.mdx | 4 +- 4 files changed, 56 insertions(+), 26 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/http.mdx b/docs/platforms/javascript/common/configuration/integrations/http.mdx index 31c73e77d9f6e..eb9d4baffd2e6 100644 --- a/docs/platforms/javascript/common/configuration/integrations/http.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/http.mdx @@ -37,10 +37,11 @@ _Import name: `Sentry.httpIntegration`_ This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). -The `httpIntegration` does two things: +The `httpIntegration` does the following: 1. It captures breadcrumbs for HTTP requests. -2. It captures spans for outgoing HTTP requests. +2. It captures spans for incoming and outgoing HTTP requests. +3. It creates sessions for incoming requests to track [Release Health](/product/releases/health/). ```JavaScript Sentry.init({ @@ -58,11 +59,11 @@ If set to false, no breadcrumbs will be captured. ### `spans` -_Type: `boolean`_ (Defaults to `false`) +_Type: `boolean`_ (Defaults to `true` when tracing is enabled) -If set to true, spans will be created for outgoing HTTP requests. +If set to false, no spans will be created for HTTP requests, neither for incoming nor for outgoing ones. -### `maxIncomingRequestBodySize` +### `maxRequestBodySize` _Type: `'none' | 'small' | 'medium' | 'always'`_ (Defaults to `'medium'`) @@ -77,7 +78,7 @@ Available options: Note that even with the `'always'` setting, bodies exceeding 1 MB will never be attached for performance and security reasons. -### `ignoreIncomingRequestBody` +### `ignoreRequestBody` _Type: `(url: string, request: RequestOptions) => boolean`_ @@ -99,7 +100,7 @@ Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `tracepa _Type: `(url: string, request: RequestOptions) => boolean`_ -Allows you to define a method to filter out outgoing requests based on the URL. If the method returns `true`, no spans or breadcrumbs will be captured for the outgoing request. +Allows you to define a method to filter out outgoing requests based on the URL. If the method returns `true`, the request is skipped entirely: no span or breadcrumb is captured, and no trace propagation headers are injected. The callback function receives two arguments: @@ -129,17 +130,23 @@ _Type: `boolean`_ If set to true, no spans will be generated for incoming requests. -### `dropSpansForIncomingRequestStatusCodes` +### `ignoreStatusCodes` _Type: `(number | [number, number])[]`_ (Defaults to `[[401, 404], [301, 303], [305, 399]]`) + + +This option is deprecated and will be removed in the next major version without a replacement. It only has an effect when `traceLifecycle` is set to `'static'`. With span streaming, child spans are sent as they end, before the response status code is known, so spans can't be dropped based on the status code. To keep requests out of Sentry, use [`ignoreIncomingRequests`](#ignoreincomingrequests), `tracesSampler`, or `ignoreSpans` instead. + + + Do not capture spans for incoming HTTP requests with the given status codes. By default, spans with some 3xx and 4xx status codes are ignored. Expects an array that can contain individual status codes (numbers) or ranges (2-element arrays of `[start, end]` where both start and end are inclusive). For example, `[[300, 399], 404]` would ignore all 3xx status codes (300-399 inclusive) and 404 status codes. -### `trackIncomingRequestsAsSessions` +### `sessions` _Type: `boolean`_ (Defaults to `true`) @@ -152,19 +159,42 @@ _Type: `number`_ (Defaults to `60000`) The delay in milliseconds before sessions are flushed as a session aggregate. This controls how frequently session data is sent to Sentry. -### `instrumentation` +### `onSpanCreated` + +_Type: `(span: Span, request: IncomingMessage, response: ServerResponse) => void`_ -You can also pass some hooks through to the [underlying OpenTelemetry Instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation-http): +A hook that's called after a span is created for an incoming request, before it's recorded. Use this to add custom attributes to incoming request spans. -```typescript -httpIntegration({ - instrumentation?: { - requestHook?: (span: Span, req: ClientRequest | HTTPModuleRequestIncomingMessage) => void; - responseHook?: (span: Span, response: HTTPModuleRequestIncomingMessage | ServerResponse) => void; - applyCustomAttributesOnSpan?: ( - span: Span, - request: ClientRequest | HTTPModuleRequestIncomingMessage, - response: HTTPModuleRequestIncomingMessage | ServerResponse, - ) => void; +```javascript +Sentry.httpIntegration({ + onSpanCreated: (span, request, response) => { + span.setAttribute("custom", true); + }, }); ``` + +### `outgoingRequestHook` + +_Type: `(span: Span, request: ClientRequest) => void`_ + +A hook that's called after a span is created for an outgoing request. Use this to add custom attributes to outgoing request spans. Only called when spans are created for outgoing requests. + +```javascript +Sentry.httpIntegration({ + outgoingRequestHook: (span, request) => { + span.setAttribute("custom", true); + }, +}); +``` + +### `outgoingResponseHook` + +_Type: `(span: Span, response: IncomingMessage) => void`_ + +A hook that's called when an outgoing request receives a response. Only called when spans are created for outgoing requests. + +### `outgoingRequestApplyCustomAttributes` + +_Type: `(span: Span, request: ClientRequest, response: IncomingMessage) => void`_ + +A hook that's called when both the outgoing request and its response are available. Only called when spans are created for outgoing requests. diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index f21526626d8e8..a4694cef67623 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -94,7 +94,7 @@ Sentry.init({ Without `dataCollection` (and with `sendDefaultPii` unset or `false`), Sentry only sends the body size inferred from the `content-length` header, not the body content itself. - On the server-side, the incoming request body is captured by default. You can disable sending the incoming request body by configuring `ignoreIncomingRequestBody` in the HTTP Integration. + On the server-side, the incoming request body is captured by default. You can disable sending the incoming request body by configuring `ignoreRequestBody` in the HTTP Integration. diff --git a/platform-includes/configuration/auto-session-tracking/javascript.mdx b/platform-includes/configuration/auto-session-tracking/javascript.mdx index 11fefd4cbc5a4..9a018ac25bfb0 100644 --- a/platform-includes/configuration/auto-session-tracking/javascript.mdx +++ b/platform-includes/configuration/auto-session-tracking/javascript.mdx @@ -23,13 +23,13 @@ Sentry.init({ By default, the Node.js-based SDKs are sending sessions. Sessions are created for every incoming request. -To disable the default sessions handling, set `trackIncomingRequestsAsSessions: false` in the `httpIntegration`: +To disable the default sessions handling, set `sessions: false` in the `httpIntegration`: ```javascript import * as Sentry from "@sentry/node"; Sentry.init({ - integrations: [httpIntegration({ trackIncomingRequestsAsSessions: false })], + integrations: [Sentry.httpIntegration({ sessions: false })], }); ``` diff --git a/platform-includes/configuration/auto-session-tracking/javascript.node.mdx b/platform-includes/configuration/auto-session-tracking/javascript.node.mdx index 7ed83295e2e2e..a6bb37d4bcea7 100644 --- a/platform-includes/configuration/auto-session-tracking/javascript.node.mdx +++ b/platform-includes/configuration/auto-session-tracking/javascript.node.mdx @@ -7,12 +7,12 @@ We mark the session as crashed if an _unhandled error_ reached our `errorHandler We mark the session as an error if the SDK captures an event that contains an exception (this includes manually captured exceptions). -By default, the SDK is sending sessions, to disable this configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`. +By default, the SDK is sending sessions, to disable this configure the `httpIntegration` with the `sessions` option set to `false`. ```javascript Sentry.init({ integrations: [Sentry.httpIntegration({ - trackIncomingRequestsAsSessions: false, // default: true + sessions: false, // default: true })] }); ``` From f531196aa6530680cfb0594ebe39b602d2dd1538 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:42:13 +0200 Subject: [PATCH 22/48] docs(nextjs): Document Vercel AI as unsupported on the Edge runtime (#19475) ## DESCRIBE YOUR PR In SDK v11, Vercel AI instrumentation relies on diagnostics channels, which the Edge runtime doesn't support. `@sentry/nextjs` keeps `vercelAIIntegration` on its Edge build as a no-op shim so imports still resolve, but it captures nothing. The Vercel AI page still told Next.js users to add the integration to `sentry.edge.config`, which would silently produce no spans. - Replace the Node vs. Edge runtime table with a note that only the Node runtime is instrumented, linking to the migration guide - Remove the Edge setup snippet and Edge-specific caveats (`recordInputs`/`recordOutputs`, options, `force`, "both runtimes" wording) - Mark the Edge runtime as unsupported in SDK `11.0.0`+ under Supported Versions Refs SDK-1483 Co-authored-by: Claude Opus 5 --- .../common/configuration/integrations/vercelai.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx index 0fde1e1a9fcb2..46395ea603f29 100644 --- a/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx @@ -29,6 +29,16 @@ Sentry.init({ }); ``` + + + + +The Edge runtime isn't instrumented. The instrumentation relies on diagnostics channels, which Edge doesn't support. `@sentry/nextjs` still exports `vercelAIIntegration` from its Edge build so imports resolve, but it captures no spans. Run AI calls in the Node runtime. + + + + + Don't use the AI SDK's `registerTelemetry` API (AI SDK v7 and above) together with this integration. `vercelAIIntegration` already instruments the AI SDK, so registering telemetry separately produces duplicate spans. From 16277e156a8251f496a62c4af8d2ee369aef411e Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 15:47:04 +0200 Subject: [PATCH 23/48] docs(js): Remove breadcrumbs console and instrumentation warnings (#19527) ## DESCRIBE YOUR PR - Remove the `console` option of `breadcrumbsIntegration`, removed in v11 from `@sentry/browser` and `@sentry/deno`; `consoleIntegration` is a default integration in both now - Remove `disableInstrumentationWarnings` from the options reference - Add `consoleIntegration` to the browser, Deno, Vue, Gatsby, and Wasm integration tables, and mark the Console page as supported on browser platforms - Update the two examples that configured the removed option, and add browser and Deno migration entries - Leaves Capacitor, Cordova, and React Native alone; they ship separate SDK trains still on older JS core Fixes SDK-1488 --------- Co-authored-by: Claude Opus 5 --- .../integrations/breadcrumbs.mdx | 13 ++------- .../configuration/integrations/console.mdx | 11 ++++++- .../configuration/integrations/index.mdx | 29 +++++++++++++++++-- .../common/configuration/options.mdx | 14 --------- .../data-management/data-collected/index.mdx | 2 +- .../common/migration/v10-to-v11/index.mdx | 3 +- .../integrations/breadcrumbs.mdx | 11 ++----- .../javascript-v11/console-breadcrumbs.mdx | 13 ++++++++- .../deno-console-breadcrumbs.mdx | 23 +++++++++++++++ .../integrations/javascript.deno.mdx | 1 + .../integrations/javascript.gatsby.mdx | 1 + .../configuration/integrations/javascript.mdx | 1 + .../integrations/javascript.vue.mdx | 1 + .../integrations/javascript.wasm.mdx | 1 + 14 files changed, 86 insertions(+), 38 deletions(-) create mode 100644 includes/migration/javascript-v11/deno-console-breadcrumbs.mdx diff --git a/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx b/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx index 72fbe1fbe7273..1fe7d59974365 100644 --- a/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx @@ -6,8 +6,6 @@ notSupportedCategories: - server-only --- - - This integration only works inside a browser environment. @@ -20,13 +18,14 @@ This integration is enabled by default. If you'd like to modify your default int The `breadcrumbsIntegration` wraps native APIs to capture breadcrumbs. -By default, the Sentry SDK wraps the `console`, `dom`, `fetch`, `history`, and `xhr` browser APIs to add breadcrumbs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture `console.log` calls as breadcrumbs) via the options below. +By default, the Sentry SDK wraps the `dom`, `fetch`, `history`, and `xhr` browser APIs to add breadcrumbs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture click and keypress events as breadcrumbs) via the options below. + +Console calls are captured by the `consoleIntegration`, which is enabled by default. ```JavaScript Sentry.init({ integrations: [ Sentry.breadcrumbsIntegration({ - console: true, dom: true, fetch: true, history: true, @@ -38,12 +37,6 @@ Sentry.init({ ## Options -### `console` - -_Type: `boolean`_ - -Log calls to `console.log`, `console.debug`, and so on. - ### `dom` _Type: `boolean` | `{ serializeAttribute: string | string[] }`_ diff --git a/docs/platforms/javascript/common/configuration/integrations/console.mdx b/docs/platforms/javascript/common/configuration/integrations/console.mdx index 2f5142476012c..677011f4b8eb2 100644 --- a/docs/platforms/javascript/common/configuration/integrations/console.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/console.mdx @@ -1,8 +1,17 @@ --- title: Console description: "Capture console logs as breadcrumbs. (default)" -customCanonicalTag: "/platforms/javascript/guides/express/configuration/integrations/console/" +customCanonicalTag: "/platforms/javascript/configuration/integrations/console/" supported: + - javascript + - javascript.angular + - javascript.ember + - javascript.gatsby + - javascript.react + - javascript.solid + - javascript.svelte + - javascript.vue + - javascript.wasm - javascript.node - javascript.eve - javascript.mastra diff --git a/docs/platforms/javascript/common/configuration/integrations/index.mdx b/docs/platforms/javascript/common/configuration/integrations/index.mdx index ea485185e3c5b..171c31599897b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/index.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/index.mdx @@ -18,19 +18,44 @@ Integrations automatically add error instrumentation, performance instrumentatio To disable system integrations, set `defaultIntegrations: false` when calling `init()`. -To override their settings, provide a new instance with your config to the `integrations` option. For example, to turn off browser capturing console calls: +To override their settings, provide a new instance with your config to the `integrations` option. + + + +For example, to stop capturing click and keypress events as breadcrumbs: ```javascript {3-7} Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ Sentry.breadcrumbsIntegration({ - console: false, + dom: false, }), ], }); ``` + + + + + +For example, to stop recording breadcrumbs for outgoing HTTP requests: + +```javascript {3-7} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.httpIntegration({ + breadcrumbs: false, + }), + ], +}); +``` + + + + ## Adding an Integration You can add additional integrations in your `init` call: diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 6cb07ab8a777d..8223a0dbdd884 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -394,20 +394,6 @@ Controls how many seconds to wait before shutting down. Sentry SDKs send events - - -Depending on your setup, the Sentry SDK will try to detect if it has been incorrectly set up. This can result in warnings like this being logged: - -> [Sentry] < libraryName > is not instrumented. This is likely because you required/imported < libraryName > before calling `Sentry.init()`. - -Or - -> [Sentry] < libraryName > is not instrumented. Please make sure to initialize Sentry in a separate file that you \`--import\` when running node, see: < docs link >. - -This means the SDK detected that the library hasn't been wrapped for automatic performance instrumentation. This may result in some spans not being reported correctly. If this is not affecting you (for example because the warning is a false positive or you do not care about these specific spans), you can disable this warning by setting this option to `true`. - - - **Note:** Electron `main` process only. diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index a4694cef67623..33fba347a6ffb 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -170,7 +170,7 @@ By default, the Sentry SDK sends information about the device and runtime to Sen By default, the Sentry SDK sends JS console logs to Sentry as breadcrumbs which may contain PII data. - To disable sending console messages, set `console: false` in your `Sentry.breadcrumbsIntegration` config, see the Breadcrumbs documentation. + To disable sending console messages, remove the `Console` integration from your `integrations` config, see the Console documentation. ## Referrer URL diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index 50b3c66731fed..2a52f57b544d3 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -948,6 +948,7 @@ BrowserTracing now automatically adds the diff --git a/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx b/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx index 4ea7e58cefb93..616a821ec58d8 100644 --- a/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx +++ b/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx @@ -10,15 +10,11 @@ _Import name: `Sentry.breadcrumbsIntegration`_ This integration is enabled by default. You can also [modify default integrations](./../#modifying-default-integrations). The `breadcrumbsIntegration` wraps native APIs to capture breadcrumbs. -By default, the Sentry SDK wraps all APIs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture `console.log` calls as breadcrumbs) via the options below. +By default, the Sentry SDK wraps all APIs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture outgoing fetch requests as breadcrumbs) via the options below. -## Options - -### `console` - -_Type: `boolean`_ +Console calls are captured by the `consoleIntegration`, which is enabled by default. -Log calls to `console.log`, `console.debug`, and so on. +## Options ### `fetch` @@ -31,4 +27,3 @@ Log HTTP requests done with the Fetch API. _Type: `boolean`_ Log whenever we send an event to the server. - diff --git a/includes/migration/javascript-v11/console-breadcrumbs.mdx b/includes/migration/javascript-v11/console-breadcrumbs.mdx index 00d8eb6ca3414..3e3001f39c65c 100644 --- a/includes/migration/javascript-v11/console-breadcrumbs.mdx +++ b/includes/migration/javascript-v11/console-breadcrumbs.mdx @@ -9,4 +9,15 @@ platformCategory: browser order: 205 --- -The `console` option of `breadcrumbsIntegration` was removed. Use `consoleIntegration` to capture console breadcrumbs. +The `console` option of `breadcrumbsIntegration` was removed. Console breadcrumbs come from the default `consoleIntegration` now, which matches the server SDKs. + +To disable console breadcrumbs, filter out the `Console` integration: + +```js +Sentry.init({ + integrations: (integrations) => + integrations.filter((integration) => integration.name !== "Console"), +}); +``` + +If you set `defaultIntegrations: false`, add `Sentry.consoleIntegration()` to keep capturing them. diff --git a/includes/migration/javascript-v11/deno-console-breadcrumbs.mdx b/includes/migration/javascript-v11/deno-console-breadcrumbs.mdx new file mode 100644 index 0000000000000..e29a4cf67b4a1 --- /dev/null +++ b/includes/migration/javascript-v11/deno-console-breadcrumbs.mdx @@ -0,0 +1,23 @@ +--- +id: deno-console-breadcrumbs +title: "Deno console breadcrumbs moved to `consoleIntegration`" +phase: code-changes +category: removed-api +severity: action-required +frameworks: [deno] +platformCategory: server +order: 311 +--- + +The `console` option of `breadcrumbsIntegration` was removed. Console breadcrumbs come from the default `consoleIntegration` now, which matches the other server SDKs. + +To disable console breadcrumbs, filter out the `Console` integration: + +```js +Sentry.init({ + integrations: integrations => + integrations.filter(integration => integration.name !== "Console"), +}); +``` + +If you set `defaultIntegrations: false`, add `Sentry.consoleIntegration()` to keep capturing them. diff --git a/platform-includes/configuration/integrations/javascript.deno.mdx b/platform-includes/configuration/integrations/javascript.deno.mdx index 84dca4a8f822b..1538e77225a05 100644 --- a/platform-includes/configuration/integrations/javascript.deno.mdx +++ b/platform-includes/configuration/integrations/javascript.deno.mdx @@ -3,6 +3,7 @@ | | **Auto Enabled** | **Errors** | **Tracing** | **Cron** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :------: | :--------------------: | | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`denoContextIntegration`](./denocontext) | ✓ | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.gatsby.mdx b/platform-includes/configuration/integrations/javascript.gatsby.mdx index 7113f03720a84..e66be97928127 100644 --- a/platform-includes/configuration/integrations/javascript.gatsby.mdx +++ b/platform-includes/configuration/integrations/javascript.gatsby.mdx @@ -4,6 +4,7 @@ |-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:| | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx index 45b1a65767256..e679e040928d9 100644 --- a/platform-includes/configuration/integrations/javascript.mdx +++ b/platform-includes/configuration/integrations/javascript.mdx @@ -5,6 +5,7 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | diff --git a/platform-includes/configuration/integrations/javascript.vue.mdx b/platform-includes/configuration/integrations/javascript.vue.mdx index 9b84a9e305c6d..bcb1b45943bec 100644 --- a/platform-includes/configuration/integrations/javascript.vue.mdx +++ b/platform-includes/configuration/integrations/javascript.vue.mdx @@ -5,6 +5,7 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | diff --git a/platform-includes/configuration/integrations/javascript.wasm.mdx b/platform-includes/configuration/integrations/javascript.wasm.mdx index ff99e1a54df39..8fde95e686b5d 100644 --- a/platform-includes/configuration/integrations/javascript.wasm.mdx +++ b/platform-includes/configuration/integrations/javascript.wasm.mdx @@ -4,6 +4,7 @@ |-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:| | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | From 30b76e31a01b342f89a4454b81650f94779e07f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 17:15:28 +0300 Subject: [PATCH 24/48] docs(bun): Document the build plugin in the instrumentation step (#19361) ## DESCRIBE YOUR PR The guide told users to run `bun --preload ./instrument.js app.js` and then warned that auto-instrumentation doesn't work with bundled code, which is backwards: library and framework spans exist only in a build, and `@sentry/bun/plugin` was never named on the page. The two compose. `--preload` guarantees init order and is always needed; the plugin build adds library and framework spans on top. Verified in the runtime audit repro `quickstarts/bun` variant (c): a `sentryBunPlugin()` bundle run with `--preload` produced errors, route-named `Bun.serve` spans, `http.client` spans carrying `sentry-trace` and `baggage`, and logs. - Add an optional "Build With the Sentry Plugin" step using `sentryBunPlugin`, before the run step - Reframe the `--preload` step as what guarantees init order, and show it for both source and built output - Drop the "Bundled Code Limitation" alert, which claimed the opposite - Add a troubleshooting entry for an instrumented package left outside the bundle, which is what silences library spans in a plugin build - Add `logs` to the onboarding options, so the logs verify block already on the page can be selected ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5 --- .../common/troubleshooting/index.mdx | 34 ++++++++++++++++ .../platforms/javascript/guides/bun/index.mdx | 40 +++++++++++++++---- 2 files changed, 67 insertions(+), 7 deletions(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 7215d03e1d5d7..7d74a04c79184 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -762,4 +762,38 @@ shamefully-hoist=true + + + The plugin can only rewrite a package that passes through the bundler. Anything left external is resolved at runtime, never reaches the transform, and publishes no channel events, so it records no spans. + + Build without `external`, which is the configuration to start from: + + ```typescript {filename:build.ts} + import { sentryBunPlugin } from "@sentry/bun/plugin"; + + await Bun.build({ + entrypoints: ["./app.ts"], + outdir: "./dist", + target: "bun", + plugins: [sentryBunPlugin()], + }); + ``` + + A blanket externalization strategy is the usual cause. Both `packages: "external"` and `"*"` in `external` push your instrumented packages back out of the bundle, and the plugin warns at build time: + + ```typescript {filename:build.ts} {diff} + await Bun.build({ + entrypoints: ["./app.ts"], + outdir: "./dist", + target: "bun", + - packages: "external", + plugins: [sentryBunPlugin()], + }); + ``` + + If you do need `external`, list only packages you don't need traced, and keep your database clients, AI SDKs and instrumented frameworks off the list. + + + + If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose). Customers on a paid plan may also contact support. diff --git a/docs/platforms/javascript/guides/bun/index.mdx b/docs/platforms/javascript/guides/bun/index.mdx index a5cb05c21e83c..310ca7d725565 100644 --- a/docs/platforms/javascript/guides/bun/index.mdx +++ b/docs/platforms/javascript/guides/bun/index.mdx @@ -16,7 +16,7 @@ categories: Choose the features you want to configure, and this guide will show you how: @@ -77,27 +77,53 @@ Sentry.init({ -### Apply Instrumentation to Your App +### Build With the Sentry Plugin (Recommended) -To make sure that Sentry initializes before any other modules, you need to preload your instrumentation file using the [`--preload`](https://bun.com/docs/runtime#param-preload) flag. +We recommend building with the Sentry plugin, because it adds spans from your dependencies, such as database drivers, AI SDKs, and web frameworks like Express, Koa and Hapi. Bun has no runtime hook Sentry can use to instrument those packages, so the plugin rewrites them as `bun build` bundles them. + +Add `sentryBunPlugin` from `@sentry/bun/plugin` to your `Bun.build()` call, then run the output the same way, with `--preload`. Errors, the spans you create yourself, and `Bun.serve`, `node:http` and `fetch` spans work either way. + + + - +```typescript {filename:build.ts} +import { sentryBunPlugin } from "@sentry/bun/plugin"; -Sentry's auto-instrumentation does not work with bundled code, including Bun's single-file executables. This is because auto-instrumentation relies on module loading hooks that are not available when code is bundled. If you need to bundle your application, you'll need to manually instrument your code instead of relying on auto-instrumentation. +await Bun.build({ + entrypoints: ["./app.ts"], + outdir: "./dist", + target: "bun", + plugins: [sentryBunPlugin()], +}); +``` - + + + + +### Apply Instrumentation to Your App + + + + + +Preload your instrumentation file with the [`--preload`](https://bun.com/docs/runtime#param-preload) flag. This is what guarantees that `Sentry.init()` runs before any other module is loaded. -```bash +```bash {tabTitle:From source} bun --preload ./instrument.js app.js ``` +```bash {tabTitle:Built output} +bun --preload ./instrument.js dist/app.js +``` + From 0473b9600c697afe9f7b37d90f0e760cc7aa894d Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Tue, 22 Sep 2026 10:33:31 -0400 Subject: [PATCH 25/48] docs(js): Document `bfcacheMetricsIntegration` for v11 (#18936) Adds documentation for the new `bfcacheMetricsIntegration` in the browser SDK, which tracks back/forward cache hit/miss rate and not-restored reasons as application metrics. Depends on the SDK integration landing in a release https://github.com/getsentry/sentry-javascript/pull/22397 --------- Co-authored-by: Martin Sonnberger --- .../configuration/integrations/bfcache.mdx | 102 ++++++++++++++++++ .../javascript/common/metrics/index.mdx | 5 + .../configuration/integrations/javascript.mdx | 1 + 3 files changed, 108 insertions(+) create mode 100644 docs/platforms/javascript/common/configuration/integrations/bfcache.mdx diff --git a/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx b/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx new file mode 100644 index 0000000000000..8450d9576a5dd --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx @@ -0,0 +1,102 @@ +--- +title: BFCache Metrics +description: "Track browser back/forward cache (bfcache) health as Sentry Application Metrics." +beta: true +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun +--- + + + + + +This integration only works inside a browser environment. + + + +_Import name: `Sentry.bfcacheMetricsIntegration`_ + +The `bfcacheMetricsIntegration` tracks the health of the browser's [back/forward cache (bfcache)](https://web.dev/articles/bfcache) and emits it as [Sentry Application Metrics](/product/metrics/). The bfcache is a browser optimization that restores a previously visited page instantly from an in-memory snapshot when the user navigates back or forward. When the cache is hit, the back button feels instant; when it isn't, the same action becomes a full page reload. + +Use this integration to answer these questions: + +- What share of back/forward navigations does the browser restore instantly? +- Which routes miss the bfcache most often? +- What is blocking the browser from caching the page? +- How expensive is the fallback reload when a restore fails? + +```javascript +Sentry.init({ + integrations: [Sentry.bfcacheMetricsIntegration()], +}); +``` + +This integration requires Sentry Application Metrics to be available in your Sentry organization. + +A **hit** is a back/forward navigation that the browser restored instantly from the bfcache; a **miss** is one that fell back to a full page load. Hit/miss detection works across modern Chromium, Firefox, and Safari. When a miss occurs, the SDK also records the [`notRestoredReasons`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons) the browser reports for it. This API is currently Chromium-only, so the SDK records misses on other browsers without reasons. + +## Options + +### `maxReasons` + +A single miss can report several not-restored reasons (for example, multiple frames can block one page). By default, the SDK emits every reported reason. Set `maxReasons` to cap how many it emits per miss: + +```javascript +Sentry.init({ + integrations: [ + Sentry.bfcacheMetricsIntegration({ + maxReasons: 3, + }), + ], +}); +``` + +The SDK clamps values below `1` to `1`, since a lower cap would drop all reason data. This option only limits the `browser.bfcache.not_restored` metric and doesn't affect the reason count on `browser.bfcache.navigation`. + +## Emitted Metrics + +| Metric | Type | Description | +| --------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `browser.bfcache.navigation` | counter | One per back/forward navigation, split by outcome (`hit` or `miss`). | +| `browser.bfcache.not_restored` | counter | One per not-restored reason on a miss. Chromium-only. | +| `browser.bfcache.reload.duration` | distribution | Duration (in milliseconds) of the fallback reload when a back/forward navigation missed the bfcache. The SDK only emits this when the browser reports a duration. | + +### Attributes + +`browser.bfcache.navigation` includes: + +| Attribute | Description | +| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `browser.bfcache.outcome` | `hit` if the browser restored the page from the bfcache, `miss` if it reloaded the page. | +| `browser.bfcache.not_restored_reason_count` | The number of reasons the browser reported for a miss. The SDK omits this on hits and on misses where the browser reported no reasons. | +| `sentry.segment.name` | The route the navigation landed on, which the SDK takes from the scope's transaction name. Falls back to `window.location.pathname` if the scope has none. | + +`browser.bfcache.not_restored` includes: + +| Attribute | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------- | +| `browser.bfcache.reason` | A reason the browser reported for not restoring the page (for example, `unload-listener`, `websocket`). | +| `browser.bfcache.frame` | Where the reason originated: the `top` document or a `child` frame. | +| `sentry.segment.name` | The route the navigation landed on. | + +`browser.bfcache.reload.duration` includes `sentry.segment.name` only. + +## A Note on Reasons + +The browser defines the `notRestoredReasons` strings, and they can change between versions. Chrome also reports a privacy-masked `masked` reason alongside real ones for cross-origin frames. Treat the reason values as a moving target rather than a fixed enum, and group on them accordingly in dashboards. diff --git a/docs/platforms/javascript/common/metrics/index.mdx b/docs/platforms/javascript/common/metrics/index.mdx index 1e3ad433ef4e9..0e00cf933f9b0 100644 --- a/docs/platforms/javascript/common/metrics/index.mdx +++ b/docs/platforms/javascript/common/metrics/index.mdx @@ -41,6 +41,11 @@ With [Sentry's Application Metrics](/product/metrics/), you can send counters, g — Automatically collect render and load timing distribution metrics for key UI elements using the browser's Element Timing API. +- + `bfcacheMetricsIntegration` + + — Track browser back/forward cache (bfcache) hit/miss rate and not-restored + reasons as metrics. diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx index e679e040928d9..9a1d0fe9b87f1 100644 --- a/platform-includes/configuration/integrations/javascript.mdx +++ b/platform-includes/configuration/integrations/javascript.mdx @@ -18,6 +18,7 @@ | [`interactionsIntegration`](./interactions) | | | ✓ | | | | [`userTimingIntegration`](./usertiming) | | | ✓ | | | | [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | +| [`bfcacheMetricsIntegration`](./bfcache) | | | | | | | [`elementTimingIntegration`](./elementtiming) | | | | | | | [`captureConsoleIntegration`](./captureconsole) | | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | From af55930c10ca53d928f2da730f0bf315d7921bc5 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 16:52:42 +0200 Subject: [PATCH 26/48] docs(javascript): Document Mistral AI integration (#19532) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the Mistral AI integration added in getsentry/sentry-javascript#24243, including automatic and manual setup, privacy controls, and supported operations. Restricts the page and discovery links to supported platforms. ## IS YOUR CHANGE URGENT? - [x] No deadline: Not urgent, can wait up to 1 week+ --------- Co-authored-by: GPT-6 Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com> Co-authored-by: Jan Peer Stöcklmair Co-authored-by: Andrei Borza --- .../configuration/integrations/mistral.mdx | 100 ++++++++++++++++++ .../integrations/javascript.cloudflare.mdx | 2 + .../integrations/javascript.deno.mdx | 1 + 3 files changed, 103 insertions(+) diff --git a/docs/platforms/javascript/common/configuration/integrations/mistral.mdx b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx index 198678d4df294..8e3a2dfacf12c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mistral.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx @@ -29,6 +29,65 @@ Sentry.init({ }); ``` + + +On Deno, preload Sentry's import hook so the Mistral SDK can be instrumented: + +```bash +deno run --allow-net --allow-env --allow-read --allow-sys --allow-write --preload=npm:@sentry/deno/import app.ts +``` + + + + + + + +With the Node.js adapter, no build step is needed. The integration is enabled by default when tracing is enabled. + +On Bun, add `sentryBunPlugin()` to your build so the plugin can instrument the bundled Mistral SDK: + + + + + +On Bun, add `sentryBunPlugin()` to your build so the plugin can instrument the bundled Mistral SDK: + + + +```typescript {filename:build.ts} +import { sentryBunPlugin } from "@sentry/bun/plugin"; + +await Bun.build({ + entrypoints: ["./src/index.ts"], + outdir: "./dist", + target: "bun", + plugins: [sentryBunPlugin()], +}); +``` + +The Mistral SDK must be part of the bundle. The plugin only runs during a build, so for unbundled applications started with `bun run`, use [Manual Instrumentation](#manual-instrumentation). + + + + + +On Cloudflare, add `sentryCloudflareVitePlugin()` alongside Cloudflare's Vite plugin so the bundled Mistral SDK is instrumented: + +```typescript {filename:vite.config.mts} +import { cloudflare } from "@cloudflare/vite-plugin"; +import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [cloudflare(), sentryCloudflareVitePlugin()], +}); +``` + +Build-time instrumentation is enabled by default, and the plugin registers the integration in both `vite dev` and `vite build`. Keep the `nodejs_compat` flag enabled in your Wrangler configuration, and see the Vite plugin page for the full setup. Without the plugin, or with `buildTimeInstrumentation: false`, use [Manual Instrumentation](#manual-instrumentation). + + + ## Supported Operations By default, tracing support is added to the following Mistral AI SDK calls: @@ -75,3 +134,44 @@ Sentry.init({ ], }); ``` + + + +## Manual Instrumentation + +_Import name: `Sentry.instrumentMistralAiClient`_ + +If your application does not use automatic instrumentation, wrap your Mistral client after setting up Sentry. Use the returned client for all Mistral calls. + + + +Import Sentry from the entry point for your runtime: `@sentry/hono/node`, `@sentry/hono/bun`, or `@sentry/hono/cloudflare`. + + + + + +```javascript +import * as Sentry from "___SDK_PACKAGE___"; +``` + + + +```javascript +import { Mistral } from "@mistralai/mistralai"; + +const mistral = new Mistral({ apiKey: "your-mistral-api-key" }); +const client = Sentry.instrumentMistralAiClient(mistral, { + recordInputs: false, + recordOutputs: false, +}); + +const response = await client.chat.complete({ + model: "mistral-small-latest", + messages: [{ role: "user", content: "Hello!" }], +}); +``` + +Use one instrumentation approach for each client. If automatic instrumentation is already active, you don't need to wrap the client. + + diff --git a/platform-includes/configuration/integrations/javascript.cloudflare.mdx b/platform-includes/configuration/integrations/javascript.cloudflare.mdx index 1a117d34ac0ce..82ee0233153bd 100644 --- a/platform-includes/configuration/integrations/javascript.cloudflare.mdx +++ b/platform-includes/configuration/integrations/javascript.cloudflare.mdx @@ -16,4 +16,6 @@ | [`prismaIntegration`](./prisma) | | | ✓ | | | | [`honoIntegration`](./hono) | ✓ | ✓ | | | | +[Mistral AI](./mistral) is automatically instrumented when built with the Sentry Cloudflare Vite plugin. Without the plugin, use `instrumentMistralAiClient`. + The [`prismaIntegration`](./prisma) is only available through the [`@sentry/cloudflare/nodejs_compat`](../../features/nodejs-compat) entrypoint. diff --git a/platform-includes/configuration/integrations/javascript.deno.mdx b/platform-includes/configuration/integrations/javascript.deno.mdx index 1538e77225a05..bc060c536aaf5 100644 --- a/platform-includes/configuration/integrations/javascript.deno.mdx +++ b/platform-includes/configuration/integrations/javascript.deno.mdx @@ -20,3 +20,4 @@ | [`instrumentPostgresJsSql`](./postgresjs) | | | ✓ | | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | | ✓ | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | | From 3fe56a8f59771f2521979b81c80d3a962b4edd5a Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 16:53:11 +0200 Subject: [PATCH 27/48] docs(deno): update minimum Deno version to 2.8.3 (#19311) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Raise the documented Deno minimum version to 2.8.3 for the Sentry JavaScript SDK v11. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- .../getting-started-prerequisites/javascript.deno.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/getting-started-prerequisites/javascript.deno.mdx b/platform-includes/getting-started-prerequisites/javascript.deno.mdx index ceb8920ff89a1..4709c0f194eb2 100644 --- a/platform-includes/getting-started-prerequisites/javascript.deno.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.deno.mdx @@ -4,4 +4,4 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- Deno version >= `2.0.0` +- Deno version >= `2.8.3` From 5c3e765ef6db2f17ec0adb36486d901b865aaea2 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 22 Sep 2026 17:23:39 +0200 Subject: [PATCH 28/48] docs(nextjs): Update getting started and manual setup for v11 (#19336) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Updates the Next.js getting started and manual setup docs for SDK v11. - `withSentryConfig` moves to `@sentry/nextjs/config` (20 occurrences) — it's no longer exported from `@sentry/nextjs` - Pages Router: replace `sentry.client.config.ts` with `instrumentation-client.ts` and add the missing `instrumentation.ts` / `onRequestError` step. Under Turbopack the old file is ignored silently, so the page produced an app with no browser SDK and no server SDK - Export `onRouterTransitionStart` unconditionally — the SDK warns whenever it's absent, regardless of whether tracing is enabled - Drop removed build options: `unstable_sentryWebpackPluginOptions`, `_experimental.turbopackApplicationKey`, top-level `automaticVercelMonitors` / `excludeServerRoutes`. Document `applicationKey`, `buildTimeInstrumentation`, unified `reactComponentAnnotation`, `_experimental.vercelCronsMonitoring` - Remove `enableLogs` references (removed in v11); state Next.js 14+ / Node 20.19.0+ prerequisites **Staying in draft until the v11 SDK and the wizard are published.** These pages describe `@sentry/nextjs/config`, which only exists in `11.0.0-beta.2`+, and the quick start page documents wizard output that still emits `@sentry/nextjs` (being updated separately). Not included: `inboundFiltersIntegration` → `eventFiltersIntegration` and the `childProcess` split. Both link to shared `common/` pages that still carry the old names, so they need a page rename plus redirect across every JS platform. Refs SDK-1493 Refs SDK-1483 --------- Co-authored-by: Claude Opus 5 (1M context) Co-authored-by: Andrei <168741329+andreiborza@users.noreply.github.com> --- .../common/configuration/filtering.mdx | 2 +- .../common/troubleshooting/index.mdx | 2 +- .../nextjs/configuration/build/index.mdx | 166 ++++++++---------- .../nextjs/configuration/tree-shaking.mdx | 2 +- .../javascript/guides/nextjs/index.mdx | 4 +- .../javascript/guides/nextjs/logs/index.mdx | 6 +- .../guides/nextjs/manual-setup/index.mdx | 5 +- .../nextjs/manual-setup/pages-router.mdx | 80 ++++++++- .../nextjs/manual-setup/webpack-setup.mdx | 77 ++++---- .../javascript.nextjs.mdx | 28 +-- .../crons/setup/javascript.nextjs.mdx | 6 +- .../javascript.nextjs.mdx | 3 +- .../sourcemaps/overview/javascript.nextjs.mdx | 7 +- 13 files changed, 199 insertions(+), 189 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/filtering.mdx b/docs/platforms/javascript/common/configuration/filtering.mdx index 70403c0d28393..d52ef5f3951bc 100644 --- a/docs/platforms/javascript/common/configuration/filtering.mdx +++ b/docs/platforms/javascript/common/configuration/filtering.mdx @@ -57,7 +57,7 @@ This integration can be very helpful in reducing noise that's not related to you -**Prerequisite**: To use the `thirdPartyErrorFilterIntegration`, ensure you are using a bundler and one of [Sentry's bundler plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins). For **Next.js with Turbopack**, use the [`_experimental.turbopackApplicationKey`](/platforms/javascript/guides/nextjs/configuration/build/#_experimentalturbopackapplicationkey) build option instead. +**Prerequisite**: To use the `thirdPartyErrorFilterIntegration`, ensure you are using a bundler and one of [Sentry's bundler plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins). For **Next.js**, set the [`applicationKey`](/platforms/javascript/guides/nextjs/configuration/build/#applicationKey) build option, which works for both Webpack and Turbopack builds. diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 7d74a04c79184..1b3b3c490f3c4 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -675,7 +675,7 @@ shamefully-hoist=true }; // The Sentry plugin should always be applied last - const { withSentryConfig } = require('@sentry/nextjs'); + const { withSentryConfig } = require('@sentry/nextjs/config'); module.exports = withSentryConfig(module.exports) ``` diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 5216a58eb971f..b243a2da237f2 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -292,6 +292,72 @@ Excluded routes will appear as raw URLs in transaction names instead of paramete + + +Annotates your React components with `data-sentry-component`, `data-sentry-element`, and `data-sentry-source-file` attributes at build time, so Sentry can identify which component a user interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). + +Disabled unless you set a value. Set `enabled: true` to turn it on, and `ignoredComponents` to skip components by name. + +This option drives both Webpack and Turbopack builds. On Turbopack it requires **Next.js 16+**; on an older version the SDK warns at build time. + +```javascript {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + reactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], + }, +}); +``` + + + The bundler-specific `webpack.reactComponentAnnotation` and + `_experimental.turbopackReactComponentAnnotation` options are deprecated in + favor of this one and will be removed in the next major version. If both a + bundler-specific option and this one are set, the bundler-specific one wins + for that bundler. + + + + + + +Application key used by [`thirdPartyErrorFilterIntegration`](/platforms/javascript/configuration/filtering/#using-thirdpartyerrorfilterintegration) to tell your code apart from third-party code, so you can drop errors coming from browser extensions, injected scripts, and third-party widgets. + +The value must match an entry in the `filterKeys` array of your `thirdPartyErrorFilterIntegration` configuration. This option works for both Webpack and Turbopack builds. + +```javascript {tabTitle:Config} {mdExpandTabs} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + applicationKey: "my-nextjs-app", +}); +``` + +```javascript {tabTitle:Client} {filename:instrumentation-client.ts} +import * as Sentry from "@sentry/nextjs"; + +Sentry.init({ + integrations: [ + Sentry.thirdPartyErrorFilterIntegration({ + filterKeys: ["my-nextjs-app"], + behaviour: "drop-error-if-exclusively-contains-third-party-frames", + }), + ], +}); +``` + + + + + +Automatically instrument server-side dependencies at build time. This is what gives you tracing for libraries that can't be patched at runtime, including on platforms like Vercel and Netlify. + +Set to `false` to turn it off. Turbopack support requires **Next.js 16+**; the Webpack path works on earlier versions. + + + ## Next.js Webpack Options @@ -343,118 +409,32 @@ Automatically create cron monitors in Sentry for your Vercel Cron Jobs if config - - Pass configuration options directly to the [Sentry Webpack - Plugin](https://www.npmjs.com/package/@sentry/webpack-plugin) that ships with - the Sentry Next.js SDK. If `withSentryConfig` doesn't provide the option you - need to modify, you may override the `sentryWebpackPluginOptions` using this - option. - - This option is considered unstable, and its API may change in a breaking way - in any release. - - - - - -Enables React component name tracking. When enabled, it annotates React components with data attributes that allow Sentry to track which components users interacted with in features like Session Replay and breadcrumbs. - - - - - -A list of React component names to exclude from component annotation. - - - Configuration options for tree shaking. Refer to the [tree shaking documentation](/platforms/javascript/guides/nextjs/configuration/tree-shaking) for more details. -## Experimental Turbopack Options +## Experimental Options - These options are experimental and require **Next.js 16+**. Their API may - change in future releases. + These options are experimental. Their API may change in future releases. - - - - -Enables React component name annotation for Turbopack builds. This is the Turbopack equivalent of [`webpack.reactComponentAnnotation`](#webpackreactcomponentannotationenabled). - -When enabled, React components are annotated with `data-sentry-component`, `data-sentry-element`, and `data-sentry-source-file` attributes at build time. These attributes allow Sentry to identify which components users interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). - -```javascript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; - -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackReactComponentAnnotation: { - enabled: true, - }, - }, -}); -``` - - + - +Automatically create [Cron Monitors](/product/monitors-and-alerts/monitors/crons/) in Sentry for the Vercel Cron Jobs configured in your `vercel.json`, by detecting cron requests and emitting check-ins from spans. -A list of React component names to exclude from annotation in Turbopack builds. +Unlike [`webpack.automaticVercelMonitors`](#webpack.automaticVercelMonitors), which wraps route handlers at build time, this works with both Webpack and Turbopack and with both the App Router and the Pages Router. If you enable both, the SDK uses this one and warns that the other is redundant. ```javascript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { _experimental: { - turbopackReactComponentAnnotation: { - enabled: true, - ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], - }, + vercelCronsMonitoring: true, }, }); ``` - - - - - -Application key used by [`thirdPartyErrorFilterIntegration`](/platforms/javascript/configuration/filtering/#using-thirdpartyerrorfilterintegration) to distinguish first-party code from third-party code in Turbopack builds. This is the Turbopack equivalent of setting `applicationKey` via the Sentry Webpack Plugin. - -When set, a Turbopack loader injects `_sentryModuleMetadata` into every first-party module, enabling the `thirdPartyErrorFilterIntegration` to filter errors from browser extensions, injected scripts, and third-party widgets. - -The value must match the `filterKeys` array in your `thirdPartyErrorFilterIntegration` configuration. - -```javascript {tabTitle:Config} {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; - -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackApplicationKey: "my-nextjs-app", - }, -}); -``` - -```javascript {tabTitle:Client} {filename:instrumentation-client.ts} -import * as Sentry from "@sentry/nextjs"; - -Sentry.init({ - integrations: [ - Sentry.thirdPartyErrorFilterIntegration({ - filterKeys: ["my-nextjs-app"], - behaviour: "drop-error-if-exclusively-contains-third-party-frames", - }), - ], -}); -``` - - diff --git a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx index 0e1449901922c..d8d95d4d7b710 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx @@ -57,7 +57,7 @@ The following sections cover each available tree-shaking option and how to confi -Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set `debug: true` in your SDK configuration). This doesn't affect Sentry's Logs product (controlled by the `enableLogs` option) or your app's logging. +Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set `debug: true` in your SDK configuration). This doesn't affect Sentry's Logs product or your app's logging. diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index bab538c431b57..761c52c7e23e1 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -72,6 +72,8 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay ], }); + +export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} @@ -146,7 +148,7 @@ Your `next.config.ts` is wrapped with `withSentryConfig` to enable source map up ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", diff --git a/docs/platforms/javascript/guides/nextjs/logs/index.mdx b/docs/platforms/javascript/guides/nextjs/logs/index.mdx index 44dba6e642a3c..e97bed7b8d1a3 100644 --- a/docs/platforms/javascript/guides/nextjs/logs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/logs/index.mdx @@ -26,10 +26,6 @@ Logs work across all Next.js runtimes: - **Server** — Node.js server-side logging - **Edge** — Edge runtime logging - - On SDK versions below `10.71.0`, logs are opt-in. Set `enableLogs: true` in your `Sentry.init` in all three runtime files to send them. - - @@ -386,7 +382,7 @@ Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or di ### Logs not appearing -On SDK versions below `10.71.0`, logs are opt-in. Make sure `enableLogs: true` is set in **all** Sentry config files: +Logs are captured as soon as you call a `Sentry.logger.*` method or add a logging integration. Check that the runtime you're logging from initializes the SDK at all: - `instrumentation-client.ts` (client) - `sentry.server.config.ts` (server) diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx index 9003589af185f..b81d9a1f6f907 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx @@ -86,7 +86,7 @@ Extend your app's default Next.js options by adding `withSentryConfig` into your ```typescript {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -154,10 +154,7 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay }); -// ___PRODUCT_OPTION_START___ performance -// This export will instrument router navigations export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; -// ___PRODUCT_OPTION_END___ performance ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx index 0f413ffe91036..ebd66d0b4c803 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx @@ -81,7 +81,7 @@ Extend your app's default Next.js options by adding `withSentryConfig` into your ```typescript {tabTitle:Webpack} {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -112,7 +112,7 @@ export default withSentryConfig(nextConfig, { ```typescript {tabTitle:Turbopack} {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -137,7 +137,7 @@ export default withSentryConfig(nextConfig, { Create the following files in your application's root directory (or `src` folder if you have one): -- `sentry.client.config.ts` - Client-side SDK initialization +- `instrumentation-client.ts` - Client-side SDK initialization - `sentry.server.config.ts` - Server-side SDK initialization - `sentry.edge.config.ts` - Edge runtime SDK initialization (if using edge routes) @@ -146,10 +146,16 @@ Create the following files in your application's root directory (or `src` folder variable like `NEXT_PUBLIC_SENTRY_DSN`. + + +Older setups initialized the browser SDK in `sentry.client.config.ts`. That file is deprecated and is **ignored entirely by Turbopack builds**, which leaves your app with no browser SDK and no build error to tell you. Use `instrumentation-client.ts` instead. + + + -```typescript {tabTitle:Client} {mdExpandTabs} {filename:sentry.client.config.ts} +```typescript {tabTitle:Client} {mdExpandTabs} {filename:instrumentation-client.ts} import * as Sentry from "@sentry/nextjs"; Sentry.init({ @@ -174,6 +180,8 @@ Sentry.init({ replaysOnErrorSampleRate: 1.0, // ___PRODUCT_OPTION_END___ session-replay }); + +export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} @@ -218,6 +226,43 @@ Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/ +### Register Server-Side SDK + +Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` in your project root (or `src` folder) to load it at server startup. + +The `onRequestError` export is what captures server-side errors in the Pages Router, including errors thrown in API routes and `getServerSideProps`. + + + The `onRequestError` hook requires `@sentry/nextjs` version `8.28.0` or higher + and Next.js 15. + + + + + +```typescript {filename:instrumentation.ts} +import * as Sentry from "@sentry/nextjs"; + +export async function register() { + if (process.env.NEXT_RUNTIME === "nodejs") { + await import("./sentry.server.config"); + } + + if (process.env.NEXT_RUNTIME === "edge") { + await import("./sentry.edge.config"); + } +} + +// Capture errors from API routes, getServerSideProps, and middleware +export const onRequestError = Sentry.captureRequestError; +``` + + + + + + + ### Capture Pages Router Errors Create or update `pages/_error.tsx` to capture errors that occur during server-side rendering or in page components. @@ -332,7 +377,7 @@ Session Replay captures video-like reproductions of user sessions. It's configur -```typescript {filename:sentry.client.config.ts} +```typescript {filename:instrumentation-client.ts} Sentry.init({ dsn: "___PUBLIC_DSN___", @@ -453,16 +498,33 @@ Automatically create [Cron Monitors](/product/monitors-and-alerts/monitors/crons ### Enable Automatic Cron Monitoring -Add the `automaticVercelMonitors` option to your `next.config.ts`. +There are two ways to do this, depending on how you build: + +- `_experimental.vercelCronsMonitoring` creates check-ins from spans. It works with both Turbopack and Webpack, and with both routers. Prefer this one. +- `webpack.automaticVercelMonitors` wraps your route handlers at build time. It only works with Webpack and the Pages Router. + +If you enable both, the SDK uses the span-based approach and logs a warning telling you to drop the other one. -```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +```typescript {tabTitle:Span-based} {mdExpandTabs} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - automaticVercelMonitors: true, + _experimental: { + vercelCronsMonitoring: true, + }, +}); +``` + +```typescript {tabTitle:Webpack} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + webpack: { + automaticVercelMonitors: true, + }, }); ``` diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx index f3cb732af68c2..c375210378619 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx @@ -20,9 +20,10 @@ For a complete reference of all build configuration options, see the [Build Conf | ------------------------------- | ------------------------------- | ---------------------------------------------------- | | Server function instrumentation | Automatic via Next.js telemetry | Build-time code injection | | Middleware instrumentation | Automatic via Next.js telemetry | Build-time code injection | +| Dependency instrumentation | Next.js 16+ | Supported | | Source map upload | Post-compile during build | During build via plugin (default) | | Route exclusion | Not supported | Supported via `webpack.excludeServerRoutes` | -| React component annotation | Experimental (Next.js 16+) | Supported via `webpack.reactComponentAnnotation` | +| React component annotation | Next.js 16+ | Supported | | Logger tree-shaking | Not supported | Supported via `webpack.treeshake.removeDebugLogging` | ## Auto-Instrumentation Options @@ -44,7 +45,7 @@ These options are enabled by default with Webpack. Disable them if you prefer ma ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { webpack: { @@ -92,7 +93,7 @@ Specify routes as URL paths (not file system paths). Routes must have a leading ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { webpack: { @@ -129,7 +130,7 @@ The Sentry Webpack Plugin runs during each webpack compilation and uploads sourc ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", @@ -160,7 +161,7 @@ Enable post-build upload for faster builds. All source maps are uploaded once af ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", @@ -182,38 +183,24 @@ export default withSentryConfig(nextConfig, { -### Advanced Webpack Plugin Options +### Control Which Files Are Uploaded -Pass options directly to the underlying Sentry Webpack Plugin for advanced configuration. - - - The `unstable_sentryWebpackPluginOptions` API may change in future releases. - - - - These options only apply when `useRunAfterProductionCompileHook` is `false` - (the default). - +If the defaults pick up too much or too little, narrow the upload with the `sourcemaps` options. These are top-level options and apply to both Webpack and Turbopack builds. See [Build Configuration](/platforms/javascript/guides/nextjs/configuration/build/) for the full list. ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, - webpack: { - // Advanced Webpack plugin options - unstable_sentryWebpackPluginOptions: { - sourcemaps: { - assets: ["./build/**/*.js", "./build/**/*.map"], - ignore: ["node_modules/**"], - }, - }, + sourcemaps: { + assets: [".next/**/*.js", ".next/**/*.map"], + ignore: ["**/node_modules/**"], }, }); ``` @@ -265,13 +252,15 @@ export async function submitForm(formData: FormData) { ## React Component Annotation -With Webpack, you can enable React component name tracking. This annotates React components with `data-sentry-*` attributes that allow Sentry to identify which components users interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). +Component annotation adds `data-sentry-*` attributes to your React components at build time, so Sentry can tell you which component a user interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). - For Turbopack builds, component annotation is available as an experimental - feature requiring Next.js 16+. See - [`_experimental.turbopackReactComponentAnnotation`](/platforms/javascript/guides/nextjs/configuration/build/#_experimentalturbopackreactcomponentannotationenabled) - in the build options reference. + `reactComponentAnnotation` is a top-level option and drives both Webpack and + Turbopack builds. On Turbopack it requires Next.js 16 or higher, enable it on + an older version and the SDK warns at build time. The bundler-specific + `webpack.reactComponentAnnotation` and + `_experimental.turbopackReactComponentAnnotation` options still work but are + deprecated, and will be removed in the next major version. @@ -287,13 +276,11 @@ Enable `reactComponentAnnotation` to track component names in your application. ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - webpack: { - reactComponentAnnotation: { - enabled: true, - }, + reactComponentAnnotation: { + enabled: true, }, }); ``` @@ -316,14 +303,12 @@ If you have components you don't want annotated (for privacy or performance reas ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - webpack: { - reactComponentAnnotation: { - enabled: true, - ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], - }, + reactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], }, }); ``` @@ -360,7 +345,7 @@ tunnelRoute: true, // Auto-generated random route ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { // Use a fixed route (recommended) @@ -377,20 +362,22 @@ export default withSentryConfig(nextConfig, { If you're upgrading to Turbopack: -1. **Remove webpack-only options** - `excludeServerRoutes` and `unstable_sentryWebpackPluginOptions` have no effect with Turbopack +1. **Drop webpack-only options** - anything under `webpack` has no effect with Turbopack, including `excludeServerRoutes` and `treeshake` 2. **Understand source map changes** - Turbopack always uses post-build upload (no plugin-based upload option) 3. **Test auto-instrumentation** - Turbopack uses Next.js telemetry instead of build-time injection; verify your monitoring still works ```typescript {filename:next.config.ts} // Before (Webpack) export default withSentryConfig(nextConfig, { - excludeServerRoutes: ["/api/health"], + webpack: { + excludeServerRoutes: ["/api/health"], + }, tunnelRoute: "/sentry-tunnel", }); // After (Turbopack) export default withSentryConfig(nextConfig, { - // excludeServerRoutes is not supported with Turbopack + // webpack.excludeServerRoutes is not supported with Turbopack tunnelRoute: "/sentry-tunnel", }); ``` diff --git a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx index 5eca495abeaf2..9641067ed53c8 100644 --- a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx +++ b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx @@ -1,27 +1,13 @@ -**Webpack:** - -```javascript {tabTitle:CJS} {filename:next.config.js} {3} -module.exports = withSentryConfig(nextConfig, { - unstable_sentryWebpackPluginOptions: { - applicationKey: "your-custom-application-key", - }, -}); -``` - -```javascript {tabTitle:ESM} {filename:next.config.mjs} {3} +```javascript {tabTitle:ESM} {filename:next.config.mjs} {2} export default withSentryConfig(nextConfig, { - unstable_sentryWebpackPluginOptions: { - applicationKey: "your-custom-application-key", - }, + applicationKey: "your-custom-application-key", }); ``` -**Turbopack (Next.js 16+, experimental):** - -```javascript {filename:next.config.ts} {3} -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackApplicationKey: "your-custom-application-key", - }, +```javascript {tabTitle:CJS} {filename:next.config.js} {2} +module.exports = withSentryConfig(nextConfig, { + applicationKey: "your-custom-application-key", }); ``` + +This works for both Webpack and Turbopack builds. diff --git a/platform-includes/crons/setup/javascript.nextjs.mdx b/platform-includes/crons/setup/javascript.nextjs.mdx index 0f6442a455cb3..1032edf4a9242 100644 --- a/platform-includes/crons/setup/javascript.nextjs.mdx +++ b/platform-includes/crons/setup/javascript.nextjs.mdx @@ -5,10 +5,12 @@ Cron monitoring is only supported in Server and Edge runtimes for Next.js If you are hosting your Next.js application on Vercel and you are using [Vercel's Cron Jobs feature](https://vercel.com/docs/cron-jobs), you can configure the Next.js SDK to automatically create Check-Ins for you. Instrumented cron jobs are decided at runtime by examining the `crons` field in your `vercel.json` file. -Set the `automaticVercelMonitors` option to `true` in your Sentry settings in `next.config.js`. See Manual Setup for more details. +Set `_experimental.vercelCronsMonitoring` to `true` in your Sentry settings in `next.config.js`. See Manual Setup for more details. -Automatic instrumentation of Vercel cron jobs currently only works for the Pages Router. App Router route handlers are not yet supported. + The older `webpack.automaticVercelMonitors` option only works with Webpack and + the Pages Router. `_experimental.vercelCronsMonitoring` works with both + bundlers and both routers. ## Automatic Crons Instrumentation diff --git a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx index bcb8b05780126..5b4b58a004bbc 100644 --- a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx @@ -2,5 +2,6 @@ You need: -- A Next.js application +- A Next.js application on version 14 or higher +- Node.js 20.19.0 or higher - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) diff --git a/platform-includes/sourcemaps/overview/javascript.nextjs.mdx b/platform-includes/sourcemaps/overview/javascript.nextjs.mdx index b03d030a4751a..c8fd38841a7a7 100644 --- a/platform-includes/sourcemaps/overview/javascript.nextjs.mdx +++ b/platform-includes/sourcemaps/overview/javascript.nextjs.mdx @@ -41,7 +41,7 @@ With **Turbopack** (Next.js 15+ default), source maps upload after the build com ```typescript {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // your existing Next.js config @@ -70,10 +70,7 @@ See Build OptionsWebpack Setup for complete Webpack configuration. From 9b89161ea7565119767baad0df53bc2aa08662a3 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 18:00:48 +0200 Subject: [PATCH 29/48] docs(agent-tracing): remove the streamGenAiSpans option (#19337) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Remove the `streamGenAiSpans` option from the docs, since v11 always streams gen AI spans and the flag no longer exists. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- .../javascript/common/agent-tracing/flue.mdx | 2 -- .../javascript/common/agent-tracing/index.mdx | 32 ------------------- .../common/configuration/options.mdx | 10 ------ 3 files changed, 44 deletions(-) diff --git a/docs/platforms/javascript/common/agent-tracing/flue.mdx b/docs/platforms/javascript/common/agent-tracing/flue.mdx index daf0370406d4b..7265653b0c474 100644 --- a/docs/platforms/javascript/common/agent-tracing/flue.mdx +++ b/docs/platforms/javascript/common/agent-tracing/flue.mdx @@ -109,7 +109,6 @@ Sentry.init({ enabled: Boolean(process.env.SENTRY_DSN), tracesSampleRate, traceLifecycle: "stream", - streamGenAiSpans: true, enableLogs: true, // Flue already emits one `chat` span per model call, so Sentry's // AI provider integrations are removed to avoid double counting. @@ -166,7 +165,6 @@ export const cloudflare = extend({ release: env.SENTRY_RELEASE, tracesSampleRate: clampRate(env.SENTRY_TRACES_SAMPLE_RATE, 0), traceLifecycle: "stream", - streamGenAiSpans: true, enableLogs: true, integrations: (defaults) => defaults.filter((i) => !SENTRY_AI_PROVIDER_INTEGRATIONS.has(i.name)), diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index ba7a87adcbcc7..3adf5c6085e7c 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -240,38 +240,6 @@ On the default CF entrypoint, control Vercel AI I/O with `experimental_telemetry From SDK `10.61.0`, `gen_ai` spans are sent as standalone envelope items (avoids large-payload drops; required for Conversations). -Self-hosted Sentry users should set `streamGenAiSpans: false` if standalone `gen_ai` spans may not be ingested. - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - streamGenAiSpans: false, -}); -``` - - - - - -```javascript -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - streamGenAiSpans: false, - }), - { - async fetch(request, env, ctx) { - /* ... */ - }, - } -); -``` - - - ## Manual Instrumentation De - - -When enabled, `gen_ai` spans are sent as standalone envelope items instead of being bundled in the transaction payload. This prevents AI spans with large inputs and outputs from being dropped due to transaction payload size limits. - -This is enabled by default starting with SDK version `10.61.0` (before that, it defaulted to `false`). Set it to `false` to send `gen_ai` spans as part of the transaction instead. - -Self-hosted Sentry users should set this option to `false`, as standalone `gen_ai` spans may not be ingested by their Sentry instance. - - - Controls how spans are sent to Sentry: From 2b6eb78dcaed54936777be57b0b3cc9cd1887a5d Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 18:08:08 +0200 Subject: [PATCH 30/48] docs(fastify): update minimum Fastify version to 3.21 (#19312) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Update the documented Fastify supported range to `^3.21.0 || ^4.0.0` since v11 drops Fastify 3.0–3.20. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- .../javascript/common/configuration/integrations/fastify.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/fastify.mdx b/docs/platforms/javascript/common/configuration/integrations/fastify.mdx index 2a3100fddb41c..41f997c579394 100644 --- a/docs/platforms/javascript/common/configuration/integrations/fastify.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/fastify.mdx @@ -30,4 +30,4 @@ Sentry.init({ ## Supported Versions -- `fastify`: `^3.0.0 || ^4.0.0` +- `fastify`: `^3.21.0 || ^4.0.0` From 625186df67857960afe8ff4e9801b6c632de13dd Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 18:08:34 +0200 Subject: [PATCH 31/48] docs(js): update attachStacktrace default to true (#19316) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Update the documented default for `attachStacktrace` to `true` for v11. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- docs/platforms/javascript/common/configuration/options.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 6db70eb6627d4..89f4f945a9374 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -190,7 +190,7 @@ This variable controls the total amount of breadcrumbs that should be captured. - + Enabled per Electron process. From 67eb835d7c3437ce63af584160f4f38536305dc7 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 18:08:50 +0200 Subject: [PATCH 32/48] docs(browser): drop Safari 14 from supported browsers (#19313) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Raise the minimum supported Safari to 15 (Safari 15 / iOS Safari 15) in the v11 browser support matrix, since v11 drops Safari 14. > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) --- .../javascript/common/troubleshooting/supported-browsers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx b/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx index 32a83dd416604..08b2661f71f5f 100644 --- a/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx +++ b/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx @@ -24,7 +24,7 @@ Sentry's latest JavaScript SDKs require ES2020 compatibility. The minimum suppor - Chrome 80 - Edge 80 -- Safari 14, iOS Safari 14.4 +- Safari 15, iOS Safari 15 - Firefox 74 - Opera 67 - Samsung Internet 13.0 From 0a3d3be7f58b5427817a642b2a15be8bc244e71d Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Tue, 22 Sep 2026 18:13:47 +0200 Subject: [PATCH 33/48] docs(agent-tracing): update gen_ai attribute names and rename instrumentLangGraph (#19338) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Apply the v11 `gen_ai.*` attribute renames (Mastra page + manual span-metrics example), rename `instrumentLangGraph` to `instrumentStateGraph`, and document the separate `instrumentCreateReactAgent` manual helper on the LangGraph pages (JavaScript and React Native). > **⚠️ Do not merge until v11 is released as stable.** ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) Co-authored-by: Andrei Borza --- .../configuration/integrations/langgraph.mdx | 72 +++++++++++++++++++ .../common/tracing/span-metrics/examples.mdx | 1 - .../common/integrations/langgraph.mdx | 23 +++++- 3 files changed, 92 insertions(+), 4 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx index cd1e54bd52660..00c486398502a 100644 --- a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx @@ -70,3 +70,75 @@ Sentry.init({ ], }); ``` + +## Manual Instrumentation + +_Import names: `Sentry.instrumentStateGraph`, `Sentry.instrumentCreateReactAgent`_ + +If your application does not use automatic instrumentation, wrap your agent after setting up Sentry. Two helpers are available, depending on how you build your agent: + +- **`instrumentStateGraph`**: for graphs you build yourself with `StateGraph`. Call it on the graph **before** calling `.compile()`. +- **`instrumentCreateReactAgent`**: for LangGraph's prebuilt `createReactAgent`. Wrap the factory, then use the wrapped version exactly like `createReactAgent`. This also captures the model and wraps tools, so you get `execute_tool` spans as well. + +Both accept the same `recordInputs` and `recordOutputs` options as the integration. + +Instrumenting a `StateGraph`: + +```javascript +import { ChatOpenAI } from "@langchain/openai"; +import { + StateGraph, + MessagesAnnotation, + START, + END, +} from "@langchain/langgraph"; +import { SystemMessage, HumanMessage } from "@langchain/core/messages"; + +// Create LLM call +const llm = new ChatOpenAI({ + modelName: "gpt-4o", + apiKey: "your-api-key", +}); + +async function callLLM(state) { + const response = await llm.invoke(state.messages); + + return { + messages: [...state.messages, response], + }; +} + +// Create the agent +const agent = new StateGraph(MessagesAnnotation) + .addNode("agent", callLLM) + .addEdge(START, "agent") + .addEdge("agent", END); + +// Instrument the graph before compiling +Sentry.instrumentStateGraph(agent, { + recordInputs: true, + recordOutputs: true, +}); + +const graph = agent.compile({ name: "my_agent" }); + +// Invoke the agent +const result = await graph.invoke({ + messages: [ + new SystemMessage("You are a helpful assistant."), + new HumanMessage("Hello!"), + ], +}); +``` + +Instrumenting a prebuilt `createReactAgent`: + +```javascript +import { createReactAgent } from "@langchain/langgraph/prebuilt"; + +// Instrument createReactAgent, then use the wrapped version in its place +const instrumentedCreateReactAgent = + Sentry.instrumentCreateReactAgent(createReactAgent); + +const agent = instrumentedCreateReactAgent({ llm, tools }); +``` diff --git a/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx b/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx index f86a45e676241..04eb4000295cf 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx @@ -811,7 +811,6 @@ app.post("/api/ai/chat", async (req: Request, res: Response) => { attributes: { "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": toolCall.function.name, - "gen_ai.tool.type": "function", "gen_ai.tool.call.arguments": toolCall.function.arguments, [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: "manual.ai.custom-llm", }, diff --git a/docs/platforms/react-native/common/integrations/langgraph.mdx b/docs/platforms/react-native/common/integrations/langgraph.mdx index 7cfd989020898..cfb5466715d82 100644 --- a/docs/platforms/react-native/common/integrations/langgraph.mdx +++ b/docs/platforms/react-native/common/integrations/langgraph.mdx @@ -3,9 +3,14 @@ title: LangGraph description: "Manually instrument LangGraph in React Native to capture spans for agent compilation and invocation." --- -_Import name: `Sentry.instrumentLangGraph`_ +_Import names: `Sentry.instrumentStateGraph`, `Sentry.instrumentCreateReactAgent`_ -The `instrumentLangGraph` helper adds instrumentation for [`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph) by wrapping a `StateGraph` before compilation and recording agent interactions with configurable input/output capture. The OpenTelemetry-based automatic integration available for Node.js does not work in React Native, so calling `instrumentLangGraph` on the graph **before** `.compile()` is the only supported path. +The OpenTelemetry-based automatic integration available for Node.js does not work in React Native, so manual instrumentation is the only supported path. Two helpers are available, depending on how you build your agent: + +- **`instrumentStateGraph`** — for graphs you build yourself with `StateGraph`. Call it on the graph **before** calling `.compile()`. +- **`instrumentCreateReactAgent`** — for LangGraph's prebuilt `createReactAgent`. Wrap the factory, then use the wrapped version exactly like `createReactAgent`. This also captures the model and wraps tools, so you get `execute_tool` spans as well. + +Both accept the same input/output recording options. ## Usage @@ -35,7 +40,7 @@ const agent = new StateGraph(MessagesAnnotation) .addEdge("agent", END); // Instrument the graph BEFORE compiling -Sentry.instrumentLangGraph(agent, { +Sentry.instrumentStateGraph(agent, { recordInputs: true, recordOutputs: true, }); @@ -50,6 +55,18 @@ const result = await graph.invoke({ }); ``` +Or, instrument LangGraph's prebuilt `createReactAgent`: + +```javascript +import * as Sentry from "@sentry/react-native"; +import { createReactAgent } from "@langchain/langgraph/prebuilt"; + +// Instrument createReactAgent, then use the wrapped version in its place +const instrumentedCreateReactAgent = Sentry.instrumentCreateReactAgent(createReactAgent); + +const agent = instrumentedCreateReactAgent({ llm, tools }); +``` + Make sure tracing is enabled for the spans produced by this integration to be captured. ## Configuration From 5ab7a0351ac5e75d8e006a68a2a4d5476221a7f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 19:14:42 +0300 Subject: [PATCH 34/48] docs(solidstart): Document the SolidStart 2 setup (#19376) ## DESCRIBE YOUR PR closes SDK-1515 `npm install @solidjs/start` gives SolidStart 2 today, and the guide described SolidStart 1 only. On SolidStart 2 there is no `app.config.ts`, `@solidjs/start/config` exports no `defineConfig`, the build emits no `.output/server/instrument.server.mjs`, and vinxi is not installed, so the documented config was ignored and the documented start command exited with `ERR_MODULE_NOT_FOUND`. Give each affected step a SolidStart 2 tab next to the SolidStart 1 one: - Server init moves to a Nitro startup plugin, `server/plugins/sentry.ts`. - The build config moves to `vite.config.ts` with `sentrySolidStart` from `@sentry/solidstart/vite`. - The server starts with a plain `node .output/server/index.mjs`. The Vite plugin instruments dependencies at build time, so no preload is needed. - Source map options move into `sentrySolidStart()`. Add a SolidStart prerequisites include naming the supported versions, so readers know which set of tabs applies to them. The guide fell back to the default include, which names no framework version at all. Scope the `--import`, limited server tracing and dynamic import installation methods to SolidStart 1, since all three configure `withSentry` in `app.config.ts`. Import `sentryBeforeResponseMiddleware` from `@sentry/solidstart`. The package exports `.`, `./solidrouter` and `./vite`, so the documented `@sentry/solidstart/middleware` path failed with `ERR_PACKAGE_PATH_NOT_EXPORTED`. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Claude Opus 5 --- .../guides/solidstart/features/middleware.mdx | 31 +++++-- .../javascript/guides/solidstart/index.mdx | 89 ++++++++++++++++--- .../guides/solidstart/install/cli-import.mdx | 8 ++ .../solidstart/install/dynamic-import.mdx | 46 ++++++---- .../guides/solidstart/install/index.mdx | 8 +- .../install/limited-server-tracing.mdx | 6 ++ .../how-to-use/javascript.solidstart.mdx | 22 ++--- .../javascript.solidstart.mdx | 15 ++++ 8 files changed, 177 insertions(+), 48 deletions(-) create mode 100644 platform-includes/getting-started-prerequisites/javascript.solidstart.mdx diff --git a/docs/platforms/javascript/guides/solidstart/features/middleware.mdx b/docs/platforms/javascript/guides/solidstart/features/middleware.mdx index feb69bae2b524..ecdb08f2c42f2 100644 --- a/docs/platforms/javascript/guides/solidstart/features/middleware.mdx +++ b/docs/platforms/javascript/guides/solidstart/features/middleware.mdx @@ -5,11 +5,11 @@ description: "Learn about Sentry's middleware for better instrumentation." The Sentry middleware enhances the data collected by Sentry on the server side by enabling distributed tracing between the client and server. -Add the Sentry middleware to your `middleware.ts` file. If you don't have a `middleware.ts` file yet, create one: +Add the Sentry middleware to your `src/middleware.ts` file. If you don't have a `src/middleware.ts` file yet, create one: -```typescript {filename:middleware.ts} -import { sentryBeforeResponseMiddleware } from '@sentry/solidstart/middleware'; -import { createMiddleware } from '@solidjs/start/middleware'; +```typescript {filename:src/middleware.ts} +import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; +import { createMiddleware } from "@solidjs/start/middleware"; export default createMiddleware({ onBeforeResponse: [ @@ -19,13 +19,28 @@ export default createMiddleware({ }); ``` -And specify `middleware.ts` in `app.config.ts`: +Then register `middleware.ts` in your build config. On SolidStart 2, pass it to the `solidStart` plugin in `vite.config.ts`. On SolidStart 1, specify it in `app.config.ts`: -```typescript {filename:app.config.ts} -import { defineConfig } from '@solidjs/start/config'; +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { solidStart } from "@solidjs/start/config"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart({ + // ... + middleware: "./src/middleware.ts", + }), + // ... + ], +}); +``` + +```typescript {tabTitle:SolidStart 1} {filename:app.config.ts} +import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ // ... - middleware: './src/middleware.ts', + middleware: "./src/middleware.ts", }); ``` diff --git a/docs/platforms/javascript/guides/solidstart/index.mdx b/docs/platforms/javascript/guides/solidstart/index.mdx index aad5f768ad29c..d9c4a20da6f77 100644 --- a/docs/platforms/javascript/guides/solidstart/index.mdx +++ b/docs/platforms/javascript/guides/solidstart/index.mdx @@ -149,12 +149,32 @@ mount(() => , document.getElementById("app")); -Create a file named `instrument.server.ts` in your `src` folder. In this file, initialize and import Sentry for your server: +Initialize Sentry on the server. On SolidStart 2, do this in a Nitro startup plugin, which runs once when the server starts. On SolidStart 1, create an `instrument.server.ts` file in your `src` folder. -```javascript {filename:src/instrument.server.ts} +```typescript {tabTitle:SolidStart 2} {filename:server/plugins/sentry.ts} {mdExpandTabs} +import * as Sentry from "@sentry/solidstart"; +import { definePlugin } from "nitro"; + +export default definePlugin(() => { + Sentry.init({ + dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + }); +}); +``` + +```javascript {tabTitle:SolidStart 1} {filename:src/instrument.server.ts} import * as Sentry from "@sentry/solidstart"; Sentry.init({ @@ -205,13 +225,29 @@ export default createMiddleware({ -Wrap your SolidStart config in `app.config.ts` with `withSentry` so that the instrumentation file gets included in your build output. -Then, specify the middleware that you've just created: +Add the Sentry plugin to your build config and register the middleware you just created. On SolidStart 2, add `sentrySolidStart` to `vite.config.ts`. On SolidStart 1, wrap your `app.config.ts` with `withSentry` so that the instrumentation file gets included in your build output. -```javascript {filename:app.config.ts} {5-15} +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { sentrySolidStart } from "@sentry/solidstart/vite"; +import { solidStart } from "@solidjs/start/config"; +import { nitro } from "nitro/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart({ + middleware: "./src/middleware.ts", + }), + sentrySolidStart(), + nitro(), + ], +}); +``` + +```javascript {tabTitle:SolidStart 1} {filename:app.config.ts} {5-15} import { withSentry } from "@sentry/solidstart"; import { defineConfig } from "@solidjs/start/config"; @@ -274,24 +310,35 @@ export default function App() { -Instrumentation needs to happen as early as possible to make sure Sentry works as intended. To do this, add an `--import` flag to the `NODE_OPTIONS` environment variable when you run your application and set it to import the instrumentation file created by the build output: `.output/server/instrument.server.mjs`. +On SolidStart 2, the Vite plugin instruments your dependencies at build time, so the server needs no preload flag. Build with `vite build` and start the output directly. + +On SolidStart 1, instrumentation has to happen as early as possible, so add an `--import` flag pointing at the instrumentation file that the build output creates: `.output/server/instrument.server.mjs`. -Run your build command to generate the `instrument.server.mjs` file before running your app. Depending on your build preset, the location of the file can differ. To find out where the file is located, monitor the build log output for: +On SolidStart 1, run your build command to generate the `instrument.server.mjs` file before running your app. Depending on your build preset, the location of the file can differ. To find out where the file is located, monitor the build log output for: `[Sentry SolidStart withSentry] Successfully created /my/project/path/.output/server/instrument.server.mjs.` -If you're not able to use the `--import` flag, check the alternative installation methods. +If you're not able to use the `--import` flag on SolidStart 1, check the alternative installation methods. For example, update your scripts in `package.json`: -```json {filename:package.json} +```json {tabTitle:SolidStart 2} {filename:package.json} {mdExpandTabs} +{ + "scripts": { + "build": "vite build", + "start": "node .output/server/index.mjs" + } +} +``` + +```json {tabTitle:SolidStart 1} {filename:package.json} { "scripts": { "start:vinxi": "NODE_OPTIONS='--import ./.output/server/instrument.server.mjs ' vinxi start", @@ -327,12 +374,32 @@ To automatically report exceptions from inside a component tree to Sentry, wrap -To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your SolidStart configuration: +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug to the Sentry plugin in your build config: -```TypeScript {filename:app.config.ts} +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { sentrySolidStart } from "@sentry/solidstart/vite"; +import { solidStart } from "@solidjs/start/config"; +import { nitro } from "nitro/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart(), + sentrySolidStart({ + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + // store your auth token in an environment variable + authToken: process.env.SENTRY_AUTH_TOKEN, + }), + nitro(), + ], +}); +``` + +```TypeScript {tabTitle:SolidStart 1} {filename:app.config.ts} import { withSentry } from '@sentry/solidstart'; import { defineConfig } from '@solidjs/start/config'; diff --git a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx index ea23fddb76902..1a179420847cb 100644 --- a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx @@ -4,6 +4,12 @@ sidebar_order: 1 description: "Learn how to use the node --import CLI flag." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding the `--import` CLI Flag The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node is the default way in ESM to preload a specified module at startup. @@ -54,11 +60,13 @@ Consult your hosting provider's documentation for specific implementation detail Most deployment platforms support this through two primary methods: #### Option 1: Direct CLI Flag + ```bash node --import ./.output/server/instrument.server.mjs your-server-entry.mjs ``` #### Option 2: Environment Variable + ```bash NODE_OPTIONS='--import ./.output/server/instrument.server.mjs' ``` diff --git a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx index a4bd655734da4..9b5d5a79302d6 100644 --- a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx @@ -4,12 +4,19 @@ sidebar_order: 3 description: "Learn about how the SolidStart SDK leverages dynamic input() in the build output." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding the `import()` expression This setting is experimental as it is not guaranteed to work with every setup and the underlying functionality could change. - We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing +We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. @@ -31,15 +38,17 @@ You can also check out the guide for installing the SDK with the + +These installation methods apply to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so the server needs no preload. + + + +SolidStart 1 uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). Those customization hooks need to be registered before the rest of the application. To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: diff --git a/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx b/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx index 8e21b35392ade..0a8f1ee3ca0d0 100644 --- a/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx @@ -4,6 +4,12 @@ sidebar_order: 2 description: "Learn how to set up the SolidStart SDK with limited server tracing by adding a top-level import to the build output." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding Limited Server Tracing Sentry needs to be initialized before the rest of the application runs. diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx index 02a15881625cc..81a950c32070e 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx @@ -3,8 +3,8 @@ To set up distributed tracing, use Sentry's middleware to inject tracing informa Create or modify the `middleware.ts` file and import and add `sentryBeforeResponseMiddleware` ```typescript {filename: middleware.ts} -import { sentryBeforeResponseMiddleware } from '@sentry/solidstart/middleware'; -import { createMiddleware } from '@solidjs/start/middleware'; +import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; +import { createMiddleware } from "@solidjs/start/middleware"; export default createMiddleware({ onBeforeResponse: [ @@ -12,16 +12,16 @@ export default createMiddleware({ // Add your other middleware handlers after `sentryBeforeResponseMiddleware` ], }); -```` +``` If you didn't use a middleware before, don't forget to specify it in `app.config.ts` ```typescript {filename: app.config.ts} -import { defineConfig } from '@solidjs/start/config'; +import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ // ... - middleware: './src/middleware.ts', + middleware: "./src/middleware.ts", }); ``` @@ -66,8 +66,8 @@ Sentry.init({ This tells Sentry to pass trace headers across the following paths: -* Your main API server (where product data comes from) -* Your authentication server (where logins happen) +- Your main API server (where product data comes from) +- Your authentication server (where logins happen) This way, if a customer experiences an error during checkout, or you want to check the performance of a specific endpoint, you can see the complete path their request took across these different services. @@ -81,16 +81,16 @@ Sentry.init({ tracePropagationTargets: [ "https://api.myapp.com", "https://media.myapp.com", - /^\/local-api\// + /^\/local-api\//, ], }); ``` This configuration lets your app track user actions across: -* Your main API server (handles most app functions) -* Your media server (handles images, videos, etc.) -* Any local API endpoints in your app +- Your main API server (handles most app functions) +- Your media server (handles images, videos, etc.) +- Any local API endpoints in your app If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service. diff --git a/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx b/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx new file mode 100644 index 0000000000000..2aad75db297c4 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx @@ -0,0 +1,15 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- SolidStart version `1.0.0`+ or `2.0.0`+ + + + +SolidStart 2 dropped vinxi and `app.config.ts`, so the two versions are set up differently. Check the `@solidjs/start` version in your `package.json`; a new project installs SolidStart 2. + +Where this guide shows **SolidStart 2** and **SolidStart 1** tabs, pick the one that matches your version. The installation methods apply to SolidStart 1 only. + + From 742ea0dbe0979e57934cdcb8ed5a222563b74621 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 19:32:25 +0300 Subject: [PATCH 35/48] docs(js): Update Deno guide for v11 (#19365) ## DESCRIBE YOUR PR closes SDK-1502 Rework the Deno getting-started path so a new user reaches a first event without hitting the gaps found in the runtime docs audit. - Document the `@sentry/deno/import` hook as the first import, with the `nodeModulesDir` setting it needs to resolve. Without it the database, messaging, AI and framework integrations never instrument anything, and the SDK gives no warning. - Replace the two separate permission commands with one `deno run` line covering all four flags, and explain what each one unlocks. The previous `--allow-net` only command crashed or silently dropped `server_name`, the OS version, context lines and app-relative frame paths. - Widen `--allow-read` from `./src` to `.`, which is what path normalization queries. A subdirectory grant loses context lines on the entry file and all `app:///` rewriting. - Stop recommending `denoCronIntegration()`. It throws inside `Sentry.init` on Deno 2.9.0 and later, is not in the Deno default integration set, and does nothing without `--unstable-cron`. - Add a troubleshooting entry for the startup crash that the import hook triggers on Deno (denoland/deno#36240). ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5 --- .../common/troubleshooting/index.mdx | 25 ++++++++ .../javascript/guides/deno/index.mdx | 61 +++++++++++++------ .../crons/setup/javascript.deno.mdx | 28 ++++++--- 3 files changed, 85 insertions(+), 29 deletions(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 1b3b3c490f3c4..bc3584dbddbc1 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -794,6 +794,31 @@ shamefully-hoist=true If you do need `external`, list only packages you don't need traced, and keep your database clients, AI SDKs and instrumented frameworks off the list. + + + + + + + +Your app imports a dependency that calls `require()` on a JSON file, and the `@sentry/deno/import` hook is active. Deno compiles the JSON as JavaScript instead, and the process stops before your code runs: + +``` +error: Uncaught SyntaxError: Unexpected token ':' +``` + +This is a Deno bug ([denoland/deno#36240](https://github.com/denoland/deno/issues/36240)): while any module hook is registered, Deno loads `.json` files with the wrong format. Express, Fastify, Hapi, Koa and mysql2 all read a JSON file this way. + +Remove the `@sentry/deno/import` line from your entry file to start your app again: + +```javascript {filename: main.ts} +import * as Sentry from "npm:@sentry/deno"; +``` + +Errors, `Deno.serve` and `node:http` spans, logs and metrics all keep working without the hook. You lose the integrations that depend on it, such as `mysql` 2.x and `pg`. Drivers that publish their own diagnostics channels, among them `mysql2` 3.20.0 and later and `ioredis` 5.11.0 and later, are instrumented either way. + + + If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose). Customers on a paid plan may also contact support. diff --git a/docs/platforms/javascript/guides/deno/index.mdx b/docs/platforms/javascript/guides/deno/index.mdx index 3a7a85c8053af..2b272ca5d4c0f 100644 --- a/docs/platforms/javascript/guides/deno/index.mdx +++ b/docs/platforms/javascript/guides/deno/index.mdx @@ -33,12 +33,13 @@ Choose the features you want to configure, and this guide will show you how: -Import the Sentry Deno SDK directly from the npm registry, before importing any other modules: +Import the Sentry Deno SDK directly from the npm registry, before importing any other modules. The first line registers the hook that instruments your database drivers, message queues, AI libraries and web frameworks. It only works as the first import of your entry file: ```javascript {filename: main.ts} +import "___SDK_PACKAGE___/import"; import * as Sentry from "___SDK_PACKAGE___"; // your other imports ``` @@ -47,6 +48,28 @@ import * as Sentry from "___SDK_PACKAGE___"; + + + + +The hook reads your dependencies from a local `node_modules` directory, not from Deno's global npm cache. Set `nodeModulesDir` in your `deno.json`: + + + + +```json {filename: deno.json} +{ + "imports": { + "@sentry/deno": "npm:@sentry/deno" + }, + "nodeModulesDir": "auto" +} +``` + + + + + ## Configure ### Initialize the Sentry SDK @@ -61,6 +84,7 @@ Initialize Sentry as early as possible in your app: ```javascript {filename: main.ts} +import "___SDK_PACKAGE___/import"; import * as Sentry from "___SDK_PACKAGE___"; // your other imports @@ -83,43 +107,42 @@ Sentry.init({ -### Enable Network Access +### Grant Permissions -To make sure the SDK can send events, enable network access for your Sentry ingestion domain: +Deno blocks access to the network, the file system and system information until you grant it. Start your app with all four permissions so that the SDK can send complete events. Add the other hosts your app talks to, separated by commas: ```bash -deno run --allow-net=___ORG_INGEST_DOMAIN___ index.ts +deno run \ + --allow-net=___ORG_INGEST_DOMAIN___ \ + --allow-env \ + --allow-read=. \ + --allow-sys=hostname,osRelease \ + main.ts ``` -### Allow Access to Source Files + - - - - -Grant read access to your source files so that the SDK can include your source code in stack traces: - - - +| Flag | What it gives you | +| -------------------------------- | -------------------------------------------------------------------------------------------- | +| `--allow-net=` | Delivery of events to Sentry. If a host is missing, Deno names it in the error. | +| `--allow-env` | The import hook. Without it, your app stops at start with `NotCapable: Requires env access`. | +| `--allow-read=.` | Source code in stack traces, and `app:///` paths instead of absolute paths. | +| `--allow-sys=hostname,osRelease` | The server name and the operating system version on events. | -```bash -deno run --allow-read=./src index.ts -``` +If you omit `--allow-read` or `--allow-sys`, the SDK sends events without that data and prints no warning. - - - + ### Add Readable Stack Traces With Source Maps (Optional) diff --git a/platform-includes/crons/setup/javascript.deno.mdx b/platform-includes/crons/setup/javascript.deno.mdx index 27ea5ba8dc7c1..d6073a862ceb3 100644 --- a/platform-includes/crons/setup/javascript.deno.mdx +++ b/platform-includes/crons/setup/javascript.deno.mdx @@ -1,9 +1,25 @@ -## Automatic Check-Ins (Recommended) +## Job Monitoring + + + +## Check-Ins + + + +## Automatic Check-Ins With `Deno.cron` + + + +The `DenoCron` integration does not work on Deno 2.9.0 and later. On these versions `Deno.cron` is a read-only property, so `Sentry.init` stops with `TypeError: Cannot set property cron of # which has only a getter` and your app does not start. Use `Sentry.withMonitor` or `Sentry.captureCheckIn` instead. -_requires SDK version 7.88.0 or higher_ + + +_requires SDK version 7.88.0 or higher, and Deno 2.8.3 or earlier_ Use the `DenoCron` integration to monitor your [`Deno.cron`](https://deno.com/blog/cron) calls and get notified when a schedule job is missed (or doesn't start when expected), if it fails due to a problem in the runtime (such as an error), or if it fails by exceeding its maximum runtime. +The integration is not part of the default set, so you must add it to `integrations` yourself: + ```TypeScript import * as Sentry from "___SDK_PACKAGE___"; @@ -13,14 +29,6 @@ Sentry.init({ }); ``` -## Job Monitoring - - - -## Check-Ins - - - ## Upserting Cron Monitors From e1bfa63f365b967dbe1a31739ade29b95f6aa3cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 19:45:56 +0300 Subject: [PATCH 36/48] docs(js): Remove the lightweight mode page (#19516) ## DESCRIBE YOUR PR closes SDK-1352 v11 has no lightweight mode. `@sentry/node-core` was merged back into `@sentry/node`, so `@sentry/node-core/light` no longer exists and the whole page described a setup that cannot be followed. The OTLP half of that page survives in a different form. The integration moved to the main export of every server SDK and was renamed to `openTelemetryIntegration()`, because it sends nothing over OTLP. Give it its own integration page covering what it does, the exporter wiring through `getOtlpTracesEndpoint()`, and the `enableOpenTelemetrySetup` caveat for `@sentry/nextjs` and `@sentry/sveltekit`. The removed `setupOtlpTracesExporter` and `collectorUrl` options are not carried over: you configure the exporter yourself now. - Drop the lightweight entry from the installation methods page. - Point the "simpler way to bridge your existing setup" line on the custom OpenTelemetry setup page at the new integration. - Point the Node.js card on the OTLP concepts page there too. - Redirect `/install/lightweight/` to the new page for the seven guides that served it. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Claude Opus 5 --- docs/concepts/otlp/sentry-with-otel.mdx | 2 +- .../javascript/common/install/lightweight.mdx | 211 ------------------ .../opentelemetry/custom-setup__v10.x.mdx | 8 - redirects.js | 35 +++ 4 files changed, 36 insertions(+), 220 deletions(-) delete mode 100644 docs/platforms/javascript/common/install/lightweight.mdx diff --git a/docs/concepts/otlp/sentry-with-otel.mdx b/docs/concepts/otlp/sentry-with-otel.mdx index 7553d9655aeb2..4e07fd25d68fb 100644 --- a/docs/concepts/otlp/sentry-with-otel.mdx +++ b/docs/concepts/otlp/sentry-with-otel.mdx @@ -87,7 +87,7 @@ If you're running both a Sentry SDK and OTel instrumentation in the same backend - - - Lightweight mode is experimental and may have breaking changes in minor or - patch releases. - - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -If you don't need automatic spans/transactions, you can use `@sentry/node-core/light` which doesn't require OpenTelemetry dependencies. This mode is ideal when: - -- You only need error tracking, logs, or metrics without tracing data (no automatic span creation) -- You want to minimize bundle size and runtime overhead -- You don't need spans emitted by OpenTelemetry instrumentation - -You still get error tracking, logs, metrics, breadcrumbs, context/user data, local variables capture, distributed tracing (via `sentry-trace` and `baggage` headers), and automatic request isolation (Node.js 22+). - -If needed, you can still manually create spans by using Sentry's custom instrumentation APIs like `startSpan`. - -If you already have your own OpenTelemetry setup, you can also use the [OTLP integration](#using-with-opentelemetry-otlp) to link Sentry errors to your OTel traces and export spans to Sentry. - -## Prerequisites - -- **Node.js 22.12.0+** is recommended for full functionality (automatic request isolation) -- Lower Node.js versions work but with limited capabilities (see [Request Isolation](#request-isolation) below) - -## Step 1: Install - -```bash {tabTitle:npm} -npm install @sentry/node-core --save -``` - -```bash {tabTitle:yarn} -yarn add @sentry/node-core -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/node-core -``` - -## Step 2: Configure - -Import from `@sentry/node-core/light` and call `Sentry.init()` as early as possible in your application lifecycle: - -```javascript {tabTitle:ESM} -import * as Sentry from "@sentry/node-core/light"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", -}); - -// Now create your HTTP server or framework app -``` - -```javascript {tabTitle:CJS} -const Sentry = require("@sentry/node-core/light"); - -Sentry.init({ - dsn: "___PUBLIC_DSN___", -}); - -// Now create your HTTP server or framework app -``` - -## Step 3: Verify - -To verify that Sentry is working, capture a test error: - -```javascript -Sentry.captureException(new Error("Sentry lightweight mode test")); -``` - -After running your application, you should see this error appear in your [Sentry dashboard](https://sentry.io). - -## Request Isolation - -Request isolation ensures that errors, breadcrumbs, and context are correctly scoped to individual requests. - -### Node.js 22.12.0+ - -Request isolation works automatically. No additional setup is needed — just make sure `Sentry.init()` is called before you create your HTTP server. - -### Node.js < 22 - -You need to manually wrap your request handler with `Sentry.withIsolationScope()`: - -```javascript -import * as Sentry from "@sentry/node-core/light"; -import http from "http"; - -const server = http.createServer((req, res) => { - Sentry.withIsolationScope(() => { - // Your request handling code - Sentry.setUser({ id: "user-id" }); - res.end("OK"); - }); -}); -``` - - - When using manual isolation on Node.js < 22, distributed tracing will not - work correctly. - - -## Conversation IDs - -To group AI spans in [Conversations](/product/agents/conversations/), add -`conversationIdIntegration` and call `setConversationId`. Neither is included in -lightweight mode by default: - -```javascript -import * as Sentry from "@sentry/node-core/light"; -import { conversationIdIntegration, setConversationId } from "@sentry/core"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - integrations: [ - ...Sentry.getDefaultIntegrations(), - conversationIdIntegration(), - ], -}); - -setConversationId("conv_abc123"); -``` - -## When to Use Lightweight Mode vs `@sentry/node` - -| | `@sentry/node` | `@sentry/node-core/light` | -| ------------------------------- | ------------------- | ---------------------------------------------- | -| **Error tracking** | Yes | Yes | -| **Logs and metrics** | Yes | Yes | -| **Automatic spans** | Yes | No | -| **OpenTelemetry auto-included** | Yes | No | -| **Dependency footprint** | Larger | Minimal | -| **Best for** | Full observability | No auto-instrumentation, manual tracing setup | - -If you need automatic spans for HTTP requests, database queries, and other operations, use `@sentry/node` (the default). If you don't need automatically created spans and want minimal dependencies, use lightweight mode. - -## Using with OpenTelemetry (OTLP) - - - -If you already have your own OpenTelemetry setup and want to bridge it with Sentry, you can use the `otlpIntegration` from `@sentry/node-core/light/otlp`. This integration: - -- Links Sentry errors and logs to the active OpenTelemetry trace context -- Exports OpenTelemetry spans to Sentry via [OTLP](/concepts/otlp/) - -### Install OpenTelemetry Dependencies - -In addition to `@sentry/node-core`, install the OpenTelemetry packages you need: - -```bash {tabTitle:npm} -npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http -``` - -```bash {tabTitle:yarn} -yarn add @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http -``` - -```bash {tabTitle:pnpm} -pnpm add @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http -``` - -### Configure - -Set up your OpenTelemetry `TracerProvider` first, then initialize Sentry with the `otlpIntegration`: - -```javascript -import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; -import * as Sentry from "@sentry/node-core/light"; -import { otlpIntegration } from "@sentry/node-core/light/otlp"; - -// Set up your OpenTelemetry TracerProvider as usual -const provider = new NodeTracerProvider(); -provider.register(); - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - integrations: [otlpIntegration()], -}); -``` - -The integration automatically derives the OTLP endpoint from your DSN. To send traces to your own collector instead, pass a `collectorUrl`: - -```javascript -otlpIntegration({ - collectorUrl: "https://my-collector.example.com/v1/traces", -}); -``` - -### Options - -| Option | Type | Default | Description | -|---|---|---|---| -| `setupOtlpTracesExporter` | `boolean` | `true` | Automatically configure an exporter to send OTLP traces to the right project from the DSN or `collectorUrl`. Set to `false` to set up the `TracerProvider` manually. | -| `collectorUrl` | `string` | `undefined` | URL of your own OpenTelemetry collector. When set, traces are sent here instead of the Sentry OTLP endpoint derived from the DSN. | diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx index 0499cec6813aa..4e30578e18196 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx @@ -39,14 +39,6 @@ If you are looking to simply add individual OpenTelemetry instrumentation to you - - - -If you don't need the full `@sentry/node` SDK and want a simpler way to bridge your existing OpenTelemetry setup with Sentry, consider using lightweight mode with the OTLP integration instead. It requires significantly less manual wiring. - - - - diff --git a/redirects.js b/redirects.js index 7fe89bbd4ca15..1722ca1dd0f7f 100644 --- a/redirects.js +++ b/redirects.js @@ -981,6 +981,41 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/aws-lambda/cjs-npm__v9.x/', destination: '/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x/', }, + { + source: '/platforms/javascript/guides/node/install/lightweight/', + destination: + '/platforms/javascript/guides/node/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/connect/install/lightweight/', + destination: + '/platforms/javascript/guides/connect/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/express/install/lightweight/', + destination: + '/platforms/javascript/guides/express/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/fastify/install/lightweight/', + destination: + '/platforms/javascript/guides/fastify/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/hapi/install/lightweight/', + destination: + '/platforms/javascript/guides/hapi/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/hono/install/lightweight/', + destination: + '/platforms/javascript/guides/hono/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/koa/install/lightweight/', + destination: + '/platforms/javascript/guides/koa/configuration/integrations/opentelemetry/', + }, { source: '/platforms/javascript/guides/react-router/features/instrumentation-api/', destination: '/platforms/javascript/guides/react-router/manual-setup/', From 1e4eeb76ebf225680967292be4c0bb9e76bb046a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Tue, 22 Sep 2026 19:47:34 +0300 Subject: [PATCH 37/48] docs(aws-lambda): Add a versioned Lambda Layer page for v10 (#19468) ## DESCRIBE YOUR PR > **IMPORTANT:** Before we merge we have to rebase and check if v11 is really rendered here in the "SDK version": http://localhost:3000/platforms/javascript/guides/aws-lambda/install/layer/ (that has to be done AFTER the lambda layer got released) closes SDK-1469 The Lambda Layer page renders its ARN from the release registry through ``. That bare canonical tracks the current major, so once the v11 layer publishes the page will follow it and readers on v10 lose their instructions. Pin a copy at `aws-layer:node:v10`, matching the existing `layer__v7.x`, `layer__v8.x` and `layer__v9.x` pages, so the switch to v11 costs nothing on release day. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5 --- .../aws-lambda/install/layer__v10.x.mdx | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx diff --git a/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx b/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx new file mode 100644 index 0000000000000..4dcd7caf6ecc5 --- /dev/null +++ b/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx @@ -0,0 +1,118 @@ +--- +title: Lambda Layer +description: >- + Learn how to add the Sentry Node Lambda Layer to use Sentry in your Lambda + functions +sidebar_order: 1 +og_image: /og-images/platforms-javascript-guides-aws-lambda-install-layer__v10.x.png +--- + +The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) instead of installing `@sentry/aws-serverless` with a package manager manually. +If you follow this guide, you don't have to worry about deploying Sentry dependencies alongside your function code. + +## Prerequisites + +Before you begin, make sure you have the following: + +- You have a Lambda function deployed in AWS. +- You know the AWS region that your function is deployed to. + +## 1. Add the Sentry Lambda Layer + +Add the Sentry Layer by navigating to your Lambda function. Select **Layers**, then **Add a Layer**. + +![](./img/lambda_view.png) + +**Specify an ARN** tab as illustrated: + +![](./img/add_layer.png) + +Choose the region and SDK version, then copy the provided ARN into the input. + + + +
+ +The Sentry Lambda Layer also bundles a Sentry Lambda extension that automatically handles event delivery. To opt out, see [`useLayerExtension`](/platforms/javascript/guides/aws-lambda/configuration/options/#useLayerExtension) in the configuration options. + +## 2. Setup Options + +### Option A: Automatic Setup (recommended) + +In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). + +Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. + + + +Set the following environment variables in your Lambda function configuration: + +```bash +NODE_OPTIONS="--import @sentry/aws-serverless/awslambda-auto" +SENTRY_DSN="___PUBLIC_DSN___" +# ___PRODUCT_OPTION_START___ performance +SENTRY_TRACES_SAMPLE_RATE="1.0" +# ___PRODUCT_OPTION_END___ performance +``` + +To set environment variables, navigate to your Lambda function, select **Configuration**, then **Environment variables**: + +![](./img/env_vars.png) + +### Option B: Manual Setup + +To further customize the SDK setup, you can also manually initialize the SDK in your lambda function. The benefit of this installation method is that you can fully customize your Sentry SDK setup in a `Sentry.init` call. + +Note that you don't have to actually install an NPM package for this to work, as the package is already included in the Lambda Layer. + +Create a new file, for example `instrument.js` to initialize the SDK: + +```javascript {filename:instrument.js} {tabTitle:CommonJS} +const Sentry = require("@sentry/aws-serverless"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // ___PRODUCT_OPTION_START___ performance + + // Add Tracing by setting tracesSampleRate and adding integration + // Set tracesSampleRate to 1.0 to capture 100% of transactions + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance +}); +``` + +```javascript {filename:instrument.mjs} {tabTitle:ESM} +import * as Sentry from "@sentry/aws-serverless"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // ___PRODUCT_OPTION_START___ performance + + // Add Tracing by setting tracesSampleRate and adding integration + // Set tracesSampleRate to 1.0 to capture 100% of transactions + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance +}); +``` + +##### Load the SDK + +To load the SDK before your function starts, you need to preload the `instrument.js` by setting the `NODE_OPTIONS` environment variable: + +```bash +NODE_OPTIONS="--import ./instrument.js" +``` + +That's it — make sure to re-deploy your function and you're all set! + +## 3. Control the Data You Send to Sentry (Optional) + + From a2d9df583f04fe866a02a4de8bfbf63d56665835 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Wed, 23 Sep 2026 07:49:15 +0300 Subject: [PATCH 38/48] docs(js): Remove the Connect guide and redirect it to Node (#19371) # IMPORTANT When we merge this we redirect `/connect` to `/node` with a permanent redirect. That means if in the future we'll readd `/connect` we have to choose another name because connect has a permanent redirect. Everyone that has that in their browser cache has it in there forever. ## DESCRIBE YOUR PR closes SDK-1498 v11 removed the Connect instrumentation, so `@sentry/node` exports neither `setupConnectErrorHandler` nor `connectIntegration`, and every app the guide printed crashed with `TypeError: Sentry.setupConnectErrorHandler is not a function` before it listened. Nothing Connect specific is left to document. A Connect app is still instrumented by the generic Node HTTP instrumentation, so the Node guide covers it, and the guide now redirects there. - Delete the Connect guide, the Connect integration page and the eleven Connect only platform includes. - Drop `javascript.connect` from the frontmatter and `PlatformSection` lists of 117 pages, and from the Logs and Metrics platform pickers. - Drop Connect from the request handler row of the span op table, in the migration page and in its include. - Drop `connect` from the `frameworks` list of ten v11 migration items, which `scripts/validate-migration-items.mjs` validates against the guide directory. - Point the React Native `RequestData` link at the Node guide. - Redirect `/platforms/javascript/guides/connect/` and everything under it to the Node guide. The v8 migration pages keep their `connectIntegration` mentions, since they record what v8 shipped. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Claude Opus 5 --- .../javascript/common/agent-tracing/index.mdx | 2 - .../agent-tracing/manual-instrumentation.mdx | 1 - .../common/best-practices/index.mdx | 1 - .../common/best-practices/micro-frontends.mdx | 1 - .../multiple-sentry-instances.mdx | 1 - .../common/best-practices/offline-caching.mdx | 1 - .../best-practices/shared-environments.mdx | 1 - .../common/configuration/async-context.mdx | 1 - .../common/configuration/event-loop-block.mdx | 1 - .../configuration/integrations/amqplib.mdx | 1 - .../common/configuration/integrations/anr.mdx | 1 - .../configuration/integrations/bfcache.mdx | 1 - .../integrations/childProcess.mdx | 1 - .../configuration/integrations/connect.mdx | 32 ---- .../configuration/integrations/console.mdx | 1 - .../configuration/integrations/dataloader.mdx | 1 - .../integrations/event-loop-block.mdx | 1 - .../integrations/fetchstreamperformance.mdx | 1 - .../common/configuration/integrations/fs.mdx | 1 - .../integrations/genericpool.mdx | 1 - .../configuration/integrations/graphql.mdx | 1 - .../configuration/integrations/http.mdx | 1 - .../integrations/interactions.mdx | 1 - .../configuration/integrations/kafka.mdx | 1 - .../configuration/integrations/knex.mdx | 1 - .../integrations/localvariables.mdx | 1 - .../integrations/lrumemoizer.mdx | 1 - .../configuration/integrations/modules.mdx | 1 - .../configuration/integrations/mongo.mdx | 1 - .../configuration/integrations/mongoose.mdx | 1 - .../configuration/integrations/mysql.mdx | 1 - .../configuration/integrations/mysql2.mdx | 1 - .../integrations/nodecontext.mdx | 1 - .../configuration/integrations/nodefetch.mdx | 1 - .../integrations/nodeprofiling.mdx | 1 - .../integrations/noderuntimemetrics.mdx | 1 - .../integrations/onuncaughtexception.mdx | 1 - .../integrations/opentelemetry.mdx | 1 - .../configuration/integrations/pino.mdx | 1 - .../configuration/integrations/postgres.mdx | 1 - .../configuration/integrations/prisma.mdx | 1 - .../integrations/prisma__v8.x.mdx | 1 - .../configuration/integrations/redis.mdx | 1 - .../integrations/requestdata.mdx | 1 - .../configuration/integrations/supabase.mdx | 1 - .../configuration/integrations/tedious.mdx | 1 - .../configuration/integrations/trpc.mdx | 1 - .../integrations/unhandledrejection.mdx | 1 - .../configuration/integrations/usertiming.mdx | 1 - .../configuration/integrations/webvitals.mdx | 1 - .../common/configuration/options.mdx | 2 +- .../common/configuration/transports.mdx | 1 - .../common/configuration/tree-shaking.mdx | 1 - .../javascript/common/crons/index.mdx | 5 +- .../common/crons/troubleshooting.mdx | 1 - .../data-management/data-collected/index.mdx | 2 +- .../request-isolation/index.mdx | 1 - .../javascript/common/install/commonjs.mdx | 1 - .../common/install/esm-without-import.mdx | 1 - .../javascript/common/install/esm.mdx | 1 - .../javascript/common/install/esm__v8.x.mdx | 1 - .../common/install/late-initialization.mdx | 1 - .../javascript/common/install/loader.mdx | 1 - .../javascript/common/install/npm.mdx | 1 - .../javascript/common/logs/index.mdx | 4 +- .../common/mcp-monitoring/index.mdx | 1 - .../javascript/common/metrics/index.mdx | 2 +- .../common/migration/v10-to-v11/index.mdx | 2 +- .../migration/v7-to-v8/v8-opentelemetry.mdx | 1 - .../common/opentelemetry/custom-setup.mdx | 1 - .../opentelemetry/custom-setup__v10.x.mdx | 1 - .../javascript/common/opentelemetry/index.mdx | 1 - .../common/opentelemetry/index__v10.x.mdx | 1 - .../using-opentelemetry-apis.mdx | 1 - .../using-opentelemetry-apis__v10.x.mdx | 1 - .../sourcemaps/uploading/hosting-publicly.mdx | 1 - .../dealing-with-cors-issues/index.mdx | 1 - .../javascript/common/tracing/index.mdx | 4 +- .../tracing/instrumentation/caches-module.mdx | 1 - .../tracing/instrumentation/queues-module.mdx | 1 - .../troubleshooting/supported-browsers.mdx | 1 - .../user-feedback/configuration/index.mdx | 2 +- .../configuration/index__v7.x.mdx | 2 +- .../javascript/common/user-feedback/index.mdx | 2 +- .../integrations/contextlines.mdx | 20 --- .../javascript/guides/connect/index.mdx | 11 -- .../automatic-instrumentation.mdx | 6 - .../enriching-events/identify-user/index.mdx | 2 +- docs/product/logs/getting-started/index.mdx | 6 - .../product/metrics/getting-started/index.mdx | 6 - ...quick-start-verify-metrics-splitlayout.mdx | 2 +- .../child-process-worker-split.mdx | 1 - .../javascript-v11/express-error-handler.mdx | 1 - .../javascript-v11/fastify-error-handler.mdx | 1 - .../hono-integration-removed.mdx | 1 - .../http-integration-options.mdx | 1 - .../koa-hapi-error-handlers.mdx | 1 - .../node-loader-entry-points.mdx | 1 - .../javascript-v11/node-removed-apis.mdx | 1 - .../javascript-v11/require-to-import.mdx | 1 - .../javascript-v11/span-op-changes.mdx | 16 +- .../unhandled-rejection-warning.mdx | 1 - includes/quick-start-features-expandable.mdx | 2 +- .../quick-start-locate-data-expandable.mdx | 2 +- middleware.ts | 4 +- .../featureflags/javascript.connect.mdx | 16 -- .../integrations/javascript.connect.mdx | 55 ------ .../crons/requirements/javascript.connect.mdx | 2 - .../javascript.connect.mdx | 1 - .../min-version/javascript.connect.mdx | 1 - .../javascript.connect.mdx | 29 --- .../javascript.connect.mdx | 33 ---- .../javascript.connect.mdx | 62 ------- .../important-changes/javascript.connect.mdx | 166 ------------------ .../javascript.connect.mdx | 14 -- .../intro/javascript.connect.mdx | 1 - .../legacy-troubleshooting/javascript.mdx | 2 +- .../legacy-uploading-methods/javascript.mdx | 2 +- .../overview/javascript.capacitor.mdx | 2 +- .../sourcemaps/overview/javascript.mdx | 2 +- .../sourcemaps/troubleshooting/javascript.mdx | 1 - .../sourcemaps/upload/primer/javascript.mdx | 4 +- redirects.js | 13 +- 123 files changed, 41 insertions(+), 585 deletions(-) delete mode 100644 docs/platforms/javascript/common/configuration/integrations/connect.mdx delete mode 100644 docs/platforms/javascript/guides/connect/configuration/integrations/contextlines.mdx delete mode 100644 docs/platforms/javascript/guides/connect/index.mdx delete mode 100644 docs/platforms/javascript/guides/connect/tracing/instrumentation/automatic-instrumentation.mdx delete mode 100644 platform-includes/configuration/featureflags/javascript.connect.mdx delete mode 100644 platform-includes/configuration/integrations/javascript.connect.mdx delete mode 100644 platform-includes/crons/requirements/javascript.connect.mdx delete mode 100644 platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx delete mode 100644 platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx delete mode 100644 platform-includes/getting-started-add-top-level-import/javascript.connect.mdx delete mode 100644 platform-includes/getting-started-use/javascript.connect.mdx delete mode 100644 platform-includes/getting-started-verify/javascript.connect.mdx delete mode 100644 platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx delete mode 100644 platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx delete mode 100644 platform-includes/migration/javascript-v8/intro/javascript.connect.mdx diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index 3adf5c6085e7c..f783c167a6d34 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -12,7 +12,6 @@ supported: - javascript.azure-functions - javascript.bun - javascript.cloudflare - - javascript.connect - javascript.deno - javascript.effect - javascript.elysia @@ -119,7 +118,6 @@ As of SDK version `11.0.0`, Sentry auto-instruments the most popular AI SDKs and "javascript.astro", "javascript.aws-lambda", "javascript.azure-functions", - "javascript.connect", "javascript.express", "javascript.fastify", "javascript.gcp-functions", diff --git a/docs/platforms/javascript/common/agent-tracing/manual-instrumentation.mdx b/docs/platforms/javascript/common/agent-tracing/manual-instrumentation.mdx index a4846d665aea3..2d3c2d08aab47 100644 --- a/docs/platforms/javascript/common/agent-tracing/manual-instrumentation.mdx +++ b/docs/platforms/javascript/common/agent-tracing/manual-instrumentation.mdx @@ -10,7 +10,6 @@ supported: - javascript.azure-functions - javascript.bun - javascript.cloudflare - - javascript.connect - javascript.deno - javascript.effect - javascript.elysia diff --git a/docs/platforms/javascript/common/best-practices/index.mdx b/docs/platforms/javascript/common/best-practices/index.mdx index 6fbf731a00c1d..53e4910a8c304 100644 --- a/docs/platforms/javascript/common/best-practices/index.mdx +++ b/docs/platforms/javascript/common/best-practices/index.mdx @@ -9,7 +9,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index 69fde67ba8326..d288edd44641d 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx b/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx index f8f01830c2263..4cde6099865e7 100644 --- a/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx +++ b/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/offline-caching.mdx b/docs/platforms/javascript/common/best-practices/offline-caching.mdx index 87f29ea9e809f..e27799bb0edbb 100644 --- a/docs/platforms/javascript/common/best-practices/offline-caching.mdx +++ b/docs/platforms/javascript/common/best-practices/offline-caching.mdx @@ -12,7 +12,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/shared-environments.mdx b/docs/platforms/javascript/common/best-practices/shared-environments.mdx index 82ae8d0786ce9..bb10d6d4fa03b 100644 --- a/docs/platforms/javascript/common/best-practices/shared-environments.mdx +++ b/docs/platforms/javascript/common/best-practices/shared-environments.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/async-context.mdx b/docs/platforms/javascript/common/configuration/async-context.mdx index ecd7a100c3c38..6ac68d46b8ceb 100644 --- a/docs/platforms/javascript/common/configuration/async-context.mdx +++ b/docs/platforms/javascript/common/configuration/async-context.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/event-loop-block.mdx b/docs/platforms/javascript/common/configuration/event-loop-block.mdx index 0f29e92c06620..c5f7cd0440179 100644 --- a/docs/platforms/javascript/common/configuration/event-loop-block.mdx +++ b/docs/platforms/javascript/common/configuration/event-loop-block.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx b/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx index 2c64c54c7e15a..dc74de0e324dd 100644 --- a/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/anr.mdx b/docs/platforms/javascript/common/configuration/integrations/anr.mdx index 80ff2fc2af6d5..4805aaa9504dd 100644 --- a/docs/platforms/javascript/common/configuration/integrations/anr.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/anr.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx b/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx index 8450d9576a5dd..028209e809a96 100644 --- a/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx b/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx index 61e0ef1e52b4f..fc9695bd3fe1c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/connect.mdx b/docs/platforms/javascript/common/configuration/integrations/connect.mdx deleted file mode 100644 index 063349091b6ad..0000000000000 --- a/docs/platforms/javascript/common/configuration/integrations/connect.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Connect -description: "Adds performance instrumentation for Connect. (default)" -supported: - - javascript.node - - javascript.connect - - javascript.hapi ---- - -For more information on setting up Sentry Connect support, see the [Connect Sentry documentation](/platforms/javascript/guides/connect/). - - - -This integration only works in the Node.js and Bun runtimes. - - - -_Import name: `Sentry.connectIntegration`_ - -This integration is enabled by default when performance monitoring is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -The `connectIntegration` adds instrumentation for the Hapi framework to capture spans using [`@opentelemetry/instrumentation-connect`](https://www.npmjs.com/package/@opentelemetry/instrumentation-connect). - -```JavaScript -Sentry.init({ - integrations: [Sentry.connectIntegration()], -}); -``` - -## Supported Versions - -- `connect`: `^3.0.0` diff --git a/docs/platforms/javascript/common/configuration/integrations/console.mdx b/docs/platforms/javascript/common/configuration/integrations/console.mdx index 677011f4b8eb2..ba89762666b4b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/console.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/console.mdx @@ -17,7 +17,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx b/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx index 1dc82214c26dd..4b94250dfb48b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx b/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx index c13728f4ddd06..e048b45bca42c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx b/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx index 3e765883aaa79..cae1dbf0ca6b6 100644 --- a/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/fs.mdx b/docs/platforms/javascript/common/configuration/integrations/fs.mdx index 50f2aeac1f41d..14f143e58904c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/fs.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/fs.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx b/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx index 3b9bd2f879aae..f44627c0438e9 100644 --- a/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/graphql.mdx b/docs/platforms/javascript/common/configuration/integrations/graphql.mdx index 3a4a61a2b0e83..8c4bb846575c0 100644 --- a/docs/platforms/javascript/common/configuration/integrations/graphql.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/graphql.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/http.mdx b/docs/platforms/javascript/common/configuration/integrations/http.mdx index eb9d4baffd2e6..5c6fde57a8957 100644 --- a/docs/platforms/javascript/common/configuration/integrations/http.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/http.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/interactions.mdx b/docs/platforms/javascript/common/configuration/integrations/interactions.mdx index 24fe7b2269a36..9fcc5a9ce4544 100644 --- a/docs/platforms/javascript/common/configuration/integrations/interactions.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/interactions.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/kafka.mdx b/docs/platforms/javascript/common/configuration/integrations/kafka.mdx index aa048fc9c1a25..590184741ae4e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/kafka.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/kafka.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/knex.mdx b/docs/platforms/javascript/common/configuration/integrations/knex.mdx index 0cdb4eae51065..2febe5759e235 100644 --- a/docs/platforms/javascript/common/configuration/integrations/knex.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/knex.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx b/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx index ff7f83c571988..99c27546e3af7 100644 --- a/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx b/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx index bc87ce11fc413..a801949e4b7a4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/modules.mdx b/docs/platforms/javascript/common/configuration/integrations/modules.mdx index f79fe7574066e..b2631cfd864e5 100644 --- a/docs/platforms/javascript/common/configuration/integrations/modules.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/modules.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mongo.mdx b/docs/platforms/javascript/common/configuration/integrations/mongo.mdx index 4f5b313332c7b..a1bc795ce82e4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mongo.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mongo.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx b/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx index 8f459e2fbebe4..dead732266b41 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mysql.mdx b/docs/platforms/javascript/common/configuration/integrations/mysql.mdx index cf22d747a0c6d..0bc57a91339a4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mysql.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mysql.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx b/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx index 4484cec1d5ee0..53423805a9ca4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx b/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx index 220f09a3aabf7..8493b9219093b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx b/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx index 1314528f41519..4044765c25c7e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx b/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx index 8b1d4ab7b8b1e..7d96d68d36db4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx b/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx index bc90666643df9..e0a2edd1a253a 100644 --- a/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/onuncaughtexception.mdx b/docs/platforms/javascript/common/configuration/integrations/onuncaughtexception.mdx index 479fa2081d112..93971d40a00a7 100644 --- a/docs/platforms/javascript/common/configuration/integrations/onuncaughtexception.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/onuncaughtexception.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx b/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx index 5c38402902538..fd65c00bb5012 100644 --- a/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx @@ -8,7 +8,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/pino.mdx b/docs/platforms/javascript/common/configuration/integrations/pino.mdx index 2fc6e9da2a295..d5c02ef49140d 100644 --- a/docs/platforms/javascript/common/configuration/integrations/pino.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/pino.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/postgres.mdx b/docs/platforms/javascript/common/configuration/integrations/postgres.mdx index 9f6e47b0daedd..b6cef3a7e7a74 100644 --- a/docs/platforms/javascript/common/configuration/integrations/postgres.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/postgres.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/prisma.mdx b/docs/platforms/javascript/common/configuration/integrations/prisma.mdx index 2c4236eea6161..e7d6d411d11c0 100644 --- a/docs/platforms/javascript/common/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/prisma.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx b/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx index 0f300c55cbf0e..118be82e733c1 100644 --- a/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/redis.mdx b/docs/platforms/javascript/common/configuration/integrations/redis.mdx index 168b28a253474..b888ac2984891 100644 --- a/docs/platforms/javascript/common/configuration/integrations/redis.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/redis.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx b/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx index 85ab98339e6ae..d721b9efb4e8e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx @@ -9,7 +9,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/supabase.mdx b/docs/platforms/javascript/common/configuration/integrations/supabase.mdx index eb831a3382703..735e653adc952 100644 --- a/docs/platforms/javascript/common/configuration/integrations/supabase.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/supabase.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/tedious.mdx b/docs/platforms/javascript/common/configuration/integrations/tedious.mdx index d2b70c6fa8208..d755e4380b25b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/tedious.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/tedious.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/trpc.mdx b/docs/platforms/javascript/common/configuration/integrations/trpc.mdx index 5cfeaf8b22fff..d137a84f25e35 100644 --- a/docs/platforms/javascript/common/configuration/integrations/trpc.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/trpc.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/unhandledrejection.mdx b/docs/platforms/javascript/common/configuration/integrations/unhandledrejection.mdx index 07d9795ff2dbe..4f32756259861 100644 --- a/docs/platforms/javascript/common/configuration/integrations/unhandledrejection.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/unhandledrejection.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx b/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx index d1131ff300dc1..5461ea644b4c7 100644 --- a/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx b/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx index 6876e00145611..815577c35500e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 89f4f945a9374..947e5d50c415f 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -727,7 +727,7 @@ If set to `true`, the SDK adds the [W3C `traceparent` header](https://www.w3.org This header is attached in addition to the `sentry-trace` and `baggage` headers. Set this option to `true` if your backend services are instrumented with e.g. OpenTelemetry or other W3C Trace Context compatible libraries and you want to continue traces from the client. - + **Important:** Make sure that your backend services' CORS configuration allows the `traceparent` header. Otherwise, requests might be blocked. diff --git a/docs/platforms/javascript/common/configuration/transports.mdx b/docs/platforms/javascript/common/configuration/transports.mdx index 1a3ba82cc54a4..be8c17b03ceb6 100644 --- a/docs/platforms/javascript/common/configuration/transports.mdx +++ b/docs/platforms/javascript/common/configuration/transports.mdx @@ -12,7 +12,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/tree-shaking.mdx b/docs/platforms/javascript/common/configuration/tree-shaking.mdx index c9ef7dde31bf3..24040c3dc27dd 100644 --- a/docs/platforms/javascript/common/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/common/configuration/tree-shaking.mdx @@ -269,7 +269,6 @@ This means that the `ClientOptions.integrations` property is the final array of + ## Requirements @@ -41,7 +40,7 @@ Once implemented, it'll allow you to get alerts and metrics to help you solve er - + ## Requirements diff --git a/docs/platforms/javascript/common/crons/troubleshooting.mdx b/docs/platforms/javascript/common/crons/troubleshooting.mdx index 3d3822f44d4bf..bfed46e4d4108 100644 --- a/docs/platforms/javascript/common/crons/troubleshooting.mdx +++ b/docs/platforms/javascript/common/crons/troubleshooting.mdx @@ -16,7 +16,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index 33fba347a6ffb..99d6ab7d4590c 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -153,7 +153,7 @@ By default, the Sentry SDK sends information about the device and runtime to Sen - + ## Session Replay diff --git a/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx index f03d771f8d06f..b0502148775f2 100644 --- a/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx @@ -6,7 +6,6 @@ supported: - javascript.node - javascript.eve - javascript.mastra - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/commonjs.mdx b/docs/platforms/javascript/common/install/commonjs.mdx index 978d93e2ea363..a5901ff9b8415 100644 --- a/docs/platforms/javascript/common/install/commonjs.mdx +++ b/docs/platforms/javascript/common/install/commonjs.mdx @@ -4,7 +4,6 @@ sidebar_order: 9 description: "Learn about running Sentry in an CJS application." supported: - javascript.node - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx index 1961f4821cfed..7b2e3946bbd0f 100644 --- a/docs/platforms/javascript/common/install/esm-without-import.mdx +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -4,7 +4,6 @@ sidebar_order: 11 description: "Learn about running Sentry in an ESM application, without the --import flag." supported: - javascript.node - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index e09572b1064ee..4aacd1bb57ee8 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -4,7 +4,6 @@ sidebar_order: 10 description: "Learn about running Sentry in an ESM application." supported: - javascript.node - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/esm__v8.x.mdx b/docs/platforms/javascript/common/install/esm__v8.x.mdx index fb850ab562d98..3796d110427da 100644 --- a/docs/platforms/javascript/common/install/esm__v8.x.mdx +++ b/docs/platforms/javascript/common/install/esm__v8.x.mdx @@ -4,7 +4,6 @@ sidebar_order: 10 description: "Learn about running Sentry in an ESM application." supported: - javascript.node - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/late-initialization.mdx b/docs/platforms/javascript/common/install/late-initialization.mdx index bea0c198f19bc..dec315fcc1eab 100644 --- a/docs/platforms/javascript/common/install/late-initialization.mdx +++ b/docs/platforms/javascript/common/install/late-initialization.mdx @@ -4,7 +4,6 @@ sidebar_order: 12 description: "Learn about running Sentry in an ESM or CJS application, in scenarios where you cannot run init early." supported: - javascript.node - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/loader.mdx b/docs/platforms/javascript/common/install/loader.mdx index 1f1609617f1a7..d22a7d614567e 100644 --- a/docs/platforms/javascript/common/install/loader.mdx +++ b/docs/platforms/javascript/common/install/loader.mdx @@ -27,7 +27,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.elysia - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/install/npm.mdx b/docs/platforms/javascript/common/install/npm.mdx index 02d5422d9c7f7..6005ae6afc6be 100644 --- a/docs/platforms/javascript/common/install/npm.mdx +++ b/docs/platforms/javascript/common/install/npm.mdx @@ -28,7 +28,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.elysia - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/logs/index.mdx b/docs/platforms/javascript/common/logs/index.mdx index f6ceea5a991c6..e73d8e8531cba 100644 --- a/docs/platforms/javascript/common/logs/index.mdx +++ b/docs/platforms/javascript/common/logs/index.mdx @@ -209,7 +209,7 @@ Sentry.init({ Everything in Sentry is linked by trace. When you're viewing a log, you can jump to the parent trace to see the full request context. When you're viewing a trace, you can see all logs emitted during that operation. This connection makes it easy to move between high-level performance data and detailed diagnostic logs. - **[Traces](/product/trace-explorer/)** — Logs emitted during an active span automatically include `sentry.trace.parent_span_id`. Click through from any log to see the full trace, or filter logs by trace ID to see everything that happened during a specific request. -- **[Session Replay](/product/session-replay/)** — Logs include `sentry.replay_id` when a replay is active. Jump from a log entry directly to the replay to see what the user was doing when the log was emitted. +- **[Session Replay](/product/session-replay/)** — Logs include `sentry.replay_id` when a replay is active. Jump from a log entry directly to the replay to see what the user was doing when the log was emitted. - **[Errors](/product/issues/)** — Logs capture the journey leading up to a failure. When an error occurs, your logs show what data was processed, which code paths executed, and what state the system was in — context that stack traces alone can't provide. ## Best Practices @@ -228,6 +228,6 @@ Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or di ## Related Features - Tracing — Logs are automatically linked to traces, so you can see logs in the context of the request or operation that produced them. -- Session Replay — Logs are automatically linked to replays, letting you jump from a log entry to see what the user was doing. +- Session Replay — Logs are automatically linked to replays, letting you jump from a log entry to see what the user was doing. - Error Monitoring — Use logs to add diagnostic context that helps you understand what led to an error. - Attributes — Set attributes once and have them automatically included on all your logs. diff --git a/docs/platforms/javascript/common/mcp-monitoring/index.mdx b/docs/platforms/javascript/common/mcp-monitoring/index.mdx index 749086994a169..b2e41af08a68d 100644 --- a/docs/platforms/javascript/common/mcp-monitoring/index.mdx +++ b/docs/platforms/javascript/common/mcp-monitoring/index.mdx @@ -8,7 +8,6 @@ supported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/metrics/index.mdx b/docs/platforms/javascript/common/metrics/index.mdx index 0e00cf933f9b0..bbbadb470aeb4 100644 --- a/docs/platforms/javascript/common/metrics/index.mdx +++ b/docs/platforms/javascript/common/metrics/index.mdx @@ -34,7 +34,7 @@ With [Sentry's Application Metrics](/product/metrics/), you can send counters, g ## Integrations - + - `elementTimingIntegration` diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index 2a52f57b544d3..461737355a25e 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -439,7 +439,7 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic | Area | Before | After | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| Request handlers (Express, Koa, Connect, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | +| Request handlers (Express, Koa, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | | Hono `app.request()` in-process dispatch | `hono.request` | `http.server` | | Web-server middleware | `middleware.express`, `middleware.koa`, `middleware.hono`, `middleware.elysia`, `middleware.nestjs`, `middleware.nuxt`, `middleware.nitro`, `middleware.tanstackstart`, `hook.fastify`, `http.server.middleware` (Next.js) | `middleware` | | Backend router layers | `router.express`, `router.koa`, `router.hapi` | `router` | diff --git a/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx b/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx index f2c096e76c4f3..2f5fad72272a7 100644 --- a/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx +++ b/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx @@ -9,7 +9,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index 67d971413573a..3e104a021c163 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -10,7 +10,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx index 4e30578e18196..772c05e4855cf 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx @@ -8,7 +8,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/index.mdx b/docs/platforms/javascript/common/opentelemetry/index.mdx index 9416efde7d57a..71ffbb03384e9 100644 --- a/docs/platforms/javascript/common/opentelemetry/index.mdx +++ b/docs/platforms/javascript/common/opentelemetry/index.mdx @@ -11,7 +11,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx index 57eb7542bc1b9..948294dfcaf6f 100644 --- a/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx +++ b/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx @@ -10,7 +10,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx index 0a1db82c1b4f7..cda9fd03bf032 100644 --- a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx +++ b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx @@ -10,7 +10,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx index d114441401a19..d5238d7e9590a 100644 --- a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx +++ b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx @@ -8,7 +8,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx b/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx index 47620afa80fdd..3a601b12587de 100644 --- a/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx +++ b/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx b/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx index 9a0469fb29ebb..c73be7a8d2063 100644 --- a/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx +++ b/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/index.mdx b/docs/platforms/javascript/common/tracing/index.mdx index 91064cd58bc00..4e9a5908067a1 100644 --- a/docs/platforms/javascript/common/tracing/index.mdx +++ b/docs/platforms/javascript/common/tracing/index.mdx @@ -95,7 +95,7 @@ You can also manually start spans to instrument specific parts of your code. Thi - Sending Span Metrics: Learn how to capture metrics on your spans - + ## Replay Linking @@ -133,7 +133,7 @@ Instead, neither `tracesSampleRate` nor `tracesSampler` should be defined in you ## Related Features -- Session Replay — Traces appear in the Replay timeline, showing performance data alongside the user's actions. +- Session Replay — Traces appear in the Replay timeline, showing performance data alongside the user's actions. - Logs — Logs emitted during a trace are automatically linked, giving you diagnostic context for each operation. ## Tracing Next Steps diff --git a/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx b/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx index 04cf8593c1dbd..562350449bb05 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx b/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx index 36c4f25dfea89..38e0c447b9e83 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx b/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx index 08b2661f71f5f..9e11f1868b6f4 100644 --- a/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx +++ b/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx @@ -9,7 +9,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx index 26359e0ac6796..6accb538b77bb 100644 --- a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx +++ b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx @@ -8,7 +8,7 @@ notSupported: - javascript.mastra --- - + ## User Feedback Widget diff --git a/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx b/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx index e696f17382cbe..9d0f276ef2091 100644 --- a/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx +++ b/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx @@ -17,7 +17,7 @@ In version 7 of our JavaScript SDK, User Feedback was released as a Beta integra - + ## User Feedback Widget diff --git a/docs/platforms/javascript/common/user-feedback/index.mdx b/docs/platforms/javascript/common/user-feedback/index.mdx index 55ce4afc68739..d3923369258d4 100644 --- a/docs/platforms/javascript/common/user-feedback/index.mdx +++ b/docs/platforms/javascript/common/user-feedback/index.mdx @@ -18,7 +18,7 @@ The User Feedback feature allows you to collect user feedback from anywhere insi feature. Lower versions may have limited functionality. - + ## User Feedback Widget diff --git a/docs/platforms/javascript/guides/connect/configuration/integrations/contextlines.mdx b/docs/platforms/javascript/guides/connect/configuration/integrations/contextlines.mdx deleted file mode 100644 index 7b3af58727490..0000000000000 --- a/docs/platforms/javascript/guides/connect/configuration/integrations/contextlines.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: ContextLines -description: "Adds source code to your stack frames. (default)" ---- - -_Import name: `Sentry.contextLinesIntegration`_ - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -This integration adds source code to your stack frames. It ensures that you can see the code that caused the error directly in the Sentry UI. - - - -## Options - -### `frameContextLines` - -_Type: `number`_ - -The number of lines to collect around each stack frame's line number. Defaults to 7. diff --git a/docs/platforms/javascript/guides/connect/index.mdx b/docs/platforms/javascript/guides/connect/index.mdx deleted file mode 100644 index 99fcbef7ffb95..0000000000000 --- a/docs/platforms/javascript/guides/connect/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Connect -description: "Learn how to manually set up Sentry in your Connect app and capture your first errors." -sdk: sentry.javascript.node -fallbackGuide: javascript.node -categories: - - server - - server-only ---- - - diff --git a/docs/platforms/javascript/guides/connect/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/guides/connect/tracing/instrumentation/automatic-instrumentation.mdx deleted file mode 100644 index 2f7c38261d7f1..0000000000000 --- a/docs/platforms/javascript/guides/connect/tracing/instrumentation/automatic-instrumentation.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Automatic Instrumentation -description: "Learn what transactions are captured after tracing is enabled in the Sentry Connect SDK." ---- - - diff --git a/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx b/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx index e76a7f3757d37..0443a344e3a66 100644 --- a/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx +++ b/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx @@ -22,7 +22,7 @@ An alternative, or addition, to the username. Sentry is aware of email addresses ### `ip_address` The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. -Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. This requires you to set the `include.ip` option to `true` in the [`RequestData`](/platforms/javascript/guides/connect/configuration/integrations/requestdata/) integration. +Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. This requires you to set the `include.ip` option to `true` in the [`RequestData`](/platforms/javascript/guides/node/configuration/integrations/requestdata/) integration. If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. diff --git a/docs/product/logs/getting-started/index.mdx b/docs/product/logs/getting-started/index.mdx index c1a6d6ab9795b..be078b92f6c2a 100644 --- a/docs/product/logs/getting-started/index.mdx +++ b/docs/product/logs/getting-started/index.mdx @@ -53,12 +53,6 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s url="/platforms/javascript/guides/cloudflare/logs/" skill="sentry-cloudflare-sdk" /> -- - -- - + In a Node.js runtime, you can use the [NodeRuntimeMetrics](/platforms/javascript/guides/node/configuration/integrations/noderuntimemetrics/) integration to automatically collect Node.js runtime health metrics. diff --git a/includes/migration/javascript-v11/child-process-worker-split.mdx b/includes/migration/javascript-v11/child-process-worker-split.mdx index cf7909a5d14a2..33cd9ce101ee9 100644 --- a/includes/migration/javascript-v11/child-process-worker-split.mdx +++ b/includes/migration/javascript-v11/child-process-worker-split.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/express-error-handler.mdx b/includes/migration/javascript-v11/express-error-handler.mdx index e94fc957c1823..6e2e4e9e9a85c 100644 --- a/includes/migration/javascript-v11/express-error-handler.mdx +++ b/includes/migration/javascript-v11/express-error-handler.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/fastify-error-handler.mdx b/includes/migration/javascript-v11/fastify-error-handler.mdx index d40238427f165..d549797964117 100644 --- a/includes/migration/javascript-v11/fastify-error-handler.mdx +++ b/includes/migration/javascript-v11/fastify-error-handler.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/hono-integration-removed.mdx b/includes/migration/javascript-v11/hono-integration-removed.mdx index 977035bd6e5fc..a13418fd78ed9 100644 --- a/includes/migration/javascript-v11/hono-integration-removed.mdx +++ b/includes/migration/javascript-v11/hono-integration-removed.mdx @@ -11,7 +11,6 @@ frameworks: azure-functions, bun, cloudflare, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/http-integration-options.mdx b/includes/migration/javascript-v11/http-integration-options.mdx index 1e0c130dc6627..d7a59260e07d9 100644 --- a/includes/migration/javascript-v11/http-integration-options.mdx +++ b/includes/migration/javascript-v11/http-integration-options.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx b/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx index ffcba16027333..5b773dbd569b1 100644 --- a/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx +++ b/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/node-loader-entry-points.mdx b/includes/migration/javascript-v11/node-loader-entry-points.mdx index 936dffaa3e7c4..cb2a6e0c8ec01 100644 --- a/includes/migration/javascript-v11/node-loader-entry-points.mdx +++ b/includes/migration/javascript-v11/node-loader-entry-points.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/node-removed-apis.mdx b/includes/migration/javascript-v11/node-removed-apis.mdx index c65e804a36d7e..e2b779bb94d57 100644 --- a/includes/migration/javascript-v11/node-removed-apis.mdx +++ b/includes/migration/javascript-v11/node-removed-apis.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/require-to-import.mdx b/includes/migration/javascript-v11/require-to-import.mdx index accc72bb4aec4..6867a78ae04a9 100644 --- a/includes/migration/javascript-v11/require-to-import.mdx +++ b/includes/migration/javascript-v11/require-to-import.mdx @@ -9,7 +9,6 @@ frameworks: astro, aws-lambda, azure-functions, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/span-op-changes.mdx b/includes/migration/javascript-v11/span-op-changes.mdx index 0e1fcd1747467..ccb3d73796b0d 100644 --- a/includes/migration/javascript-v11/span-op-changes.mdx +++ b/includes/migration/javascript-v11/span-op-changes.mdx @@ -17,14 +17,14 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic **Backend HTTP, handlers, middleware, and routers** -| Area | Before | After | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| Request handlers (Express, Koa, Connect, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | -| Hono `app.request()` in-process dispatch | `hono.request` | `http.server` | -| Web-server middleware | `middleware.express`, `middleware.koa`, `middleware.hono`, `middleware.elysia`, `middleware.nestjs`, `middleware.nuxt`, `middleware.nitro`, `middleware.tanstackstart`, `hook.fastify`, `http.server.middleware` (Next.js) | `middleware` | -| Backend router layers | `router.express`, `router.koa`, `router.hapi` | `router` | -| Hapi server extensions | `server.ext.hapi` | `middleware` | -| NestJS setup and lifecycle handlers | `app_creation.nestjs`, `request_context.nestjs`, `event.nestjs` | `function` | +| Area | Before | After | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| Request handlers (Express, Koa, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | +| Hono `app.request()` in-process dispatch | `hono.request` | `http.server` | +| Web-server middleware | `middleware.express`, `middleware.koa`, `middleware.hono`, `middleware.elysia`, `middleware.nestjs`, `middleware.nuxt`, `middleware.nitro`, `middleware.tanstackstart`, `hook.fastify`, `http.server.middleware` (Next.js) | `middleware` | +| Backend router layers | `router.express`, `router.koa`, `router.hapi` | `router` | +| Hapi server extensions | `server.ext.hapi` | `middleware` | +| NestJS setup and lifecycle handlers | `app_creation.nestjs`, `request_context.nestjs`, `event.nestjs` | `function` | **Framework functions** diff --git a/includes/migration/javascript-v11/unhandled-rejection-warning.mdx b/includes/migration/javascript-v11/unhandled-rejection-warning.mdx index fd58dc05c9a11..66bda3b963ce3 100644 --- a/includes/migration/javascript-v11/unhandled-rejection-warning.mdx +++ b/includes/migration/javascript-v11/unhandled-rejection-warning.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index 8ee5e2d2aef86..2ba4813cab311 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -27,7 +27,7 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; - + - + ('FeatureFlags'); -if (flagsIntegration) { - flagsIntegration.addFeatureFlag('test-flag', false); -} else { - // Something went wrong, check your DSN and/or integrations -} -Sentry.captureException(new Error('Something went wrong!')); -``` diff --git a/platform-includes/configuration/integrations/javascript.connect.mdx b/platform-includes/configuration/integrations/javascript.connect.mdx deleted file mode 100644 index 50e06fb7aea44..0000000000000 --- a/platform-includes/configuration/integrations/javascript.connect.mdx +++ /dev/null @@ -1,55 +0,0 @@ -### Integrations - -| | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | -| --------------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | -| [`amqplibIntegration`](./amqplib) | ✓ | | ✓ | | -| [`consoleIntegration`](./console) | ✓ | | | ✓ | -| [`connectIntegration`](./connect) | ✓ | | ✓ | | -| [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | -| [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | -| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | -| [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | -| [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | -| [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | -| [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | -| [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | -| [`modulesIntegration`](./modules) | ✓ | | | ✓ | -| [`mongoIntegration`](./mongo) | ✓ | | ✓ | | -| [`mongooseIntegration`](./mongoose) | ✓ | | ✓ | | -| [`mysqlIntegration`](./mysql) | ✓ | | ✓ | | -| [`mysql2Integration`](./mysql2) | ✓ | | ✓ | | -| [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | -| [`nativeNodeFetchIntegration`](./nodefetch) | ✓ | | ✓ | ✓ | -| [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | -| [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | -| [`postgresIntegration`](./postgres) | ✓ | | ✓ | | -| [`redisIntegration`](./redis) | ✓ | | ✓ | | -| [`requestDataIntegration`](./requestdata) | ✓ | | ✓ | | -| [`tediousIntegration`](./tedious) | ✓ | | ✓ | | -| [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | -| [`rewriteFramesIntegration`](./rewriteframes) | ✓ | ✓ | | | -| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](./openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | -| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | -| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | -| [`groqIntegration`](./groq) | ✓ | | ✓ | | -| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | -| [`anrIntegration`](./anr) | | ✓ | | | -| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | -| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | -| [`dataloaderIntegration`](./dataloader) | | | ✓ | | -| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | -| [`fsIntegration`](./fs) | | | ✓ | | -| [`knexIntegration`](./knex) | | | ✓ | | -| [`localVariablesIntegration`](./localvariables) | | ✓ | | | -| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | -| [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | -| [`prismaIntegration`](./prisma) | | | ✓ | | -| [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | -| [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/crons/requirements/javascript.connect.mdx b/platform-includes/crons/requirements/javascript.connect.mdx deleted file mode 100644 index ee5931db169fd..0000000000000 --- a/platform-includes/crons/requirements/javascript.connect.mdx +++ /dev/null @@ -1,2 +0,0 @@ -- Use our getting started guide to install and configure the Sentry SDK (version `7.51.1` or newer) for your recurring job. -- [Create and configure](https://sentry.io/issues/alerts/new/crons/) your first Monitor. diff --git a/platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx b/platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx deleted file mode 100644 index bba2907e90464..0000000000000 --- a/platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx +++ /dev/null @@ -1 +0,0 @@ -The generic `featureFlagsIntegration` allows you to manually track feature flag evaluations. Read the documentation to learn more. diff --git a/platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx b/platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx deleted file mode 100644 index c4a235b1ddad3..0000000000000 --- a/platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx +++ /dev/null @@ -1 +0,0 @@ -This integration is available in Sentry SDK **versions 9.31.0 or higher.** diff --git a/platform-includes/getting-started-add-top-level-import/javascript.connect.mdx b/platform-includes/getting-started-add-top-level-import/javascript.connect.mdx deleted file mode 100644 index e54c7a3135529..0000000000000 --- a/platform-includes/getting-started-add-top-level-import/javascript.connect.mdx +++ /dev/null @@ -1,29 +0,0 @@ -```javascript {tabTitle:CommonJS} -// Ensure to require this before requiring any other modules! -require('./instrument.js') - -const connect = require('connect'); -const Sentry = require("@sentry/node"); -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` - -```javascript {tabTitle:ESM} -// Ensure to import this before importing any other modules! -import './instrument.js' - -import connect from 'connect'; -import * as Sentry from "@sentry/node"; -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` diff --git a/platform-includes/getting-started-use/javascript.connect.mdx b/platform-includes/getting-started-use/javascript.connect.mdx deleted file mode 100644 index 9accba2961a23..0000000000000 --- a/platform-includes/getting-started-use/javascript.connect.mdx +++ /dev/null @@ -1,33 +0,0 @@ -```javascript {tabTitle:CommonJS} -// Require this first! -require("./instrument"); - -// Now require other modules -const connect = require("connect"); -const Sentry = require("@sentry/node"); - -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` - -```javascript {tabTitle:ESM} -// Import this first! -import "./instrument.mjs"; - -// Now import other modules -import connect from "connect"; -import * as Sentry from "@sentry/node"; - -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` diff --git a/platform-includes/getting-started-verify/javascript.connect.mdx b/platform-includes/getting-started-verify/javascript.connect.mdx deleted file mode 100644 index 7449938a9aa41..0000000000000 --- a/platform-includes/getting-started-verify/javascript.connect.mdx +++ /dev/null @@ -1,62 +0,0 @@ -### Issues - - - - - -First, let's make sure Sentry is correctly capturing errors and creating issues in your project. Add the following code snippet to your main application file; it defines a route that will deliberately trigger an error when called: - - - - -```javascript -app.use("/debug-sentry", (req, res) => { - throw new Error("My first Sentry error!"); -}); -``` - - - - - - - -### Tracing - - - - - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes to execute your code: - - - - -```javascript -app.use("/debug-sentry", async (req, res) => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); -}); -``` - - - - - - - - - - - - - - diff --git a/platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx b/platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx deleted file mode 100644 index 13c630acb863d..0000000000000 --- a/platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx +++ /dev/null @@ -1,166 +0,0 @@ -### Supported versions - -Sentry Node SDK `8.x` supports Node `14.18.0` or higher - -If you need to support older versions of Node.js, please use Sentry Node SDK `7.x`. - -### Updated SDK initialization - -With 8.x, @sentry/node has been completely overhauled. It is now powered by [OpenTelemetry](https://opentelemetry.io/) under the hood. You do not need to know or understand what OpenTelemetry is in order to use Sentry. We set up OpenTelemetry under the hood. If you use OpenTelemetry-native APIs to start spans, Sentry will pick up everything automatically. - -Here's an example of instrumentating a Connect application with Sentry Node SDK `8.x`: - -```javascript {tabTitle:CommonJS} -require("./instrument"); -const connect = require("connect"); -const Sentry = require("@sentry/node"); -const app = connect(); - -// Add routes etc. here - -Sentry.setupConnectErrorHandler(app); - -app.listen(3000); -``` - -```javascript {tabTitle:ESM} -import "./instrument"; -import connect from "connect"; -import * as Sentry from "@sentry/node"; -const app = connect(); - -// Add your routes, etc. here - -Sentry.setupConnectErrorHandler(app); - -app.listen(3030); -``` - -To migrate your Connect app to Sentry Node SDK `8.x`, you need to make the following changes: - -1. Create an external file called `instrument.js` and move your `Sentry.init` call to it. - -Due to the way that auto instrumentation works in `8.x` of the Sentry Node SDK, it is required that you initialize Sentry before you require or import any other package. Any package that is required/imported before Sentry is initialized may not be correctly auto-instrumented. - -```JavaScript {tabTitle:CommonJS} {filename: instrument.js} -const Sentry = require('@sentry/node'); - -Sentry.init({ - // ... -}); -``` - -```JavaScript diff {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - // ... -}); -``` - -2. Remove any performance related integrations - -All performance auto-instrumentation will be automatically enabled if the package is found. You do not need to add any integration yourself, and `autoDiscoverNodePerformanceMonitoringIntegrations()` has also been removed. This means you can remove all custom `requestHandler` and `tracingMiddleware` Sentry code. - -We now support the following integrations out of the box with 0 configuration: - -- `httpIntegration`: Automatically instruments Node http and https standard libraries -- `nativeNodeFetchIntegration`: Automatically instruments top level fetch and undici -- `koaIntegration`: Automatically instruments Koa -- `graphqlIntegration`: Automatically instruments GraphQL -- `mongoIntegration`: Automatically instruments MongoDB -- `mongooseIntegration`: Automatically instruments Mongoose -- `mysqlIntegration`: Automatically instruments MySQL -- `mysql2Integration`: Automatically instruments MySQL2 -- `postgresIntegration`: Automatically instruments PostgreSQL - -3. Require `instrument.js` before any other module in your application - -```JavaScript diff {tabTitle:CommonJS} -+require('./instrument'); - const connect = require('connect'); - const Sentry = require('@sentry/node'); - const app = connect(); -``` - -```JavaScript diff {tabTitle:ESM} -+import './instrument'; - import connect from 'connect'; - import * as Sentry from "@sentry/node"; - const app = connect(); -``` - - - -If you run your application with ESM, you need to import the Sentry Initialization file before importing any other modules. See running Sentry with ESM. -If you are unsure how you are running your application, see Installation Methods for more information. - - - -4. Add Sentry error handler - -Previously you had to use `Sentry.Handlers.requestHandler()`, `Sentry.Handlers.tracingHandler()`, and `Sentry.Handlers.errorHandler()` to add Sentry instrumentation to your Connect app. In `8.x`, you only need to use `Sentry.setupConnectErrorHandler(app)`, you can remove all other handlers. - -```JavaScript diff {tabTitle:CommonJS} - require('./instrument'); - const connect = require('connect'); - const Sentry = require('@sentry/node'); - const app = connect(); - --app.use(Sentry.Handlers.requestHandler()); --app.use(Sentry.Handlers.tracingHandler()); - -// add routes etc. here - --app.use(Sentry.Handlers.errorHandler()); -+Sentry.setupConnectErrorHandler(app); - - app.listen(3000); -``` - -```JavaScript diff {tabTitle:ESM} - import './instrument'; - import connect from 'connect'; - import * as Sentry from "@sentry/node"; - const app = connect(); - --app.use(Sentry.Handlers.requestHandler()); --app.use(Sentry.Handlers.tracingHandler()); - -// add routes etc. here - --app.use(Sentry.Handlers.errorHandler()); -+Sentry.setupConnectErrorHandler(app); - - app.listen(3000); -``` - -### Ensure Request Isolation - -For any non-HTTP scenarios (e.g. websockets or a scheduled job), you'll have to manually ensure request isolation by wrapping the function with `Sentry.withIsolationScope()`. Previously we recommended you use `Sentry.runWithAsyncContext` for this but that has been removed in `8.x`. - -```javascript {tabTitle:CommonJS} -const Sentry = require("@sentry/node"); - -function myScheduledJob() { - return Sentry.withIsolationScope(async () => { - await doSomething(); - await doSomethingElse(); - return { status: "DONE" }; - }); -} -``` - -```javascript {tabTitle:ESM} -import * as Sentry from "@sentry/node"; - -function myScheduledJob() { - return Sentry.withIsolationScope(async () => { - await doSomething(); - await doSomethingElse(); - return { status: "DONE" }; - }); -} -``` - -This way, anything happening inside of this function will be isolated, even if they run concurrently. diff --git a/platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx b/platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx deleted file mode 100644 index 4f7f6ab6537eb..0000000000000 --- a/platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx +++ /dev/null @@ -1,14 +0,0 @@ -### Removal of `@sentry/integrations` package - -`@sentry/integrations` has been removed and will no longer be published. We moved pluggable integrations from their own package (`@sentry/integrations`) to `@sentry/node`. In addition they are now functions instead of classes. - -Integrations that are now exported from `@sentry/node` for server-side init: - -- `captureConsoleIntegration` (`CaptureConsole`) -- `debugIntegration` (`Debug`) -- `extraErrorDataIntegration` (`ExtraErrorData`) -- `rewriteFramesIntegration` (`RewriteFrames`) -- `sessionTimingIntegration` (`SessionTiming`) -- `dedupeIntegration` (`Dedupe`) - Note: enabled by default, not pluggable - -The `Transaction` integration has been removed from `@sentry/integrations`. There is no replacement API. diff --git a/platform-includes/migration/javascript-v8/intro/javascript.connect.mdx b/platform-includes/migration/javascript-v8/intro/javascript.connect.mdx deleted file mode 100644 index 1654e8dd1f386..0000000000000 --- a/platform-includes/migration/javascript-v8/intro/javascript.connect.mdx +++ /dev/null @@ -1 +0,0 @@ -`8.x` simplifies Sentry Node SDK initialization and leverages Node.js OpenTelemetry instrumentation for tracing. diff --git a/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx b/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx index cb6da7d5b4f7f..e73e949efbd3d 100644 --- a/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx +++ b/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx @@ -39,7 +39,7 @@ To verify that the distribution has been set correctly in the SDK, open an issue If you've uploaded source maps and they aren't applying to your code in an issue in Sentry, take a look at the JSON of the event and look for the `abs_path` to see exactly where we're attempting to resolve the file - for example, `http://localhost:8000/scripts/script.js` (`abs_path` will appear once for each frame in the stack trace - match this up with the file(s) that are not deminified.). A link to the JSON view can be found at the top of the issue page next to the date the event occurred. The uploaded artifact names must match these values. -If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the `rewriteFrames` integration`rewriteFrames` integration to change your `abs_path` values. +If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the `rewriteFrames` integration`rewriteFrames` integration to change your `abs_path` values. ### Using sentry-cli diff --git a/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx b/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx index aa5af4955018b..df7829193bb77 100644 --- a/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx +++ b/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx @@ -328,7 +328,7 @@ To verify that the distribution has been set correctly in the SDK, open an issue If you've uploaded source maps and they aren't applying to your code in an issue in Sentry, take a look at the JSON of the event and look for the `abs_path` to see exactly where we're attempting to resolve the file - for example, `http://localhost:8000/scripts/script.js` (`abs_path` will appear once for each frame in the stack trace - match this up with the file(s) that are not deminified.). A link to the JSON view can be found at the top of the issue page next to the date the event occurred. The uploaded artifact names must match these values. -If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the `rewriteFrames` integration`rewriteFrames` integration to change your `abs_path` values. +If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the `rewriteFrames` integration`rewriteFrames` integration to change your `abs_path` values. #### Using sentry-cli diff --git a/platform-includes/sourcemaps/overview/javascript.capacitor.mdx b/platform-includes/sourcemaps/overview/javascript.capacitor.mdx index 2e80008f76640..b64502cfa0761 100644 --- a/platform-includes/sourcemaps/overview/javascript.capacitor.mdx +++ b/platform-includes/sourcemaps/overview/javascript.capacitor.mdx @@ -50,7 +50,7 @@ If you used Create React App to set up your React application see our Sentry CLI. - + diff --git a/platform-includes/sourcemaps/overview/javascript.mdx b/platform-includes/sourcemaps/overview/javascript.mdx index 0461bec03fa66..bdf2eaf2dead5 100644 --- a/platform-includes/sourcemaps/overview/javascript.mdx +++ b/platform-includes/sourcemaps/overview/javascript.mdx @@ -58,7 +58,7 @@ If you used Create React App to set up your React application see our Sentry CLI. - + diff --git a/platform-includes/sourcemaps/troubleshooting/javascript.mdx b/platform-includes/sourcemaps/troubleshooting/javascript.mdx index 0a478c5e54635..9015bf368ce4e 100644 --- a/platform-includes/sourcemaps/troubleshooting/javascript.mdx +++ b/platform-includes/sourcemaps/troubleshooting/javascript.mdx @@ -133,7 +133,6 @@ Sometimes build scripts and plugins produce pre-compressed minified files (for e 'javascript.node', 'javascript.aws-lambda', 'javascript.azure-functions', - 'javascript.connect', 'javascript.express', 'javascript.fastify', 'javascript.gcp-functions', diff --git a/platform-includes/sourcemaps/upload/primer/javascript.mdx b/platform-includes/sourcemaps/upload/primer/javascript.mdx index f181c01f57bc5..45e543f4beaf5 100644 --- a/platform-includes/sourcemaps/upload/primer/javascript.mdx +++ b/platform-includes/sourcemaps/upload/primer/javascript.mdx @@ -1,7 +1,7 @@ We provide guides on uploading source maps to Sentry for the most popular JavaScript build tools. Pick one from the list below to learn more. - + @@ -11,7 +11,7 @@ If you can't find the tool of your choice in the list below, we recommend you ch - + diff --git a/redirects.js b/redirects.js index 1722ca1dd0f7f..de8c5c6479dd3 100644 --- a/redirects.js +++ b/redirects.js @@ -982,14 +982,17 @@ const userDocsRedirects = [ destination: '/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x/', }, { - source: '/platforms/javascript/guides/node/install/lightweight/', - destination: - '/platforms/javascript/guides/node/configuration/integrations/opentelemetry/', + source: '/platforms/javascript/guides/connect/', + destination: '/platforms/javascript/guides/node/', }, { - source: '/platforms/javascript/guides/connect/install/lightweight/', + source: '/platforms/javascript/guides/connect/:path*', + destination: '/platforms/javascript/guides/node/', + }, + { + source: '/platforms/javascript/guides/node/install/lightweight/', destination: - '/platforms/javascript/guides/connect/configuration/integrations/opentelemetry/', + '/platforms/javascript/guides/node/configuration/integrations/opentelemetry/', }, { source: '/platforms/javascript/guides/express/install/lightweight/', From 10a06e772788692db5161047112574641a2cd968 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 08:09:47 +0200 Subject: [PATCH 39/48] docs(javascript): Correct Anthropic instrumented operations (#19568) Remove token counting and model lookup methods from Anthropic's automatically traced operations. We no longer instrument these with v11. Co-authored-by: GPT-6 --- .../javascript/common/configuration/integrations/anthropic.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx index cc7fb6ce54fb1..6682c766cf3d8 100644 --- a/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx @@ -35,10 +35,7 @@ By default, tracing support is added to the following Anthropic SDK calls: - `messages.create()` - Create messages with Claude models - `messages.stream()` - Stream messages with Claude models -- `messages.countTokens()` - Count tokens for messages -- `models.get()` - Get model information - `completions.create()` - Create completions (legacy) -- `models.retrieve()` - Retrieve model details - `beta.messages.create()` - Beta messages API Streaming and non-streaming requests are automatically detected and handled appropriately. From 889462361e33936c60b6dbf91aee9183b1cfe317 Mon Sep 17 00:00:00 2001 From: Andrei <168741329+andreiborza@users.noreply.github.com> Date: Wed, 23 Sep 2026 08:58:20 +0200 Subject: [PATCH 40/48] docs(js): Remove sendDefaultPii from the v11 docs (#19574) ## DESCRIBE YOUR PR v11 removes `sendDefaultPii`, so the docs now use `dataCollection` as the only option to control data collection. The Data Collected page now describes the v11 defaults, where all `dataCollection` categories are on unless you opt out. - Remove the `sendDefaultPii` option from the options page and its mentions from the APIs page - Update the Data Collected page for the v11 defaults - Remove `sendDefaultPii: true` from the wasm and Electron setup snippets Fixes https://linear.app/getsentry/issue/SDK-1468/remove-senddefaultpii-from-the-optionsapis-reference-in-docs ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) Co-authored-by: Claude --- .../javascript/common/configuration/apis.mdx | 4 +- .../common/configuration/options.mdx | 36 ------------------ .../data-management/data-collected/index.mdx | 37 +++++++++---------- .../javascript/guides/electron/index.mdx | 3 -- .../javascript/guides/wasm/index.mdx | 4 -- 5 files changed, 19 insertions(+), 65 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/apis.mdx b/docs/platforms/javascript/common/configuration/apis.mdx index 3f3c47c563738..44d8be66000da 100644 --- a/docs/platforms/javascript/common/configuration/apis.mdx +++ b/docs/platforms/javascript/common/configuration/apis.mdx @@ -472,13 +472,13 @@ Sentry.setContext("character", { On the server, the IP address will be inferred from the incoming HTTP request, if available. - This is automatically done if you have configured `dataCollection: { userInfo: true }` (or the deprecated `sendDefaultPii: true`) in your SDK configuration. + This is automatically done if you have configured `dataCollection: { userInfo: true }` in your SDK configuration. On the browser, if the users' `ip_address` is set to `"{{ auto }}"`, Sentry will infer the IP address from the connection between your app and Sentry's - server. `{{auto}}` is automatically set if you have configured `dataCollection: { userInfo: true }` (or the deprecated `sendDefaultPii: true`) in your SDK configuration. + server. `{{auto}}` is automatically set if you have configured `dataCollection: { userInfo: true }` in your SDK configuration. To ensure your users' IP addresses are never stored in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data scrubbing](/security-legal-pii/scrubbing/) to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 947e5d50c415f..827aa46c95391 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -103,42 +103,6 @@ Set to `false` to opt out, for example, when using a custom `tunnel` or when run - - - - `sendDefaultPii` is deprecated and will be removed in the next major version - (v11). Use [`dataCollection`](#dataCollection) instead. - - -Set this option to `true` to send default PII data to Sentry. Among other things, enabling this will enable automatic IP address collection on events. - -For backwards compatibility, `sendDefaultPii: true` behaves like enabling all [`dataCollection`](#dataCollection) categories. -If both options are set, `dataCollection` takes precedence. - - - Passing [`dataCollection`](#dataCollection) opts you into the more permissive `dataCollection` defaults. To preserve the old `sendDefaultPii: false` behavior while using `dataCollection`, opt out of each category explicitly: - -```javascript -Sentry.init({ - dataCollection: { - userInfo: false, - graphQL: { document: false, variables: false }, - genAI: { inputs: false, outputs: false }, - databaseQueryData: false, - queues: false, - httpBodies: [], - httpHeaders: { deny: ["forwarded", "-ip", "remote-", "via", "-user"] }, - cookies: { deny: ["forwarded", "-ip", "remote-", "via", "-user"] }, - urlQueryParams: { deny: ["forwarded", "-ip", "remote-", "via", "-user"] }, - }, -}); -``` - -Data you set explicitly (for example, via `Sentry.setUser()`) is always sent, regardless of `dataCollection`. - - - - Controls which categories of data the SDK collects automatically. All fields are optional. diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index 99d6ab7d4590c..aa992f15c778e 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -12,9 +12,9 @@ The category types and amount of data collected vary, depending on the integrati -You can control many of the categories listed here with the `dataCollection` option, which lets you opt in or out of each data category individually. The `sendDefaultPii` option is still supported, but deprecated as of version `10.54.0`. +You can control many of the categories listed here with the `dataCollection` option, which lets you opt in or out of each data category individually. -How much data the SDK collects by default depends on which option you use. Without `dataCollection` (and with `sendDefaultPii` unset or `false`), the SDK collects conservatively, and the defaults described on this page apply. As soon as you pass a `dataCollection` object, the categories you don't set explicitly fall back to their `dataCollection` defaults, which are more permissive. For example, cookies, query parameters (with sensitive values scrubbed), and AI message content is then collected unless you opt out. Setting `sendDefaultPii: true` is equivalent to enabling all `dataCollection` categories. If both are set, `sendDefaultPii` is ignored. +By default, the SDK collects all `dataCollection` categories and scrubs values whose keys match the built-in sensitive denylist. To collect less, opt out of a category or restrict it. Regardless of these options, you can always scrub any data before it's sent to Sentry. See Scrubbing Sensitive Data for details. @@ -28,15 +28,13 @@ Use the `dataCollection.httpHeaders` option to control this. For example, set `d ## Cookies -By default, the Sentry SDK doesn't send cookies. When using `dataCollection`, however, cookies are collected with sensitive values (like `token` or `key`) scrubbed. Opt out by setting `dataCollection: { cookies: false }`. - -To collect cookies when not using `dataCollection`, set the deprecated `sendDefaultPii: true` in `Sentry.init()`. To disable cookie collection when using `dataCollection`, set `dataCollection: { cookies: false }`. You can also restrict which cookie values are sent using `{ allow: [...] }` or `{ deny: [...] }`. +By default, the Sentry SDK sends cookies and scrubs sensitive values (like `token` or `key`). To disable cookie collection, set `dataCollection: { cookies: false }`. You can also restrict which cookie values are sent using `{ allow: [...] }` or `{ deny: [...] }`. ## Information About Logged-in User -When using `dataCollection`, the SDK automatically populates user identity fields (`user.id`, `user.email`, `user.username`) from instrumentation. To disable this, set `dataCollection: { userInfo: false }`. +By default, the SDK populates user identity fields (`user.id`, `user.email`, `user.username`) from instrumentation. To disable this, set `dataCollection: { userInfo: false }`. -Without `dataCollection` (and with `sendDefaultPii` unset or `false`), user identity fields are not sent automatically. Some integrations (e.g. User Feedback) may still send data like the user ID, username, and email address when explicitly configured. +With `userInfo: false`, user identity fields are not sent automatically. Some integrations (e.g. User Feedback) may still send data like the user ID, username, and email address when explicitly configured. ### Local Device User @@ -46,14 +44,13 @@ Without `dataCollection` (and with `sendDefaultPii` unset or `false`), user iden ## Users' IP Address and Location -When using `dataCollection`, the SDK sends the user's IP address by default. To disable it, set `dataCollection: { userInfo: false }`. +By default, the SDK sends the user's IP address. To disable it, set `dataCollection: { userInfo: false }`. -Without `dataCollection` (and with `sendDefaultPii` unset or `false`), the user's IP address is not sent. In some integrations such as [`handleRequest`](/platforms/javascript/guides/astro/#customize-server-instrumentation) in Astro, the user's IP address can also be sent by enabling `trackClientIp`. If sending the IP address is enabled we will try to infer the IP address or use the IP address provided by `ip_address` in `Sentry.setUser()`. If you set `ip_address: null`, the IP address won't be inferred. -Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). If you use `dataCollection`, add these terms to the partially-matched deny lists for those categories so their values are filtered: +Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). Add these terms to the partially-matched deny lists for those categories so their values are filtered: ```JavaScript Sentry.init({ @@ -74,13 +71,13 @@ The full request URL of outgoing and incoming HTTP requests is **always sent to By default, the full request query string of outgoing and incoming HTTP requests is sent to Sentry. Depending on your application, this could contain PII data. For example, a query string like `?user_id=1234`, where `1234` is a user id (which may be considered PII). -Use the `dataCollection.urlQueryParams` option to control this. Set it to `false` to disable collection entirely, or use `{ allow: [...] }` / `{ deny: [...] }` to filter which values are sent. When `dataCollection` is used, values whose keys match the built-in sensitive denylist (terms like `auth`, `token`, `password`, and `secret`) are scrubbed automatically. +Use the `dataCollection.urlQueryParams` option to control this. Set it to `false` to disable collection entirely, or use `{ allow: [...] }` / `{ deny: [...] }` to filter which values are sent. Values whose keys match the built-in sensitive denylist (terms like `auth`, `token`, `password`, and `secret`) are scrubbed automatically. Sentry also has some additional [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) in place to remove sensitive data from the query string. ## Request Body -When using `dataCollection`, incoming and outgoing request bodies are collected by default. To disable body collection, set `dataCollection: { httpBodies: [] }`. You can also collect only specific body types by providing a subset: `"incomingRequest"`, `"outgoingRequest"`, `"incomingResponse"`, and `"outgoingResponse"`. +By default, incoming and outgoing request bodies are collected. To disable body collection, set `dataCollection: { httpBodies: [] }`. You can also collect only specific body types by providing a subset: `"incomingRequest"`, `"outgoingRequest"`, `"incomingResponse"`, and `"outgoingResponse"`. ```js Sentry.init({ @@ -91,7 +88,7 @@ Sentry.init({ }); ``` -Without `dataCollection` (and with `sendDefaultPii` unset or `false`), Sentry only sends the body size inferred from the `content-length` header, not the body content itself. +If you disable body collection, Sentry only sends the body size inferred from the `content-length` header, not the body content itself. On the server-side, the incoming request body is captured by default. You can disable sending the incoming request body by configuring `ignoreRequestBody` in the HTTP Integration. @@ -115,9 +112,9 @@ On the server-side, the more details in the Session Replay documentation. - The `dataCollection` and `sendDefaultPii` options don't affect Session Replay. Because Replay is opt-in by default (it masks everything unless you allow it), while `dataCollection` is opt-out, the two use opposite privacy models. To avoid changing behavior on a privacy-sensitive feature, Replay's masking and network capture are controlled exclusively by the Replay integration's own privacy options, regardless of your `dataCollection` or `sendDefaultPii` settings. + The `dataCollection` option doesn't affect Session Replay. Because Replay is opt-in by default (it masks everything unless you allow it), while `dataCollection` is opt-out, the two use opposite privacy models. To avoid changing behavior on a privacy-sensitive feature, Replay's masking and network capture are controlled exclusively by the Replay integration's own privacy options, regardless of your `dataCollection` settings. Session Replay also captures basic information about all outgoing fetch and XHR requests in your application. This includes the URL, request and response body size, method, and status code. If `networkDetailAllowUrls` are defined, the request and response body will be sent to Sentry as well. This can include PII data if the request or response body contains PII information. @@ -229,9 +226,9 @@ By default, the Sentry SDK sends information about the device and runtime to Sen ## tRPC Context - When using `dataCollection`, tRPC input is collected by default because `httpBodies` includes `"incomingRequest"` by default. To disable it, set `dataCollection: { httpBodies: [] }` or use a list that excludes `"incomingRequest"`. + By default, tRPC input is collected because `httpBodies` includes `"incomingRequest"` by default. To disable it, set `dataCollection: { httpBodies: [] }` or use a list that excludes `"incomingRequest"`. - Without `dataCollection` (and with `sendDefaultPii` unset or `false`), tRPC input is not collected. You can still opt in per-middleware by setting `attachRpcInput: true` in the `Sentry.trpcMiddleware()` options, regardless of the global `dataCollection` setting. + If you exclude `"incomingRequest"`, tRPC input is not collected. You can still opt in per-middleware by setting `attachRpcInput: true` in the `Sentry.trpcMiddleware()` options, regardless of the global `dataCollection` setting. @@ -240,7 +237,7 @@ By default, the Sentry SDK sends information about the device and runtime to Sen When you use a GraphQL integration, the Sentry SDK sends the operation name and the operation type to Sentry. -When you use `dataCollection`, the SDK also sends the GraphQL document (the query or mutation source text) and the variables passed to the operation by default. This data can include PII. Use the `dataCollection.graphQL` option (available since version `10.66.0`) to control it: +By default, the SDK also sends the GraphQL document (the query or mutation source text) and the variables passed to the operation by default. This data can include PII. Use the `dataCollection.graphQL` option (available since version `10.66.0`) to control it: ```JavaScript Sentry.init({ @@ -259,7 +256,7 @@ Sentry.init({ When using AI integrations, metadata like model ID and used tokens is sent to Sentry. - The content of generative AI inputs (system instructions, prompt messages, tool definitions, and tool call arguments) and outputs (such as completion text and tool call results) might carry personal data. Whether it's recorded depends on your configuration: it's not recorded by default with `sendDefaultPii`, but when you use `dataCollection`, the `genAI` category records both inputs and outputs unless you opt out. Metadata like model ID and token counts is always collected. + The content of generative AI inputs (system instructions, prompt messages, tool definitions, and tool call arguments) and outputs (such as completion text and tool call results) might carry personal data. By default, the SDK records both inputs and outputs. Metadata like model ID and token counts is always collected. Use the `dataCollection.genAI` option to control this. For example, opt out of recording AI message content while keeping the metadata: diff --git a/docs/platforms/javascript/guides/electron/index.mdx b/docs/platforms/javascript/guides/electron/index.mdx index b38197a202d4a..34a498d591133 100644 --- a/docs/platforms/javascript/guides/electron/index.mdx +++ b/docs/platforms/javascript/guides/electron/index.mdx @@ -104,9 +104,6 @@ Initialize the SDK in your Electron renderer processes as early as possible. All import * as Sentry from "@sentry/electron/renderer"; Sentry.init({ - // Adds request headers and IP for users, for more info visit: - // https://docs.sentry.io/platforms/javascript/guides/electron/configuration/options/#sendDefaultPii - sendDefaultPii: true, integrations: [ // ___PRODUCT_OPTION_START___ performance Sentry.browserTracingIntegration(), diff --git a/docs/platforms/javascript/guides/wasm/index.mdx b/docs/platforms/javascript/guides/wasm/index.mdx index 7bcc43e5e01f6..594bcf1f9d56e 100644 --- a/docs/platforms/javascript/guides/wasm/index.mdx +++ b/docs/platforms/javascript/guides/wasm/index.mdx @@ -74,10 +74,6 @@ import { wasmIntegration } from "@sentry/wasm"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // Adds request headers and IP for users, for more info visit: - // https://docs.sentry.io/platforms/javascript/guides/wasm/configuration/options/#sendDefaultPii - sendDefaultPii: true, - integrations: [ // ___PRODUCT_OPTION_START___ performance Sentry.browserTracingIntegration(), From 6ddcd6a4db9e8af1e3af900b32f38150577bf2af Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 09:24:10 +0200 Subject: [PATCH 41/48] docs(javascript): Document Google Gen AI v2 and embeddings support (#19566) Align the Google Gen AI supported version range with the SDK instrumentation and document the existing `models.embedContent()` support in the v11 integration docs. ## IS YOUR CHANGE URGENT? - [x] No deadline: Not urgent, can wait up to 1 week+ Co-authored-by: GPT-6 --- .../common/configuration/integrations/google-genai.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx index 9cbf727ed774f..e28027998f703 100644 --- a/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx @@ -35,6 +35,7 @@ By default, tracing support is added to the following Google Gen AI SDK calls: - `models.generateContent()` - Generate content with a given model - `models.generateContentStream()` - Stream content generation with a given model +- `models.embedContent()` - Generate embeddings with a given model - `chats.create()` - Create chat sessions - `sendMessage()` - Send messages in chat sessions - `sendMessageStream()` - Stream messages in chat sessions @@ -43,7 +44,7 @@ Streaming and non-streaming requests are automatically detected and handled appr ## Supported Versions -- `@google/genai`: `>=0.10.0 <=2` +- `@google/genai`: `>=0.10.0 <3` ## Options From daa0d362da367b85fa241681e37204bbb4b938ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Wed, 23 Sep 2026 10:27:48 +0300 Subject: [PATCH 42/48] docs(cloudflare): Rework the guide for v11 (#19331) ## DESCRIBE YOUR PR closes SDK-1426 Updates the Cloudflare guide for the APIs v11 removes or changes. Hold until v11 ships; every claim here is wrong on the v10 line. - Remove the `@sentry/cloudflare/nodejs_compat` entrypoint, which no longer exists, from the guide, the Prisma page, the integrations table and the Vercel AI page, and delete its feature page - Drop the `_experimental` Vite plugin options for `buildTimeInstrumentation` and `autoInstrumentation`, both on by default, and remove the experimental alert on the plugin page - Import `wrapRequestHandler` from `@sentry/cloudflare/request`, the only entry that still exports it - Delete the removed `honoIntegration` page - Describe spans as streamed by default on the MCP pages and in troubleshooting, and keep the v10 opt-in as a separate case - Drop the caveat that configured classes must be declared in the Worker entry, fixed by https://github.com/getsentry/sentry-javascript/pull/23282 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [x] Other deadline: 2026-09-16 - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Claude Opus 5 Co-authored-by: Martin Sonnberger --- .../javascript/common/agent-tracing/index.mdx | 2 +- .../common/mcp-monitoring/index.mdx | 24 ++------- .../cloudflare/agent-tracing/agents-sdk.mdx | 2 +- .../configuration/integrations/hono.mdx | 45 ----------------- .../configuration/integrations/prisma.mdx | 12 ++--- .../cloudflare/features/nodejs-compat.mdx | 50 ------------------- .../guides/cloudflare/features/pages.mdx | 4 +- .../javascript/guides/cloudflare/index.mdx | 6 --- .../guides/cloudflare/install/vite-plugin.mdx | 26 ++-------- docs/product/mcp-servers/getting-started.mdx | 2 +- .../integrations/javascript.cloudflare.mdx | 3 +- .../how-to-use/javascript.cloudflare.mdx | 6 ++- redirects.js | 16 ++++++ 13 files changed, 37 insertions(+), 161 deletions(-) delete mode 100644 docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx delete mode 100644 docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index f783c167a6d34..53bde1929d3d4 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -230,7 +230,7 @@ export default Sentry.withSentry( ); ``` -On the default CF entrypoint, control Vercel AI I/O with `experimental_telemetry` per call (or integration-level `record*` via `nodejs_compat`). See each integration page. +On Cloudflare, control Vercel AI I/O with integration-level `record*` options or with `experimental_telemetry` per call. See each integration page. diff --git a/docs/platforms/javascript/common/mcp-monitoring/index.mdx b/docs/platforms/javascript/common/mcp-monitoring/index.mdx index b2e41af08a68d..4728e643811e7 100644 --- a/docs/platforms/javascript/common/mcp-monitoring/index.mdx +++ b/docs/platforms/javascript/common/mcp-monitoring/index.mdx @@ -56,29 +56,11 @@ These options override the corresponding `dataCollection.genAI.inputs` and `data ## Preserve MCP Spans After the Response -Cloudflare MCP work can finish after the Worker returns an HTTP response, including work kept alive with `waitUntil()`. In transaction mode, Sentry snapshots the request transaction when the response is returned, so MCP spans that finish later may be missing. +Cloudflare MCP work can finish after the Worker returns an HTTP response, including work kept alive with `waitUntil()`. The SDK streams spans by default, sending each sampled span as it finishes, so this work is captured without extra configuration. You still need to wrap the MCP server as shown above. -Span streaming is enabled by default, so the SDK can send each sampled span when it finishes. Use `traceLifecycle: "stream"` to preserve spans that finish after the response. You still need to wrap the MCP server as shown above. +If you set `traceLifecycle: "static"`, the SDK snapshots the request transaction when the response is returned and MCP spans that finish later are dropped. Remove the option to get them back. -```javascript {filename:index.js} -import * as Sentry from "@sentry/cloudflare"; - -const worker = { - async fetch(request, env, ctx) { - return handleMcpRequest(request, env, ctx); - }, -}; - -export default Sentry.withSentry( - (env) => ({ - dsn: env.SENTRY_DSN, - tracesSampleRate: 1.0, - }), - worker -); -``` - -Use `beforeSendSpan` to modify each finished span's `name` and `attributes`, with an `is_segment` guard to target service spans. Use the object form of `ignoreSpans` to drop spans by name and operation. See Streamed Spans for examples. +Streaming sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. Use beforeSendSpan and ignoreSpans instead. If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and wrap the Agent class separately with `instrumentAgentWithSentry` to preserve request and RPC context. Agent instrumentation, MCP server wrapping, and span streaming solve different parts of the setup; none replaces the others. See Agents SDK. diff --git a/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx b/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx index d74c495d47609..50a6f45095517 100644 --- a/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx +++ b/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx @@ -36,7 +36,7 @@ export const MyAgent = Sentry.instrumentAgentWithSentry( The Worker that calls the agent names its binding in `rpcTracePropagationBindings`. See RPC Trace Propagation. -`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the Sentry Cloudflare Vite plugin's `autoInstrumentation`, the plugin detects and wraps Agent classes automatically. +`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the Sentry Cloudflare Vite plugin, it detects and wraps Agent classes for you, so you only need this wrapper on a plain Wrangler build. ## Conversation IDs diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx deleted file mode 100644 index adba0ecd9b05b..0000000000000 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Hono -description: "Reports Hono errors to Sentry. (default)" ---- - -_Import name: `Sentry.honoIntegration`_ - - - -**Deprecated**: `honoIntegration` is deprecated. Use the [dedicated `@sentry/hono` SDK](/platforms/javascript/guides/hono/) instead, which supports Hono across Cloudflare Workers, Node.js, and Bun with improved performance and a simpler setup. - - - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -The `honoIntegration` automatically captures errors from Hono's `onError` function and sends them to Sentry. By default, the integration doesn't capture errors that have a 3xx or 4xx HTTP status code. - -## Options - -You can configure the `honoIntegration` by passing an options object to the function. - -### `shouldHandleError` - -This option allows you to provide a function that determines whether an error should be captured, giving you full control over which errors are sent to Sentry. - -The function receives the error as an argument and should return `true` if the error should be reported, and `false` otherwise. - -For example, to report all errors except for 404s, add this to the integrations array when initializing Sentry: - -```javascript -integrations: [ - honoIntegration({ - shouldHandleError(error) { - // return true // Would report all errors - - if (error instanceof HTTPException && error.status === 404) { - // Don't report 404s - return false; - } - // Report all other errors - return true; - }, - }), -] -``` diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx index febbd812a4af1..c6f8ae2472a07 100644 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx @@ -1,22 +1,16 @@ --- title: Prisma -description: "Adds instrumentation for Prisma ORM queries on Cloudflare Workers running with Node.js compatibility." +description: "Adds instrumentation for Prisma ORM queries on Cloudflare Workers." --- - - -On Cloudflare, the `prismaIntegration` is only available through the `@sentry/cloudflare/nodejs_compat` entrypoint, which requires SDK version `10.64.0` or higher. - - - _Import name: `Sentry.prismaIntegration`_ Sentry supports tracing [Prisma ORM](https://www.prisma.io/) queries with the Prisma integration. The integration creates a span for each query and reports relevant details to Sentry. -To enable it on Cloudflare, import Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint and add the `prismaIntegration` to your `Sentry.init` call: +The integration relies on Node.js APIs, so your Worker must run with the `nodejs_compat` compatibility flag. Add the `prismaIntegration` to your `Sentry.init` call: ```javascript {3,5} -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; +import * as Sentry from "@sentry/cloudflare"; Sentry.init({ tracesSampleRate: 1.0, diff --git a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx b/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx deleted file mode 100644 index 44d85ea68781e..0000000000000 --- a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Node.js Compatibility Entrypoint -description: "Learn how the nodejs_compat entrypoint unlocks additional Node.js SDK features on Cloudflare Workers, such as Prisma instrumentation." ---- - -Cloudflare Workers can run with Node.js APIs enabled through the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/). To take advantage of this, the Cloudflare SDK ships a dedicated `@sentry/cloudflare/nodejs_compat` entrypoint that unlocks Node.js SDK features which aren't available in the default Workers runtime. - - - -The `@sentry/cloudflare/nodejs_compat` entrypoint requires SDK version `10.64.0` or higher. It will become the default entrypoint in the next major version (v11). - - - -## What It Unlocks - -The `/nodejs_compat` entrypoint enables Node.js-only integrations and features on Cloudflare, including: - -- The `prismaIntegration` for tracing Prisma ORM queries. -- Vercel AI SDK v7 support for the `vercelAIIntegration`. - -## Usage - -The entrypoint is a drop-in replacement for `@sentry/cloudflare`, so switching over only requires changing your imports: - -```javascript {tabTitle:After} -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; -``` - -```javascript {tabTitle:Before} -import * as Sentry from "@sentry/cloudflare"; -``` - -To use the entrypoint, your Worker must set the `nodejs_compat` compatibility flag in your Wrangler configuration: - - -```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} -{ - "compatibility_flags": ["nodejs_compat"], -} -``` - -```toml {tabTitle:Toml} {filename:wrangler.toml} -compatibility_flags = ["nodejs_compat"] -``` - - - -We recommend that you also keep `compatibility_date` and Wrangler up to date. Some instrumentation depends on Node.js APIs that Cloudflare only exposes from a given compatibility date on, and an older date can turn that instrumentation off without an error message. The Vercel AI integration, for example, needs `2026-02-19` or later. - - diff --git a/docs/platforms/javascript/guides/cloudflare/features/pages.mdx b/docs/platforms/javascript/guides/cloudflare/features/pages.mdx index afc7c2d363142..4b73ef8dccd58 100644 --- a/docs/platforms/javascript/guides/cloudflare/features/pages.mdx +++ b/docs/platforms/javascript/guides/cloudflare/features/pages.mdx @@ -82,7 +82,7 @@ If you don't have access to the `onRequest` middleware API, you can use the `wra ```javascript // hooks.server.js -import * as Sentry from "@sentry/cloudflare"; +import { wrapRequestHandler } from "@sentry/cloudflare/request"; export const handle = ({ event, resolve }) => { const requestHandlerOptions = { @@ -93,7 +93,7 @@ export const handle = ({ event, resolve }) => { request: event.request, context: event.platform.ctx, }; - return Sentry.wrapRequestHandler(requestHandlerOptions, () => resolve(event)); + return wrapRequestHandler(requestHandlerOptions, () => resolve(event)); }; ``` diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index 1ca6aba3bf96a..ea39fc1018fe9 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -59,12 +59,6 @@ Run the command for your preferred package manager to add the Sentry SDK to your - - -Importing Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint unlocks additional Node.js SDK features on Cloudflare. It requires SDK version `10.64.0` or higher and will become the default in the next major version. [Learn more](./features/nodejs-compat). - - - ## Configure This guide sets Sentry up through Vite, which is what we recommend for Cloudflare Workers. The plugin does the wiring at build time, so your Worker code stays untouched. diff --git a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx index 8007e7ff0208c..d5f43e559d5ab 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx @@ -5,11 +5,6 @@ description: "Learn how to use the Sentry Cloudflare Vite plugin to instrument b - - The Sentry Cloudflare Vite plugin has **experimental** stability. - Configuration options and behavior may change or be removed in any release. - - The Sentry Cloudflare Vite plugin (`sentryCloudflareVitePlugin`) instruments your Worker at build time. It can: 1. **Instrument bundled dependencies**: instruments supported packages in your bundle, such as database clients and AI SDKs, giving you more traces out of the box. @@ -25,7 +20,7 @@ options, and the details that matter once it's running. The plugin reads your wrangler config (probing `wrangler.json`, `wrangler.jsonc`, and `wrangler.toml` at the Vite root, or the file set with [`wranglerConfigPath`](#wranglerconfigpath)) to find the entry point, Durable Objects, workflows, and Agents SDK classes. It wraps Agents SDK classes (`Agent`, `AIChatAgent`, `McpAgent`) with `instrumentAgentWithSentry`, which also gives them automatic conversation IDs (see Cloudflare Agents SDK). -Any entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, set `autoInstrumentation: false` and follow the Wrangler setup. +An entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. To keep the plugin out of your entry entirely, set [`autoInstrumentation`](#autoinstrumentation) to `false` and wrap it yourself as shown in the Wrangler setup. With auto-instrumentation, you can optionally provide Sentry options via a co-located `instrument.server.*` file (`.ts`, `.mts`, `.js`, `.mjs`, or `.cjs`) next to your Worker entry. The plugin resolves this location from `main` in your wrangler config. For example, if `main` is `src/worker/index.ts`, place the file at `src/worker/instrument.server.ts`, not at the project root. Use `defineCloudflareOptions` for full type-checking: @@ -40,20 +35,7 @@ export default defineCloudflareOptions((env) => ({ If no `instrument.server.*` file exists, the SDK reads all configuration (DSN, release, environment, sample rate, etc.) from the Worker's `env` bindings at runtime. -Configured Durable Object, Workflow, and Agents SDK classes must be declared in the Worker entry for the plugin to wrap them automatically. The plugin cannot rewrite a class that the entry only imports or re-exports from another module. In that case, wrap the imported class in the entry with its matching helper and pass it the options callback from `instrument.server.*`: - -```typescript {filename:src/worker/index.ts} -import * as Sentry from "@sentry/cloudflare"; -import sentryOptions from "./instrument.server"; -import { MyAgent as MyAgentBase } from "./my-agent"; - -export const MyAgent = Sentry.instrumentAgentWithSentry( - sentryOptions, - MyAgentBase -); -``` - -Use `instrumentDurableObjectWithSentry` for a plain Durable Object or `instrumentWorkflowWithSentry` for a Workflow. +Configured classes are wrapped wherever they reach the Worker entry, whether they're declared there, imported from another module and exported by name, or re-exported straight through. A class you wrapped yourself is left as it is. ### Derived RPC Trace Propagation @@ -63,7 +45,7 @@ The plugin knows which bindings point at classes it wrapped itself: Durable Obje Bindings to _other_ Workers stay opt-in, because their receivers may not run Sentry. List those yourself in `instrument.server.*`; whatever you list is added on top of the derived names. -The plugin derives only the classes it wrapped itself. A class you wrapped by hand, or one re-exported from another module, runs on its own options and stays out. +The plugin derives only the classes it wrapped itself. A class you wrapped by hand runs on its own options and stays out. This applies to Vite builds only. At runtime a `DurableObjectNamespace` exposes no origin and a `Fetcher` does not say which service it points at, so a plain wrangler build still has to list its bindings. @@ -96,7 +78,7 @@ A package is only instrumented if it's actually bundled. A dependency you mark a -Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry` (SDK version 10.69.0 or higher). Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). Set to `false` to opt out. +Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry`. Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings`. Set to `false` to opt out. diff --git a/docs/product/mcp-servers/getting-started.mdx b/docs/product/mcp-servers/getting-started.mdx index 3cb4760765a24..4705cbc8f315e 100644 --- a/docs/product/mcp-servers/getting-started.mdx +++ b/docs/product/mcp-servers/getting-started.mdx @@ -76,7 +76,7 @@ Defaults to `dataCollection.genAI.outputs`. In Sentry JavaScript SDK 10.x, when #### Cloudflare Workers -MCP work on Cloudflare can finish after the Worker returns an HTTP response. Configure `traceLifecycle: "stream"` so spans are sent when they finish instead of depending on a static request snapshot. This requires `@sentry/cloudflare` version `10.49.0` or newer. +MCP work on Cloudflare can finish after the Worker returns an HTTP response. The SDK streams spans by default, sending each one when it finishes, so this work is captured without extra configuration. Setting `traceLifecycle: "static"` drops the spans that finish after the response. See [MCP Monitoring on Cloudflare](/platforms/javascript/guides/cloudflare/mcp-monitoring/) for the configuration and filtering differences in stream mode. diff --git a/platform-includes/configuration/integrations/javascript.cloudflare.mdx b/platform-includes/configuration/integrations/javascript.cloudflare.mdx index 82ee0233153bd..a4c0a16fb41bf 100644 --- a/platform-includes/configuration/integrations/javascript.cloudflare.mdx +++ b/platform-includes/configuration/integrations/javascript.cloudflare.mdx @@ -14,8 +14,7 @@ | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | | [`instrumentPostgresJsSql`](./postgresjs) | | | ✓ | | | | [`prismaIntegration`](./prisma) | | | ✓ | | | -| [`honoIntegration`](./hono) | ✓ | ✓ | | | | [Mistral AI](./mistral) is automatically instrumented when built with the Sentry Cloudflare Vite plugin. Without the plugin, use `instrumentMistralAiClient`. -The [`prismaIntegration`](./prisma) is only available through the [`@sentry/cloudflare/nodejs_compat`](../../features/nodejs-compat) entrypoint. +The [`prismaIntegration`](./prisma) needs the `nodejs_compat` compatibility flag on your Worker. diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx index 7073f9ba97de6..805bb88f317ec 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx @@ -11,7 +11,11 @@ By default, traces are not propagated across [RPC calls](https://developers.clou That trailing argument is why propagation is opt-in per binding: only a Sentry-instrumented receiver strips it again. List the bindings whose receiver you know runs Sentry in `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). Setting the option also turns on the receiver side, so a Worker that both calls and receives needs nothing else. - If you build with the Sentry Cloudflare Vite plugin and its `autoInstrumentation` option, the plugin configures the bindings that point at classes in the same Worker. You only need to list bindings to other Workers. + If you build with the Sentry + Cloudflare Vite plugin, it derives the bindings that point at + classes in this Worker, so you only need to list bindings to other Workers. + See Derived + RPC Trace Propagation. **Worker Side (Caller):** diff --git a/redirects.js b/redirects.js index de8c5c6479dd3..c65c4da64712c 100644 --- a/redirects.js +++ b/redirects.js @@ -2367,6 +2367,22 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/cloudflare/features/vite-plugin/:path*', destination: '/platforms/javascript/guides/cloudflare/install/vite-plugin/:path*', }, + // The nodejs_compat entrypoint was removed in v11; the guide covers the single entry. + { + source: '/platforms/javascript/guides/cloudflare/features/nodejs-compat.md', + destination: '/platforms/javascript/guides/cloudflare.md', + }, + { + source: + '/platforms/javascript/guides/cloudflare/features/nodejs-compat/:path*', + destination: '/platforms/javascript/guides/cloudflare/', + }, + // honoIntegration was removed in v11 in favor of the @sentry/hono SDK. + { + source: + '/platforms/javascript/guides/cloudflare/configuration/integrations/hono/:path*', + destination: '/platforms/javascript/guides/hono/', + }, // Cloudflare AI pages moved from Features to Agent Tracing. { source: '/platforms/javascript/guides/cloudflare/features/agents-sdk.md', From 4ccf1b3ec82fbd3de6412759a11f1bc78daeaa74 Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Wed, 23 Sep 2026 09:34:00 +0200 Subject: [PATCH 43/48] feat(docs): Add agent prompt for JavaScript v11 migration (#19575) ## DESCRIBE YOUR PR Add a one-click migration prompt to the full and interactive JavaScript v11 migration guides. Users can paste it into their AI agent to read the guide for their selected framework, apply the relevant changes, preserve their intended data collection behavior, and run the project's checks. Reuse the existing agent setup callout with custom migration instructions, omitting the setup-specific plugin links. Fixes [SDK-1523](https://linear.app/getsentry/issue/SDK-1523/prepare-a-copy-agent-instructions-copy-paste-prompt). ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] 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](https://github.com/orgs/getsentry/teams/docs) --- .../common/migration/v10-to-v11/index.mdx | 2 + .../migration/v10-to-v11/interactive.mdx | 2 + includes/javascript-v11-agent-migration.mdx | 5 ++ src/components/agentMigrationCallout.tsx | 35 ++++++++ src/components/agentSetupCallout/index.tsx | 88 +++++++++++-------- src/mdxComponents.ts | 2 + 6 files changed, 98 insertions(+), 36 deletions(-) create mode 100644 includes/javascript-v11-agent-migration.mdx create mode 100644 src/components/agentMigrationCallout.tsx diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index 461737355a25e..e04359f9c8a81 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -16,6 +16,8 @@ Make sure to select your framework in the dropdown in the top left corner of the + + Version 11 of the Sentry JavaScript SDK focuses on better OpenTelemetry interoperability, more flexible instrumentation, and better out-of-the-box defaults. The biggest changes are: - **OpenTelemetry interoperability:** The SDK no longer takes over your OpenTelemetry setup. diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx index 5a4a3bb2c4302..3f95c52b9c0b4 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx @@ -16,6 +16,8 @@ Make sure to select your framework in the dropdown in the top left corner of the + + Version 11 of the Sentry JavaScript SDK focuses on better OpenTelemetry interoperability, more flexible instrumentation, and better out-of-the-box defaults. It raises the minimum versions of Node.js, TypeScript, and several frameworks. We recommend upgrading to the most recent 10.x release first, because most of what v11 removes is already deprecated there. diff --git a/includes/javascript-v11-agent-migration.mdx b/includes/javascript-v11-agent-migration.mdx new file mode 100644 index 0000000000000..c680f40487ba0 --- /dev/null +++ b/includes/javascript-v11-agent-migration.mdx @@ -0,0 +1,5 @@ + diff --git a/src/components/agentMigrationCallout.tsx b/src/components/agentMigrationCallout.tsx new file mode 100644 index 0000000000000..2b3949535db68 --- /dev/null +++ b/src/components/agentMigrationCallout.tsx @@ -0,0 +1,35 @@ +import {getCurrentPlatformOrGuide} from 'sentry-docs/docTree'; +import {serverContext} from 'sentry-docs/serverContext'; + +import {AgentSetupCallout} from './agentSetupCallout'; + +type Props = { + /** Absolute URL, site-relative path, or path relative to the selected platform. */ + guideUrl: string; + /** Migration instructions to follow after reading the guide. */ + prompt: string; + description?: string; +}; + +export function AgentMigrationCallout({ + guideUrl, + prompt, + description = 'Copy this prompt into your AI agent to migrate your Sentry SDK.', +}: Props) { + const {rootNode, path} = serverContext(); + const platform = getCurrentPlatformOrGuide(rootNode, path); + const resolvedGuideUrl = new URL( + guideUrl, + `https://docs.sentry.io${platform?.url ?? '/'}` + ).href; + + return ( + + ); +} diff --git a/src/components/agentSetupCallout/index.tsx b/src/components/agentSetupCallout/index.tsx index 4f55dffc8bf9c..5c8043f2f412f 100644 --- a/src/components/agentSetupCallout/index.tsx +++ b/src/components/agentSetupCallout/index.tsx @@ -17,14 +17,21 @@ type Props = { platformName?: string; /** Skill package name, e.g. "sentry-nextjs-sdk". Omit for generic/all skills. */ skill?: string; + /** Custom instructions for tasks other than SDK setup. */ + instructions?: { + title: string; + prompt: string; + description: string; + }; }; -export function AgentSetupCallout({skill, platformName}: Props) { +export function AgentSetupCallout({skill, platformName, instructions}: Props) { const [copied, setCopied] = useState(false); const [isExpanded, setIsExpanded] = useState(false); const {emit} = usePlausibleEvent(); - const prompt = buildPrompt(platformName); + const prompt = instructions?.prompt ?? buildPrompt(platformName); + const title = instructions?.title ?? 'Agent-Assisted Setup'; const copyPrompt = useCallback( async (event: React.MouseEvent) => { @@ -32,7 +39,10 @@ export function AgentSetupCallout({skill, platformName}: Props) { event.preventDefault(); emit('Copy AI Prompt', { - props: {page: window.location.pathname, title: 'Agent Setup Callout'}, + props: { + page: window.location.pathname, + title: instructions?.title ?? 'Agent Setup Callout', + }, }); try { @@ -50,18 +60,20 @@ export function AgentSetupCallout({skill, platformName}: Props) { setCopied(false); } }, - [prompt, emit, skill] + [prompt, emit, skill, instructions?.title] ); - const description = platformName - ? `Your agent will set up Sentry in your ${platformName} app automatically.` - : 'Your agent will set up Sentry automatically.'; + const description = + instructions?.description ?? + (platformName + ? `Your agent will set up Sentry in your ${platformName} app automatically.` + : 'Your agent will set up Sentry automatically.'); return (
- Agent-Assisted Setup + {title}
{prompt} @@ -76,36 +88,40 @@ export function AgentSetupCallout({skill, platformName}: Props) { {description} Works with Cursor, Claude Code, Codex, and more. - - View docs ↗ - + {!instructions && ( + + View docs ↗ + + )}
-
setIsExpanded(e.currentTarget.open)} - > - - {isExpanded ? ( - - ) : ( - - )} - Install the full plugin - -
-

- Install the Sentry plugin to give your assistant every skill. See the{' '} - installation docs for more details. -

- - 
-              npx @sentry/agent-plugin install
-
- -
-
+ {!instructions && ( +
setIsExpanded(e.currentTarget.open)} + > + + {isExpanded ? ( + + ) : ( + + )} + Install the full plugin + +
+

+ Install the Sentry plugin to give your assistant every skill. See the{' '} + installation docs for more details. +

+ + 
+                npx @sentry/agent-plugin install
+
+ +
+
+ )}
); } diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts index 71a3e813dc990..15b0b589b8f88 100644 --- a/src/mdxComponents.ts +++ b/src/mdxComponents.ts @@ -1,3 +1,4 @@ +import {AgentMigrationCallout} from './components/agentMigrationCallout'; import {AgentSetupCallout} from './components/agentSetupCallout'; import {Alert} from './components/alert'; import {Arcade} from './components/arcade'; @@ -77,6 +78,7 @@ export function mdxComponents( wrapper: any = ({children}) => children ) { return { + AgentMigrationCallout, AgentSetupCallout, Alert, Arcade, From a54bf735de82ca15cb0d5ceb4683bc854c6b658e Mon Sep 17 00:00:00 2001 From: Sigrid <32902192+s1gr1d@users.noreply.github.com> Date: Wed, 23 Sep 2026 10:46:09 +0200 Subject: [PATCH 44/48] docs(nuxt): Update docs for v11 (#19466) I added the changes in two separate commits so it's easier to review. The first commit (add v10 versioned docs) is just a copy-paste. - Adds versioned docs for v10 (just a copy-paste) - Updates the current docs to mention the bundling on the server-config (no `--import`) - Renames "Installation Methods" in the sidebar to "Server-Side Initialization" so it works for both versions and we have a fallback Linear: https://linear.app/getsentry/issue/SDK-1510/nuxt-getting-started-manual-setup --- .../common/migration/v10-to-v11/index.mdx | 23 +- .../common/troubleshooting/index.mdx | 25 +- .../javascript/guides/nuxt/index.mdx | 23 +- .../javascript/guides/nuxt/index__v10.x.mdx | 140 +++++ .../{cli-import.mdx => cli-import__v10.x.mdx} | 2 +- ...c-import.mdx => dynamic-import__v10.x.mdx} | 4 +- .../javascript/guides/nuxt/install/index.mdx | 98 +++- .../guides/nuxt/install/index__v10.x.mdx | 14 + ....mdx => limited-server-tracing__v10.x.mdx} | 2 +- .../guides/nuxt/manual-setup__v10.x.mdx | 521 ++++++++++++++++++ .../nuxt-auto-inject-deprecated.mdx | 17 + .../nuxt-server-config-bundled.mdx | 26 + .../nuxt-server-instrument-file.mdx | 6 +- middleware.ts | 2 +- .../javascript.nuxt.mdx | 18 +- .../javascript.nuxt__v10.x.mdx | 35 ++ redirects.js | 29 +- 17 files changed, 939 insertions(+), 46 deletions(-) create mode 100644 docs/platforms/javascript/guides/nuxt/index__v10.x.mdx rename docs/platforms/javascript/guides/nuxt/install/{cli-import.mdx => cli-import__v10.x.mdx} (95%) rename docs/platforms/javascript/guides/nuxt/install/{dynamic-import.mdx => dynamic-import__v10.x.mdx} (90%) create mode 100644 docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx rename docs/platforms/javascript/guides/nuxt/install/{limited-server-tracing.mdx => limited-server-tracing__v10.x.mdx} (91%) create mode 100644 docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx create mode 100644 includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx create mode 100644 includes/migration/javascript-v11/nuxt-server-config-bundled.mdx create mode 100644 platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index e04359f9c8a81..29973b4b7bc3e 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -1247,12 +1247,33 @@ The generated client snippet always includes the Replay integration with default `public/instrument.server.[ext]` is no longer supported. Move the file next to `nuxt.config.ts` and rename it to `sentry.server.config.[ext]`. Its contents don't change. -After the rename, the SDK emits `.output/server/sentry.server.config.mjs` for you to preload: +After the rename, the SDK [bundles the file](#the-nuxt-server-config-is-bundled) into the Nitro server build. You no longer preload it with `--import`. + +### The Nuxt Server Config Is Bundled + +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. Instrumentation happens at build time, so you no longer preload the config file. Remove the `--import` flag from your start commands: ```bash +# Before node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev + +# After +node .output/server/index.mjs +nuxt dev ``` +Existing start commands continue to work. The SDK still writes a file to the old path, but this file only prints a reminder to remove the flag. If you preload your own file that calls `Sentry.init()`, that call initializes the SDK and the bundled initialization is skipped. + +The SDK doesn't initialize while Nitro prerenders pages at build time, so builds no longer send events. + +Because a preload is no longer needed, these Nuxt module options are deprecated and will be removed in the next major version. Remove them from the `sentry` options in your `nuxt.config.ts`: + +- `autoInjectServerSentry` (`"top-level-import"` and `"experimental_dynamic-import"`) +- `experimental_entrypointWrappedFunctions` + +While `autoInjectServerSentry` is set, the SDK uses that mode instead of the bundled initialization and prints a deprecation warning during the build. To learn more, see [Server-Side Installation](/platforms/javascript/guides/nuxt/install/). + diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index bc3584dbddbc1..c66d2df35f4ad 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -553,6 +553,8 @@ shamefully-hoist=true + This applies to SDK version 10 and earlier. Version 11 and above don't use `import-in-the-middle`. + After adding `sentry.server.config.ts` and building the project, you might get an error like this: `Failed to register ESM hook import-in-the-middle/hook.mjs`. You can add an override (npm/pnpm) or a resolution (yarn) for `@vercel/nft` to fix this. This will add the `hook.mjs` file to your build output. See the [underlying issue in the Nitro project](https://github.com/nitrojs/nitro/issues/2703). @@ -584,6 +586,8 @@ shamefully-hoist=true + This applies to SDK version 10 and earlier. Version 11 and above don't use `import-in-the-middle`. + Sentry injects `import "import-in-the-middle/hook.mjs"` in your server entry. This import acts as a hint for node bundlers to really include this file. As pnpm implements a strict dependency isolation, this import might cause problems. Per default, `shamefully-hoist` is `false` ([pnpm docs here](https://pnpm.io/next/npmrc#shamefully-hoist)) and this prevents accessing non-declared dependencies. @@ -596,14 +600,27 @@ shamefully-hoist=true - Nuxt builds the server-side Nitro application as ES Modules, which introduces limitations for server-side tracing during development. - Currently, trace collection is only supported when building and running the application. Development mode (`nuxt dev`) is currently not supported. + The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts, in production and in development mode. + Read more about this in Server-Side Installation. + + If the server side doesn't send events, check the following: - When running the build output, Sentry needs to be initialized before running the rest of the application. This is done automatically, but might not work for your use case. - Read more about this in installation methods. + - The `sentry.server.config.ts` file is in the root of your project, next to `nuxt.config.ts`. + - Enable `debug` in the `sentry` options of your `nuxt.config.ts`. The SDK then prints a message during the build when it bundles the server config. + - Remove the deprecated `autoInjectServerSentry` option, so that the SDK uses the bundled initialization. + - If you're using a Cloudflare Nitro preset, the SDK doesn't use `sentry.server.config.ts`. Use the [Cloudflare Nitro plugin](/platforms/javascript/guides/cloudflare/frameworks/nuxt/) instead. + - The SDK doesn't initialize while Nitro prerenders pages at build time, so builds don't send events. --- + **SDK version 10 and earlier** + + Nuxt builds the server-side Nitro application as ES Modules, which introduces limitations for server-side tracing during development. + Trace collection is only supported when building and running the application. Development mode (`nuxt dev`) is not supported. + + When running the build output, Sentry needs to be initialized before running the rest of the application. + Read more about this in the [installation methods for version 10](/platforms/javascript/guides/nuxt/install__v10.x/). + We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). For the time being, you can add the following overrides to your application: diff --git a/docs/platforms/javascript/guides/nuxt/index.mdx b/docs/platforms/javascript/guides/nuxt/index.mdx index f28e244552bc4..ce1cc6c33dff3 100644 --- a/docs/platforms/javascript/guides/nuxt/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/index.mdx @@ -48,12 +48,7 @@ To test the server side as well, refer to the "Verify" section in the [Manual se To test Sentry, you can run your Nuxt application in either production or development mode. We **recommend testing in production mode** as it most closely resembles your deployed application's environment. - - By default, the SDK will add the server config as `sentry.server.config.mjs` - to the build. To find the exact path to this file, enable `debug` mode in your - Sentry configuration within `nuxt.config.ts`. Sentry will then print the exact - path during the build process. - +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. To learn more, see Server-Side Installation. ### Run in Production Mode (Recommended) @@ -61,14 +56,14 @@ We **recommend testing in production mode** as it most closely resembles your de -After building with `nuxi build`, run your project and make sure to load Sentry on the server side by explicitly adding it via `--import` (read more about this flag in [Installation Methods](/platforms/javascript/guides/nuxt/install)). +Build your project with `nuxi build`, then start the server. -``` +```bash # Start your app after building your project with `nuxi build` -node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +node .output/server/index.mjs ``` @@ -81,16 +76,16 @@ node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs -The server config file is generated in the `.nuxt` directory the first time you run `nuxt dev`. If you delete your `.nuxt` directory, you'll need to run `nuxt dev` once without the `NODE_OPTIONS` variable to regenerate it. +Sentry also monitors the server side during development. Start the dev server as usual. -If you only want to use Sentry on the client-side or only need basic error monitoring on the server side, you can omit the `--import` flag when running your application. +Spans from some libraries, such as database clients, can be missing in development mode. +Errors and request traces always work. To learn more, see Development Mode. -``` -# Run the dev server with the --import flag after running `nuxt dev` once (without the flag) -NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev +```bash +nuxt dev ``` diff --git a/docs/platforms/javascript/guides/nuxt/index__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/index__v10.x.mdx new file mode 100644 index 0000000000000..cca2c3cb97831 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/index__v10.x.mdx @@ -0,0 +1,140 @@ +--- +title: Nuxt +description: Learn how to set up and configure Sentry in your Nuxt application using the installation wizard, capture your first errors, and view them in Sentry. +sdk: sentry.javascript.nuxt +categories: + - javascript + - browser + - server +--- + + + + + +## Install + + + + + + + + + +## Avoid Ad Blockers With Tunneling (Optional) + + + +## Control the Data You Send to Sentry (Optional) + + + +## Verify Your Setup + +The `sentry init` command checks the integration files it creates or modifies before it finishes. To confirm runtime events are reaching Sentry, start your Nuxt app, exercise the parts of your app that should send events, and then check your Sentry project. + +If you used the Nuxt installation wizard instead, you can also verify your setup with the example page or component it creates. + + +The wizard creates a `SentryErrorButton` component when it fails to add an example page to your project. This usually happens if you don't have a `app.vue` file or if that file does not contain the `NuxtPage` component. To verify your setup, follow these steps before continuing with the next section, "View Captured Data in Sentry": + +1. Add the `SentryErrorButton` component to a page and open it in your browser. For most Nuxt applications, this will be at localhost. +2. Click the "Throw Sample Error" button, which triggers an error and starts a performance trace on the client side. + +To test the server side as well, refer to the "Verify" section in the [Manual setup guide](/platforms/javascript/guides/nuxt/manual-setup__v10.x/). + + + +To test Sentry, you can run your Nuxt application in either production or development mode. +We **recommend testing in production mode** as it most closely resembles your deployed application's environment. + + + By default, the SDK will add the server config as `sentry.server.config.mjs` + to the build. To find the exact path to this file, enable `debug` mode in your + Sentry configuration within `nuxt.config.ts`. Sentry will then print the exact + path during the build process. + + +### Run in Production Mode (Recommended) + + + + + +After building with `nuxi build`, run your project and make sure to load Sentry on the server side by explicitly adding it via `--import` (read more about this flag in [Installation Methods](/platforms/javascript/guides/nuxt/install__v10.x/)). + + + + +``` +# Start your app after building your project with `nuxi build` +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +``` + + + + + +### Run in Development Mode + + + + + +The server config file is generated in the `.nuxt` directory the first time you run `nuxt dev`. If you delete your `.nuxt` directory, you'll need to run `nuxt dev` once without the `NODE_OPTIONS` variable to regenerate it. + +If you only want to use Sentry on the client-side or only need basic error monitoring on the server side, you can omit the `--import` flag when running your application. + + + + +``` +# Run the dev server with the --import flag after running `nuxt dev` once (without the flag) +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev +``` + + + + + +If you used the Nuxt installation wizard, after building and running your project: + +1. Open the example page `/sentry-example-page` in your browser. For most Nuxt applications, this will be at localhost. +2. Click the "Throw sample error" button. This triggers two errors: + - a frontend error + - an error within the API route + +Sentry captures both of these errors for you. Additionally, the button click starts a performance trace to measure the time it takes for the API request to complete. + + + +### View Captured Data in Sentry + +Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). + + + + + +## Next Steps + +At this point, you should have integrated Sentry into your Nuxt application and should already be sending error and performance data to your Sentry project. + +Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/javascript/guides/nuxt/usage/) +- Continue to [customize your configuration](/platforms/javascript/guides/nuxt/configuration/) +- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts +- Learn how to [track your Vue components or your Pinia store](/platforms/javascript/guides/nuxt/features/) +- Learn how to [add support for different Nitro deployment presets](/platforms/javascript/guides/nuxt/features/nitro-deployment-presets/) (like Cloudflare) + + + +- If you encountered issues with our installation wizard, try [setting up Sentry manually](/platforms/javascript/guides/nuxt/manual-setup__v10.x/) +- [Get support](https://www.sentry.help/en/) + + + + diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import__v10.x.mdx similarity index 95% rename from docs/platforms/javascript/guides/nuxt/install/cli-import.mdx rename to docs/platforms/javascript/guides/nuxt/install/cli-import__v10.x.mdx index c36bd401a2362..12673c5f5e8d8 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import__v10.x.mdx @@ -18,7 +18,7 @@ This will register Sentry's [loader hook](https://nodejs.org/api/module.html#cus - At this time, it isn't possible to properly configure `--import` in **Vercel**. If any of those points apply to you, you cannot use the `--import` flag to initialize Sentry on the server-side. -Check out the guide for using limited server tracing instead. +Check out the guide for using [limited server tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/) instead. ## Initializing Sentry with `--import` diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x.mdx similarity index 90% rename from docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx rename to docs/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x.mdx index 8a09ed9890077..935a720fb314c 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x.mdx @@ -9,7 +9,7 @@ description: "Learn about how the Nuxt SDK leverages dynamic input() in the buil This installation method doesn't work with more recent versions of Nuxt/Nitro. - We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + We recommend reading the guide for installing the SDK with the [CLI flag `--import`](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) or [limited server tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/) The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. @@ -48,7 +48,7 @@ As a temporary workaround, you can add the following overrides in your applicati } ``` -You can also check out the guide for installing the SDK with the CLI flag `--import` or limited-server-tracing. +You can also check out the guide for installing the SDK with the [CLI flag `--import`](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) or [limited-server-tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/). ## Initializing Sentry with Dynamic `import()` diff --git a/docs/platforms/javascript/guides/nuxt/install/index.mdx b/docs/platforms/javascript/guides/nuxt/install/index.mdx index b9e212e5ae87d..298c08d02db09 100644 --- a/docs/platforms/javascript/guides/nuxt/install/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/index.mdx @@ -1,12 +1,98 @@ --- -title: Installation Methods +title: Server-Side Installation sidebar_order: 1.5 -description: "Review our alternate installation methods." +description: "Learn how the Nuxt SDK initializes Sentry on the server side, and how to upgrade to version 11." --- -Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). -Those customization hooks need to be registered before the rest of the application. + + This page applies to SDK version `11.0.0` and above. Version 10 and earlier + need the Node `--import` flag. For those versions, see the [installation + methods for version 10](/platforms/javascript/guides/nuxt/install__v10.x/). + -To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: +## How the SDK Initializes on the Server - +The SDK bundles your `sentry.server.config.ts` file into the Nitro server build. A Nitro plugin that the SDK generates imports this file, so `Sentry.init()` runs when the server starts. + +The SDK adds its instrumentation at build time. Because of this, Sentry doesn't have to load before the rest of your application. You start your application as usual, in production and in development mode, and on hosts where you can't set Node CLI flags, such as Vercel or Netlify. + +To confirm that the SDK bundled your server config, enable `debug` in the `sentry` options of your `nuxt.config.ts`. The SDK then prints a message during the build. + +### Development Mode + +In `nuxt dev`, spans from some libraries can be missing. Errors and request traces always work, and production builds are not affected. + +In a production build, Sentry prepares your libraries for tracing while Nuxt builds your app. +The dev server has no build step, so Sentry can only prepare a library that loads after Sentry starts. +Nuxt loads most libraries before that, for example your database client. + +Some libraries send tracing data on their own through [tracing channels](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). +Sentry always picks up this data, also in development mode. +This includes recent versions of `ioredis`, `redis`, `mysql2`, and `mongoose`. + +To see all spans, test with a production build: run `nuxi build`, then start your app. + +### Prerendering + +The SDK doesn't initialize Sentry while Nitro prerenders your pages at build time. As a result, builds don't send events to Sentry, and prerendered HTML doesn't contain trace meta tags. + +### Cloudflare + +With a Cloudflare Nitro preset, the SDK doesn't use `sentry.server.config.ts`. Set up the SDK with the [Cloudflare Nitro plugin](/platforms/javascript/guides/cloudflare/frameworks/nuxt/) instead. + +## Upgrade to SDK Version 11 + +### Remove the `--import` Flag + +Remove the `--import` flag from the command that starts your production build: + +```bash +# Before +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs + +# After +node .output/server/index.mjs +``` + +Do the same in development mode: + +```bash +# Before +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev + +# After +nuxt dev +``` + +Also remove the flag from the `NODE_OPTIONS` environment variable of your hosting provider, if you set it there. + +Existing start commands continue to work. The SDK still writes a file to `.output/server/sentry.server.config.mjs`, but this file only prints a reminder to remove the flag. + +If you preload your own file that calls `Sentry.init()`, that call initializes the SDK. The SDK then skips the bundled initialization and prints a notice. + +### Deprecated Options + +Because a preload is no longer necessary, the following `sentry` module options are deprecated. They continue to work in version 11 and will be removed in the next major version. + +| Option | Replacement | +| ------------------------------------------------------- | ------------------------------------------- | +| `autoInjectServerSentry: "top-level-import"` | Remove the option. The default replaces it. | +| `autoInjectServerSentry: "experimental_dynamic-import"` | Remove the option. The default replaces it. | +| `experimental_entrypointWrappedFunctions` | Remove the option. It has no replacement. | + +If you set `autoInjectServerSentry`, the SDK uses that mode instead of the bundled initialization and prints a deprecation warning during the build. Remove the option to use the bundled initialization: + +```typescript {filename:nuxt.config.ts} +// Before +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + sentry: { + autoInjectServerSentry: "top-level-import", + }, +}); + +// After +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], +}); +``` diff --git a/docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx new file mode 100644 index 0000000000000..8d30b07ff5253 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx @@ -0,0 +1,14 @@ +--- +title: Installation Methods +sidebar_order: 1.5 +description: "Review our alternate installation methods." +--- + +Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). +Those customization hooks need to be registered before the rest of the application. + +To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: + +- [`--import` CLI flag (default)](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) +- [Limited Server Tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/) +- [Dynamic Import (experimental)](/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x/) diff --git a/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx b/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x.mdx similarity index 91% rename from docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx rename to docs/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x.mdx index 97665847a8761..7a0f2a0691a33 100644 --- a/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x.mdx @@ -7,7 +7,7 @@ description: "Learn how to set up the Nuxt SDK with limited server tracing by ad ## Understanding Limited Server Tracing Sentry needs to be initialized before the rest of the application runs. -If the default way of adding an `--import` CLI flag doesn't work for you, +If the default way of adding an [`--import` CLI flag](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) doesn't work for you, enable the SDK to add a top-level `import`. The automatically added top-level `import` will then import the Sentry server-side config at the top of the Nuxt server entry file. diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx new file mode 100644 index 0000000000000..127f7c256d04a --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx @@ -0,0 +1,521 @@ +--- +title: Manual Setup +sidebar_order: 1 +description: "Learn how to manually set up Sentry in your Nuxt app and capture your first errors." +--- + + + Looking for automatic setup with `sentry init` or the Nuxt wizard? Follow the + [Nuxt quickstart](/platforms/javascript/guides/nuxt__v10.x/) instead. + Continue with this guide to set up Sentry manually. + + +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- Nuxt version `3.7.0` or above (`3.14.0`+ recommended) + + + Add the following overrides: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { + "overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" + } +} +``` + + + + + +## Install + +Choose the features you want to configure, and this guide will show you how: + + + + + + + +### Install the Sentry SDK + + + + + +Run the command for your preferred package manager to add the Sentry SDK to your application: + + + + +```bash {tabTitle:npm} +npm install @sentry/nuxt --save +``` + +```bash {tabTitle:yarn} +yarn add @sentry/nuxt +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/nuxt +``` + + + + + +## Configure + +### Apply Instrumentation to Your App + + + + + +Add the Sentry Nuxt module to your `nuxt.config.ts` file: + + + + +```javascript {filename:nuxt.config.ts} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], +}); +``` + + + + + +### Configure Client-Side Sentry + + + + + +Add a `sentry.client.config.ts` file to the root of your project (this is probably the same level as the `package.json`). In this file, import and initialize Sentry, specifying any SDK options for the client: + + + + +```javascript {filename:sentry.client.config.ts} +import * as Sentry from "@sentry/nuxt"; + +Sentry.init({ + // If set up, you can use the Nuxt runtime config here + // dsn: useRuntimeConfig().public.sentry.dsn + // modify depending on your custom runtime config + dsn: "___PUBLIC_DSN___", + + // ___PRODUCT_OPTION_START___ session-replay + + // Replay may only be enabled for the client-side + integrations: [ + Sentry.replayIntegration(), + // ___PRODUCT_OPTION_START___ user-feedback + Sentry.feedbackIntegration({ + // Additional SDK configuration goes in here, for example: + colorScheme: "system", + }), + // ___PRODUCT_OPTION_END___ user-feedback + ], + // ___PRODUCT_OPTION_END___ session-replay + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ session-replay + + // Capture Replay for 10% of all sessions, + // plus for 100% of sessions with an error + // Learn more at + // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ session-replay +}); +``` + + + + + + + +We recommend you store your Sentry [Data Source Name](/concepts/key-terms/dsn-explainer/) (DSN) in an environment variable and configure it via the Nuxt runtime config. + +This allows you to access the DSN using `useRuntimeConfig().public.sentry.dsn`. + + + + +```javascript {filename:nuxt.config.ts} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + runtimeConfig: { + public: { + sentry: { + dsn: process.env.NUXT_PUBLIC_SENTRY_DSN, // Use a public environment variable for the DSN + }, + }, + }, +}); +``` + + + + + +### Configure Server-Side Sentry + + + + + +Add a `sentry.server.config.ts` file to the root of your project and initialize Sentry in it. + +We recommend you store your Sentry [Data Source Name](/concepts/key-terms/dsn-explainer/) (DSN) in an environment variable. + + + + +```javascript {filename:sentry.server.config.ts} +import * as Sentry from "@sentry/nuxt"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance +}); +``` + + + + + + + + + + +Since Sentry on the server side needs to be loaded before `useRuntimeConfig()` is fully available, environment variables are only accessible via `process.env`. To make sure your environment variables are available, use one of these methods: + + + + +Load environment variables from your `.env` file when starting the server: + +```bash {tabTitle: node} +node --env-file=.env .output/server/index.mjs +``` + +or use the `dotenv` package: + +```javascript {tabTitle: Server Config} {filename:sentry.server.config.ts} {1,3} +import dotenv from "dotenv"; + +dotenv.config(); + +// ... rest of the file +``` + + + + + + + + + + +**Sentry's server-side monitoring doesn't work in development mode**. To enable it, you first need to build your application and then load the Sentry server-side config using the `--import` flag when running your application. + +Check out the [`--import` CLI flag](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) docs for setup instructions. + + + + +``` +# Start your app after building your project with `nuxi build` +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +``` + + + + + + +### Add Readable Stack Traces With Source Maps (Optional) + + + + + +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slugs in the `sentry` options inside your configuration file: + +These `sentry` options only affect the **build time** of the SDK. + + + + +```javascript {filename:nuxt.config.ts} {3-10} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + sentry: { + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + // store your auth token in an environment variable + authToken: process.env.SENTRY_AUTH_TOKEN, + }, +}); +``` + + + + + + + +To keep your auth token secure, always store it in an environment variable instead of directly in your files: + + + + + + +```bash {filename:.env} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + + + + + +#### Enable Client-Side Source Maps + + + + + +While Nuxt generates source maps on the server side by default, you need to explicitly enable client-side source maps in your Nuxt configuration. + +The `hidden` option enables source map generation while preventing source map reference comments that would normally appear at the end of each generated file in the build output. + + + + +```javascript {filename:nuxt.config.ts} {2} +export default defineNuxtConfig({ + sourcemap: { client: "hidden" }, +}); +``` + + + + + +### Avoid Ad Blockers With Tunneling (Optional) + + + +### Control the Data You Send to Sentry (Optional) + + + +## Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +### Issues + + + + + +To verify that Sentry captures errors and creates issues in your Sentry project, create a test page with a button. + + + + + + +```html {tabTitle:Vue} {filename:pages/example-error.vue} + + + +``` + + + + + + +### Tracing + + + + + +To test tracing, create a test API route `server/api/sentry-example.get.ts`: + + + + +```js {tabTitle:Nitro} {filename:server/api/sentry-example.get.ts} +export default defineEventHandler((event) => { + throw new Error("Sentry Example API Route Error"); +}); +``` + + + + + + + +Then update the test page by including a new button that executes a function to fetch your API route: + + + + +```html {tabTitle:Vue} {filename:pages/example-error.vue} + + + +``` + + + + + + + + + + + + + + + + + Once you have your test code in place, open the page in a browser and click + the button to trigger an error. + + + + +Once you have your test code in place, you need to build your project since Sentry's **server-side monitoring doesn't work in development** mode. + + +Then start your app and make sure to load Sentry on the server side by explicitly adding the Sentry server config in the build output via [`--import`](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/). + + +After running your project, open your test page in a browser and click the buttons. + + + +### View Captured Data in Sentry + +Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). + + + + + +## Next Steps + +At this point, you should have integrated Sentry into your Nuxt application and should already be sending data to your Sentry project. + +Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/javascript/guides/nuxt/usage/) +- Continue to [customize your configuration](/platforms/javascript/guides/nuxt/configuration/) +- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts +- Learn how to [track your Vue components or your Pinia store](/platforms/javascript/guides/nuxt/features/) +- Learn how to [add support for different Nitro deployment presets](/platforms/javascript/guides/nuxt/features/nitro-deployment-presets/) (like Cloudflare) + + + +- If you encountered issues with setting up Sentry manually, [try our installation wizard](/platforms/javascript/guides/nuxt__v10.x/) +- Find various support topics in troubleshooting +- Review alternative [installation methods](/platforms/javascript/guides/nuxt/install__v10.x/) +- [Get support](https://www.sentry.help/en/) + + + + + diff --git a/includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx b/includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx new file mode 100644 index 0000000000000..23f975213a8af --- /dev/null +++ b/includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx @@ -0,0 +1,17 @@ +--- +id: nuxt-auto-inject-deprecated +title: "`autoInjectServerSentry` and `experimental_entrypointWrappedFunctions` are deprecated" +phase: cleanup +category: behavior +severity: informational +frameworks: [nuxt] +platformCategory: all +order: 60 +--- + +The SDK [bundles the server config](#nuxt-server-config-bundled) by default, so the Nuxt module options that inject it are no longer needed. They are deprecated and will be removed in the next major version. Remove them from the `sentry` options in your `nuxt.config.ts`: + +- `autoInjectServerSentry` (`"top-level-import"` and `"experimental_dynamic-import"`) +- `experimental_entrypointWrappedFunctions` + +While `autoInjectServerSentry` is set, the SDK uses that mode instead of the bundled initialization and prints a deprecation warning during the build. diff --git a/includes/migration/javascript-v11/nuxt-server-config-bundled.mdx b/includes/migration/javascript-v11/nuxt-server-config-bundled.mdx new file mode 100644 index 0000000000000..8e1d1bd761c67 --- /dev/null +++ b/includes/migration/javascript-v11/nuxt-server-config-bundled.mdx @@ -0,0 +1,26 @@ +--- +id: nuxt-server-config-bundled +title: "The Nuxt server config is bundled, `--import` is no longer needed" +phase: packages +category: behavior +severity: behavior-change +frameworks: [nuxt] +platformCategory: all +order: 87 +--- + +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. Instrumentation happens at build time, so you no longer preload the config file. Remove the `--import` flag from your start commands: + +```bash +# Before +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev + +# After +node .output/server/index.mjs +nuxt dev +``` + +Existing start commands continue to work. The SDK still writes a file to the old path, but this file only prints a reminder to remove the flag. If you preload your own file that calls `Sentry.init()`, that call initializes the SDK and the bundled initialization is skipped. + +The SDK doesn't initialize while Nitro prerenders pages at build time, so builds no longer send events. diff --git a/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx b/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx index 60f4db28168c5..81f957f844b95 100644 --- a/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx +++ b/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx @@ -11,8 +11,4 @@ order: 85 `public/instrument.server.[ext]` is no longer supported. Move the file next to `nuxt.config.ts` and rename it to `sentry.server.config.[ext]`. Its contents don't change. -After the rename, the SDK emits `.output/server/sentry.server.config.mjs` for you to preload: - -```bash -node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs -``` +After the rename, the SDK [bundles the file](#nuxt-server-config-bundled) into the Nitro server build. You no longer preload it with `--import`. diff --git a/middleware.ts b/middleware.ts index ac51067f4848e..0ff9e45010b5e 100644 --- a/middleware.ts +++ b/middleware.ts @@ -467,7 +467,7 @@ const USER_DOCS_REDIRECTS: Redirect[] = [ }, { from: '/platforms/javascript/guides/nuxt/install/top-level-import/', - to: '/platforms/javascript/guides/nuxt/install/limited-server-tracing/', + to: '/platforms/javascript/guides/nuxt/install/', }, { from: '/account/early-adopter-features/discord/', diff --git a/platform-includes/getting-started-complete/javascript.nuxt.mdx b/platform-includes/getting-started-complete/javascript.nuxt.mdx index 46bb9bfabe540..9ca4d128758db 100644 --- a/platform-includes/getting-started-complete/javascript.nuxt.mdx +++ b/platform-includes/getting-started-complete/javascript.nuxt.mdx @@ -234,16 +234,16 @@ dotenv.config(); -**Sentry's server-side monitoring doesn't work in development mode**. To enable it, you first need to build your application and then load the Sentry server-side config using the `--import` flag when running your application. +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. This works in production and in development mode. -Check out the `--import` CLI flag docs for setup instructions. +To learn more, see [Server-Side Installation](/platforms/javascript/guides/nuxt/install/). -``` +```bash # Start your app after building your project with `nuxi build` -node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +node .output/server/index.mjs ``` @@ -509,11 +509,15 @@ Then update the test page by including a new button that executes a function to -Once you have your test code in place, you need to build your project since Sentry's **server-side monitoring doesn't work in development** mode. + + +Once you have your test code in place, build and run your project. + + -Then start your app and make sure to load Sentry on the server side by explicitly adding the Sentry server config in the build output via{" "} `--import`. +Once you have your test code in place, run your project in production mode (`nuxi build`, then `node .output/server/index.mjs`) or in development mode (`nuxt dev`). @@ -555,7 +559,7 @@ Now's a good time to customize your setup and look into more advanced topics. Ou - If you encountered issues with setting up Sentry manually, [try our installation wizard](/platforms/javascript/guides/nuxt/) - Find various support topics in troubleshooting -- Review alternative installation methods +- Learn how the SDK initializes on the server side - [Get support](https://www.sentry.help/en/) diff --git a/platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx b/platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx new file mode 100644 index 0000000000000..2d7cc44809687 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx @@ -0,0 +1,35 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- Nuxt version `3.7.0` or above (`3.14.0`+ recommended) + + + Add the following overrides: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { + "overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" + } +} +``` + + diff --git a/redirects.js b/redirects.js index c65c4da64712c..9edbd5d4a8de8 100644 --- a/redirects.js +++ b/redirects.js @@ -981,6 +981,26 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/aws-lambda/cjs-npm__v9.x/', destination: '/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x/', }, + { + // Previous Nuxt setup method (--import) + source: '/platforms/javascript/guides/nuxt/install/cli-import/', + destination: '/platforms/javascript/guides/nuxt/install/', + }, + { + // Previous Nuxt setup method (top-level import) + source: '/platforms/javascript/guides/nuxt/install/limited-server-tracing/', + destination: '/platforms/javascript/guides/nuxt/install/', + }, + { + // Previous Nuxt setup method (dynamic import) + source: '/platforms/javascript/guides/nuxt/install/dynamic-import/', + destination: '/platforms/javascript/guides/nuxt/install/', + }, + { + // The Nuxt SDK links to this path in its Cloudflare build warning + source: '/platforms/javascript/guides/nuxt/install/cloudflare-workers/', + destination: '/platforms/javascript/guides/cloudflare/frameworks/nuxt/', + }, { source: '/platforms/javascript/guides/connect/', destination: '/platforms/javascript/guides/node/', @@ -2373,8 +2393,7 @@ const userDocsRedirects = [ destination: '/platforms/javascript/guides/cloudflare.md', }, { - source: - '/platforms/javascript/guides/cloudflare/features/nodejs-compat/:path*', + source: '/platforms/javascript/guides/cloudflare/features/nodejs-compat/:path*', destination: '/platforms/javascript/guides/cloudflare/', }, // honoIntegration was removed in v11 in favor of the @sentry/hono SDK. @@ -2710,8 +2729,10 @@ const userDocsRedirects = [ destination: '/platforms/javascript/configuration/integrations/eventfilters/', }, { - source: '/platforms/javascript/guides/:guide/configuration/integrations/inboundfilters/', - destination: '/platforms/javascript/guides/:guide/configuration/integrations/eventfilters/', + source: + '/platforms/javascript/guides/:guide/configuration/integrations/inboundfilters/', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/eventfilters/', }, // agent-tracing-browser merged into agent-tracing { From a3bc96cf7f865280d9ab46c0ab2eb622581bf6d7 Mon Sep 17 00:00:00 2001 From: Francesco Gringl-Novy Date: Wed, 23 Sep 2026 11:47:11 +0200 Subject: [PATCH 45/48] feat(node): Update node docs for v11 (#19577) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Updates the Node.js guides (and the other Node-based server guides) for SDK v11, focusing on the quickstart and the installation methods. In v11, `--import` works for both ESM and CommonJS, bundler plugins allow build-time instrumentation without `--import`, and instrumentation no longer relies on `import-in-the-middle`. The docs are restructured to match. **Quickstart (getting-started)** - Simplified the Node quickstart to a single `--import` step that covers both CommonJS and ESM (tabbed), removing the old CJS-vs-ESM "Apply Instrumentation" split and the surrounding `SplitLayout` scaffolding. - Minor cleanup of the shared `getting-started-config` snippet. **Installation methods** - Added a new **With a Bundler** method: instrument dependencies at build time with the Sentry bundler plugin (Vite/Rollup/webpack/esbuild) and a top-level import, so you can start your app with a plain `node` command and no `--import` flag. Surfaced at the top of the install methods. - Removed the standalone **ESM (MJS)** and **CommonJS (CJS)** pages — `--import` now works for both, so this guidance lives in the quickstart. Old URLs redirect to the quickstart. - Renamed **ESM without CLI Flag** → **Deferred Entrypoint** and trimmed it to just that pattern; split the **Single Executable Applications (SEA)** content out into its own page. - Reworked **Late Initialization** and aligned the filtering of all methods. - Made platform filtering consistent: install methods now show only on the relevant server frameworks (node, express, fastify, hapi, hono, koa) and are hidden for nitro, nestjs, azure-functions, serverless/edge runtimes (aws-lambda, gcp-functions, firebase, cloudflare, bun, deno, elysia), and the AI-framework guides (eve, mastra). Removed nestjs's bespoke ESM/CJS/index install overrides. - Added redirects in `redirects.js` from all removed install pages to the relevant quickstart. **Troubleshooting** - Removed the four `import-in-the-middle` troubleshooting entries, since v11 instruments through diagnostics channels (`orchestrion`) instead of `import-in-the-middle`. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) --- .../javascript/common/install/bundler.mdx | 95 +++++++++++ .../javascript/common/install/commonjs.mdx | 28 ---- .../common/install/esm-without-import.mdx | 157 +++--------------- .../javascript/common/install/esm.mdx | 50 ------ .../javascript/common/install/index.mdx | 13 +- .../common/install/late-initialization.mdx | 29 ++-- .../single-executable-applications.mdx | 67 ++++++++ .../common/troubleshooting/index.mdx | 48 ------ .../guides/nestjs/install/commonjs.mdx | 17 -- .../nestjs/install/esm-without-import.mdx | 51 ------ .../javascript/guides/nestjs/install/esm.mdx | 41 ----- .../guides/nestjs/install/index.mdx | 30 ---- .../javascript.node.mdx | 2 - .../getting-started-node/javascript.mdx | 61 +------ redirects.js | 18 ++ 15 files changed, 233 insertions(+), 474 deletions(-) create mode 100644 docs/platforms/javascript/common/install/bundler.mdx delete mode 100644 docs/platforms/javascript/common/install/commonjs.mdx delete mode 100644 docs/platforms/javascript/common/install/esm.mdx create mode 100644 docs/platforms/javascript/common/install/single-executable-applications.mdx delete mode 100644 docs/platforms/javascript/guides/nestjs/install/commonjs.mdx delete mode 100644 docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx delete mode 100644 docs/platforms/javascript/guides/nestjs/install/esm.mdx delete mode 100644 docs/platforms/javascript/guides/nestjs/install/index.mdx diff --git a/docs/platforms/javascript/common/install/bundler.mdx b/docs/platforms/javascript/common/install/bundler.mdx new file mode 100644 index 0000000000000..e5d7d0e7a8a6e --- /dev/null +++ b/docs/platforms/javascript/common/install/bundler.mdx @@ -0,0 +1,95 @@ +--- +title: With a Bundler +sidebar_order: 1 +description: "Learn how to run your app with Sentry using a bundler plugin, without the --import flag." +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +If you build your server with a bundler, you can instrument your dependencies at build time with the Sentry bundler plugin instead of loading Sentry with the [`--import`](https://nodejs.org/api/cli.html#--importmodule) flag. Because the instrumentation is baked into your bundle, a plain top-level import of your instrument file is enough, and you can start your app with a regular `node` command, without the `--import` flag. + +Use this method if you can't pass a command line flag to the Node.js binary, for example when your start command is fixed by your platform or process manager. + +## 1. Create Your Instrument File + +Create a file named `instrument.(js|mjs)` in the root directory of your project that initializes Sentry: + + + +## 2. Add the Sentry Bundler Plugin + +Add the Sentry plugin for your bundler to your build configuration. The plugin instruments your dependencies at build time, so the SDK no longer depends on `Sentry.init()` running before your other imports. + +```javascript {tabTitle:Vite} {filename: vite.config.mjs} +import { sentryVitePlugin } from "@sentry/node/vite"; + +export default { + plugins: [sentryVitePlugin()], +}; +``` + +```javascript {tabTitle:Rollup} {filename: rollup.config.mjs} +import { sentryRollupPlugin } from "@sentry/node/rollup"; + +export default { + plugins: [sentryRollupPlugin()], +}; +``` + +```javascript {tabTitle:webpack} {filename: webpack.config.mjs} +import { sentryWebpackPlugin } from "@sentry/node/webpack"; + +export default { + plugins: [sentryWebpackPlugin()], +}; +``` + +```javascript {tabTitle:esbuild} {filename: build.mjs} +import { sentryEsbuildPlugin } from "@sentry/node/esbuild"; + +await esbuild.build({ + plugins: [sentryEsbuildPlugin()], +}); +``` + +## 3. Import Your Instrument File First + +Import `instrument.(js|mjs)` at the very top of your application's entry point, before any other imports: + +```javascript {filename: app.mjs} +// Import this first! +import "./instrument.mjs"; + +// Now import other modules +import express from "express"; + +// Your application code goes here +``` + +## 4. Run Your App + +Start your application as usual. No `--import` flag is required, because the instrumentation is already part of your bundle: + +```bash +node app.mjs +``` + +If you can't use a bundler, review our other [installation methods](../) for alternatives that don't rely on the `--import` flag. diff --git a/docs/platforms/javascript/common/install/commonjs.mdx b/docs/platforms/javascript/common/install/commonjs.mdx deleted file mode 100644 index a5901ff9b8415..0000000000000 --- a/docs/platforms/javascript/common/install/commonjs.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: CommonJS (CJS) -sidebar_order: 9 -description: "Learn about running Sentry in an CJS application." -supported: - - javascript.node - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. -CommonJS uses `require()` to load modules. Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. - -You need to create a file named `instrument.js` that imports and initializes Sentry: - - - -You need to require or import the `instrument.js` file before requiring any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application: - - diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx index 7b2e3946bbd0f..5cdf6b0619c43 100644 --- a/docs/platforms/javascript/common/install/esm-without-import.mdx +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -1,14 +1,22 @@ --- -title: ESM without CLI Flag -sidebar_order: 11 -description: "Learn about running Sentry in an ESM application, without the --import flag." -supported: - - javascript.node - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa +title: Deferred Entrypoint +sidebar_order: 3 +description: "Learn about running Sentry without the --import flag." +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs --- @@ -16,90 +24,11 @@ supported: [installation methods](../). -When running your application in ESM mode, you'll most likely want to follow the ESM instructions. +If you can neither run your application with `--import`, nor use a bundler, you can use a deferred entrypoint to run your application with Sentry. -If you can't pass the `--import` command line option, pick one of these instead: +This assumes you've already created an `instrument.mjs` file that calls `Sentry.init()`, as shown in the quickstart. -- Use a [bundler plugin with a top-level import](#bundler-plugin-and-top-level-import) if you bundle your server code. -- Use a [deferred entry point](#deferred-entry-point) if you don't bundle it. -- Use the [SEA bootstrap setup](#nodejs-single-executable-applications) if you build a Node.js Single Executable Application. - -All three need an `instrument.mjs` file that initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -## Why a Top-Level Import Alone Isn't Enough - -ESM evaluates every `import` in a file before it runs the first line of that file. So even when `import "./instrument.mjs"` is written above your other imports, the modules below it are already loaded by the time `Sentry.init()` runs, and the SDK can no longer wrap them. - -What that costs depends on the library. Express, Fastify, Hapi and Hono register their instrumentation at runtime, so they still report spans and errors. Koa does not: it loses its router and middleware spans, its route names, and, without the deprecated `Sentry.setupKoaErrorHandler(app)` call, its error capture. - -The patterns below work around this. The bundler plugin instruments your dependencies at build time, so the order no longer matters. The deferred entry point loads your application only after `Sentry.init()` has run. - -## Bundler Plugin and Top-Level Import - -Instrument your dependencies at build time with the Sentry bundler plugin, then import `instrument.mjs` at the top of your entry point. Because the instrumentation is baked into the bundle, it no longer depends on `Sentry.init()` running before the imports. - -The plugin ships for Vite, Rollup, webpack and esbuild: - -```javascript {tabTitle:Vite} {filename: vite.config.mjs} -import { sentryVitePlugin } from "@sentry/node/vite"; - -export default { - plugins: [sentryVitePlugin()], -}; -``` - -```javascript {tabTitle:Rollup} {filename: rollup.config.mjs} -import { sentryRollupPlugin } from "@sentry/node/rollup"; - -export default { - plugins: [sentryRollupPlugin()], -}; -``` - -```javascript {tabTitle:webpack} {filename: webpack.config.mjs} -import { sentryWebpackPlugin } from "@sentry/node/webpack"; - -export default { - plugins: [sentryWebpackPlugin()], -}; -``` - -```javascript {tabTitle:esbuild} {filename: build.mjs} -import { sentryEsbuildPlugin } from "@sentry/node/esbuild"; - -await esbuild.build({ - plugins: [sentryEsbuildPlugin()], -}); -``` - -Then import your instrument file first: - -```javascript {filename: app.mjs} -// Import this first! -import "./instrument.mjs"; - -// Now import other modules -import express from "express"; - -// Your application code goes here -``` - -## Deferred Entry Point - -Without a bundler, split the entry point in two. The static import runs `Sentry.init()`, and the dynamic `import()` loads your application afterwards, so your application's modules are wrapped: +Split the entrypoint in two. The static import runs `Sentry.init()`, and the dynamic `import()` loads your application afterwards, so your application's modules are wrapped: ```javascript {filename: main.mjs} import "./instrument.mjs"; @@ -112,47 +41,3 @@ Your application code stays in `app.mjs` and needs no changes. Start it as usual ```bash node main.mjs ``` - -## Node.js Single Executable Applications - -Node.js Single Executable Applications (SEA) may not load your Sentry instrumentation early enough, so you need to package a small bootstrap file as the SEA main instead of packaging your app entrypoint directly. - -The embedded SEA main should only load a filesystem bootstrap file next to the -executable: - -```javascript {filename: sea-main.cjs} -const { createRequire } = require("node:module"); - -createRequire(__filename)("./sea-bootstrap.cjs"); -``` - -The filesystem bootstrap imports Sentry first, then imports your real app -entrypoint: - -```javascript {filename: sea-bootstrap.cjs} -async function startApp() { - await import("./instrument.mjs"); - await import("./app.mjs"); -} - -startApp(); -``` - -This is the deferred entry point pattern above, packaged for SEA. Keep your Sentry setup in `instrument.mjs`. - -Then configure SEA to use `sea-main.cjs` as its main script: - -```json {filename: sea-config.json} -{ - "main": "sea-main.cjs", - "output": "sea-prep.blob", - "disableExperimentalSEAWarning": true, - "useSnapshot": false -} -``` - -Keep `sea-bootstrap.cjs`, `instrument.mjs`, and `app.mjs` available on the filesystem next to the executable. - -This setup lets the Sentry SDK register ESM instrumentation hooks before your application imports instrumented modules, such as Express or database clients. Your instrumentation file and app entrypoint can stay ESM. The verified bootstrap pattern shown here uses CommonJS only for the small SEA entry files. - -Node.js SEA support is still evolving, including how embedded ESM entrypoints and module loading are configured. The embedded SEA main may not be able to load filesystem modules with `import()` directly, so the example above uses `module.createRequire()` to bridge from the embedded main to a normal filesystem bootstrap. The important requirement is startup order: load Sentry before loading the application modules you want Sentry to instrument. diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx deleted file mode 100644 index 4aacd1bb57ee8..0000000000000 --- a/docs/platforms/javascript/common/install/esm.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: ESM (MJS) -sidebar_order: 10 -description: "Learn about running Sentry in an ESM application." -supported: - - javascript.node - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -When running your application in ESM mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. - -You need to create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.mjs`, which contains your `Sentry.init()` code: - -```bash -node --import ./instrument.mjs app.mjs -``` - -If it is not possible for you to pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows: - -```bash -NODE_OPTIONS="--import ./instrument.mjs" npm run start -``` - -If you're building a Node.js Single Executable Application (SEA) and can't rely -on `--import` or `NODE_OPTIONS`, use the SEA -bootstrap setup instead. diff --git a/docs/platforms/javascript/common/install/index.mdx b/docs/platforms/javascript/common/install/index.mdx index 4c48bc6df0a18..464c2e71387d8 100644 --- a/docs/platforms/javascript/common/install/index.mdx +++ b/docs/platforms/javascript/common/install/index.mdx @@ -5,6 +5,9 @@ description: "Review our alternate installation methods." notSupported: - javascript.eve - javascript.mastra + - javascript.nitro + - javascript.nestjs + - javascript.azure-functions - javascript.angular - javascript.astro - javascript.bun @@ -57,17 +60,17 @@ This runs `Sentry.init()` before any of your application's modules load, so ever node --import ./instrument.js app.js ``` -Note that `--require` is no longer supported for initialization. See ESM (MJS) and CommonJS (CJS). +Note that `--require` is no longer supported for initialization. ### Bundler Plugin and a Top-Level Import -If you can't pass a flag to the Node.js binary, instrument your dependencies at build time with the Sentry bundler plugin and import `instrument.mjs` at the top of your entry file. See ESM without CLI Flag. +If you build your server with a bundler, instrument your dependencies at build time with the Sentry bundler plugin and import `instrument.mjs` at the top of your entry file. Because the plugin bakes the instrumentation into your bundle, a top-level import is enough and you don't need a flag on the Node.js binary. See With a Bundler. -A top-level import on its own isn't equivalent to `--import`, because ESM evaluates every import in a file before it runs the first line of that file. That page explains what you lose and how to avoid it. +If you can't use a bundler, a top-level import on its own isn't equivalent to `--import`, because ESM evaluates every import in a file before it runs the first line of that file. See Deferred Entrypoint for an alternative way to run your application in this case. -### Load the SDK With `--import` and Initialize Later +### Prepare the instrumentation with `--import` and Initialize Later -If you can't call `Sentry.init()` at startup, for example because you fetch your DSN from an external source, `--import` the SDK itself and call `Sentry.init()` at a later point: +If you can't call `Sentry.init()` at startup, for example because you fetch your DSN from an external source, `--import` the instrumentation early and call `Sentry.init()` at a later point: ```bash node --import @sentry/node/import main.mjs diff --git a/docs/platforms/javascript/common/install/late-initialization.mdx b/docs/platforms/javascript/common/install/late-initialization.mdx index dec315fcc1eab..93bb6184fafd6 100644 --- a/docs/platforms/javascript/common/install/late-initialization.mdx +++ b/docs/platforms/javascript/common/install/late-initialization.mdx @@ -1,14 +1,22 @@ --- -title: Late Initialization (ESM or CJS) -sidebar_order: 12 +title: Late Initialization +sidebar_order: 2 description: "Learn about running Sentry in an ESM or CJS application, in scenarios where you cannot run init early." -supported: - - javascript.node - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs --- @@ -56,8 +64,7 @@ Sentry.init({ Use this method only if it's strictly necessary. Anything that happens before `Sentry.init()` runs isn't captured, so an error thrown during startup goes unreported. In most cases it's better to find a way to run `Sentry.init()` - early, as described in{" "} - ESM (MJS). + early, as described in the quickstart. ## What Wrapping Means diff --git a/docs/platforms/javascript/common/install/single-executable-applications.mdx b/docs/platforms/javascript/common/install/single-executable-applications.mdx new file mode 100644 index 0000000000000..c84d922759266 --- /dev/null +++ b/docs/platforms/javascript/common/install/single-executable-applications.mdx @@ -0,0 +1,67 @@ +--- +title: Single Executable Applications +sidebar_order: 4 +description: "Learn about running Sentry in a Single Executable Application (SEA)" +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +Node.js Single Executable Applications (SEA) may not load your Sentry instrumentation early enough, so you need to package a small bootstrap file as the SEA main instead of packaging your app entrypoint directly. + +The embedded SEA main should only load a filesystem bootstrap file next to the +executable: + +```javascript {filename: sea-main.cjs} +const { createRequire } = require("node:module"); + +createRequire(__filename)("./sea-bootstrap.cjs"); +``` + +The filesystem bootstrap imports Sentry first, then imports your real app +entrypoint: + +```javascript {filename: sea-bootstrap.cjs} +async function startApp() { + await import("./instrument.mjs"); + await import("./app.mjs"); +} + +startApp(); +``` + +This is the deferred entrypoint pattern, packaged for SEA. Keep your Sentry setup in `instrument.mjs`. + +Then configure SEA to use `sea-main.cjs` as its main script: + +```json {filename: sea-config.json} +{ + "main": "sea-main.cjs", + "output": "sea-prep.blob", + "disableExperimentalSEAWarning": true, + "useSnapshot": false +} +``` + +Keep `sea-bootstrap.cjs`, `instrument.mjs`, and `app.mjs` available on the filesystem next to the executable. + +This setup lets the Sentry SDK register ESM instrumentation hooks before your application imports instrumented modules, such as Express or database clients. Your instrumentation file and app entrypoint can stay ESM. The verified bootstrap pattern shown here uses CommonJS only for the small SEA entry files. + +Node.js SEA support is still evolving, including how embedded ESM entrypoints and module loading are configured. The embedded SEA main may not be able to load filesystem modules with `import()` directly, so the example above uses `module.createRequire()` to bridge from the embedded main to a normal filesystem bootstrap. The important requirement is startup order: load Sentry before loading the application modules you want Sentry to instrument. diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index c66d2df35f4ad..63edebae93985 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -171,20 +171,6 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati - - - - When using ESM, by default all packages are wrapped under the hood by - [import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle). - `import-in-the-middle` has compatibility issues with some packages and - can throw errors in these situations. - -Check out the ESM Troubleshooting Instrumentation section for more information. - - - - - @@ -517,40 +503,6 @@ Learn more about fixing these caching issues in the - -When using pnpm, you might encounter errors related to packages that can't be external, particularly with packages like `import-in-the-middle` and `require-in-the-middle`. These errors typically occur due to pnpm's strict dependency management and hoisting behavior. - -While adding these packages as direct dependencies might remove the warning messages, it often doesn't resolve the underlying functionality issues: - -```bash -pnpm add import-in-the-middle require-in-the-middle -``` - -As a workaround, create or modify `.npmrc` in your project root. First, try to specifically hoist the dependencies in question: - -```ini {filename:.npmrc} -public-hoist-pattern[]=*import-in-the-middle* -public-hoist-pattern[]=*require-in-the-middle* -``` - -If that doesn't work, you can also tell pnpm to hoist all dependencies: - -```ini {filename:.npmrc} -shamefully-hoist=true -``` - - - **Note**: While `shamefully-hoist=true` usually isn't the ideal solution from - a dependency management perspective, it's sometimes necessary for - compatibility with certain packages that expect Node.js module resolution - behavior similar to npm or yarn. - - - - - This applies to SDK version 10 and earlier. Version 11 and above don't use `import-in-the-middle`. diff --git a/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx b/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx deleted file mode 100644 index 72438c712846d..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: CommonJS (CJS) -sidebar_order: 9 -description: "Learn about running Sentry in an CJS application." -supported: - - javascript.nestjs ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules. -Nest.js, by default, transpiles your TypeScript code into CommonJS. - -You can follow the installation instructions in the SDK's Quick Start guide. diff --git a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx b/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx deleted file mode 100644 index c3c8100559235..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: ESM Without CLI Flag -sidebar_order: 11 -description: "Learn about running Sentry in an ESM application, without the --import flag." -supported: - - javascript.nestjs ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you'll most likely want to follow the ESM instructions. However, if you want to avoid using the `--import` command line option, for example, if you have no way of configuring a CLI flag, you can also follow an alternative setup that involves importing the `instrument.mjs` file directly in your application. - - - -This installation method has the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module). - -As a result, the Sentry SDK will **not** capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. - -We recommend using this only if the `--import` flag is not an option for you. - - - -**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/nestjs"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -**Step 2:** Import the `instrument.mjs` file before importing any other modules in your in the `main.ts` file of your application. This ensures that Sentry can automatically instrument all modules in your application: - -```javascript {filename: main.ts} -// Import this first! -import "./instrument.mjs"; - -// Now import other modules -import { NestFactory } from "@nestjs/core"; -// ... -// Your application code goes here -``` diff --git a/docs/platforms/javascript/guides/nestjs/install/esm.mdx b/docs/platforms/javascript/guides/nestjs/install/esm.mdx deleted file mode 100644 index c43f28f39d153..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/esm.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: ESM (MJS) -sidebar_order: 10 -description: "Learn about running Sentry in an ESM application." -supported: - - javascript.nestjs ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. - -**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/nestjs"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -**Step 2:** Adjust your application's start command to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter: - -```bash -"start": "--import ./instrument.mjs nest start" -``` - -If you can't pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows: - -```bash -NODE_OPTIONS="--import ./instrument.mjs" npm run start -``` diff --git a/docs/platforms/javascript/guides/nestjs/install/index.mdx b/docs/platforms/javascript/guides/nestjs/install/index.mdx deleted file mode 100644 index eedeb840fe395..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/index.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Installation Methods -sidebar_order: 1 -description: "Review our alternate installation methods for Sentry using Nest.js." -supported: - - javascript.nestjs ---- - - - -## How To Decide Which Installation Method To Use - -Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules. -Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. However, if your application is run in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, this will not work, in which case you can follow the [ESM docs](./esm). - -Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. In this case, you should follow the [CommonJS instructions](./commonjs). - -### My application uses the default Nest.js setup - -Nest.js transpiles to CJS by default, so you should follow the [CommonJS installation instructions](./commonjs). Keep reading if you have a more customized application or build setup. - -### My application uses `require` - -If you're using `require()` in your application, you should follow the [CommonJS instructions](./commonjs). - -### My application uses `import` - -If you're using `import` in your application, your installation method depends on how your application is _run_. If you compile your application (for example, into a `/dist` folder or similar) before running it, you need to check how the compiled code looks like. Is the compiled code using `require`? Then you should follow the [CommonJS instructions](./commonjs). If the compiled code is using `import`, you should follow the [ESM instructions](./esm). - -If you do not compile your code, you'll need to follow the [ESM instructions](./esm). diff --git a/platform-includes/getting-started-config/javascript.node.mdx b/platform-includes/getting-started-config/javascript.node.mdx index c66e3af06ee26..334bd8776680e 100644 --- a/platform-includes/getting-started-config/javascript.node.mdx +++ b/platform-includes/getting-started-config/javascript.node.mdx @@ -4,10 +4,8 @@ const Sentry = require("@sentry/node"); const { nodeProfilingIntegration } = require("@sentry/profiling-node"); // ___PRODUCT_OPTION_END___ profiling -// Ensure to call this before requiring any other modules! Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ profiling integrations: [ diff --git a/platform-includes/getting-started-node/javascript.mdx b/platform-includes/getting-started-node/javascript.mdx index 8b543151099ca..81903833422b8 100644 --- a/platform-includes/getting-started-node/javascript.mdx +++ b/platform-includes/getting-started-node/javascript.mdx @@ -33,70 +33,21 @@ Run the command for your preferred package manager to add the Sentry SDK to your ### Initialize the Sentry SDK - - - - To import and initialize Sentry, create a file named `instrument.(js|mjs)` in the root directory of your project and add the following code: - - - - - - - -### Apply Instrumentation to Your App - - - -Import `instrument.js` before any other modules to ensure Sentry initializes early. If you initialize later, auto-instrumentation and modules like database monitoring, agent tracing, tracing may not work. - - - - - -The method for applying instrumentation depends on whether your application uses CommonJS (CJS) or ECMAScript Modules (ESM). If you're unsure which system you're using or if you're looking for alternative installation methods, see here. - - - -#### CommonJS - - - - +Then, use the [--import](https://nodejs.org/api/cli.html#--importmodule) command line option and point it to your `instrument.(js|mjs)` file to load the module before the application starts: -Require the `instrument.js` file before any other modules: - - - - - - - - - - -#### ESM - - - - - -When running your application in ESM mode, use the [--import](https://nodejs.org/api/cli.html#--importmodule) command line option and point it to `instrument.mjs` to load the module before the application starts: - - - +```bash {tabTitle:CommonJS} +node --import ./instrument.js app.js +``` -```bash +```bash {tabTitle:ESM} node --import ./instrument.mjs app.mjs ``` - - - +If you are using a bundler like vite, you can also follow the bundler setup docs instead. diff --git a/redirects.js b/redirects.js index 9edbd5d4a8de8..c743142ec4d67 100644 --- a/redirects.js +++ b/redirects.js @@ -1039,6 +1039,24 @@ const userDocsRedirects = [ destination: '/platforms/javascript/guides/koa/configuration/integrations/opentelemetry/', }, + { + source: + '/platforms/javascript/guides/:guide(node|express|fastify|hapi|hono|koa|nestjs)/install/esm/', + destination: '/platforms/javascript/guides/:guide/', + }, + { + source: + '/platforms/javascript/guides/:guide(node|express|fastify|hapi|hono|koa|nestjs)/install/commonjs/', + destination: '/platforms/javascript/guides/:guide/', + }, + { + source: '/platforms/javascript/guides/nestjs/install/esm-without-import/', + destination: '/platforms/javascript/guides/nestjs/', + }, + { + source: '/platforms/javascript/guides/nestjs/install/', + destination: '/platforms/javascript/guides/nestjs/', + }, { source: '/platforms/javascript/guides/react-router/features/instrumentation-api/', destination: '/platforms/javascript/guides/react-router/manual-setup/', From a32b264a2159db092fb409518b113710fefd06ea Mon Sep 17 00:00:00 2001 From: Sigrid <32902192+s1gr1d@users.noreply.github.com> Date: Wed, 23 Sep 2026 13:36:06 +0200 Subject: [PATCH 46/48] docs(js): Update dataCollection snippets for v10 and genAI (#19579) Improvements for `dataCollection` snippets so they are aligned everywhere. Especially for genAI snippets and versioned docs (v10). Reference (regarding MCP): https://github.com/getsentry/sentry-javascript/issues/24604 --- .../common/configuration/options.mdx | 4 +++ .../data-management/data-collected/index.mdx | 2 ++ .../common/mcp-monitoring/index.mdx | 17 ++++++++-- .../aws-lambda/install/layer__v10.x.mdx | 6 +++- .../cloudflare/frameworks/hydrogen-remix.mdx | 4 +++ .../platforms/javascript/guides/eve/index.mdx | 17 ++-------- .../javascript/guides/mastra/cloudflare.mdx | 13 +++++--- .../javascript/guides/mastra/index.mdx | 15 ++------- .../guides/nuxt/manual-setup__v10.x.mdx | 6 +++- includes/mastra/captured-summary.mdx | 2 +- .../javascript.aws-lambda__v10.x.mdx | 32 +++++++++++++++++++ .../javascript.eve.mdx | 30 +++++++++++++++++ .../javascript.mastra.mdx | 28 ++++++++++++++++ .../javascript.nuxt__v10.x.mdx | 32 +++++++++++++++++++ 14 files changed, 172 insertions(+), 36 deletions(-) create mode 100644 platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx create mode 100644 platform-includes/getting-started-data-collection/javascript.eve.mdx create mode 100644 platform-includes/getting-started-data-collection/javascript.mastra.mdx create mode 100644 platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 827aa46c95391..b8ec0ae52f01b 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -108,6 +108,10 @@ Set to `false` to opt out, for example, when using a custom `tunnel` or when run Controls which categories of data the SDK collects automatically. All fields are optional. By default the SDK collects rich debugging context (including user identity, request/response bodies, and generative AI content) and scrubs values whose keys match the built-in sensitive denylist (`auth`, `token`, `password`, and similar). +In version 10 of the SDK, the defaults below apply only when you set the `dataCollection` option. +Without it, the deprecated `sendDefaultPii` option controls data collection. +Starting with version 11, the defaults always apply. + For more on what data Sentry collects and how to control it, see Data Management. | Key | Type | Default | Description | diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index aa992f15c778e..280657b5c519c 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -258,6 +258,8 @@ Sentry.init({ The content of generative AI inputs (system instructions, prompt messages, tool definitions, and tool call arguments) and outputs (such as completion text and tool call results) might carry personal data. By default, the SDK records both inputs and outputs. Metadata like model ID and token counts is always collected. + The same setting applies to MCP servers instrumented with `wrapMcpServerWithSentry`. By default, the SDK records the inputs and outputs of tool calls, prompt retrievals, and resource reads. Use the wrapper's `recordInputs` and `recordOutputs` options to control recording per server. + Use the `dataCollection.genAI` option to control this. For example, opt out of recording AI message content while keeping the metadata: ```JavaScript diff --git a/docs/platforms/javascript/common/mcp-monitoring/index.mdx b/docs/platforms/javascript/common/mcp-monitoring/index.mdx index 4728e643811e7..47ed98f9ae6b1 100644 --- a/docs/platforms/javascript/common/mcp-monitoring/index.mdx +++ b/docs/platforms/javascript/common/mcp-monitoring/index.mdx @@ -41,7 +41,20 @@ Support for `@modelcontextprotocol/server` 2.x requires Sentry JavaScript SDK ve ### Configure Input and Output Recording -MCP inputs and outputs may contain sensitive data. Use `recordInputs` and `recordOutputs` to control collection for a specific server: +By default, the SDK sends the inputs and outputs of your MCP tool calls, prompt retrievals, and resource reads. This gives you rich debugging context. MCP payloads can carry sensitive data, such as tokens, file paths, or private user content. Review what your server handles before you deploy to production. + +The `dataCollection.genAI` option controls this recording globally for both MCP and AI instrumentation: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + genAI: { inputs: false, outputs: false }, + }, +}); +``` + +Use `recordInputs` and `recordOutputs` to control recording for a specific server. These options override the `dataCollection.genAI` settings: ```javascript const server = Sentry.wrapMcpServerWithSentry(mcpServer, { @@ -50,7 +63,7 @@ const server = Sentry.wrapMcpServerWithSentry(mcpServer, { }); ``` -These options override the corresponding `dataCollection.genAI.inputs` and `dataCollection.genAI.outputs` settings and require Sentry JavaScript SDK version `10.33.0` or newer. +The `recordInputs` and `recordOutputs` options require Sentry JavaScript SDK version `10.33.0` or newer. In version 10, the SDK records inputs and outputs only when you set the `dataCollection` option or enable them on the wrapper. Starting with version 11, it records them by default. diff --git a/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx b/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx index 4dcd7caf6ecc5..0df5798b10387 100644 --- a/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx +++ b/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx @@ -115,4 +115,8 @@ That's it — make sure to re-deploy your function and you're all set! ## 3. Control the Data You Send to Sentry (Optional) - + diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx index 0bc2d4d382e54..e56cb7ea4eedd 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx @@ -146,6 +146,10 @@ Sentry.init({ }); ``` +## Control the Data You Send to Sentry (Optional) + + + ## Trace Propagation diff --git a/docs/platforms/javascript/guides/eve/index.mdx b/docs/platforms/javascript/guides/eve/index.mdx index 1d189e3e8d404..fde9b2967a745 100644 --- a/docs/platforms/javascript/guides/eve/index.mdx +++ b/docs/platforms/javascript/guides/eve/index.mdx @@ -118,7 +118,7 @@ export default defineInstrumentation( With this setup, Sentry captures errors thrown by your agent and AI spans for every turn — model calls, tool executions, token usage, and latency — along with outgoing HTTP and `fetch` requests. It also groups every turn in an Eve session into one Sentry conversation. Prompts and model outputs are recorded on your agent spans by default, so the Agent Tracing transcript shows the full exchange without any extra configuration. -To also instrument the rest of your Node app, see [Instrument Other Dependencies](#instrument-other-dependencies) below. To review what's captured and turn recording of prompts and responses off, see [Privacy Controls](#privacy-controls). +To also instrument the rest of your Node app, see [Instrument Other Dependencies](#instrument-other-dependencies) below. To review what's captured and turn recording of prompts and responses off, see [Control the Data You Send to Sentry](#control-the-data-you-send-to-sentry-optional). ## Verify @@ -133,20 +133,9 @@ If no data appears, confirm that: -## Privacy Controls +## Control the Data You Send to Sentry (Optional) -Generative AI inputs and outputs — the prompts your agent sends and the model responses it receives — are recorded on your agent spans by default. Review the data your agent handles and tighten this before production. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`: - -```typescript {filename:agent/instrumentation/sentry.ts} -export default defineInstrumentation( - Sentry.eveInstrumentation({ - dsn: "___PUBLIC_DSN___", - dataCollection: { - genAI: { inputs: false, outputs: false }, - }, - }) -); -``` + ## Customize Conversation Grouping diff --git a/docs/platforms/javascript/guides/mastra/cloudflare.mdx b/docs/platforms/javascript/guides/mastra/cloudflare.mdx index 4ef25a0cc8bc7..20168aff2ea71 100644 --- a/docs/platforms/javascript/guides/mastra/cloudflare.mdx +++ b/docs/platforms/javascript/guides/mastra/cloudflare.mdx @@ -87,11 +87,16 @@ With the plugin in place, `Sentry.init()` runs automatically — you don't add a -### Privacy Controls +### Control the Data You Send to Sentry (Optional) -The SDK will record generative AI inputs and outputs (the prompts your agent sends and the model responses it receives) by default. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`: +By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. +This will give you rich debugging context. Review the data your agent handles before you deploy to production. -```typescript {filename:src/instrument.server.ts} +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option: + +```typescript {filename:src/instrument.server.ts} {3-5} export default (env: Env) => ({ dsn: "___PUBLIC_DSN___", dataCollection: { @@ -100,7 +105,7 @@ export default (env: Env) => ({ }); ``` -See [`dataCollection` documentation](../configuration/options/#dataCollection) for details on privacy control options. +For the full list of categories and their defaults, see the [`dataCollection` options](../configuration/options/#dataCollection). diff --git a/docs/platforms/javascript/guides/mastra/index.mdx b/docs/platforms/javascript/guides/mastra/index.mdx index 49b9a2f2ff122..6e3318bcf5bd0 100644 --- a/docs/platforms/javascript/guides/mastra/index.mdx +++ b/docs/platforms/javascript/guides/mastra/index.mdx @@ -129,20 +129,9 @@ Preload the instrument file when you start Mastra by passing it through `--custo -### Privacy Controls +### Control the Data You Send to Sentry (Optional) -The SDK will record generative AI inputs and outputs (the prompts your agent sends and the model responses it receives) by default. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`: - -```javascript {filename:src/mastra/public/instrument.mjs} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - dataCollection: { - genAI: { inputs: false, outputs: false }, - }, -}); -``` - -See [`dataCollection` documentation](./configuration/options/#dataCollection) for details on privacy control options. + diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx index 127f7c256d04a..29eddc1e790d7 100644 --- a/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx +++ b/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx @@ -363,7 +363,11 @@ export default defineNuxtConfig({ ### Control the Data You Send to Sentry (Optional) - + ## Verify Your Setup diff --git a/includes/mastra/captured-summary.mdx b/includes/mastra/captured-summary.mdx index 653845bed99ed..f04e0c2cf2e3f 100644 --- a/includes/mastra/captured-summary.mdx +++ b/includes/mastra/captured-summary.mdx @@ -1,3 +1,3 @@ With this setup, Sentry captures errors thrown by your agents and AI spans for every run (agent runs, model generations, tool calls, workflows, token usage, and latency) along with outgoing HTTP and `fetch` requests. Prompts and model outputs are recorded on your AI spans by default. -To review what's captured and turn recording of prompts and responses off, see [Privacy Controls](#privacy-controls) below. +To review what's captured and turn recording of prompts and responses off, see [Control the Data You Send to Sentry](#control-the-data-you-send-to-sentry-optional) below. diff --git a/platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx b/platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx new file mode 100644 index 0000000000000..a5db4c83c07c3 --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx @@ -0,0 +1,32 @@ + + + + +When you set the `dataCollection` option, you opt into the SDK's new data collection behavior, which is the default in version 11. +The SDK then sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. +This will give you rich debugging context. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```javascript {3-8} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: + // https://docs.sentry.io/platforms/javascript/guides/aws-lambda/configuration/options/#dataCollection + // userInfo: false, + // httpBodies: [], + }, +}); +``` + + + + diff --git a/platform-includes/getting-started-data-collection/javascript.eve.mdx b/platform-includes/getting-started-data-collection/javascript.eve.mdx new file mode 100644 index 0000000000000..5b5abf0dca45e --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.eve.mdx @@ -0,0 +1,30 @@ + + + + +By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. +This will give you rich debugging context. Review the data your agent handles before you deploy to production. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```typescript {filename:agent/instrumentation/sentry.ts} {4-6} +export default defineInstrumentation( + Sentry.eveInstrumentation({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + genAI: { inputs: false, outputs: false }, + }, + }) +); +``` + + + + diff --git a/platform-includes/getting-started-data-collection/javascript.mastra.mdx b/platform-includes/getting-started-data-collection/javascript.mastra.mdx new file mode 100644 index 0000000000000..521f25e282159 --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.mastra.mdx @@ -0,0 +1,28 @@ + + + + +By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. +This will give you rich debugging context. Review the data your agent handles before you deploy to production. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```javascript {filename:src/mastra/public/instrument.mjs} {3-5} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + genAI: { inputs: false, outputs: false }, + }, +}); +``` + + + + diff --git a/platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx b/platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx new file mode 100644 index 0000000000000..025b60e9029ea --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx @@ -0,0 +1,32 @@ + + + + +When you set the `dataCollection` option, you opt into the SDK's new data collection behavior, which is the default in version 11. +The SDK then sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. +This will give you rich debugging context. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```javascript {3-8} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: + // https://docs.sentry.io/platforms/javascript/guides/nuxt/configuration/options/#dataCollection + // userInfo: false, + // httpBodies: [], + }, +}); +``` + + + + From e4920f71c69bf089a66d3c570ee533822f9e9ef5 Mon Sep 17 00:00:00 2001 From: Martin Sonnberger Date: Wed, 23 Sep 2026 13:43:23 +0200 Subject: [PATCH 47/48] docs(javascript): Sync v11 migration guides with SDK changes (#19582) ## DESCRIBE YOUR PR Bring the static and interactive v11 migration guides in line with the latest [JavaScript SDK migration notes](https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md). Both guides now cover the missing span names and attributes, Web Vitals changes, AI span removals, Next.js tunnel middleware behavior, Remix source-map uploads, and webpack plugin requirements. The interactive guide adds dedicated items for Next.js tunnel requests, the webpack import change, and removed non-inference AI spans. Existing tracing items carry the corresponding naming and attribute updates so both guides give the same migration guidance. ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ --- .../common/migration/v10-to-v11/index.mdx | 87 ++++++++++++++++++- .../javascript-v11/ai-non-inference-spans.mdx | 14 +++ .../browser-web-vital-options.mdx | 4 + .../nextjs-tunnel-middleware.mdx | 12 +++ .../javascript-v11/remix-vite-subpath.mdx | 2 + .../javascript-v11/span-attribute-changes.mdx | 7 ++ .../javascript-v11/span-name-changes.mdx | 51 ++++++++++- .../javascript-v11/span-op-changes.mdx | 2 +- .../javascript-v11/webpack-plugin-entry.mdx | 20 +++++ 9 files changed, 192 insertions(+), 7 deletions(-) create mode 100644 includes/migration/javascript-v11/ai-non-inference-spans.mdx create mode 100644 includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx create mode 100644 includes/migration/javascript-v11/webpack-plugin-entry.mdx diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index 29973b4b7bc3e..88e22990b520b 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -391,8 +391,24 @@ Whatever the name no longer carries stays on an attribute, in both trace lifecyc | `db` (Mongoose) | `mongoose..` (`mongoose.BlogPost.findOne`) | The operation and collection (`findOne blogposts`), the database namespace, or `mongodb` | | `db` (Supabase) | The query builder call and table (`select(...) from(users)`), or `auth ` | The operation and table (`select users`), or the dotted auth method (`auth.signInWithPassword`) | | `db.query` (Redis, ioredis) | The serialized command with redacted arguments (`set test-key [1 other arguments]`) | The operation and connection (`SET localhost:6379`), the operation and redis function for `FCALL`, or `redis` | - -A few consequences worth checking: +| `browser.*` navigation timing | The document URL | A static phase name, such as `DNS lookup`, `Request`, or `Load event` | +| `function` | Integration-specific, such as `serverAction/updateUser` or `LOADER routes/users.$id` | `code.function.name`, such as `updateUser` or `loader` | +| `function` (Angular `TraceMethod`) | `` or `` | The decorator's `name`, or `Function execution` | +| `function` (SvelteKit) | The route or request path | The wrapped function's name, such as `load` or `GET` | +| `function` (Ember route hooks) | The full route name | The hook name, such as `beforeModel`, `model`, or `setupController` | +| `function` (React Router route hooks) | The route, raw URL path, or fetcher key | The hook name, such as `loader`, `action`, `clientLoader`, or `fetcher` | +| `function` (NestJS `@OnEvent`) | `event user.created` | The event name, such as `user.created` | +| `function` (TanStack Start server functions) | `GET /_serverFn/abc123` | The function name, or `serverFn` until middleware resolves it | +| `function.gcp` | The HTTP method and path, or trigger type | The function name, or `Serverless function execution` | +| `function.aws` | The Lambda function name | Unchanged, with `Serverless function execution` as the fallback | +| `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | ``, `Vue `, `Application Render`, or `init` | The unwrapped component name, or `Component mount`, `Component render`, `Component update`, or `Component unmount` | +| `ui.task` | `runloop` | `UI task` | +| `ui.action.click` | The pageload or navigation span's name | `router.navigation.route.id`, `url.template`, or `http.route`, in that order, or `Click` | +| `ui.interaction.*` | The element's DOM path | The annotated component name, or `Click`, `Hover`, `Drag`, or `Key press` | +| `ui.webvital.lcp` | The LCP element's DOM path | The annotated component name, or `Largest contentful paint` | +| `ui.webvital.cls` | The first layout-shift source's DOM path | The annotated component name, or `Layout shift` | + +In transaction mode, span names remain unchanged. A few consequences worth checking: - `useOperationNameForRootSpan` no longer renames the enclosing root span. The operations stay on that span's `sentry.graphql.operation` attribute. - `graphqlClientIntegration` no longer appends the operation to the outgoing request span name. It's on `graphql.operation.name` and `graphql.operation.type` instead. @@ -406,6 +422,37 @@ A few consequences worth checking: + + +Browser navigation timing spans use these names: + +| Span op | Name | +| ---------------------------------- | ------------------------ | +| `browser.cache` | `Cache lookup` | +| `browser.dns` | `DNS lookup` | +| `browser.connect` | `Connect` | +| `browser.tls_ssl` | `TLS handshake` | +| `browser.redirect` | `Redirect` | +| `browser.request` | `Request` | +| `browser.response` | `Response` | +| `browser.unload_event` | `Unload event` | +| `browser.dom_content_loaded_event` | `DOMContentLoaded event` | +| `browser.load_event` | `Load event` | + +The document URL stays on `url.full` in both trace lifecycles, subject to `dataCollection.urlQueryParams`. Update name-based filters to use that attribute. + +Framework function spans keep the previous name on `sentry.description`. For SvelteKit, this includes `wrapLoadWithSentry`, `wrapServerLoadWithSentry`, `wrapServerRouteWithSentry`, and spans from SvelteKit's own tracing. Match the route on `http.route`, or `url.template` for client-side universal loads, and the request path on `url.path`. + +GCP and Firebase function names come from `FUNCTION_TARGET` or `K_SERVICE`. The function name stays on `faas.name`, trigger details on `gcp.function.context.*`, and HTTP method and path on `http.request.method` and `url.path`. AWS Lambda spans fall back to `Serverless function execution` when neither the invocation context nor `AWS_LAMBDA_FUNCTION_NAME` provides a name. Their `sentry.segment.name.source` is now `component` in both trace lifecycles. + +Component spans keep their original names on `sentry.description`. Vue's `Application Render` becomes `Root`, and Ember's `init` becomes `Component mount`. Update filters matching `` or `Vue ` to use the new name or the description. + +Click idle spans copy `router.navigation.route.id`, `url.template`, `http.route`, `url.path`, and `url.full` from the route span. Event Timing and INP spans keep the DOM path on `browser.web_vital.inp.target` and the annotated component on `ui.component_name`, in both trace lifecycles. Match the target attribute if you previously filtered by DOM path. + +LCP and CLS DOM paths stay on `browser.web_vital.lcp.element` and `browser.web_vital.cls.source.1`. Long task and long animation frame names remain `Main UI thread blocked`. + + + `ignoreSpans` and `tracesSampler` both run when a span **starts**, so a span may not have its final name yet. Match on attributes instead: @@ -461,7 +508,7 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic | Frontend routing | `ui.angular.routing`, `ui.sveltekit.routing`, `ui.ember.transition` | `router` | | React, Vue, and Svelte component lifecycles | `ui.react.mount`/`render`/`update`, `ui.svelte.init`/`update`, Vue `render`/`update`/`mount`/`create`/`activate`/`unmount`/`destroy` | `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | | Angular tracing decorators | `ui.angular.init`, `ui.angular.` | `ui.mount`, `function` | -| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`function`/`ui.mount` | +| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`ui.resolve`/`ui.mount` | | Browser paint entries | `paint` | `browser.paint` | **Databases, cache, and messaging** @@ -543,6 +590,10 @@ Legacy span attributes were replaced by their semantic-convention equivalents. U Transport values change from `ip_tcp` and `ip_udp` to `tcp` and `udp`. HTTP instrumentation reports the protocol as `network.protocol.name` and its version as `network.protocol.version`. +HTTP header attribute names keep their hyphens instead of replacing them with underscores. For example, `http.request.header.user_agent` becomes `http.request.header.user-agent`. Header values are now string arrays, with one entry per value: `['gzip', 'deflate']` replaces `'gzip;deflate'`. + +Cookies are no longer split into attributes per cookie name. `http.request.header.cookie` and `http.request.header.set-cookie` now hold arrays of `name=value` entries in the order sent, such as `['session=[Filtered]', 'theme=dark']`. Sensitive values remain filtered, and Set-Cookie attributes such as `HttpOnly` are still omitted. + On server-side HTTP spans, the `content-length` header is always reported as `http.request.body.size` and `http.response.body.size`, instead of switching to `http.request_body_size_uncompressed` when no encoding was present. @@ -597,6 +648,9 @@ The Anthropic integration no longer sets `gen_ai.prompt`. The legacy Completions - On `ui.long_animation_frame` spans, `code.filepath` and `code.function` became `code.file.path` and `code.function.name`. - On `file` spans, `fs_error` became `error.type` and holds the syscall error code (`ENOENT`) instead of the full message. - The TanStack Router integration reports path parameters as `url.path.parameter.` instead of `url.path.params.`. +- Vue Router's `navigation.route.id` became `router.navigation.route.id`, with the same matched route name. +- AWS Lambda spans use `faas.invocation_id` instead of `faas.execution` for the request ID, and `cloud.resource_id` instead of `faas.id` for the invoked function ARN. Lambda `Invoke` spans from `awsIntegration` also use `faas.invocation_id`. +- Koa router and middleware spans no longer set `koa.name`. Use `http.route` for the route and `code.function.name` for the middleware handler. - The Cloudflare-specific `sentry.cloudflare_tracer` attribute is no longer set. - Import attribute constants from `@sentry/core` directly. The `semanticAttributes` re-export was removed. - `sentry.source` (`SEMANTIC_ATTRIBUTE_SENTRY_SOURCE`) was replaced by `sentry.segment.name.source`, which is only set on the root span. @@ -692,6 +746,12 @@ If you used the v10 integration from `@sentry/node-core/light/otlp`: it moved to How the SDK hooks into your app changed, along with the way some frameworks are set up. +### AI Integrations No Longer Trace Non-Inference Operations + +AI integrations now trace model invocations, tool calls, and agent invocations only. They no longer emit spans for Anthropic `messages.countTokens`, `models.retrieve`, or `models.get`, or LangGraph graph compilation with `gen_ai.create_agent`. + +Update dashboards and alerts that reference these spans. LangGraph's `gen_ai.invoke_agent` and `gen_ai.execute_tool` spans are unchanged. + ### Channel-Based Instrumentation Is the Default Instrumentation now runs through diagnostics channels (`orchestrion`) instead of `import-in-the-middle`. It allows instrumentation at run time and build time, which enables tracing on deployment targets like Vercel and Netlify, and on non-Node.js runtimes like Cloudflare, Bun, and Deno. Most setups need no changes. @@ -934,11 +994,12 @@ Sentry.init({ BrowserTracing now automatically adds the WebVitals integration. Web Vitals changed as follows: - CLS and LCP are recorded as measurements on the pageload span, or as dedicated spans in stream mode. +- LCP and CLS spans no longer set `browser.web_vital.lcp.report_event` or `browser.web_vital.cls.report_event`, including when soft-navigation reporting is disabled. Finalization timing is unchanged. Remove filters on these attributes from searches and dashboards. - When collected, INP is always sent as a Web Vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement. Built-in dashboards do not need adjustments. - The `enableInp` option is deprecated. To disable INP, use `browserTracingIntegration({ webVitals: { ignore: ["inp"] } })`. The `ignore` array can also contain `"cls"` or `"lcp"` to skip those vitals. - To configure Web Vitals, pass `webVitals` options to BrowserTracing, or add `webVitalsIntegration()` explicitly. Explicit registration takes precedence over BrowserTracing's `webVitals` and `enableInp` options. - Soft-navigation vitals are enabled by default in stream mode on browsers that support the Soft Navigations API. Set `webVitals: { softNavigations: false }` to keep one set of vitals for the page lifetime. -- BrowserTracing starts a navigation span after a back/forward-cache restore by default. Set `instrumentBfcacheRestore: false` to disable it. Web Vitals for restores are collected by default in stream mode when `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. +- BrowserTracing starts a navigation span after a back/forward-cache restore by default. Set `instrumentBfcacheRestore: false` to disable it. Web Vitals for restores are collected by default in stream mode when `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. Restore vitals carry `browser.navigation.type: bfcache`. Filter by that attribute to analyze restores separately from page loads, since near-instant restores can lower combined aggregates. @@ -1056,6 +1117,10 @@ The top-level options of `withSentryConfig` that were deprecated in 10.30.0 were | `_experimental.turbopackApplicationKey` | `applicationKey` | | `unstable_sentryWebpackPluginOptions` | Set the plugin options as build options | +### Tunnel Requests Run Through Middleware + +Webpack builds no longer bypass your middleware for `tunnelRoute` requests. If your middleware blocks unauthenticated requests globally, set `tunnelRoute` to a fixed string instead of `true` and exclude that path in your middleware `matcher` so Sentry events can reach the tunnel. + ### Unified `reactComponentAnnotation` Option React component annotation is configured through a single top-level option that applies to webpack and Turbopack builds: @@ -1184,6 +1249,18 @@ The `assets` and `filesToDeleteAfterUpload` fields moved into `sourcemaps`. Deploys that the bundler plugins create on Vercel use `VERCEL_TARGET_ENV` as their environment now, instead of `vercel-production` and `vercel-preview`. That matches the runtime default. If your events use a different environment, set `release.deploy.env` to the same value, or set `release.deploy` to `false` to opt out. +### The webpack Plugin Entry Point Changed + +The Sentry webpack plugin requires webpack **5.1** or newer. The `@sentry/bundler-plugins/webpack5` entry point was removed. Update imports to `@sentry/bundler-plugins/webpack`: + +```js +// Before +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack5"; + +// After +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack"; +``` + ### The `unstable_` Bundler Plugin Options Were Removed The `unstable_sentry*PluginOptions` escape hatch was removed from every SDK, because the Sentry bundler plugins now live in the SDK monorepo and release in lockstep. Every supported plugin option is a first-class build option: @@ -1332,6 +1409,8 @@ import { sentryRemixVitePlugin } from "@sentry/remix/vite"; The plugin applies the build-time instrumentation transform now. If you added `sentryOrchestrionPlugin()` from `@sentry/server-utils/orchestrion/vite` yourself, remove it. Opt out with `sentryRemixVitePlugin({ buildTimeInstrumentation: false })`. +The plugin also injects debug IDs and uploads source maps when you pass `org`, `project`, and `authToken`. Disable source-map processing with `sentryRemixVitePlugin({ sourcemaps: { disable: true } })`. + `captureActionFormDataKeys` is an integration-level override now, so it opts in on its own and no longer needs `dataCollection.httpBodies` to include `'incomingRequest'`: ```js diff --git a/includes/migration/javascript-v11/ai-non-inference-spans.mdx b/includes/migration/javascript-v11/ai-non-inference-spans.mdx new file mode 100644 index 0000000000000..79e90171a9840 --- /dev/null +++ b/includes/migration/javascript-v11/ai-non-inference-spans.mdx @@ -0,0 +1,14 @@ +--- +id: ai-non-inference-spans +title: "AI integrations no longer trace non-inference operations" +phase: verify +category: behavior +severity: behavior-change +frameworks: all +platformCategory: server +order: 96 +--- + +AI integrations now trace model invocations, tool calls, and agent invocations only. They no longer emit spans for Anthropic `messages.countTokens`, `models.retrieve`, or `models.get`, or LangGraph graph compilation with `gen_ai.create_agent`. + +Update dashboards and alerts that reference these spans. LangGraph's `gen_ai.invoke_agent` and `gen_ai.execute_tool` spans are unchanged. diff --git a/includes/migration/javascript-v11/browser-web-vital-options.mdx b/includes/migration/javascript-v11/browser-web-vital-options.mdx index 2f4e48b7aaf20..ac4f3693a8dfa 100644 --- a/includes/migration/javascript-v11/browser-web-vital-options.mdx +++ b/includes/migration/javascript-v11/browser-web-vital-options.mdx @@ -16,3 +16,7 @@ CLS and LCP are recorded as measurements on the pageload span, or as dedicated s Configure collection through `browserTracingIntegration({ webVitals: { ... } })`. The `enableInp` option is deprecated. Use `webVitals: { ignore: ["inp"] }` to disable INP, or include `"cls"` or `"lcp"` in `ignore` to skip those vitals. If you explicitly add `webVitalsIntegration()`, its options take precedence. Soft-navigation vitals are enabled by default in stream mode on supporting browsers. Set `webVitals: { softNavigations: false }` to keep one set of vitals for the page lifetime. Back/forward-cache vitals are also enabled by default in stream mode when BrowserTracing's `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable collection for restores. See WebVitals for requirements. + +LCP and CLS spans no longer set `browser.web_vital.lcp.report_event` or `browser.web_vital.cls.report_event`, including when soft-navigation reporting is disabled. Finalization timing is unchanged. Remove filters on these attributes from searches and dashboards. + +Restore vitals carry `browser.navigation.type: bfcache`. Filter by that attribute to analyze restores separately from page loads, since near-instant restores can lower combined aggregates. diff --git a/includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx b/includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx new file mode 100644 index 0000000000000..e343d22a890e8 --- /dev/null +++ b/includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx @@ -0,0 +1,12 @@ +--- +id: nextjs-tunnel-middleware +title: "Tunnel requests now run through Next.js middleware" +phase: code-changes +category: behavior +severity: action-required +frameworks: [nextjs] +platformCategory: all +order: 335 +--- + +Webpack builds no longer bypass your middleware for `tunnelRoute` requests. If your middleware blocks unauthenticated requests globally, set `tunnelRoute` to a fixed string instead of `true` and exclude that path in your middleware `matcher` so Sentry events can reach the tunnel. diff --git a/includes/migration/javascript-v11/remix-vite-subpath.mdx b/includes/migration/javascript-v11/remix-vite-subpath.mdx index 65288da8dc23c..ce997529a4f43 100644 --- a/includes/migration/javascript-v11/remix-vite-subpath.mdx +++ b/includes/migration/javascript-v11/remix-vite-subpath.mdx @@ -20,3 +20,5 @@ import { sentryRemixVitePlugin } from "@sentry/remix/vite"; ``` The plugin applies the build-time instrumentation transform now. If you added `sentryOrchestrionPlugin()` from `@sentry/server-utils/orchestrion/vite` yourself, remove it. Opt out with `sentryRemixVitePlugin({ buildTimeInstrumentation: false })`. + +The plugin also injects debug IDs and uploads source maps when you pass `org`, `project`, and `authToken`. Disable source-map processing with `sentryRemixVitePlugin({ sourcemaps: { disable: true } })`. diff --git a/includes/migration/javascript-v11/span-attribute-changes.mdx b/includes/migration/javascript-v11/span-attribute-changes.mdx index cdc9c2c2060b6..78831ab1c8db6 100644 --- a/includes/migration/javascript-v11/span-attribute-changes.mdx +++ b/includes/migration/javascript-v11/span-attribute-changes.mdx @@ -42,6 +42,10 @@ Legacy span attributes were replaced by their semantic-convention equivalents. U Transport values change from `ip_tcp` and `ip_udp` to `tcp` and `udp`. HTTP instrumentation reports the protocol as `network.protocol.name` and its version as `network.protocol.version`. +HTTP header attribute names keep their hyphens instead of replacing them with underscores. For example, `http.request.header.user_agent` becomes `http.request.header.user-agent`. Header values are now string arrays, with one entry per value: `['gzip', 'deflate']` replaces `'gzip;deflate'`. + +Cookies are no longer split into attributes per cookie name. `http.request.header.cookie` and `http.request.header.set-cookie` now hold arrays of `name=value` entries in the order sent, such as `['session=[Filtered]', 'theme=dark']`. Sensitive values remain filtered, and Set-Cookie attributes such as `HttpOnly` are still omitted. + On server-side HTTP spans, the `content-length` header is always reported as `http.request.body.size` and `http.response.body.size`, instead of switching to `http.request_body_size_uncompressed` when no encoding was present. @@ -96,6 +100,9 @@ The Anthropic integration no longer sets `gen_ai.prompt`. The legacy Completions - On `ui.long_animation_frame` spans, `code.filepath` and `code.function` became `code.file.path` and `code.function.name`. - On `file` spans, `fs_error` became `error.type` and holds the syscall error code (`ENOENT`) instead of the full message. - The TanStack Router integration reports path parameters as `url.path.parameter.` instead of `url.path.params.`. +- Vue Router's `navigation.route.id` became `router.navigation.route.id`, with the same matched route name. +- AWS Lambda spans use `faas.invocation_id` instead of `faas.execution` for the request ID, and `cloud.resource_id` instead of `faas.id` for the invoked function ARN. Lambda `Invoke` spans from `awsIntegration` also use `faas.invocation_id`. +- Koa router and middleware spans no longer set `koa.name`. Use `http.route` for the route and `code.function.name` for the middleware handler. - The Cloudflare-specific `sentry.cloudflare_tracer` attribute is no longer set. - Import attribute constants from `@sentry/core` directly. The `semanticAttributes` re-export was removed. - `sentry.source` (`SEMANTIC_ATTRIBUTE_SENTRY_SOURCE`) was replaced by `sentry.segment.name.source`, which is only set on the root span. diff --git a/includes/migration/javascript-v11/span-name-changes.mdx b/includes/migration/javascript-v11/span-name-changes.mdx index 137a5055e9261..89653cdaa5532 100644 --- a/includes/migration/javascript-v11/span-name-changes.mdx +++ b/includes/migration/javascript-v11/span-name-changes.mdx @@ -51,8 +51,24 @@ Whatever the name no longer carries stays on an attribute, in both trace lifecyc | `db` (Mongoose) | `mongoose..` (`mongoose.BlogPost.findOne`) | The operation and collection (`findOne blogposts`), the database namespace, or `mongodb` | | `db` (Supabase) | The query builder call and table (`select(...) from(users)`), or `auth ` | The operation and table (`select users`), or the dotted auth method (`auth.signInWithPassword`) | | `db.query` (Redis, ioredis) | The serialized command with redacted arguments (`set test-key [1 other arguments]`) | The operation and connection (`SET localhost:6379`), the operation and redis function for `FCALL`, or `redis` | +| `browser.*` navigation timing | The document URL | A static phase name, such as `DNS lookup`, `Request`, or `Load event` | +| `function` | Integration-specific, such as `serverAction/updateUser` or `LOADER routes/users.$id` | `code.function.name`, such as `updateUser` or `loader` | +| `function` (Angular `TraceMethod`) | `` or `` | The decorator's `name`, or `Function execution` | +| `function` (SvelteKit) | The route or request path | The wrapped function's name, such as `load` or `GET` | +| `function` (Ember route hooks) | The full route name | The hook name, such as `beforeModel`, `model`, or `setupController` | +| `function` (React Router route hooks) | The route, raw URL path, or fetcher key | The hook name, such as `loader`, `action`, `clientLoader`, or `fetcher` | +| `function` (NestJS `@OnEvent`) | `event user.created` | The event name, such as `user.created` | +| `function` (TanStack Start server functions) | `GET /_serverFn/abc123` | The function name, or `serverFn` until middleware resolves it | +| `function.gcp` | The HTTP method and path, or trigger type | The function name, or `Serverless function execution` | +| `function.aws` | The Lambda function name | Unchanged, with `Serverless function execution` as the fallback | +| `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | ``, `Vue `, `Application Render`, or `init` | The unwrapped component name, or `Component mount`, `Component render`, `Component update`, or `Component unmount` | +| `ui.task` | `runloop` | `UI task` | +| `ui.action.click` | The pageload or navigation span's name | `router.navigation.route.id`, `url.template`, or `http.route`, in that order, or `Click` | +| `ui.interaction.*` | The element's DOM path | The annotated component name, or `Click`, `Hover`, `Drag`, or `Key press` | +| `ui.webvital.lcp` | The LCP element's DOM path | The annotated component name, or `Largest contentful paint` | +| `ui.webvital.cls` | The first layout-shift source's DOM path | The annotated component name, or `Layout shift` | -A few consequences worth checking: +In transaction mode, span names remain unchanged. A few consequences worth checking: - `useOperationNameForRootSpan` no longer renames the enclosing root span. The operations stay on that span's `sentry.graphql.operation` attribute. - `graphqlClientIntegration` no longer appends the operation to the outgoing request span name. It's on `graphql.operation.name` and `graphql.operation.type` instead. @@ -66,6 +82,37 @@ A few consequences worth checking: + + +Browser navigation timing spans use these names: + +| Span op | Name | +| ---------------------------------- | ------------------------ | +| `browser.cache` | `Cache lookup` | +| `browser.dns` | `DNS lookup` | +| `browser.connect` | `Connect` | +| `browser.tls_ssl` | `TLS handshake` | +| `browser.redirect` | `Redirect` | +| `browser.request` | `Request` | +| `browser.response` | `Response` | +| `browser.unload_event` | `Unload event` | +| `browser.dom_content_loaded_event` | `DOMContentLoaded event` | +| `browser.load_event` | `Load event` | + +The document URL stays on `url.full` in both trace lifecycles, subject to `dataCollection.urlQueryParams`. Update name-based filters to use that attribute. + +Framework function spans keep the previous name on `sentry.description`. For SvelteKit, this includes `wrapLoadWithSentry`, `wrapServerLoadWithSentry`, `wrapServerRouteWithSentry`, and spans from SvelteKit's own tracing. Match the route on `http.route`, or `url.template` for client-side universal loads, and the request path on `url.path`. + +GCP and Firebase function names come from `FUNCTION_TARGET` or `K_SERVICE`. The function name stays on `faas.name`, trigger details on `gcp.function.context.*`, and HTTP method and path on `http.request.method` and `url.path`. AWS Lambda spans fall back to `Serverless function execution` when neither the invocation context nor `AWS_LAMBDA_FUNCTION_NAME` provides a name. Their `sentry.segment.name.source` is now `component` in both trace lifecycles. + +Component spans keep their original names on `sentry.description`. Vue's `Application Render` becomes `Root`, and Ember's `init` becomes `Component mount`. Update filters matching `` or `Vue ` to use the new name or the description. + +Click idle spans copy `router.navigation.route.id`, `url.template`, `http.route`, `url.path`, and `url.full` from the route span. Event Timing and INP spans keep the DOM path on `browser.web_vital.inp.target` and the annotated component on `ui.component_name`, in both trace lifecycles. Match the target attribute if you previously filtered by DOM path. + +LCP and CLS DOM paths stay on `browser.web_vital.lcp.element` and `browser.web_vital.cls.source.1`. Long task and long animation frame names remain `Main UI thread blocked`. + + + `ignoreSpans` and `tracesSampler` both run when a span **starts**, so a span may not have its final name yet. Match on attributes instead: @@ -83,7 +130,7 @@ Sentry.init({ { attributes: { "db.query.text": "SELECT * FROM health_check" } }, ], tracesSampler: ({ attributes, inheritOrSampleWith }) => - inheritOrSampleWith(attributes["url.path"] === "/health" ? 0 : 1), + inheritOrSampleWith(attributes?.["url.path"] === "/health" ? 0 : 1), }); ``` diff --git a/includes/migration/javascript-v11/span-op-changes.mdx b/includes/migration/javascript-v11/span-op-changes.mdx index ccb3d73796b0d..757e1b28aece4 100644 --- a/includes/migration/javascript-v11/span-op-changes.mdx +++ b/includes/migration/javascript-v11/span-op-changes.mdx @@ -39,7 +39,7 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic | Frontend routing | `ui.angular.routing`, `ui.sveltekit.routing`, `ui.ember.transition` | `router` | | React, Vue, and Svelte component lifecycles | `ui.react.mount`/`render`/`update`, `ui.svelte.init`/`update`, Vue `render`/`update`/`mount`/`create`/`activate`/`unmount`/`destroy` | `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | | Angular tracing decorators | `ui.angular.init`, `ui.angular.` | `ui.mount`, `function` | -| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`function`/`ui.mount` | +| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`ui.resolve`/`ui.mount` | | Browser paint entries | `paint` | `browser.paint` | **Databases, cache, and messaging** diff --git a/includes/migration/javascript-v11/webpack-plugin-entry.mdx b/includes/migration/javascript-v11/webpack-plugin-entry.mdx new file mode 100644 index 0000000000000..5fbd4c05f6a8a --- /dev/null +++ b/includes/migration/javascript-v11/webpack-plugin-entry.mdx @@ -0,0 +1,20 @@ +--- +id: webpack-plugin-entry +title: "The webpack plugin requires webpack 5.1 and a new import path" +phase: packages +category: removed-api +severity: action-required +frameworks: all +platformCategory: all +order: 68 +--- + +The Sentry webpack plugin requires webpack **5.1** or newer. The `@sentry/bundler-plugins/webpack5` entry point was removed. Update imports to `@sentry/bundler-plugins/webpack`: + +```js +// Before +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack5"; + +// After +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack"; +``` From 4772a16c8afa0babe6df0bcf4bd53ea3bc0c02fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Wed, 23 Sep 2026 14:52:59 +0300 Subject: [PATCH 48/48] docs(cloudflare): Replace D1 page with a bindings overview (#19581) ## DESCRIBE YOUR PR `instrumentD1WithSentry` was removed in v11, and `withSentry()` instruments D1 and other bindings on env automatically. Remove the D1 page and add a Bindings page that lists which bindings the SDK instruments and what each one captures. Redirect the old D1 URL to the new page and link to it from the v11 migration entry. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: 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 supplied a deadline. 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](https://github.com/orgs/getsentry/teams/docs) ## LEGAL BOILERPLATE Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms. ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) Co-authored-by: Claude Opus 5.5 --- .../guides/cloudflare/features/bindings.mdx | 50 +++++++++++++++++++ .../guides/cloudflare/features/d1.mdx | 16 ------ .../cloudflare-instrument-d1.mdx | 2 +- redirects.js | 9 ++++ 4 files changed, 60 insertions(+), 17 deletions(-) create mode 100644 docs/platforms/javascript/guides/cloudflare/features/bindings.mdx delete mode 100644 docs/platforms/javascript/guides/cloudflare/features/d1.mdx diff --git a/docs/platforms/javascript/guides/cloudflare/features/bindings.mdx b/docs/platforms/javascript/guides/cloudflare/features/bindings.mdx new file mode 100644 index 0000000000000..5b2ea4429a4b5 --- /dev/null +++ b/docs/platforms/javascript/guides/cloudflare/features/bindings.mdx @@ -0,0 +1,50 @@ +--- +title: Cloudflare Bindings +sidebar_title: Bindings +description: "Learn which Cloudflare bindings Sentry instruments automatically and what each binding captures." +--- + +The Sentry Cloudflare SDK instruments the bindings on your `env` object automatically. You don't have to wrap a binding or call a function. When your code reads a binding from `env`, the SDK detects its type and returns an instrumented version. + +## Supported Bindings + +| Binding | What Sentry captures | +| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| [D1](https://developers.cloudflare.com/d1/) | Database queries | +| [R2](https://developers.cloudflare.com/r2/) | Bucket operations, such as reads and uploads | +| [Queues](https://developers.cloudflare.com/queues/) | Messages that you send to a queue | +| [Workers AI](https://developers.cloudflare.com/workers-ai/) | Model calls, see Workers AI | +| [Durable Objects](https://developers.cloudflare.com/durable-objects/) | Traces that continue in the Durable Object, see Cloudflare Durable Objects | +| [Service bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/) | Traces that continue in the other Worker, if it also uses Sentry | + +For RPC calls to Durable Objects and service bindings, add the binding to `rpcTracePropagationBindings`. + +## Which `env` Is Instrumented + +The SDK instruments the `env` object that Cloudflare gives to the handlers and classes that Sentry wraps, such as your Worker, Durable Objects, and Workflows. + + + +The global `env` that you import from `cloudflare:workers` is not instrumented. Bindings that you read from it don't create spans. Use the `env` argument of your handler or class instead: + +```javascript +import * as Sentry from "@sentry/cloudflare"; +import { env as globalEnv } from "cloudflare:workers"; + +export default Sentry.withSentry( + (env) => ({ dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0 }), + { + async fetch(request, env) { + // Creates a span: `env` is the handler argument + await env.DB.prepare("SELECT * FROM users").all(); + + // Does not create a span: `globalEnv` is the global env + await globalEnv.DB.prepare("SELECT * FROM users").all(); + + return new Response("OK"); + }, + } +); +``` + + diff --git a/docs/platforms/javascript/guides/cloudflare/features/d1.mdx b/docs/platforms/javascript/guides/cloudflare/features/d1.mdx deleted file mode 100644 index f9fa8b301ea63..0000000000000 --- a/docs/platforms/javascript/guides/cloudflare/features/d1.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Cloudflare D1 Instrumentation -description: "Learn how to add span instrumentation for Cloudflare D1." ---- - -You can use the `instrumentD1WithSentry` method to instrument [Cloudflare D1](https://developers.cloudflare.com/d1/), -Cloudflare's serverless SQL database with Sentry. - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -// env.DB is the D1 DB binding configured in your `wrangler.jsonc`/`wrangler.toml` config -const db = Sentry.instrumentD1WithSentry(env.DB); -// Now you can use the database as usual -await db.prepare("SELECT * FROM table WHERE id = ?").bind(1).run(); -``` diff --git a/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx b/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx index 3b2d1f1e09c1f..76545ea915bf1 100644 --- a/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx +++ b/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx @@ -9,4 +9,4 @@ platformCategory: serverless order: 430 --- -`instrumentD1WithSentry` was removed. `withSentry()` instruments all D1 bindings on `env` automatically. +`instrumentD1WithSentry` was removed. `withSentry()` instruments all D1 bindings on `env` automatically. Remove the call and use the binding directly. For the list of bindings that the SDK instruments, see [Cloudflare Bindings](/platforms/javascript/guides/cloudflare/features/bindings/). diff --git a/redirects.js b/redirects.js index c743142ec4d67..643052fa57bfc 100644 --- a/redirects.js +++ b/redirects.js @@ -2414,6 +2414,15 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/cloudflare/features/nodejs-compat/:path*', destination: '/platforms/javascript/guides/cloudflare/', }, + // instrumentD1WithSentry was removed in v11; withSentry() instruments D1 bindings automatically. + { + source: '/platforms/javascript/guides/cloudflare/features/d1.md', + destination: '/platforms/javascript/guides/cloudflare/features/bindings.md', + }, + { + source: '/platforms/javascript/guides/cloudflare/features/d1/:path*', + destination: '/platforms/javascript/guides/cloudflare/features/bindings/', + }, // honoIntegration was removed in v11 in favor of the @sentry/hono SDK. { source: