You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/migration/v8-to-v9.md
+113-107
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,5 @@
1
1
# Upgrading from 8.x to 9.x
2
2
3
-
**DISCLAIMER: THIS MIGRATION GUIDE IS WORK IN PROGRESS**
4
-
5
3
Version 9 of the Sentry SDK concerns API cleanup and compatibility updates.
6
4
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).
7
5
@@ -24,7 +22,7 @@ This includes features like Nullish Coalescing (`??`), Optional Chaining (`?.`),
24
22
If you observe failures due to syntax or features listed above, it may indicate that your current runtime does not support ES2020.
25
23
If your runtime does not support ES2020, we recommend transpiling the SDK using Babel or similar tooling.
26
24
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.
28
26
We no longer test against Node 14 and Node 16 and cannot guarantee that the SDK will work as expected on these versions.
29
27
30
28
**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:
52
50
53
51
### TypeScript Version Policy
54
52
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`.
56
54
57
55
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.
58
56
@@ -71,7 +69,7 @@ Older Typescript versions _may_ still work, but we will not test them anymore an
71
69
});
72
70
```
73
71
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.
75
73
- The `beforeSendSpan` hook now receives the root span as well as the child spans.
76
74
- 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):
77
75
@@ -154,7 +152,7 @@ Older Typescript versions _may_ still work, but we will not test them anymore an
154
152
155
153
- The `sentry` property on the Next.js config object has officially been discontinued. Pass options to `withSentryConfig` directly.
156
154
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`)
158
156
159
157
- Updated source map generation to respect the user-provided value of your build config, such as `vite.build.sourcemap`:
160
158
@@ -170,10 +168,6 @@ The `componentStack` field in the `ErrorBoundary` component is now typed as `str
170
168
171
169
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.
172
170
173
-
### Uncategorized (TODO)
174
-
175
-
TODO
176
-
177
171
## 3. Package Removals
178
172
179
173
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.
190
184
We decided to keep this package around to temporarily lessen the upgrade burden.
191
185
It will be removed in a future major version.
192
186
193
-
## 4. Removal of Deprecated APIs (TODO)
187
+
## 4. Removal of Deprecated APIs
194
188
195
189
### `@sentry/core` / All SDKs
196
190
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
+
197
195
- The `debugIntegration` has been removed. To log outgoing events, use [Hook Options](https://docs.sentry.io/platforms/javascript/configuration/options/#hooks) (`beforeSend`, `beforeSendTransaction`, ...).
196
+
198
197
- 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
+
199
199
- The `addOpenTelemetryInstrumentation` method has been removed. Use the `openTelemetryInstrumentations` option in `Sentry.init()` or your custom Sentry Client instead.
- The `DEFAULT_USER_INCLUDES` constant has been removed.
214
+
214
215
- 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.
215
216
216
217
### `@sentry/browser`
@@ -239,24 +240,23 @@ Sentry.init({
239
240
- The `sentrySolidStartVite` plugin is no longer exported. Instead, wrap the SolidStart config with `withSentry` and
240
241
provide Sentry options as the second parameter.
241
242
242
-
```
243
+
```ts
243
244
// app.config.ts
244
245
import { defineConfig } from '@solidjs/start/config';
/* Sentry build-time config (like project and org) */
255
+
},
256
+
),
250
257
);
251
258
```
252
259
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
-
260
260
### `@sentry/nestjs`
261
261
262
262
- 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
278
278
- The `wrapUseRoutes` method has been removed. Use the `wrapUseRoutesV6` or `wrapUseRoutesV7` methods instead depending on what version of react router you are using.
279
279
- The `wrapCreateBrowserRouter` method has been removed. Use the `wrapCreateBrowserRouterV6` or `wrapCreateBrowserRouterV7` methods depending on what version of react router you are using.
280
280
281
-
## `@sentry/vue`
281
+
### `@sentry/vue`
282
282
283
283
- The options `tracingOptions`, `trackComponents`, `timeout`, `hooks` have been removed everywhere except in the `tracingOptions` option of `vueIntegration()`.
284
284
@@ -313,6 +313,13 @@ The following changes are unlikely to affect users of the SDK. They are listed h
313
313
314
314
- 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.
315
315
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. Theevent was no longer used for some time, instead you can (optionally) pass a count of dropped events as third argument.
322
+
316
323
## 5. Build Changes
317
324
318
325
Previously the CJS versions of the SDKcode (wrongfully) contained compatibility statements for default exportsinESM:
@@ -326,19 +333,18 @@ Let us know if this is causing issues in your setup by opening an issue on GitHu
326
333
327
334
### `@sentry/deno`
328
335
329
-
The minimum supported Deno version is now **2.0.0**.
336
+
-The minimum supported Deno versionfor the Deno SDK (`@sentry/deno`) is now **2.0.0**.
330
337
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:
333
339
334
-
```javascript
335
-
import * as Sentry from 'npm:@sentry/deno';
340
+
```javascript
341
+
import * as Sentry from 'npm:@sentry/deno';
336
342
337
-
Sentry.init({
338
-
dsn: '__DSN__',
339
-
// ...
340
-
});
341
-
```
343
+
Sentry.init({
344
+
dsn: '__DSN__',
345
+
// ...
346
+
});
347
+
```
342
348
343
349
## 6. Type Changes
344
350
@@ -383,49 +389,49 @@ The following outlines deprecations that were introduced in version 8 of the SDK
383
389
384
390
-**Passing `undefined` to `tracesSampleRate`/`tracesSampler`/`enableTracing` will be handled differently in v9**
385
391
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.
387
393
388
-
```ts
389
-
Sentry.init({
390
-
tracesSampleRate: undefined,
391
-
});
392
-
```
394
+
```ts
395
+
Sentry.init({
396
+
tracesSampleRate: undefined,
397
+
});
398
+
```
393
399
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.
395
401
396
-
If you are relying on `undefined` being passed in and having tracing enabled because ofthis, 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 ofthis, you should update your config to set e.g. `tracesSampleRate: 0` instead, which will also enable tracing in v9.
397
403
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).
399
405
400
406
-**The `autoSessionTracking` option is deprecated.**
401
407
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.
403
409
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, inNode.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, inNode.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.
406
412
407
-
-**The metrics APIhas been removed from the SDK.**
413
+
-**The metrics APIis deprecated.**
408
414
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`ofthe SDK. Learn more in the Sentry [help center docs](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Metrics-Beta-Ended-on-October-7th).
410
416
411
417
## `@sentry/utils`
412
418
413
419
-**The `@sentry/utils`package has been deprecated. Import everything from `@sentry/core` instead.**
414
420
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.
429
435
430
436
## `@sentry/core`
431
437
@@ -461,10 +467,10 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
461
467
462
468
- **The `@sentry/types` package has been deprecated. Import everything from `@sentry/core` instead.**
463
469
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.
468
474
469
475
## `@sentry/nuxt`
470
476
@@ -474,23 +480,23 @@ The Sentry metrics beta has ended and the metrics API has been removed from the
474
480
475
481
- Deprecated `tracingOptions`, `trackComponents`, `timeout`, `hooks` options everywhere other than in the `tracingOptions` option of the `vueIntegration()`.
476
482
477
-
These options should now be set as follows:
483
+
These options should now be set as follows:
478
484
479
-
```ts
480
-
import * as Sentry from '@sentry/vue';
485
+
```ts
486
+
import * as Sentry from '@sentry/vue';
481
487
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
+
```
494
500
495
501
- Deprecated `logErrors` in the `vueIntegration`. The Sentry Vue error handler will propagate the error to a user-defined error handler
496
502
or just re-throw the error (which will log the error without modifying).
@@ -499,24 +505,24 @@ Sentry.init({
499
505
500
506
- When component tracking is enabled, "update" spans are no longer created by default.
501
507
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
0 commit comments