feat(javascript): Add interactive JavaScript v11 migration guide

docs/platforms/javascript/common/migration/v10-to-v11.mdx

@@ -0,0 +1,45 @@
+---
+title: Migrate from 10.x to 11.x
+sidebar_order: 8870
+description: "Learn about migrating from Sentry JavaScript SDK 10.x to 11.x, with an interactive checklist of the changes that apply to your setup."
+notSupported:
+  - javascript.capacitor
+  - javascript.cordova
+  - javascript.electron
+---
+
+<PlatformSection supported={["javascript"]}>
+<Alert title="Using a framework or Node.js?" level="info">
+
+This page shows the changes that apply to browser JavaScript. To see the steps for your setup instead, switch to the guide for it with the platform dropdown in the top-left corner, or go straight to [Next.js](/platforms/javascript/guides/nextjs/migration/v10-to-v11/), [React](/platforms/javascript/guides/react/migration/v10-to-v11/), [Node.js](/platforms/javascript/guides/node/migration/v10-to-v11/), or [any other JavaScript platform](/platforms/javascript/).
+
+</Alert>
+</PlatformSection>
+
+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. For many of these breaking changes, you can migrate automatically:
+
+```bash
+npx sentry@latest migrate
+```
+
+We recommend upgrading to the most recent 10.x release first, since most of what v11 removes is already deprecated there.
+
+Version 11 is compatible with Sentry self-hosted 24.4.2 or higher, unchanged from v10. Lower versions may continue to work, but may not support all features.
+
+<Alert level="warning">
+
+TypeScript and other tooling won't catch all of these changes. Read through the steps below before upgrading, rather than upgrading and fixing what breaks.
+
+</Alert>
+
+## Your Migration Steps
+
+<MigrationGuide />
+
+## No Version Support Timeline
+
+Version support timelines are stressful for everybody using the SDK, so we won't be defining one. Instead, we will be applying bug fixes and features to older versions as long as there is demand.
+
+Additionally, we hold ourselves accountable to any security issues, meaning that if any vulnerabilities are found, we will in almost all cases backport them.
+
+It's decided on a case-by-case basis what gets backported. If you need a fix or feature in a previous version of the SDK, please reach out via a [GitHub issue](https://github.com/getsentry/sentry-javascript/issues).

docs/platforms/javascript/guides/effect/index.mdx

@@ -2,6 +2,10 @@
 title: Effect
 sdk: sentry.javascript.effect
 description: Learn how to set up and configure Sentry in your Effect application, capture your first errors, and view them in Sentry.
+categories:
+  - javascript
+  - server
+  - server-node
 ---
 
 <Alert level="warning" title="Important">

includes/migration/javascript-v11/ai-exports-moved.mdx

@@ -0,0 +1,17 @@
+---
+id: ai-exports-moved
+title: "AI instrumentation moved out of `@sentry/core`"
+phase: code-changes
+category: removed-api
+severity: action-required
+frameworks: all
+features: [ai-agents]
+platformCategory: server
+order: 270
+---
+
+AI instrumentation moved from `@sentry/core` to `@sentry/server-utils`, and is no longer available in the browser SDK. The `enableTruncation` and `streamGenAiSpans` flags were removed, along with the internal `sentry.sdk_meta.gen_ai.input.messages.original_length` attribute.
+
+Importing a helper from `@sentry/node` or another platform SDK still works. If you imported one directly from `@sentry/core`, import it from `@sentry/server-utils` instead: `instrumentOpenAiClient`, `instrumentAnthropicAiClient`, `instrumentGoogleGenAIClient`, `instrumentWorkersAiClient`, `createLangChainCallbackHandler`, `instrumentLangChainEmbeddings`, `instrumentStateGraph`, `instrumentStateGraphCompile`, `instrumentCreateReactAgent`, `addVercelAiProcessors`.
+
+Remove `enableTruncation` and `streamGenAiSpans` from your config, and remove AI integrations from browser setups.

includes/migration/javascript-v11/ai-internal-exports-removed.mdx

@@ -0,0 +1,17 @@
+---
+id: ai-internal-exports-removed
+title: "Low-level AI exports are no longer public API"
+phase: code-changes
+category: removed-api
+severity: informational
+frameworks: all
+features: [ai-agents]
+platformCategory: server
+order: 280
+---
+
+These provider-instrumentation internals are no longer exported from `@sentry/core`:
+
+- **Helpers:** `extractOpenAiRequestAttributes`, `addOpenAiRequestAttributes`, `addOpenAiResponseAttributes`, `extractOpenAiRequestParameters`, `instrumentOpenAiStream`, `extractAnthropicRequestAttributes`, `addAnthropicRequestAttributes`, `addAnthropicResponseAttributes`, `instrumentAsyncIterableStream`, `instrumentMessageStream`, `extractGoogleGenAIRequestAttributes`, `addGoogleGenAIRequestAttributes`, `addGoogleGenAIResponseAttributes`, `instrumentGoogleGenAIStream`, `getProviderMetadataAttributes`, `getTruncatedJsonString`, `shouldEnableTruncation`, `resolveAIRecordingOptions`, `wrapToolsWithSpans`, `extractLLMFromParams`, `extractAgentNameFromParams`, `instrumentCompiledGraphInvoke`
+- **Integration-name constants:** `OPENAI_INTEGRATION_NAME`, `ANTHROPIC_AI_INTEGRATION_NAME`, `GOOGLE_GENAI_INTEGRATION_NAME`, `LANGCHAIN_INTEGRATION_NAME`, `LANGGRAPH_INTEGRATION_NAME`
+- **Types:** `OpenAiClient`, `OpenAiOptions`, `InstrumentedMethod`, `AnthropicAiClient`, `AnthropicAiOptions`, `AnthropicAiResponse`, `AnthropicAiInstrumentedMethod`, `GoogleGenAIClient`, `GoogleGenAIChat`, `GoogleGenAIOptions`, `GoogleGenAIResponse`, `GoogleGenAIInstrumentedMethod`, `GoogleGenAIIstrumentedMethod`, `WorkersAiClient`, `WorkersAiOptions`, `LangChainOptions`, `LangChainIntegration`, `LangGraphOptions`, `LangGraphIntegration`, `CompiledGraph`

includes/migration/javascript-v11/ai-non-inference-spans.mdx

@@ -0,0 +1,15 @@
+---
+id: ai-non-inference-spans
+title: "AI integrations no longer trace non-inference operations"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+features: [ai-agents]
+platformCategory: server
+order: 90
+---
+
+AI integrations only trace model invocations, tool calls, and agent invocations now. Anthropic `messages.countTokens`, `models.retrieve` and `models.get`, and LangGraph `gen_ai.create_agent` on graph compilation, no longer produce spans.
+
+Update dashboards and alerts that reference these spans.

includes/migration/javascript-v11/astro-min-version.mdx

@@ -0,0 +1,15 @@
+---
+id: astro-min-version
+title: "Astro 3 support was dropped"
+phase: prerequisites
+category: version-support
+severity: action-required
+frameworks: [astro]
+features: []
+platformCategory: all
+order: 70
+---
+
+`@sentry/astro` now requires Astro 4.
+
+Upgrade Astro before upgrading the SDK.

includes/migration/javascript-v11/astro-runtime-options.mdx

@@ -0,0 +1,44 @@
+---
+id: astro-runtime-options
+title: "Runtime SDK options moved out of `sentryAstro()`"
+phase: code-changes
+category: removed-api
+severity: action-required
+frameworks: [astro]
+features: []
+platformCategory: all
+order: 400
+---
+
+Runtime SDK options (`dsn`, `environment`, `release` as a string, `sampleRate`, `tracesSampleRate`, `replaysSessionSampleRate`, `replaysOnErrorSampleRate`) can no longer be passed to `sentryAstro()`. `release` and `debug` are build-time options now, and the generated client snippet always includes the `Replay` integration.
+
+Keep build-time options in `astro.config.mjs`:
+
+```ts
+export default defineConfig({
+  integrations: [
+    sentry({
+      org: 'my-org',
+      project: 'my-project',
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+      release: { name: '1.0.0' },
+      debug: true,
+    }),
+  ],
+});
+```
+
+Move runtime options to `sentry.client.config.ts` or `sentry.server.config.ts`:
+
+```ts
+import * as Sentry from '@sentry/astro';
+
+Sentry.init({
+  dsn: 'https://example@sentry.io/123',
+  release: '1.0.0',
+  environment: 'production',
+  tracesSampleRate: 0.5,
+});
+```
+
+To customize or remove Replay, create a `sentry.client.config.ts`.

includes/migration/javascript-v11/attach-stacktrace-default.mdx

@@ -0,0 +1,15 @@
+---
+id: attach-stacktrace-default
+title: "`attachStacktrace` now defaults to `true`"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+features: []
+platformCategory: all
+order: 40
+---
+
+`attachStacktrace` now defaults to `true`, so `Sentry.captureMessage` events and non-`Error` values passed to `Sentry.captureException` get a synthetic stack trace. Expect new issue groups, and expect these events to mark sessions as errored (crash-free rate is unaffected).
+
+Set `attachStacktrace: false` to restore the previous behavior. For purely informational output, use Sentry Logs instead.

includes/migration/javascript-v11/aws-lambda-layer.mdx

@@ -0,0 +1,15 @@
+---
+id: aws-lambda-layer
+title: "A new AWS Lambda Layer is published for v11"
+phase: packages
+category: package
+severity: action-required
+frameworks: [aws-lambda]
+features: []
+platformCategory: serverless
+order: 50
+---
+
+The v11 AWS Lambda Layer is published as `SentryNodeServerlessSDKv11`. Version 10 updates continue as `SentryNodeServerlessSDKv10`.
+
+Point your functions at the new layer ARN, listed in the [Lambda layer docs](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/install/cjs-layer/). The layer supports the `nodejs20.x`, `nodejs22.x`, and `nodejs24.x` runtimes, so functions on `nodejs18.x` need a newer runtime first.

includes/migration/javascript-v11/before-send-span-format.mdx

@@ -0,0 +1,49 @@
+---
+id: before-send-span-format
+title: "`beforeSendSpan` receives the streamed span format"
+phase: code-changes
+category: behavior
+severity: action-required
+frameworks: all
+features: [tracing]
+platformCategory: all
+order: 50
+---
+
+`beforeSendSpan` now receives a `StreamedSpanJSON` object as each span finishes, rather than every span of a transaction just before it is sent. The fields were renamed:
+
+| Before (`SpanJSON`) | After (`StreamedSpanJSON`)     |
+| ------------------- | ------------------------------ |
+| `description`       | `name`                         |
+| `data`              | `attributes`                   |
+| `op`                | `attributes['sentry.op']`      |
+| `timestamp`         | `end_timestamp`                |
+| `status` (`string`) | `status` (`'ok'` or `'error'`) |
+
+Update the callback:
+
+```js
+// Before
+Sentry.init({
+  beforeSendSpan: span => {
+    if (span.op === 'db.query') {
+      span.description = scrub(span.description);
+      span.data['db.statement'] = scrub(span.data['db.statement']);
+    }
+    return span;
+  },
+});
+
+// After
+Sentry.init({
+  beforeSendSpan: span => {
+    if (span.attributes?.['sentry.op'] === 'db.query') {
+      span.name = scrub(span.name);
+      span.attributes['db.statement'] = scrub(span.attributes['db.statement']);
+    }
+    return span;
+  },
+});
+```
+
+Use `ignoreSpans` to drop spans; returning `null` is a no-op. A callback that does not match your `traceLifecycle` is never invoked: wrap it in `Sentry.withStaticSpan()` for `'static'`, leave it unwrapped for `'stream'`.

includes/migration/javascript-v11/before-send-transaction-removed.mdx

@@ -0,0 +1,41 @@
+---
+id: before-send-transaction-removed
+title: "`beforeSendTransaction` no longer runs"
+phase: code-changes
+category: behavior
+severity: action-required
+frameworks: all
+features: [tracing]
+platformCategory: all
+order: 60
+---
+
+`beforeSendTransaction` no-ops, because span streaming produces no transaction events.
+
+Move scrubbing to `beforeSendSpan` and guard on `is_segment`, and move dropping to `ignoreSpans`:
+
+```js
+// Before
+Sentry.init({
+  beforeSendTransaction: event => {
+    if (event.transaction === 'GET /health') {
+      return null;
+    }
+    event.transaction = scrubIds(event.transaction);
+    return event;
+  },
+});
+
+// After
+Sentry.init({
+  ignoreSpans: ['GET /health'],
+  beforeSendSpan: span => {
+    if (span.is_segment) {
+      span.name = scrubIds(span.name);
+    }
+    return span;
+  },
+});
+```
+
+Scope `tags` and `extra` are not carried over to streamed spans. Use `Sentry.setAttribute()` or `Sentry.setAttributes()`.

includes/migration/javascript-v11/browser-http-headers-data-collection.mdx

@@ -0,0 +1,15 @@
+---
+id: browser-http-headers-data-collection
+title: "Browser request headers follow `dataCollection`"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+features: []
+platformCategory: browser
+order: 140
+---
+
+`httpContextIntegration` attached `Referer` and `User-Agent` regardless of your configuration. Both now filter through `dataCollection.httpHeaders.request`, matching the server SDKs. Headers you set yourself are left alone.
+
+Nothing to do, unless you set `httpHeaders: { request: false }` and relied on those two headers still arriving from the browser.

includes/migration/javascript-v11/browser-session-lifecycle-page.mdx

@@ -0,0 +1,21 @@
+---
+id: browser-session-lifecycle-page
+title: "`page` is the default browser session lifecycle mode"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+features: []
+platformCategory: browser
+order: 30
+---
+
+`browserSessionIntegration` now defaults to `lifecycle: 'page'`, so a session is created on page load and not renewed on navigation. Expect session counts to drop for single-page apps.
+
+To keep the previous behavior:
+
+```js
+Sentry.init({
+  integrations: [Sentry.browserSessionIntegration({ lifecycle: 'route' })],
+});
+```

includes/migration/javascript-v11/browser-session-unhandled.mdx

@@ -0,0 +1,15 @@
+---
+id: browser-session-unhandled
+title: "Browser sessions use `unhandled` instead of `crashed`"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+features: []
+platformCategory: browser
+order: 20
+---
+
+Browser sessions affected by an uncaught error are recorded as `unhandled` instead of `crashed`, so crash-free session rates will shift.
+
+Review Release Health alerts built on crash-free rate before rolling out.

includes/migration/javascript-v11/browser-support.mdx

@@ -0,0 +1,15 @@
+---
+id: browser-support
+title: "Safari 14 support was dropped"
+phase: prerequisites
+category: version-support
+severity: behavior-change
+frameworks: all
+features: []
+platformCategory: browser
+order: 30
+---
+
+The SDK now supports Safari 15 and higher. Safari 14 was dropped.
+
+Some SDK features rely on newer browser APIs and don't work on Safari 15.

includes/migration/javascript-v11/browser-user-timing.mdx

@@ -0,0 +1,32 @@
+---
+id: browser-user-timing
+title: "`performance.mark()` spans moved to `userTimingIntegration`"
+phase: code-changes
+category: removed-api
+severity: action-required
+frameworks: all
+features: [tracing]
+platformCategory: browser
+order: 210
+---
+
+`browserTracingIntegration` no longer captures `performance.mark()` and `performance.measure()` spans. The `ignorePerformanceApiSpans` option moved to `userTimingIntegration` as `ignore`.
+
+Add `userTimingIntegration()` to keep capturing them:
+
+```js
+// Before
+Sentry.init({
+  integrations: [
+    Sentry.browserTracingIntegration({ ignorePerformanceApiSpans: ['third-party-mark'] }),
+  ],
+});
+
+// After
+Sentry.init({
+  integrations: [
+    Sentry.browserTracingIntegration(),
+    Sentry.userTimingIntegration({ ignore: ['third-party-mark'] }),
+  ],
+});
+```