From 8a2faaadfecb999b7af70db4af773a7885808bec Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 28 Apr 2022 16:40:25 +0200 Subject: [PATCH 1/4] docs(transports): update Migration document with custom transport migration instructions --- MIGRATION.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index e7f2ecd7b028..a97df4516cde 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -102,7 +102,113 @@ const storeEndpoint = api.getStoreEndpointWithUrlEncodedAuth(); const envelopeEndpoint = api.getEnvelopeEndpointWithUrlEncodedAuth(); ``` -## Enum changes +## Transport Changes + +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](https://develop.sentry.dev/sdk/store/) to the [Envelopes endpoint](https://develop.sentry.dev/sdk/envelopes/). + +This example shows the new v7 and the v6 Transport API: + +```js +// New in v7: +export interface Transport { + /* Sends an envelope to the Envelope endpoint in Sentry */ + send(request: Envelope): PromiseLike; + /* Waits for all events to be sent or the timeout to expire, whichever comes first */ + flush(timeout?: number): PromiseLike; +} + +// Before: +export interface Transport { + /* Sends the event to the Store endpoint in Sentry */ + sendEvent(event: Event): PromiseLike; + /* Sends the session to the Envelope endpoint in Sentry */ + sendSession?(session: Session | SessionAggregates): PromiseLike; + /* Waits for all events to be sent or the timeout to expire, whichever comes first */ + close(timeout?: number): PromiseLike; + /* Increment the counter for the specific client outcome */ + recordLostEvent?(type: Outcome, category: SentryRequestType): void; +} +``` + +### Custom Transports +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 method 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: + +```js +// 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 { + // this is where your sending logic goes + const myCustomRequest = { + request.body, + url: options.url + }; + 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({ bufferSize: options.bufferSize }, 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 { + // 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 {...} + // ... +} + +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 `createTransport` 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. + +Passing in the factory function instead of an initialized transport provides the advantage that you do not have to take +care of decoding the URL from your DSN. Essentially, it provides the same abstraction level as in v6 +where you passed in the class instead of an instance. + +For a complete v7 transport implementation, take a look at our [browser fetch transport](https://github.com/getsentry/sentry-javascript/blob/ebc938a03d6efe7d0c4bbcb47714e84c9a566a9c/packages/browser/src/transports/fetch.ts#L1-L34). + +## Enum Changes 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. From 7d092ba3dae50fbd4606792d4eb4080910d39f3b Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 28 Apr 2022 17:00:44 +0200 Subject: [PATCH 2/4] fix wording --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index a97df4516cde..144d6d7af5ea 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -135,7 +135,7 @@ export interface Transport { 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 method in the `Sentry.init` options object instead passing the custom +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: From b81f1c7d119d12f4b7d9f0f87f6e2a05ee3d4587 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 28 Apr 2022 17:11:37 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Abhijeet Prasad --- MIGRATION.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 144d6d7af5ea..145e5e23689a 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -149,9 +149,10 @@ export function makeMyCustomTransport(options: BaseTransportOptions): Transport function makeRequest(request: TransportRequest): PromiseLike { // this is where your sending logic goes const myCustomRequest = { - request.body, + 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'), @@ -199,7 +200,7 @@ Sentry.init({ 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 `createTransport` as demonstrated in the example above which, besides creating the `Transport` +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. Passing in the factory function instead of an initialized transport provides the advantage that you do not have to take From e7b8291bfe260f94ddf81cf32f81a06a59db9d8b Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 28 Apr 2022 17:14:52 +0200 Subject: [PATCH 4/4] remove unnecessary paragraph --- MIGRATION.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 145e5e23689a..646fb4e86036 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -203,10 +203,6 @@ 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. -Passing in the factory function instead of an initialized transport provides the advantage that you do not have to take -care of decoding the URL from your DSN. Essentially, it provides the same abstraction level as in v6 -where you passed in the class instead of an instance. - For a complete v7 transport implementation, take a look at our [browser fetch transport](https://github.com/getsentry/sentry-javascript/blob/ebc938a03d6efe7d0c4bbcb47714e84c9a566a9c/packages/browser/src/transports/fetch.ts#L1-L34). ## Enum Changes