Skip to content

Commit 9ce4ad1

Browse files
authored
chore: Review copy/formatting for migration docs (#15178)
Some more formatting changes to the migration docs, also remove todos where appropriate.
1 parent d12d105 commit 9ce4ad1

File tree

1 file changed

+113
-107
lines changed

1 file changed

+113
-107
lines changed

docs/migration/v8-to-v9.md

+113-107
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# Upgrading from 8.x to 9.x
22

3-
**DISCLAIMER: THIS MIGRATION GUIDE IS WORK IN PROGRESS**
4-
53
Version 9 of the Sentry SDK concerns API cleanup and compatibility updates.
64
This update contains behavioral changes that will not be caught by TypeScript or linters, so we recommend carefully reading the section on [Behavioral Changes](#2-behavior-changes).
75

@@ -24,7 +22,7 @@ This includes features like Nullish Coalescing (`??`), Optional Chaining (`?.`),
2422
If you observe failures due to syntax or features listed above, it may indicate that your current runtime does not support ES2020.
2523
If your runtime does not support ES2020, we recommend transpiling the SDK using Babel or similar tooling.
2624

27-
**Node.js:** The minimum supported Node.js version is **18.0.0**, except for ESM-only SDKs (nuxt, solidstart, astro) which require Node **18.19.1** or up.
25+
**Node.js:** The minimum supported Node.js version is **18.0.0**, except for ESM-only SDKs (`@sentry/astro`, `@sentry/nuxt`, `@sentry/sveltekit`) which require Node.js version **18.19.1** or higher.
2826
We no longer test against Node 14 and Node 16 and cannot guarantee that the SDK will work as expected on these versions.
2927

3028
**Browsers:** Due to SDK code now including ES2020 features, the minimum supported browser list now looks as follows:
@@ -52,7 +50,7 @@ Support for the following frameworks and library versions are dropped:
5250

5351
### TypeScript Version Policy
5452

55-
In preparation for the OpenTelemetry SDK v2, which will raise the minimum required TypeScript version, the minimum required TypeScript version is increased to version `5.0.4` (TBD https://github.com/open-telemetry/opentelemetry-js/pull/5145).
53+
In preparation for the OpenTelemetry SDK v2, which will raise the minimum required TypeScript version, the minimum required TypeScript version is increased to version `5.0.4`.
5654

5755
Additionally, like the OpenTelemetry SDK, the Sentry JavaScript SDK will follow [DefinitelyType's version support policy](https://github.com/DefinitelyTyped/DefinitelyTyped#support-window) which has a support time frame of 2 years for any released version of TypeScript.
5856

@@ -71,7 +69,7 @@ Older Typescript versions _may_ still work, but we will not test them anymore an
7169
});
7270
```
7371

74-
- Dropping spans in the `beforeSendSpan` hook is no longer possible.
72+
- Dropping spans in the `beforeSendSpan` hook is no longer possible. This means you cannot return `null` from the `beforeSendSpan` hook anymore.
7573
- The `beforeSendSpan` hook now receives the root span as well as the child spans.
7674
- In previous versions, we determined if tracing is enabled (for Tracing Without Performance) by checking if either `tracesSampleRate` or `traceSampler` are _defined_ at all, in `Sentry.init()`. This means that e.g. the following config would lead to tracing without performance (=tracing being enabled, even if no spans would be started):
7775

@@ -154,7 +152,7 @@ Older Typescript versions _may_ still work, but we will not test them anymore an
154152

155153
- The `sentry` property on the Next.js config object has officially been discontinued. Pass options to `withSentryConfig` directly.
156154

157-
### All Meta-Framework SDKs (`@sentry/astro`, `@sentry/nuxt`, `@sentry/solidstart`)
155+
### All Meta-Framework SDKs (`@sentry/astro`, `@sentry/nextjs`, `@sentry/nuxt`, `@sentry/sveltekit`, `@sentry/solidstart`)
158156

159157
- Updated source map generation to respect the user-provided value of your build config, such as `vite.build.sourcemap`:
160158

@@ -170,10 +168,6 @@ The `componentStack` field in the `ErrorBoundary` component is now typed as `str
170168

171169
In the `onUnmount` lifecycle method, the `componentStack` field is now typed as `string | null`. The `componentStack` is `null` when no error has been thrown at time of unmount.
172170

173-
### Uncategorized (TODO)
174-
175-
TODO
176-
177171
## 3. Package Removals
178172

179173
As part of an architectural cleanup, we deprecated the following packages:
@@ -190,27 +184,34 @@ You may experience slight compatibility issues in the future by using it.
190184
We decided to keep this package around to temporarily lessen the upgrade burden.
191185
It will be removed in a future major version.
192186
193-
## 4. Removal of Deprecated APIs (TODO)
187+
## 4. Removal of Deprecated APIs
194188
195189
### `@sentry/core` / All SDKs
196190
191+
- **The metrics API has been removed from the SDK.**
192+
193+
The Sentry metrics beta has ended and the metrics API has been removed from the SDK. Learn more in the Sentry [help center docs](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Metrics-Beta-Ended-on-October-7th).
194+
197195
- The `debugIntegration` has been removed. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...).
196+
198197
- The `sessionTimingIntegration` has been removed. To capture session durations alongside events, use [Context](https://docs.sentry.io/platforms/javascript/enriching-events/context/) (`Sentry.setContext()`).
198+
199199
- The `addOpenTelemetryInstrumentation` method has been removed. Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead.
200200
201-
```js
202-
import * as Sentry from '@sentry/node';
201+
```js
202+
import * as Sentry from '@sentry/node';
203203
204-
// before
205-
Sentry.addOpenTelemetryInstrumentation(new GenericPoolInstrumentation());
204+
// before
205+
Sentry.addOpenTelemetryInstrumentation(new GenericPoolInstrumentation());
206206
207-
// after
208-
Sentry.init({
209-
openTelemetryInstrumentations: [new GenericPoolInstrumentation()],
210-
});
211-
```
207+
// after
208+
Sentry.init({
209+
openTelemetryInstrumentations: [new GenericPoolInstrumentation()],
210+
});
211+
```
212212
213213
- The `DEFAULT_USER_INCLUDES` constant has been removed.
214+
214215
- The `getCurrentHub()`, `Hub` and `getCurrentHubShim()` APIs have been removed. They were on compatibility life support since the release of v8 and have now been fully removed from the SDK.
215216
216217
### `@sentry/browser`
@@ -239,24 +240,23 @@ Sentry.init({
239240
- The `sentrySolidStartVite` plugin is no longer exported. Instead, wrap the SolidStart config with `withSentry` and
240241
provide Sentry options as the second parameter.
241242
242-
```
243+
```ts
243244
// app.config.ts
244245
import { defineConfig } from '@solidjs/start/config';
245246
import { withSentry } from '@sentry/solidstart';
246247
247-
export default defineConfig(withSentry(
248-
{ /* SolidStart config */ },
249-
{ /* Sentry build-time config (like project and org) */ })
248+
export default defineConfig(
249+
withSentry(
250+
{
251+
/* SolidStart config */
252+
},
253+
{
254+
/* Sentry build-time config (like project and org) */
255+
},
256+
),
250257
);
251258
```
252259
253-
#### Other/Internal Changes
254-
255-
The following changes are unlikely to affect users of the SDK. They are listed here only for completion sake, and to alert users that may be relying on internal behavior.
256-
257-
- `client._prepareEvent()` now requires a currentScope & isolationScope to be passed as last arugments
258-
- `client.recordDroppedEvent()` no longer accepts an `event` as third argument. The event was no longer used for some time, instead you can (optionally) pass a count of dropped events as third argument.
259-
260260
### `@sentry/nestjs`
261261
262262
- Removed `WithSentry` decorator. Use the `SentryExceptionCaptured` decorator instead.
@@ -278,7 +278,7 @@ The following changes are unlikely to affect users of the SDK. They are listed h
278278
- The `wrapUseRoutes` method has been removed. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead depending on what version of react router you are using.
279279
- The `wrapCreateBrowserRouter` method has been removed. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods depending on what version of react router you are using.
280280
281-
## `@sentry/vue`
281+
### `@sentry/vue`
282282
283283
- The options `tracingOptions`, `trackComponents`, `timeout`, `hooks` have been removed everywhere except in the `tracingOptions` option of `vueIntegration()`.
284284
@@ -313,6 +313,13 @@ The following changes are unlikely to affect users of the SDK. They are listed h
313313

314314
- The `fetchProxyScriptNonce` option in `sentryHandle()` was removed due to security concerns. If you previously specified this option for your CSP policy, specify a [script hash](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#configure-csp-for-client-side-fetch-instrumentation) in your CSP config or [disable](https://docs.sentry.io/platforms/javascript/guides/sveltekit/manual-setup/#disable-client-side-fetch-proxy-script) the injection of the script entirely.
315315

316+
#### Other/Internal Changes
317+
318+
The following changes are unlikely to affect users of the SDK. They are listed here only for completion sake, and to alert users that may be relying on internal behavior.
319+
320+
- `client._prepareEvent()` now requires a currentScope & isolationScope to be passed as last arugments
321+
- `client.recordDroppedEvent()` no longer accepts an `event` as third argument. The event was no longer used for some time, instead you can (optionally) pass a count of dropped events as third argument.
322+
316323
## 5. Build Changes
317324

318325
Previously the CJS versions of the SDK code (wrongfully) contained compatibility statements for default exports in ESM:
@@ -326,19 +333,18 @@ Let us know if this is causing issues in your setup by opening an issue on GitHu
326333

327334
### `@sentry/deno`
328335

329-
The minimum supported Deno version is now **2.0.0**.
336+
- The minimum supported Deno version for the Deno SDK (`@sentry/deno`) is now **2.0.0**.
330337

331-
- `@sentry/deno` is no longer published on `deno.land` so you'll need to import
332-
from npm:
338+
- `@sentry/deno` is no longer published on the `deno.land` registry so you'll need to import the SDK from npm:
333339
334-
```javascript
335-
import * as Sentry from 'npm:@sentry/deno';
340+
```javascript
341+
import * as Sentry from 'npm:@sentry/deno';
336342
337-
Sentry.init({
338-
dsn: '__DSN__',
339-
// ...
340-
});
341-
```
343+
Sentry.init({
344+
dsn: '__DSN__',
345+
// ...
346+
});
347+
```
342348
343349
## 6. Type Changes
344350
@@ -383,49 +389,49 @@ The following outlines deprecations that were introduced in version 8 of the SDK
383389

384390
- **Passing `undefined` to `tracesSampleRate` / `tracesSampler` / `enableTracing` will be handled differently in v9**
385391

386-
In v8, explicitly setting `tracesSampleRate` (even if it is set to `undefined`) resulted in tracing being _enabled_, although no spans were generated.
392+
In v8, explicitly setting `tracesSampleRate` (even if it is set to `undefined`) resulted in tracing being _enabled_, although no spans were generated.
387393

388-
```ts
389-
Sentry.init({
390-
tracesSampleRate: undefined,
391-
});
392-
```
394+
```ts
395+
Sentry.init({
396+
tracesSampleRate: undefined,
397+
});
398+
```
393399

394-
In v9, we will streamline this behavior so that passing `undefined` will result in tracing being disabled, the same as not passing the option at all.
400+
In v9, we will streamline this behavior so that passing `undefined` will result in tracing being disabled, the same as not passing the option at all.
395401

396-
If you are relying on `undefined` being passed in and having tracing enabled because of this, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9.
402+
If you are relying on `undefined` being passed in and having tracing enabled because of this, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9.
397403

398-
The `enableTracing` option was removed. In v9, to emulate `enableTracing: true`, set `tracesSampleRate: 1`. To emulate `enableTracing: false`, remove the `tracesSampleRate` and `tracesSampler` options (if configured).
404+
The `enableTracing` option was removed. In v9, to emulate `enableTracing: true`, set `tracesSampleRate: 1`. To emulate `enableTracing: false`, remove the `tracesSampleRate` and `tracesSampler` options (if configured).
399405

400406
- **The `autoSessionTracking` option is deprecated.**
401407

402-
To enable session tracking, it is recommended to unset `autoSessionTracking` and ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added.
408+
To enable session tracking, it is recommended to unset `autoSessionTracking` and ensure that either, in browser environments the `browserSessionIntegration` is added, or in server environments the `httpIntegration` is added.
403409

404-
To disable session tracking, it is recommended unset `autoSessionTracking` and to remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`.
405-
Additionally, in Node.js environments, a session was automatically created for every node process when `autoSessionTracking` was set to `true`. This behavior has been replaced by the `processSessionIntegration` which is configured by default.
410+
To disable session tracking, it is recommended unset `autoSessionTracking` and to remove the `browserSessionIntegration` in browser environments, or in server environments configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`.
411+
Additionally, in Node.js environments, a session was automatically created for every node process when `autoSessionTracking` was set to `true`. This behavior has been replaced by the `processSessionIntegration` which is configured by default.
406412

407-
- **The metrics API has been removed from the SDK.**
413+
- **The metrics API is deprecated.**
408414

409-
The Sentry metrics beta has ended and the metrics API has been removed from the SDK. Learn more in [help center docs](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Metrics-Beta-Ended-on-October-7th).
415+
The Sentry metrics beta has ended and the metrics API has been deprecated in `8.x`. The entire API will be removed in `9.x` of the SDK. Learn more in the Sentry [help center docs](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Metrics-Beta-Ended-on-October-7th).
410416

411417
## `@sentry/utils`
412418

413419
- **The `@sentry/utils` package has been deprecated. Import everything from `@sentry/core` instead.**
414420

415-
- Deprecated `AddRequestDataToEventOptions.transaction`. This option effectively doesn't do anything anymore, and will be removed in v9.
416-
- Deprecated `TransactionNamingScheme` type.
417-
- Deprecated `validSeverityLevels`. Will not be replaced.
418-
- Deprecated `urlEncode`. No replacements.
419-
- Deprecated `addRequestDataToEvent`. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`.
420-
- Deprecated `extractRequestData`. Instead manually extract relevant data off request.
421-
- Deprecated `arrayify`. No replacements.
422-
- Deprecated `memoBuilder`. No replacements.
423-
- Deprecated `getNumberOfUrlSegments`. No replacements.
424-
- Deprecated `BAGGAGE_HEADER_NAME`. Use the `"baggage"` string constant directly instead.
425-
- Deprecated `makeFifoCache`. No replacements.
426-
- Deprecated `dynamicRequire`. No replacements.
427-
- Deprecated `flatten`. No replacements.
428-
- Deprecated `_browserPerformanceTimeOriginMode`. No replacements.
421+
- Deprecated `AddRequestDataToEventOptions.transaction`. This option effectively doesn't do anything anymore, and will be removed in v9.
422+
- Deprecated `TransactionNamingScheme` type.
423+
- Deprecated `validSeverityLevels`. Will not be replaced.
424+
- Deprecated `urlEncode`. No replacements.
425+
- Deprecated `addRequestDataToEvent`. Use `httpRequestToRequestData` instead and put the resulting object directly on `event.request`.
426+
- Deprecated `extractRequestData`. Instead manually extract relevant data off request.
427+
- Deprecated `arrayify`. No replacements.
428+
- Deprecated `memoBuilder`. No replacements.
429+
- Deprecated `getNumberOfUrlSegments`. No replacements.
430+
- Deprecated `BAGGAGE_HEADER_NAME`. Use the `"baggage"` string constant directly instead.
431+
- Deprecated `makeFifoCache`. No replacements.
432+
- Deprecated `dynamicRequire`. No replacements.
433+
- Deprecated `flatten`. No replacements.
434+
- Deprecated `_browserPerformanceTimeOriginMode`. No replacements.
429435
430436
## `@sentry/core`
431437
@@ -461,10 +467,10 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
461467
462468
- **The `@sentry/types` package has been deprecated. Import everything from `@sentry/core` instead.**
463469
464-
- Deprecated `Request` in favor of `RequestEventData`.
465-
- Deprecated `RequestSession`. No replacements.
466-
- Deprecated `RequestSessionStatus`. No replacements.
467-
- Deprecated `SessionFlusherLike`. No replacements.
470+
- Deprecated `Request` in favor of `RequestEventData`.
471+
- Deprecated `RequestSession`. No replacements.
472+
- Deprecated `RequestSessionStatus`. No replacements.
473+
- Deprecated `SessionFlusherLike`. No replacements.
468474
469475
## `@sentry/nuxt`
470476
@@ -474,23 +480,23 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
474480
475481
- Deprecated `tracingOptions`, `trackComponents`, `timeout`, `hooks` options everywhere other than in the `tracingOptions` option of the `vueIntegration()`.
476482
477-
These options should now be set as follows:
483+
These options should now be set as follows:
478484
479-
```ts
480-
import * as Sentry from '@sentry/vue';
485+
```ts
486+
import * as Sentry from '@sentry/vue';
481487
482-
Sentry.init({
483-
integrations: [
484-
Sentry.vueIntegration({
485-
tracingOptions: {
486-
trackComponents: true,
487-
timeout: 1000,
488-
hooks: ['mount', 'update', 'unmount'],
489-
},
490-
}),
491-
],
492-
});
493-
```
488+
Sentry.init({
489+
integrations: [
490+
Sentry.vueIntegration({
491+
tracingOptions: {
492+
trackComponents: true,
493+
timeout: 1000,
494+
hooks: ['mount', 'update', 'unmount'],
495+
},
496+
}),
497+
],
498+
});
499+
```
494500
495501
- Deprecated `logErrors` in the `vueIntegration`. The Sentry Vue error handler will propagate the error to a user-defined error handler
496502
or just re-throw the error (which will log the error without modifying).
@@ -499,24 +505,24 @@ Sentry.init({
499505
500506
- When component tracking is enabled, "update" spans are no longer created by default.
501507
502-
Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior.
503-
504-
```ts
505-
Sentry.init({
506-
integrations: [
507-
Sentry.vueIntegration({
508-
tracingOptions: {
509-
trackComponents: true,
510-
hooks: [
511-
'mount',
512-
'update', // <--
513-
'unmount',
514-
],
515-
},
516-
}),
517-
],
518-
});
519-
```
508+
Add an `"update"` item to the `tracingOptions.hooks` option via the `vueIntegration()` to restore this behavior.
509+
510+
```ts
511+
Sentry.init({
512+
integrations: [
513+
Sentry.vueIntegration({
514+
tracingOptions: {
515+
trackComponents: true,
516+
hooks: [
517+
'mount',
518+
'update', // add this line to re-enable update spans
519+
'unmount',
520+
],
521+
},
522+
}),
523+
],
524+
});
525+
```
520526
521527
## `@sentry/astro`
522528

0 commit comments

Comments
 (0)