# Workflow: migrate the JS SDK from v10 to v11

v11 changes how spans are collected, what gets collected by default, and which options still exist. Treat it as a migration, not a version bump.

## 1. Check the gates first

- Node 20.19.0 or newer (special minimums apply on Node 22 and 23). Older runtimes cannot run v11.
- Self-hosted Sentry 26.4.2 or newer. Span streaming needs a backend that understands it.
- If either gate fails, stop. Upgrade those first.

## 2. Audit the dead options

These no longer work in v11's streaming mode:

- `beforeSendTransaction` and `ignoreTransactions`: replace with span processors or sampling logic.
- `sendDefaultPii`: replaced by `dataCollection`. Note v11 collects more by default than v10, so review what now flows.

Search the codebase for each before upgrading. Every hit is a behavior change, not just a rename.

## 3. Move span metadata to attributes

Scope tags and extras no longer propagate to spans in stream mode. Use `setAttribute` for span metadata instead. Anything you filter or alert on that was a tag needs migrating, or those alerts go blind.

## 4. Upgrade in stages

1. Staging first, with the full test suite plus synthetic traffic.
2. Compare event volume and content before/after: more data by default means quota impact. Check usage stats, not just functionality.
3. Canary one production service. Watch for the two silent breakages: missing transaction filters and missing span metadata.
4. Roll out fleet-wide.

## 5. Verify the data contract

After each stage, confirm: error events still carry the expected context, spans carry attributes (not tags), sampling behaves as configured, and dashboards/queries built on old tag names are updated or replaced.

## Verify

One production release cycle with no data-contract surprises: volume within expected bounds, all downstream queries and alerts working, and the old v10 options fully removed from the codebase.