docs/migration/v6-to-v7.md
The v7 version of the JavaScript SDK requires a self-hosted version of Sentry 20.6.0 or higher.
The main goal of version 7 is to reduce bundle size. This version is breaking because we removed deprecated APIs, upgraded our build tooling, and restructured npm package contents. Below we will outline all the breaking changes you should consider when upgrading.
TL;DR If you only use basic features of Sentry, or you simply copy & pasted the setup examples from our docs, here's what changed for you:
@sentry/tracing alongside your Sentry SDK (e.g. @sentry/react
or @sentry/node), make sure to upgrade all of them to version 7.whitelistUrls and blacklistUrls have been renamed to allowUrls and denyUrls in the Sentry.init() options.UserAgent integration is now called HttpContext.Node.js version 6 has reached end of life in April 2019. For Sentry JavaScript SDK version 7, we will no longer be supporting version 6 of Node.js.
As far as SDK development goes, dropping support means no longer running integration tests for Node.js version 6, and also no longer handling edge cases specific to version 6. Running the new SDK version on Node.js v6 is therefore highly discouraged.
@sentry/minimalThe @sentry/minimal package was deleted and it's functionality was moved to @sentry/hub. All exports from
@sentry/minimal should be available in @sentry/hub other than _callOnClient function which was removed.
// New in v7:
import { addBreadcrumb, captureException, configureScope, setTag } from '@sentry/hub';
// Before:
import { addBreadcrumb, captureException, configureScope, setTag } from '@sentry/minimal';
In v7, we've updated the Client to have options separate from the options passed into Sentry.init. This means that
constructing a client now requires 3 options: integrations, transport and stackParser. These can be customized as
you see fit.
import { BrowserClient, defaultStackParser, defaultIntegrations, makeFetchTransport } from '@sentry/browser';
// New in v7:
const client = new BrowserClient({
transport: makeFetchTransport,
stackParser: defaultStackParser,
integrations: defaultIntegrations,
});
// Before:
const client = new BrowserClient();
Since you now explicitly pass in the dependencies of the client, you can also tree-shake out dependencies that you do not use this way. For example, you can tree-shake out the SDK's default integrations and only use the ones that you want like so:
import {
BrowserClient,
Breadcrumbs,
Dedupe,
defaultStackParser,
GlobalHandlers,
Integrations,
makeFetchTransport,
LinkedErrors,
} from '@sentry/browser';
// New in v7:
const client = new BrowserClient({
transport: makeFetchTransport,
stackParser: defaultStackParser,
integrations: [new Breadcrumbs(), new GlobalHandlers(), new LinkedErrors(), new Dedupe()],
});
@sentry/integrations PackageThe following classes will be removed from the @sentry/integrations package and can no longer be used:
AngularEmberVueThese classes have been superseded and were moved into their own packages, @sentry/angular, @sentry/ember, and
@sentry/vue in a previous version. Refer to those packages if you want to integrate Sentry into your Angular, Ember,
or Vue application.
From version 7 onwards, the CommonJS files in Sentry JavaScript SDK packages will use ES6.
If you need to support Internet Explorer 11 or old Node.js versions, we recommend using a preprocessing tool like Babel to convert Sentry packages to ES5.
CDN bundles will be ES6 by default. Files that followed the naming scheme bundle.es6.min.js were renamed to
bundle.min.js and any bundles using ES5 (files without .es6) turned into bundle.es5.min.js.
See our docs on CDN bundles for more information.
Up until v6.x, we have published our packages on npm with the following structure:
build folder contained CDN bundlesdist folder contained CommonJS files and TypeScript declarationsesm folder contained ESM files and TypeScript declarationsMoving forward the JavaScript SDK packages will generally have the following structure:
cjs folder contains CommonJS filesesm folder contains ESM filestypes folder contains TypeScript declarationsCDN bundles of version 7 or higher will no longer be distributed through our npm package. This means that most third-party CDNs like unpkg or jsDelivr will also not provide them.
If you depend on any specific files in a Sentry JavaScript npm package, you will most likely need to update their
references. For example, imports on @sentry/browser/dist/client will become @sentry/browser/cjs/client. However,
directly importing from specific files is discouraged.
API class from @sentry/coreThe internal API class was removed in favor of using client options explicitly.
// New in v7:
import {
initAPIDetails,
getEnvelopeEndpointWithUrlEncodedAuth,
getStoreEndpointWithUrlEncodedAuth,
} from '@sentry/core';
const client = getCurrentHub().getClient();
const dsn = client.getDsn();
const options = client.getOptions();
const envelopeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(dsn, options.tunnel);
// Before:
import { API } from '@sentry/core';
const api = new API(dsn, metadata, tunnel);
const dsn = api.getDsn();
const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth();
const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth();
The Transport API was simplified and some functionality (e.g. APIDetails and client reports) was refactored and moved
to the Client. To send data to Sentry, we switched from the previously used
Store endpoint to the
Envelopes endpoint.
This example shows the new v7 and the v6 Transport API:
// New in v7:
export interface Transport {
/* Sends an envelope to the Envelope endpoint in Sentry */
send(request: Envelope): PromiseLike<void>;
/* Waits for all events to be sent or the timeout to expire, whichever comes first */
flush(timeout?: number): PromiseLike<boolean>;
}
// Before:
export interface Transport {
/* Sends the event to the Store endpoint in Sentry */
sendEvent(event: Event): PromiseLike<Response>;
/* Sends the session to the Envelope endpoint in Sentry */
sendSession?(session: Session | SessionAggregates): PromiseLike<Response>;
/* Waits for all events to be sent or the timeout to expire, whichever comes first */
close(timeout?: number): PromiseLike<boolean>;
/* Increment the counter for the specific client outcome */
recordLostEvent?(type: Outcome, category: SentryRequestType): void;
}
If you rely on a custom transport, you will need to make some adjustments to how it is created when migrating to v7.
Note that we changed our transports from a class-based to a functional approach, meaning that the previously class-based
transports are now created via functions. This also means that custom transports are now passed by specifying a factory
function in the Sentry.init options object instead passing the custom transport's class.
The following example shows how to create a custom transport in v7 vs. how it was done in v6:
// New in v7:
import { BaseTransportOptions, Transport, TransportMakeRequestResponse, TransportRequest } from '@sentry/types';
import { createTransport } from '@sentry/core';
export function makeMyCustomTransport(options: BaseTransportOptions): Transport {
function makeRequest(request: TransportRequest): PromiseLike<TransportMakeRequestResponse> {
// this is where your sending logic goes
const myCustomRequest = {
body: request.body,
url: options.url
};
// you define how `sendMyCustomRequest` works
return sendMyCustomRequest(myCustomRequest).then(response => ({
headers: {
'x-sentry-rate-limits': response.headers.get('X-Sentry-Rate-Limits'),
'retry-after': response.headers.get('Retry-After'),
},
}));
}
// `createTransport` takes care of rate limiting and flushing
return createTransport(options, makeRequest);
}
Sentry.init({
dsn: '...',
transport: makeMyCustomTransport, // this function will be called when the client is initialized
...
})
// Before:
class MyCustomTransport extends BaseTransport {
constructor(options: TransportOptions) {
// initialize your transport here
super(options);
}
public sendEvent(event: Event): PromiseLike<Response> {
// this is where your sending logic goes
// `url` is decoded from dsn in BaseTransport
const myCustomRequest = createMyCustomRequestFromEvent(event, this.url);
return sendMyCustomRequest(myCustomRequest).then(() => resolve({status: 'success'}));
}
public sendSession(session: Session): PromiseLike<Response> {...}
// ...
}
Sentry.init({
dsn: '...',
transport: MyCustomTransport, // the constructor was called when the client was initialized
...
})
Overall, the new way of transport creation allows you to create your custom sending implementation without having to
deal with the conversion of events or sessions to envelopes. We recommend calling using the createTransport function
from @sentry/core as demonstrated in the example above which, besides creating the Transport object with your custom
logic, will also take care of rate limiting and flushing.
For a complete v7 transport implementation, take a look at our browser fetch transport.
To clean up the options interface, we now require users to pass down transport related options under the
transportOptions key. The options that were changed were caCerts, httpProxy, and httpsProxy. In addition,
httpProxy and httpsProxy were unified to a single option under the transportOptions key, proxy.
// New in v7:
Sentry.init({
dsn: '...',
transportOptions: {
caCerts: getMyCaCert(),
proxy: 'http://example.com',
},
});
// Before:
Sentry.init({
dsn: '...',
caCerts: getMyCaCert(),
httpsProxy: 'http://example.com',
});
Given that enums have a high bundle-size impact, our long term goal is to eventually remove all enums from the SDK in favor of string literals.
Status was removed (see
#4891).RequestSessionStatus was removed (see
#4889) in favor of string literals.SessionStatus was removed (see
#4890) in favor of string literals.The two enums SpanStatus, and Severity remain deprecated, as we decided to limit the number of high-impact breaking
changes in v7. They will be removed in the next major release which is why we strongly recommend moving to the
corresponding string literals. Here's how to adjust Severity and
SpanStatus.
Note: These changes are not relevant for the majority of Sentry users but if you are building an SDK on top of the
Javascript SDK, you might need to make some adaptions. The internal Session class was refactored and replaced with a
more functional approach in #5054. Instead of the class, we
now export a Session interface from @sentry/types and three utility functions to create and update a Session
object from @sentry/hub. This short example shows what has changed and how to deal with the new functions:
// New in v7:
import { makeSession, updateSession, closeSession } from '@sentry/hub';
const session = makeSession({ release: 'v1.0' });
updateSession(session, { environment: 'prod' });
closeSession(session, 'ok');
// Before:
import { Session } from '@sentry/hub';
const session = new Session({ release: 'v1.0' });
session.update({ environment: 'prod' });
session.close('ok');
We introduced a new way of propagating tracing and transaction-related information between services. This change adds
the baggage HTTP header to outgoing requests if the instrumentation of requests is
enabled. Since this adds a header to your HTTP requests, you might need to adjust your Server's CORS settings to allow
this additional header. Take a look at the
Sentry docs
for more in-depth instructions what to change.
For our efforts to reduce bundle size of the SDK we had to remove and refactor parts of the package which introduced a few changes to the API:
@sentry/apm package. @sentry/tracing should be used instead.user field from DSN. publicKey should be used instead.whitelistUrls and blacklistUrls options from Sentry.init. They have been superseded by
allowUrls and denyUrls specifically. See
our docs page on inclusive language for more details.Sentry from window object.Status, SessionStatus, and RequestSessionStatus enums. These were only part of an internal
API. If you are using these enums, we encourage you to to look at
b177690d,
5fc3147d, and
f99bdd16 to to see
the changes we've made to our code as result. We generally recommend using string literals instead of the removed
enums.getActiveDomain method and DomainAsCarrier type from @sentry/hub.registerRequestInstrumentation to instrumentOutgoingRequests in @sentry/tracing.Backend and port its functionality into Client (see
#4911 and
#4919). Backend was an unnecessary abstraction which is
not present in other Sentry SDKs. For the sake of reducing complexity, increasing consistency with other Sentry SDKs
and decreasing bundle-size, Backend was removed.UserAgent integration to HttpContext. (see
#5027)SDK_NAME export from @sentry/browser, @sentry/node, @sentry/tracing and @sentry/vue packages.eventStatusFromHttpCode to save on bundle size.BrowserTracing maxTransactionDuration option with finalTimeout optionignoreSentryErrors option from AWS lambda SDK. Errors originating from the SDK will now always be caught
internally.Integrations.BrowserTracing export from @sentry/nextjs. Please import BrowserTracing from
@sentry/nextjs directly.id property from BrowserTracing integration.event.stacktrace fieldThe Sentry Angular SDK (@sentry/angular) is now compiled with the Angular compiler (see
#4641). This change was necessary to fix a long-lasting bug
in the SDK (see #3282): TraceDirective and TraceModule
can now be used again without risking an application compiler error or having to disable AOT compilation.
As in v6, we continue to list Angular 10-13 in our peer dependencies, meaning that these are the Angular versions we officially support. If you are using v7 with Angular <10 in your project and you experience problems, we recommend staying on the latest 6.x version until you can upgrade your Angular version. As v7 of our SDK is compiled with the Angular 10 compiler and we upgraded our Typescript version, the SDK will work with Angular 10 and above. Tests have shown that Angular 9 seems to work as well (use at your own risk) but we recommend upgrading to a more recent Angular version.
Due to the compiler change, our NPM package structure changed as well as it now conforms to the
Angular Package Format v10. In
case you're importing from specific paths other than @sentry/angular you will have to adjust these paths. As an
example, import ... from '@sentry/angular/esm/injex.js' should be changed to
import ... from '@sentry/angular/esm2015/index.js'. Generally, we strongly recommend only importing from
@sentry/angular.
Version 6.18.0 deprecates the frameContextLines top-level option for the Node SDK. This option will be removed in an
upcoming major version. To migrate off of the top-level option, pass it instead to the new ContextLines integration.
// New in 6.18.0
init({
dsn: '__DSN__',
integrations: [new ContextLines({ frameContextLines: 10 })],
});
// Before:
init({
dsn: '__DSN__',
frameContextLines: 10,
});
You only need to make changes when migrating to 6.17.x if you are using our internal Dsn class. Our internal API
class and typescript enums were deprecated, so we recommend you migrate them as well.
The internal Dsn class was removed in 6.17.0. For additional details, you can look at the
PR where this change happened. To migrate, see the following
example.
// New in 6.17.0:
import { dsnToString, makeDsn } from '@sentry/utils';
const dsn = makeDsn(process.env.SENTRY_DSN);
console.log(dsnToString(dsn));
// Before:
import { Dsn } from '@sentry/utils';
const dsn = new Dsn(process.env.SENTRY_DSN);
console.log(dsn.toString());
The internal API class was deprecated, and will be removed in the next major release. More details can be found in the PR that made this change. To migrate, see the following example.
// New in 6.17.0:
import {
initAPIDetails,
getEnvelopeEndpointWithUrlEncodedAuth,
getStoreEndpointWithUrlEncodedAuth,
} from '@sentry/core';
const dsn = initAPIDetails(dsn, metadata, tunnel);
const dsn = api.dsn;
const storeEndpoint = getStoreEndpointWithUrlEncodedAuth(api.dsn);
const envelopeEndpoint = getEnvelopeEndpointWithUrlEncodedAuth(api.dsn, api.tunnel);
// Before:
import { API } from '@sentry/core';
const api = new API(dsn, metadata, tunnel);
const dsn = api.getDsn();
const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth();
const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth();
The enums Status, SpanStatus, and Severity were deprecated, and we've detailed how to migrate away from them
below. We also deprecated the TransactionMethod, Outcome and RequestSessionStatus enums, but those are
internal-only APIs. If you are using them, we encourage you to take a look at the corresponding PRs to see how we've
changed our code as a result.
TransactionMethod: https://github.com/getsentry/sentry-javascript/pull/4314Outcome: https://github.com/getsentry/sentry-javascript/pull/4315RequestSessionStatus: https://github.com/getsentry/sentry-javascript/pull/4316We deprecated the Status enum in @sentry/types and it will be removed in the next major release. We recommend using
string literals to save on bundle size. PR. We also removed
the Status.fromHttpCode method. This was done to save on bundle size.
// New in 6.17.0:
import { eventStatusFromHttpCode } from '@sentry/utils';
const status = eventStatusFromHttpCode(500);
// Before:
import { Status } from '@sentry/types';
const status = Status.fromHttpCode(500);
We deprecated the Status enum in @sentry/tracing and it will be removed in the next major release. We recommend
using string literals to save on bundle size. PR. We also
removed the SpanStatus.fromHttpCode method. This was done to save on bundle size.
// New in 6.17.0:
import { spanStatusfromHttpCode } from '@sentry/tracing';
const status = spanStatusfromHttpCode(403);
// Before:
import { SpanStatus } from '@sentry/tracing';
const status = SpanStatus.fromHttpCode(403);
We deprecated the Severity enum in @sentry/types and it will be removed in the next major release. We recommend
using string literals (typed as SeverityLevel) to save on bundle size.
// New in 6.17.5:
import { SeverityLevel } from '@sentry/types';
const levelA = "error" as SeverityLevel;
const levelB: SeverityLevel = "error"
// Before:
import { Severity, SeverityLevel } from '@sentry/types';
const levelA = Severity.error;
const levelB: SeverityLevel = "error"