diff --git a/.github/CANARY_FAILURE_TEMPLATE.md b/.github/CANARY_FAILURE_TEMPLATE.md index a99ec1e844f7..9e05fcfc44ae 100644 --- a/.github/CANARY_FAILURE_TEMPLATE.md +++ b/.github/CANARY_FAILURE_TEMPLATE.md @@ -2,4 +2,5 @@ title: '{{ env.TITLE }}' labels: 'Type: Tests, Waiting for: Product Owner' --- + Canary tests failed: {{ env.RUN_LINK }} diff --git a/dev-packages/browser-integration-tests/README.md b/dev-packages/browser-integration-tests/README.md index 0c57f7c1ca45..b24bdfb86ee3 100644 --- a/dev-packages/browser-integration-tests/README.md +++ b/dev-packages/browser-integration-tests/README.md @@ -1,19 +1,29 @@ # Integration Tests for Sentry Browser SDK -Integration tests for Sentry's Browser SDK use [Playwright](https://playwright.dev/) internally. These tests are run on latest stable versions of Chromium, Firefox and Webkit. +Integration tests for Sentry's Browser SDK use [Playwright](https://playwright.dev/) internally. These tests are run on +latest stable versions of Chromium, Firefox and Webkit. ## Structure -The tests are grouped by their scope such as `breadcrumbs` or `onunhandledrejection`. In every group of tests, there are multiple folders containing test cases with their optional supporting assets. +The tests are grouped by their scope such as `breadcrumbs` or `onunhandledrejection`. In every group of tests, there are +multiple folders containing test cases with their optional supporting assets. -Each case group has a default HTML skeleton named `template.hbs`, and also a default initialization script named `init.js `, which contains the `Sentry.init()` call. These defaults are used as fallbacks when a specific `template.hbs` or `init.js` is not defined in a case folder. +Each case group has a default HTML skeleton named `template.hbs`, and also a default initialization script named +`init.js `, which contains the `Sentry.init()` call. These defaults are used as fallbacks when a specific `template.hbs` +or `init.js` is not defined in a case folder. -`subject.js` contains the logic that sets up the environment to be tested. It also can be defined locally and as a group fallback. Unlike `template.hbs` and `init.js`, it's not required to be defined for a group, as there may be cases that does not require a subject, instead the logic is injected using `injectScriptAndGetEvents` from `utils/helpers.ts`. +`subject.js` contains the logic that sets up the environment to be tested. It also can be defined locally and as a group +fallback. Unlike `template.hbs` and `init.js`, it's not required to be defined for a group, as there may be cases that +does not require a subject, instead the logic is injected using `injectScriptAndGetEvents` from `utils/helpers.ts`. -`test.ts` is required for each test case, which contains the assertions (and if required the script injection logic). For every case, any set of `init.js`, `template.hbs` and `subject.js` can be defined locally, and each one of them will have precedence over the default definitions of the test group. +`test.ts` is required for each test case, which contains the assertions (and if required the script injection logic). +For every case, any set of `init.js`, `template.hbs` and `subject.js` can be defined locally, and each one of them will +have precedence over the default definitions of the test group. -To test page multi-page navigations, you can specify additional `page-*.html` (e.g. `page-0.html`, `page-1.html`) files. These will also be compiled and initialized with the same `init.js` and `subject.js` files that are applied to `template.hbs/html`. Note: `page-*.html` file lookup **doesn not** fall back to the -parent directories, meaning that page files have to be directly in the `test.ts` directory. +To test page multi-page navigations, you can specify additional `page-*.html` (e.g. `page-0.html`, `page-1.html`) files. +These will also be compiled and initialized with the same `init.js` and `subject.js` files that are applied to +`template.hbs/html`. Note: `page-*.html` file lookup **doesn not** fall back to the parent directories, meaning that +page files have to be directly in the `test.ts` directory. ``` suites/ @@ -33,11 +43,16 @@ suites/ ### Helpers -`utils/helpers.ts` contains helpers that could be used in assertions (`test.ts`). These helpers define a convenient and reliable API to interact with Playwright's native API. It's highly recommended to define all common patterns of Playwright usage in helpers. +`utils/helpers.ts` contains helpers that could be used in assertions (`test.ts`). These helpers define a convenient and +reliable API to interact with Playwright's native API. It's highly recommended to define all common patterns of +Playwright usage in helpers. ### Fixtures -[Fixtures](https://playwright.dev/docs/api/class-fixtures) allows us to define the globals and test-specific information in assertion groups (`test.ts` files). In it's current state, `fixtures.ts` contains an extension over the pure version of `test()` function of Playwright. All the tests should import `sentryTest` function from `utils/fixtures.ts` instead of `@playwright/test` to be able to access the extra fixtures. +[Fixtures](https://playwright.dev/docs/api/class-fixtures) allows us to define the globals and test-specific information +in assertion groups (`test.ts` files). In it's current state, `fixtures.ts` contains an extension over the pure version +of `test()` function of Playwright. All the tests should import `sentryTest` function from `utils/fixtures.ts` instead +of `@playwright/test` to be able to access the extra fixtures. ## Running Tests Locally @@ -47,8 +62,7 @@ Tests can be run locally using the latest version of Chromium with: To run tests with a different browser such as `firefox` or `webkit`: -`yarn test --project='firefox'` -`yarn test --project='webkit'` +`yarn test --project='firefox'` `yarn test --project='webkit'` Or to run on all three browsers: @@ -60,18 +74,27 @@ To filter tests by their title: You can refer to [Playwright documentation](https://playwright.dev/docs/test-cli) for other CLI options. -You can set env variable `PW_BUNDLE` to set specific build or bundle to test against. -Available options: `esm`, `cjs`, `bundle`, `bundle_min` +You can set env variable `PW_BUNDLE` to set specific build or bundle to test against. Available options: `esm`, `cjs`, +`bundle`, `bundle_min` ### Troubleshooting -Apart from [Playwright-specific issues](https://playwright.dev/docs/troubleshooting), below are common issues that might occur while writing tests for Sentry Browser SDK. +Apart from [Playwright-specific issues](https://playwright.dev/docs/troubleshooting), below are common issues that might +occur while writing tests for Sentry Browser SDK. - #### Flaky Tests - If a test fails randomly, giving a `Page Closed`, `Target Closed` or a similar error, most of the times, the reason is a race condition between the page action defined in the `subject` and the listeners of the Sentry event / request. It's recommended to firstly check `utils/helpers.ts` whether if that async logic can be replaced by one of the helpers. If not, whether the awaited (or non-awaited on purpose in some cases) Playwright methods can be orchestrated by [`Promise.all`](http://mdn.io/promise.all). Manually-defined waiting logic such as timeouts are not recommended, and should not be required in most of the cases. + + If a test fails randomly, giving a `Page Closed`, `Target Closed` or a similar error, most of the times, the reason is + a race condition between the page action defined in the `subject` and the listeners of the Sentry event / request. + It's recommended to firstly check `utils/helpers.ts` whether if that async logic can be replaced by one of the + helpers. If not, whether the awaited (or non-awaited on purpose in some cases) Playwright methods can be orchestrated + by [`Promise.all`](http://mdn.io/promise.all). Manually-defined waiting logic such as timeouts are not recommended, + and should not be required in most of the cases. - #### Build Errors - Before running, a page for each test case is built under the case folder inside `dist`. If a page build is failed, it's recommended to check: + + Before running, a page for each test case is built under the case folder inside `dist`. If a page build is failed, + it's recommended to check: - If both default `template.hbs` and `init.js` are defined for the test group. - If a `subject.js` is defined for the test case. diff --git a/dev-packages/e2e-tests/test-applications/create-remix-app-express-vite-dev/README.md b/dev-packages/e2e-tests/test-applications/create-remix-app-express-vite-dev/README.md index ec619a8eb455..31400e85106f 100644 --- a/dev-packages/e2e-tests/test-applications/create-remix-app-express-vite-dev/README.md +++ b/dev-packages/e2e-tests/test-applications/create-remix-app-express-vite-dev/README.md @@ -1,6 +1,7 @@ # Welcome to Remix + Vite! -📖 See the [Remix docs](https://remix.run/docs) and the [Remix Vite docs](https://remix.run/docs/en/main/future/vite) for details on supported features. +📖 See the [Remix docs](https://remix.run/docs) and the [Remix Vite docs](https://remix.run/docs/en/main/future/vite) +for details on supported features. ## Development @@ -28,7 +29,8 @@ Now you'll need to pick a host to deploy it to. ### DIY -If you're familiar with deploying Express applications you should be right at home. Just make sure to deploy the output of `npm run build` +If you're familiar with deploying Express applications you should be right at home. Just make sure to deploy the output +of `npm run build` - `build/server` - `build/client` diff --git a/dev-packages/node-integration-tests/README.md b/dev-packages/node-integration-tests/README.md index ec202b5a8252..35b3c10883b7 100644 --- a/dev-packages/node-integration-tests/README.md +++ b/dev-packages/node-integration-tests/README.md @@ -19,25 +19,37 @@ utils/ |---- server.ts [default Express server configuration] ``` -The tests are grouped by their scopes, such as `public-api` or `tracing`. In every group of tests, there are multiple folders containing test scenarios and assertions. +The tests are grouped by their scopes, such as `public-api` or `tracing`. In every group of tests, there are multiple +folders containing test scenarios and assertions. -Tests run on Express servers (a server instance per test). By default, a simple server template inside `utils/defaults/server.ts` is used. Every server instance runs on a different port. +Tests run on Express servers (a server instance per test). By default, a simple server template inside +`utils/defaults/server.ts` is used. Every server instance runs on a different port. -A custom server configuration can be used, supplying a script that exports a valid express server instance as default. `runServer` utility function accepts an optional `serverPath` argument for this purpose. +A custom server configuration can be used, supplying a script that exports a valid express server instance as default. +`runServer` utility function accepts an optional `serverPath` argument for this purpose. -`scenario.ts` contains the initialization logic and the test subject. By default, `{TEST_DIR}/scenario.ts` is used, but `runServer` also accepts an optional `scenarioPath` argument for non-standard usage. +`scenario.ts` contains the initialization logic and the test subject. By default, `{TEST_DIR}/scenario.ts` is used, but +`runServer` also accepts an optional `scenarioPath` argument for non-standard usage. -`test.ts` is required for each test case, and contains the server runner logic, request interceptors for Sentry requests, and assertions. Test server, interceptors and assertions are all run on the same Jest thread. +`test.ts` is required for each test case, and contains the server runner logic, request interceptors for Sentry +requests, and assertions. Test server, interceptors and assertions are all run on the same Jest thread. ### Utilities `utils/` contains helpers and Sentry-specific assertions that can be used in (`test.ts`). -`TestEnv` class contains methods to create and execute requests on a test server instance. `TestEnv.init()` which starts a test server and returns a `TestEnv` instance must be called by each test. The test server is automatically shut down after each test, if a data collection helper method such as `getEnvelopeRequest` and `getAPIResponse` is used. Tests that do not use those helper methods will need to end the server manually. +`TestEnv` class contains methods to create and execute requests on a test server instance. `TestEnv.init()` which starts +a test server and returns a `TestEnv` instance must be called by each test. The test server is automatically shut down +after each test, if a data collection helper method such as `getEnvelopeRequest` and `getAPIResponse` is used. Tests +that do not use those helper methods will need to end the server manually. -`TestEnv` instance has two public properties: `url` and `server`. The `url` property is the base URL for the server. The `http.Server` instance is used to finish the server eventually. +`TestEnv` instance has two public properties: `url` and `server`. The `url` property is the base URL for the server. The +`http.Server` instance is used to finish the server eventually. -Nock interceptors are internally used to capture envelope requests by `getEnvelopeRequest` and `getMultipleEnvelopeRequest` helpers. After capturing required requests, the interceptors are removed. Nock can manually be used inside the test cases to intercept requests but should be removed before the test ends, as not to cause flakiness. +Nock interceptors are internally used to capture envelope requests by `getEnvelopeRequest` and +`getMultipleEnvelopeRequest` helpers. After capturing required requests, the interceptors are removed. Nock can manually +be used inside the test cases to intercept requests but should be removed before the test ends, as not to cause +flakiness. ## Running Tests Locally diff --git a/dev-packages/overhead-metrics/README.md b/dev-packages/overhead-metrics/README.md index d7aa5fab0534..51e7d2587ac0 100644 --- a/dev-packages/overhead-metrics/README.md +++ b/dev-packages/overhead-metrics/README.md @@ -1,11 +1,13 @@ # Overhead performance metrics -Evaluates Sentry & Replay impact on website performance by running a web app in Chromium via Playwright and collecting various metrics. +Evaluates Sentry & Replay impact on website performance by running a web app in Chromium via Playwright and collecting +various metrics. -The general idea is to run a web app without Sentry, and then run the same app again with Sentry and another one with Sentry+Replay included. -For the three scenarios, we collect some metrics (CPU, memory, vitals) and later compare them and post as a comment in a PR. -Changes in the metrics, compared to previous runs from the main branch, should be evaluated on case-by-case basis when preparing and reviewing the PR. +The general idea is to run a web app without Sentry, and then run the same app again with Sentry and another one with +Sentry+Replay included. For the three scenarios, we collect some metrics (CPU, memory, vitals) and later compare them +and post as a comment in a PR. Changes in the metrics, compared to previous runs from the main branch, should be +evaluated on case-by-case basis when preparing and reviewing the PR. ## Resources -* https://github.com/addyosmani/puppeteer-webperf +- https://github.com/addyosmani/puppeteer-webperf diff --git a/dev-packages/overhead-metrics/configs/README.md b/dev-packages/overhead-metrics/configs/README.md index cb9724ba4619..ceb96835f975 100644 --- a/dev-packages/overhead-metrics/configs/README.md +++ b/dev-packages/overhead-metrics/configs/README.md @@ -1,4 +1,4 @@ # Replay metrics configuration & entrypoints (scripts) -* [dev](dev) contains scripts launched during local development -* [ci](ci) contains scripts launched in CI +- [dev](dev) contains scripts launched during local development +- [ci](ci) contains scripts launched in CI diff --git a/dev-packages/overhead-metrics/test-apps/jank/README.md b/dev-packages/overhead-metrics/test-apps/jank/README.md index 3e0f46b66a1e..beb81a4eadd2 100644 --- a/dev-packages/overhead-metrics/test-apps/jank/README.md +++ b/dev-packages/overhead-metrics/test-apps/jank/README.md @@ -1,4 +1,6 @@ # Chrome DevTools Jank article sample code -* Originally coming from [devtools-samples](https://github.com/GoogleChrome/devtools-samples/tree/4818abc9dbcdb954d0eb9b70879f4ea18756451f/jank), licensed under Apache 2.0. -* Linking article: +- Originally coming from + [devtools-samples](https://github.com/GoogleChrome/devtools-samples/tree/4818abc9dbcdb954d0eb9b70879f4ea18756451f/jank), + licensed under Apache 2.0. +- Linking article: diff --git a/dev-packages/rollup-utils/README.md b/dev-packages/rollup-utils/README.md index 2d79f3eabeec..ff38b562ced2 100644 --- a/dev-packages/rollup-utils/README.md +++ b/dev-packages/rollup-utils/README.md @@ -1,5 +1,7 @@ # The `rollup-utils` Package -This is a small utility packages for all the Rollup configurations we have in this project. It contains helpers to create standardized configs, custom rollup plugins, and other things that might have to do with the build process like polyfill snippets. +This is a small utility packages for all the Rollup configurations we have in this project. It contains helpers to +create standardized configs, custom rollup plugins, and other things that might have to do with the build process like +polyfill snippets. This package will not be published and is only intended to be used inside this repository. diff --git a/docs/migration/v4-to-v5_v6.md b/docs/migration/v4-to-v5_v6.md index 6928022eef20..4fcf8c1410ea 100644 --- a/docs/migration/v4-to-v5_v6.md +++ b/docs/migration/v4-to-v5_v6.md @@ -1,6 +1,7 @@ # Upgrading from 4.x to 5.x/6.x -We recommend upgrading from `4.x` to `6.x` directly. Migrating from `5.x` to `6.x` has no breaking changes to the SDK's API. +We recommend upgrading from `4.x` to `6.x` directly. Migrating from `5.x` to `6.x` has no breaking changes to the SDK's +API. In this version upgrade, there are a few breaking changes. This guide should help you update your code accordingly. diff --git a/docs/migration/v6-to-v7.md b/docs/migration/v6-to-v7.md index ac6ce0519e8e..8bd0da2b7a8e 100644 --- a/docs/migration/v6-to-v7.md +++ b/docs/migration/v6-to-v7.md @@ -541,4 +541,3 @@ const levelA = Severity.error; const levelB: SeverityLevel = "error" ``` - diff --git a/docs/v8-new-performance-apis.md b/docs/v8-new-performance-apis.md index cdf7bc6f9d0c..713e99d5d1f1 100644 --- a/docs/v8-new-performance-apis.md +++ b/docs/v8-new-performance-apis.md @@ -55,12 +55,8 @@ interface SpanContext { name: string; attributes?: SpanAttributes; op?: string; - // TODO: Not yet implemented, but you should be able to pass a scope to base this off scope?: Scope; - // TODO: The list below may change a bit... - origin?: SpanOrigin; - source?: SpanSource; - metadata?: Partial; + forceTransaction?: boolean; } ``` diff --git a/docs/v8-node.md b/docs/v8-node.md new file mode 100644 index 000000000000..960541889c3e --- /dev/null +++ b/docs/v8-node.md @@ -0,0 +1,103 @@ +# Using `@sentry/node` in v8 + +With v8, `@sentry/node` has been completely overhauled. It is now powered by [OpenTelemetry](https://opentelemetry.io/) +under the hood. + +## What is OpenTelemetry + +You do not need to know or understand what OpenTelemetry is in order to use Sentry. We set up OpenTelemetry under the +hood, no knowledge of it is required in order to get started. + +If you want, you can use OpenTelemetry-native APIs to start spans, and Sentry will pick up everything automatically. + +## Supported Frameworks & Libraries + +We support the following Node Frameworks out of the box: + +- [Express](#express) +- Fastify +- Koa +- Nest.js +- Hapi + +We also support auto instrumentation for the following libraries: + +- mysql +- mysql2 +- pg +- GraphQL (including Apollo Server) +- mongo +- mongoose +- Prisma + +## General Changes to v7 + +There are some general changes that have been made that apply to any usage of `@sentry/node`. + +### `Sentry.init()` has to be called before any other require/import + +Due to the way that OpenTelemetry auto instrumentation works, it is required that you initialize Sentry _before_ you +require or import any other package. Any package that is required/imported before Sentry is initialized may not be +correctly auto-instrumented. + +```js +// In v7, this was fine: +const Sentry = require('@sentry/node'); +const express = require('express'); + +Sentry.init({ + // ... +}); + +const app = express(); +``` + +```js +// In v8, in order to ensure express is instrumented, +// you have to initialize before you import: +const Sentry = require('@sentry/node'); +Sentry.init({ + // ... +}); + +const express = require('express'); +const app = express(); +``` + +### Performance Instrumentation is enabled by default + +All performance auto-instrumentation will be automatically enabled if the package is found. You do not need to add any +integration yourself, and `autoDiscoverNodePerformanceMonitoringIntegrations()` has also been removed. + +### Old Performance APIs are removed + +See [New Performance APIs](./v8-new-performance-apis.md) for details. + +### ESM Support + +For now, ESM support is only experimental. For the time being we only fully support CJS-based Node application - we are +working on this during the v8 alpha/beta cycle. + +## Express + +The following shows how you can setup Express instrumentation in v8. This will capture performance data & errors for +your Express app. + +```js +const Sentry = require('@sentry/node'); + +Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1, +}); + +const express = require('express'); +const app = express(); + +// add routes etc. here + +Sentry.setupExpressErrorHandler(app); +// add other error middleware below this, if needed + +app.listen(3000); +``` diff --git a/package.json b/package.json index 220c6943f868..196c36528657 100644 --- a/package.json +++ b/package.json @@ -22,14 +22,14 @@ "fix": "run-s fix:biome fix:prettier fix:lerna", "fix:lerna": "lerna run fix", "fix:biome": "biome check --apply .", - "fix:prettier": "prettier **/*.md *.md **/*.css --write", + "fix:prettier": "prettier \"**/*.md\" \"**/*.css\" --write", "changelog": "ts-node ./scripts/get-commit-list.ts", "link:yarn": "lerna exec yarn link", "lint": "run-s lint:lerna lint:biome lint:prettier", "lint:clang": "lerna run lint:clang", "lint:lerna": "lerna run lint", "lint:biome": "biome check .", - "lint:prettier": "prettier **/*.md *.md **/*.css --check", + "lint:prettier": "prettier \"**/*.md\" \"**/*.css\" --check", "postpublish": "lerna run --stream --concurrency 1 postpublish", "test": "lerna run --ignore \"@sentry-internal/{browser-integration-tests,e2e-tests,integration-shims,node-integration-tests,overhead-metrics}\" test", "test:unit": "lerna run --ignore \"@sentry-internal/{browser-integration-tests,e2e-tests,integration-shims,node-integration-tests,overhead-metrics}\" test:unit", diff --git a/packages/angular-ivy/README.md b/packages/angular-ivy/README.md index 1e9cd19977ec..6252cec45454 100644 --- a/packages/angular-ivy/README.md +++ b/packages/angular-ivy/README.md @@ -18,10 +18,11 @@ This SDK officially supports Angular 12 to 17 with Angular's new rendering engine, Ivy. -If you're using Angular 10, 11 or a newer Angular version with View Engine instead of Ivy, please use [`@sentry/angular`](https://github.com/getsentry/sentry-javascript/blob/develop/packages/angular/README.md). +If you're using Angular 10, 11 or a newer Angular version with View Engine instead of Ivy, please use +[`@sentry/angular`](https://github.com/getsentry/sentry-javascript/blob/develop/packages/angular/README.md). -If you're using an older version of Angular and experience problems with the Angular SDK, we recommend downgrading the SDK to version 6.x. -Please note that we don't provide any support for Angular versions below 10. +If you're using an older version of Angular and experience problems with the Angular SDK, we recommend downgrading the +SDK to version 6.x. Please note that we don't provide any support for Angular versions below 10. ## General @@ -53,8 +54,8 @@ platformBrowserDynamic() ### ErrorHandler -`@sentry/angular-ivy` exports a function to instantiate an ErrorHandler provider that will automatically send Javascript errors -captured by the Angular's error handler. +`@sentry/angular-ivy` exports a function to instantiate an ErrorHandler provider that will automatically send Javascript +errors captured by the Angular's error handler. ```javascript import { NgModule, ErrorHandler } from '@angular/core'; @@ -89,17 +90,14 @@ initializations. Registering a Trace Service is a 3-step process. -1. Register and configure the `BrowserTracing` integration, including custom Angular routing - instrumentation: +1. Register and configure the `BrowserTracing` integration, including custom Angular routing instrumentation: ```javascript import { init, browserTracingIntegration } from '@sentry/angular-ivy'; init({ dsn: '__DSN__', - integrations: [ - browserTracingIntegration(), - ], + integrations: [browserTracingIntegration()], tracePropagationTargets: ['localhost', 'https://yourserver.io/api'], tracesSampleRate: 1, }); @@ -213,7 +211,8 @@ export class FooterComponent implements OnInit { } ``` -You can also add your own custom spans via `startSpan()`. For example, if you'd like to track the duration of Angular boostraping process, you can do it as follows: +You can also add your own custom spans via `startSpan()`. For example, if you'd like to track the duration of Angular +boostraping process, you can do it as follows: ```javascript import { enableProdMode } from '@angular/core'; @@ -223,12 +222,13 @@ import { init, startSpan } from '@sentry/angular'; import { AppModule } from './app/app.module'; // ... -startSpan({ - name: 'platform-browser-dynamic', - op: 'ui.angular.bootstrap' +startSpan( + { + name: 'platform-browser-dynamic', + op: 'ui.angular.bootstrap', }, async () => { await platformBrowserDynamic().bootstrapModule(AppModule); - } + }, ); ``` diff --git a/packages/angular/README.md b/packages/angular/README.md index f330bff2fdea..c451b39ea9ef 100644 --- a/packages/angular/README.md +++ b/packages/angular/README.md @@ -17,11 +17,14 @@ ## Angular Version Compatibility -**Important**: This package is not compatible with Angular 16 or newer. Please use [`@sentry/angular-ivy`](https://github.com/getsentry/sentry-javascript/tree/master/packages/angular-ivy) instead. +**Important**: This package is not compatible with Angular 16 or newer. Please use +[`@sentry/angular-ivy`](https://github.com/getsentry/sentry-javascript/tree/master/packages/angular-ivy) instead. -If you're using Angular 12 or newer, we recommend using `@sentry/angular-ivy` for native support with Angular's rendering engine Ivy. +If you're using Angular 12 or newer, we recommend using `@sentry/angular-ivy` for native support with Angular's +rendering engine Ivy. -This SDK still officially supports Angular 10-15. If you are using an older version of Angular and experience problems with the Angular SDK, we recommend downgrading the SDK to version 6.x. +This SDK still officially supports Angular 10-15. If you are using an older version of Angular and experience problems +with the Angular SDK, we recommend downgrading the SDK to version 6.x. ## General @@ -80,26 +83,23 @@ see `ErrorHandlerOptions` interface in `src/errorhandler.ts`. ### Tracing -`@sentry/angular` exports a Trace Service, Directive and Decorators that leverage the tracing -features to add Angular-related spans to transactions. If tracing is not enabled, this functionality -will not work. The SDK's `TraceService` itself tracks route changes and durations, while directive and decorators are tracking -components initializations. +`@sentry/angular` exports a Trace Service, Directive and Decorators that leverage the tracing features to add +Angular-related spans to transactions. If tracing is not enabled, this functionality will not work. The SDK's +`TraceService` itself tracks route changes and durations, while directive and decorators are tracking components +initializations. #### Install Registering a Trace Service is a 3-step process. -1. Register and configure the `BrowserTracing` integration, including custom Angular routing - instrumentation: +1. Register and configure the `BrowserTracing` integration, including custom Angular routing instrumentation: ```javascript import { init, browserTracingIntegration } from '@sentry/angular'; init({ dsn: '__DSN__', - integrations: [ - browserTracingIntegration(), - ], + integrations: [browserTracingIntegration()], tracePropagationTargets: ['localhost', 'https://yourserver.io/api'], tracesSampleRate: 1, }); @@ -213,7 +213,8 @@ export class FooterComponent implements OnInit { } ``` -You can also add your own custom spans via `startSpan()`. For example, if you'd like to track the duration of Angular boostraping process, you can do it as follows: +You can also add your own custom spans via `startSpan()`. For example, if you'd like to track the duration of Angular +boostraping process, you can do it as follows: ```javascript import { enableProdMode } from '@angular/core'; @@ -223,12 +224,13 @@ import { init, startSpan } from '@sentry/angular'; import { AppModule } from './app/app.module'; // ... -startSpan({ - name: 'platform-browser-dynamic', - op: 'ui.angular.bootstrap' +startSpan( + { + name: 'platform-browser-dynamic', + op: 'ui.angular.bootstrap', }, async () => { await platformBrowserDynamic().bootstrapModule(AppModule); - } + }, ); ``` diff --git a/packages/astro/README.md b/packages/astro/README.md index 696b5f948ab0..bbcf09f03720 100644 --- a/packages/astro/README.md +++ b/packages/astro/README.md @@ -12,12 +12,12 @@ ## Links - - [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/astro/) +- [Official SDK Docs](https://docs.sentry.io/platforms/javascript/guides/astro/) ## SDK Status -This SDK is in Beta and not yet fully stable. -If you have feedback or encounter any bugs, feel free to [open an issue](https://github.com/getsentry/sentry-javascript/issues/new/choose). +This SDK is in Beta and not yet fully stable. If you have feedback or encounter any bugs, feel free to +[open an issue](https://github.com/getsentry/sentry-javascript/issues/new/choose). ## General @@ -34,15 +34,15 @@ npx astro add @sentry/astro Add your DSN and source maps upload configuration: ```javascript -import { defineConfig } from "astro/config"; -import sentry from "@sentry/astro"; +import { defineConfig } from 'astro/config'; +import sentry from '@sentry/astro'; export default defineConfig({ integrations: [ sentry({ - dsn: "__DSN__", + dsn: '__DSN__', sourceMapsUploadOptions: { - project: "your-sentry-project-slug", + project: 'your-sentry-project-slug', authToken: process.env.SENTRY_AUTH_TOKEN, }, }), @@ -50,7 +50,8 @@ export default defineConfig({ }); ``` -Follow [this guide](https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens) to create an auth token and add it to your environment variables: +Follow [this guide](https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens) to create an auth +token and add it to your environment variables: ```bash SENTRY_AUTH_TOKEN="your-token" @@ -58,14 +59,15 @@ SENTRY_AUTH_TOKEN="your-token" ### Server Instrumentation -For Astro apps configured for (hybrid) Server Side Rendering (SSR), the Sentry integration will automatically add middleware to your server to instrument incoming requests **if you're using Astro 3.5.2 or newer**. +For Astro apps configured for (hybrid) Server Side Rendering (SSR), the Sentry integration will automatically add +middleware to your server to instrument incoming requests **if you're using Astro 3.5.2 or newer**. If you're using Astro <3.5.2, complete the setup by adding the Sentry middleware to your `src/middleware.js` file: ```javascript // src/middleware.js -import { sequence } from "astro:middleware"; -import * as Sentry from "@sentry/astro"; +import { sequence } from 'astro:middleware'; +import * as Sentry from '@sentry/astro'; export const onRequest = sequence( Sentry.handleRequest(), @@ -74,6 +76,7 @@ export const onRequest = sequence( ``` The Sentry middleware enhances the data collected by Sentry on the server side by: + - Enabeling distributed tracing between client and server - Collecting performance spans for incoming requests - Enhancing captured errors with additional information @@ -83,26 +86,25 @@ The Sentry middleware enhances the data collected by Sentry on the server side b You can opt out of using the automatic sentry server instrumentation in your `astro.config.mjs` file: ```javascript -import { defineConfig } from "astro/config"; -import sentry from "@sentry/astro"; +import { defineConfig } from 'astro/config'; +import sentry from '@sentry/astro'; export default defineConfig({ integrations: [ sentry({ - dsn: "__DSN__", + dsn: '__DSN__', autoInstrumentation: { requestHandler: false, - } + }, }), ], }); ``` - ## Configuration Check out our docs for configuring your SDK setup: -* [Getting Started](https://docs.sentry.io/platforms/javascript/guides/astro/) -* [Manual Setup and Configuration](https://docs.sentry.io/platforms/javascript/guides/astro/manual-setup/) -* [Source Maps Upload](https://docs.sentry.io/platforms/javascript/guides/astro/sourcemaps/) +- [Getting Started](https://docs.sentry.io/platforms/javascript/guides/astro/) +- [Manual Setup and Configuration](https://docs.sentry.io/platforms/javascript/guides/astro/manual-setup/) +- [Source Maps Upload](https://docs.sentry.io/platforms/javascript/guides/astro/sourcemaps/) diff --git a/packages/aws-serverless/README.md b/packages/aws-serverless/README.md index d9569d4b5d9a..5a1ea8a1cc00 100644 --- a/packages/aws-serverless/README.md +++ b/packages/aws-serverless/README.md @@ -41,7 +41,8 @@ exports.handler = Sentry.wrapHandler((event, context, callback) => { }); ``` -If you also want to trace performance of all the incoming requests and also outgoing AWS service requests, just set the `tracesSampleRate` option. +If you also want to trace performance of all the incoming requests and also outgoing AWS service requests, just set the +`tracesSampleRate` option. ```javascript import * as Sentry from '@sentry/aws-serverless'; @@ -61,4 +62,6 @@ Another and much simpler way to integrate Sentry to your AWS Lambda function is 3. Go to Environment variables and add: - `NODE_OPTIONS`: `-r @sentry/aws-serverless/build/npm/cjs/awslambda-auto`. - `SENTRY_DSN`: `your dsn`. - - `SENTRY_TRACES_SAMPLE_RATE`: a number between 0 and 1 representing the chance a transaction is sent to Sentry. For more information, see [docs](https://docs.sentry.io/platforms/node/guides/aws-lambda/configuration/options/#tracesSampleRate). + - `SENTRY_TRACES_SAMPLE_RATE`: a number between 0 and 1 representing the chance a transaction is sent to Sentry. For + more information, see + [docs](https://docs.sentry.io/platforms/node/guides/aws-lambda/configuration/options/#tracesSampleRate). diff --git a/packages/browser/test/integration/debugging.md b/packages/browser/test/integration/debugging.md index d5fec3818115..9f0cd250566a 100644 --- a/packages/browser/test/integration/debugging.md +++ b/packages/browser/test/integration/debugging.md @@ -1,23 +1,37 @@ ### Debugging Hints -These tests are hard to debug, because the testing system is somewhat complex, straightforward debugging doesn't work (see below), and the output of most `console.log` calls gets swallowed. Here, future debugger, are some tips to make it easier, to hopefully save you the hour(s) of trial and error it took to figure them out. +These tests are hard to debug, because the testing system is somewhat complex, straightforward debugging doesn't work +(see below), and the output of most `console.log` calls gets swallowed. Here, future debugger, are some tips to make it +easier, to hopefully save you the hour(s) of trial and error it took to figure them out. - `suites/shell.js`: + - Remove the loader options from the `variants` array. - - Delete all of the placeholders of the form `{{ suites/something.js }}` except for the one you're interested in. It's not enough to comment them out, because they'll still exist in the file and get replaced by the test runner. Don't forget the one at the bottom of the file. + - Delete all of the placeholders of the form `{{ suites/something.js }}` except for the one you're interested in. It's + not enough to comment them out, because they'll still exist in the file and get replaced by the test runner. Don't + forget the one at the bottom of the file. - `suites/helpers.js`: - - Add `sandbox.contentWindow.console.log = (...args) => console.log(...args);` just before the return in `createSandbox()`. This will make it so that `console.log` statements come through to the terminal. (Yes, Karma theoretically has settings for that, but they don't seem to work. See https://github.com/karma-runner/karma-mocha/issues/47.) + + - Add `sandbox.contentWindow.console.log = (...args) => console.log(...args);` just before the return in + `createSandbox()`. This will make it so that `console.log` statements come through to the terminal. (Yes, Karma + theoretically has settings for that, but they don't seem to work. See + https://github.com/karma-runner/karma-mocha/issues/47.) - `suites.yourTestFile.js`: + - Use `it.only` to only run the single test you're interested in. - Repo-level `rollup/bundleHelpers.js`: + - Comment out all bundle variants except whichever one `run.js` is turning into `artifacts/sdk.js`. -- Run `build:bundle:watch` in a separate terminal tab, so that when you add `console.log`s to the SDK, they get picked up. +- Run `build:bundle:watch` in a separate terminal tab, so that when you add `console.log`s to the SDK, they get picked + up. -- Don't bother trying to copy one of our standard VSCode debug profiles, because it won't work, except to debug the testing system itself. (It will pause the node process running the tests, not the headless browser in which the tests themselves run.) +- Don't bother trying to copy one of our standard VSCode debug profiles, because it won't work, except to debug the + testing system itself. (It will pause the node process running the tests, not the headless browser in which the tests + themselves run.) - To make karma do verbose logging, run `export DEBUG=1`. To turn it off, run `unset DEBUG`. diff --git a/packages/bun/README.md b/packages/bun/README.md index d9c99350a613..43a80713e45b 100644 --- a/packages/bun/README.md +++ b/packages/bun/README.md @@ -15,7 +15,8 @@ - [Official SDK Docs](https://docs.sentry.io/quickstart/) - [TypeDoc](http://getsentry.github.io/sentry-javascript/) -The Sentry Bun SDK is in beta. Please help us improve the SDK by [reporting any issues or giving us feedback](https://github.com/getsentry/sentry-javascript/issues). +The Sentry Bun SDK is in beta. Please help us improve the SDK by +[reporting any issues or giving us feedback](https://github.com/getsentry/sentry-javascript/issues). ## Usage @@ -34,8 +35,8 @@ Sentry.init({ }); ``` -To set context information or send manual events, use the exported functions of `@sentry/bun`. Note that these -functions will not perform any action before you have called `init()`: +To set context information or send manual events, use the exported functions of `@sentry/bun`. Note that these functions +will not perform any action before you have called `init()`: ```javascript // Set user information, as well as tags and further extras @@ -60,8 +61,9 @@ Sentry.captureEvent({ }); ``` -It's not possible to capture unhandled exceptions, unhandled promise rejections now - Bun is working on adding support for it. -[Github Issue](https://github.com/oven-sh/bun/issues/5091) follow this issue. To report errors to Sentry, you have to manually try-catch and call `Sentry.captureException` in the catch block. +It's not possible to capture unhandled exceptions, unhandled promise rejections now - Bun is working on adding support +for it. [Github Issue](https://github.com/oven-sh/bun/issues/5091) follow this issue. To report errors to Sentry, you +have to manually try-catch and call `Sentry.captureException` in the catch block. ```ts import * as Sentry from '@sentry/bun'; @@ -72,4 +74,3 @@ try { Sentry.captureException(e); } ``` - diff --git a/packages/deno/README.md b/packages/deno/README.md index 67ac88fedc6e..502778cf8abb 100644 --- a/packages/deno/README.md +++ b/packages/deno/README.md @@ -16,16 +16,17 @@ - [Official SDK Docs](https://docs.sentry.io/quickstart/) - [TypeDoc](http://getsentry.github.io/sentry-javascript/) -The Sentry Deno SDK is in beta. Please help us improve the SDK by [reporting any issues or giving us feedback](https://github.com/getsentry/sentry-javascript/issues). +The Sentry Deno SDK is in beta. Please help us improve the SDK by +[reporting any issues or giving us feedback](https://github.com/getsentry/sentry-javascript/issues). ## Usage -To use this SDK, call `Sentry.init(options)` as early as possible in the main entry module. This will initialize the SDK and -hook into the environment. Note that you can turn off almost all side effects using the respective options. +To use this SDK, call `Sentry.init(options)` as early as possible in the main entry module. This will initialize the SDK +and hook into the environment. Note that you can turn off almost all side effects using the respective options. ```javascript // Import from the Deno registry -import * as Sentry from "https://deno.land/x/sentry/index.mjs"; +import * as Sentry from 'https://deno.land/x/sentry/index.mjs'; // or import from npm registry import * as Sentry from 'npm:@sentry/deno'; @@ -36,8 +37,8 @@ Sentry.init({ }); ``` -To set context information or send manual events, use the exported functions of the Deno SDK. Note that these -functions will not perform any action before you have called `init()`: +To set context information or send manual events, use the exported functions of the Deno SDK. Note that these functions +will not perform any action before you have called `init()`: ```javascript // Set user information, as well as tags and further extras @@ -61,6 +62,3 @@ Sentry.captureEvent({ ], }); ``` - - - diff --git a/packages/ember/README.md b/packages/ember/README.md index 347184277530..2376869d107f 100644 --- a/packages/ember/README.md +++ b/packages/ember/README.md @@ -13,13 +13,12 @@ ## General -This package is an Ember addon that wraps `@sentry/browser`, with added functionality related to Ember. All methods available in -`@sentry/browser` can be imported from `@sentry/ember`. +This package is an Ember addon that wraps `@sentry/browser`, with added functionality related to Ember. All methods +available in `@sentry/browser` can be imported from `@sentry/ember`. ### Installation -As with other Ember addons, run: -`ember install @sentry/ember` +As with other Ember addons, run: `ember install @sentry/ember` Then add the following to your `/app.js` @@ -38,8 +37,9 @@ Then add the following to your `/app.js` ### Usage -To use this SDK, call `Sentry.init` before the application is initialized, in `app.js`. This will allow Sentry to capture information while your app is starting. -Any additional SDK settings can be modified via the usual config in `environment.js` for you, see the Additional Configuration section for more details. +To use this SDK, call `Sentry.init` before the application is initialized, in `app.js`. This will allow Sentry to +capture information while your app is starting. Any additional SDK settings can be modified via the usual config in +`environment.js` for you, see the Additional Configuration section for more details. ```javascript import Application from '@ember/application'; @@ -66,7 +66,8 @@ export default class App extends Application { ### Additional Configuration -Aside from configuration passed from this addon into `@sentry/browser` via the `sentry` property, there is also the following Ember specific configuration: +Aside from configuration passed from this addon into `@sentry/browser` via the `sentry` property, there is also the +following Ember specific configuration: ```javascript ENV['@sentry/ember'] = { @@ -93,8 +94,8 @@ ENV['@sentry/ember'] = { #### Disabling Performance - -`@sentry/ember` captures performance by default, if you would like to disable the automatic performance instrumentation, you can add the following to your `config/environment.js`: +`@sentry/ember` captures performance by default, if you would like to disable the automatic performance instrumentation, +you can add the following to your `config/environment.js`: ```javascript ENV['@sentry/ember'] = { @@ -102,7 +103,6 @@ ENV['@sentry/ember'] = { }; ``` - ### Performance #### Routes @@ -149,8 +149,8 @@ ENV['@sentry/ember'] = { }; ``` -Additionally, components whose render time is below a threshold (by default 2ms) will not be included as spans. -If you would like to change this threshold, add the following to your config: +Additionally, components whose render time is below a threshold (by default 2ms) will not be included as spans. If you +would like to change this threshold, add the following to your config: ```javascript ENV['@sentry/ember'] = { @@ -172,8 +172,8 @@ ENV['@sentry/ember'] = { ### Supported Versions -* **Ember.js**: v4.0 or above -* **Node**: v14.18 or above +- **Ember.js**: v4.0 or above +- **Node**: v14.18 or above ### Previous Integration @@ -182,8 +182,8 @@ this Ember addon to offer more Ember-specific error and performancing monitoring ## Testing -For this package itself, you can find example instrumentation in the `dummy` application, which is also used for testing. -To test with the dummy application, you must pass the dsn as an environment variable. +For this package itself, you can find example instrumentation in the `dummy` application, which is also used for +testing. To test with the dummy application, you must pass the dsn as an environment variable. ```javascript SENTRY_DSN=__DSN__ ember serve diff --git a/packages/feedback/README.md b/packages/feedback/README.md index fb5b20400a71..336e74da6593 100644 --- a/packages/feedback/README.md +++ b/packages/feedback/README.md @@ -6,15 +6,20 @@ # Sentry Integration for Feedback -This SDK is **considered experimental and in a beta state**. It may experience breaking changes, and may be discontinued at any time. Please reach out on -[GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback/concerns. +This SDK is **considered experimental and in a beta state**. It may experience breaking changes, and may be discontinued +at any time. Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have +any feedback/concerns. -To view Feedback in Sentry, your [Sentry organization must be an early adopter](https://docs.sentry.io/product/accounts/early-adopter-features/). +To view Feedback in Sentry, your +[Sentry organization must be an early adopter](https://docs.sentry.io/product/accounts/early-adopter-features/). ## Installation -Please read the [offical integration documentation](https://docs.sentry.io/platforms/javascript/user-feedback/) for installation instructions. +Please read the [offical integration documentation](https://docs.sentry.io/platforms/javascript/user-feedback/) for +installation instructions. ## Configuration -The Feedback integration is highly customizable, please read the [official integration documentation](https://docs.sentry.io/platforms/javascript/user-feedback/configuration/) for the most up-to-date configuration options. +The Feedback integration is highly customizable, please read the +[official integration documentation](https://docs.sentry.io/platforms/javascript/user-feedback/configuration/) for the +most up-to-date configuration options. diff --git a/packages/gatsby/README.md b/packages/gatsby/README.md index c20f3355e297..b87b99c365c1 100644 --- a/packages/gatsby/README.md +++ b/packages/gatsby/README.md @@ -13,17 +13,19 @@ module.exports = { // ... plugins: [ { - resolve: "@sentry/gatsby", + resolve: '@sentry/gatsby', options: { - dsn: process.env.SENTRY_DSN, // this is the default - } + dsn: process.env.SENTRY_DSN, // this is the default + }, }, // ... - ] -} + ], +}; ``` -Options will be passed directly to `Sentry.init`. See all available options in [our docs](https://docs.sentry.io/error-reporting/configuration/?platform=javascript). The `environment` value defaults to `NODE_ENV` (or `'development'` if `NODE_ENV` is not set). +Options will be passed directly to `Sentry.init`. See all available options in +[our docs](https://docs.sentry.io/error-reporting/configuration/?platform=javascript). The `environment` value defaults +to `NODE_ENV` (or `'development'` if `NODE_ENV` is not set). ## GitHub Actions @@ -35,18 +37,21 @@ The `release` value is inferred from `COMMIT_REF`. ## Vercel -To automatically capture the `release` value on Vercel you will need to register appropriate [system environment variable](https://vercel.com/docs/v2/build-step#system-environment-variables) (e.g. `VERCEL_GITHUB_COMMIT_SHA`) in your project. +To automatically capture the `release` value on Vercel you will need to register appropriate +[system environment variable](https://vercel.com/docs/v2/build-step#system-environment-variables) (e.g. +`VERCEL_GITHUB_COMMIT_SHA`) in your project. ## Sentry Performance -To enable tracing, supply either `tracesSampleRate` or `tracesSampler` to the options. This will turn on the `BrowserTracing` integration for automatic instrumentation of pageloads and navigations. +To enable tracing, supply either `tracesSampleRate` or `tracesSampler` to the options. This will turn on the +`BrowserTracing` integration for automatic instrumentation of pageloads and navigations. ```javascript module.exports = { // ... plugins: [ { - resolve: "@sentry/gatsby", + resolve: '@sentry/gatsby', options: { dsn: process.env.SENTRY_DSN, // this is the default @@ -60,24 +65,21 @@ module.exports = { // for this transaction. // Can return 0 to drop the transaction entirely. - if ("...") { - return 0.5 // These are important - take a big sample - } - else if ("...") { - return 0.01 // These are less important or happen much more frequently - only take 1% of them - } - else if ("...") { - return 0 // These aren't something worth tracking - drop all transactions like this + if ('...') { + return 0.5; // These are important - take a big sample + } else if ('...') { + return 0.01; // These are less important or happen much more frequently - only take 1% of them + } else if ('...') { + return 0; // These aren't something worth tracking - drop all transactions like this + } else { + return 0.1; // Default sample rate } - else { - return 0.1 // Default sample rate - } - } - } + }, + }, }, // ... - ] -} + ], +}; ``` If you want to supply options to the `BrowserTracing` integration, use the `browserTracingOptions` parameter. @@ -87,19 +89,19 @@ module.exports = { // ... plugins: [ { - resolve: "@sentry/gatsby", + resolve: '@sentry/gatsby', options: { - dsn: process.env.SENTRY_DSN, // this is the default - tracesSampleRate: 1, // or tracesSampler (see above) - browserTracingOptions: { - // disable creating spans for XHR requests - traceXHR: false, - } - } + dsn: process.env.SENTRY_DSN, // this is the default + tracesSampleRate: 1, // or tracesSampler (see above) + browserTracingOptions: { + // disable creating spans for XHR requests + traceXHR: false, + }, + }, }, // ... - ] -} + ], +}; ``` ## Links diff --git a/packages/integration-shims/README.md b/packages/integration-shims/README.md index 523e3e4fd85f..e315b1f61051 100644 --- a/packages/integration-shims/README.md +++ b/packages/integration-shims/README.md @@ -6,4 +6,5 @@ # Sentry Integration Shims -This internal package exports shims for Integrations, which are used in order to guarantee a consistent CDN bundle output. +This internal package exports shims for Integrations, which are used in order to guarantee a consistent CDN bundle +output. diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md index 26322828afe4..119a591621df 100644 --- a/packages/nextjs/README.md +++ b/packages/nextjs/README.md @@ -21,7 +21,8 @@ Currently, the minimum Next.js supported version is `10.0.8`. ## General -This package is a wrapper around `@sentry/node` for the server and `@sentry/react` for the client, with added functionality related to Next.js. +This package is a wrapper around `@sentry/node` for the server and `@sentry/react` for the client, with added +functionality related to Next.js. To use this SDK, init it in the Sentry config files. @@ -31,7 +32,7 @@ To use this SDK, init it in the Sentry config files. import * as Sentry from '@sentry/nextjs'; Sentry.init({ - dsn: "__DSN__", + dsn: '__DSN__', // ... }); ``` @@ -42,7 +43,7 @@ Sentry.init({ import * as Sentry from '@sentry/nextjs'; Sentry.init({ - dsn: "__DSN__", + dsn: '__DSN__', // ... }); ``` diff --git a/packages/nextjs/vercel/instructions.md b/packages/nextjs/vercel/instructions.md index 90e074968a90..6a1890494ffc 100644 --- a/packages/nextjs/vercel/instructions.md +++ b/packages/nextjs/vercel/instructions.md @@ -12,7 +12,7 @@ repo, only a full repo itself. Since we run a monorepo, this won't work in our c From `packages/nextjs`, run - `yarn vercel:branch`. +`yarn vercel:branch`. This will delete unneeded packages (angular, vue, etc) in order to speed up deployment. It will then commit that change. When your branch is ready to PR, just rebase and drop that commit. @@ -24,7 +24,7 @@ want to test are pushed to GitHub. From `packages/nextjs`, run - `yarn vercel:project `. +`yarn vercel:project `. This will copy the `install-sentry-from-branch.sh` script into a `.sentry` folder at the root level of your test app, and create a `set-branch-name.sh` script in the same location. (The first script is the one you'll run on Vercel. The @@ -33,11 +33,11 @@ commit (but not push) this change. Go into your project settings on Vercel and change the install command to - `bash .sentry/install-sentry-from-branch.sh` +`bash .sentry/install-sentry-from-branch.sh` and the build command to - `yarn build && bash .sentry/post-app-build.sh`. +`yarn build && bash .sentry/post-app-build.sh`. If you're using bundle analyzer, the post-build script will move the visualizations it creates so that they're available on your deployed site at `/client.html` and `/server.html`. diff --git a/packages/node-experimental/README.md b/packages/node-experimental/README.md index 715359fc55f8..324700199b53 100644 --- a/packages/node-experimental/README.md +++ b/packages/node-experimental/README.md @@ -4,36 +4,28 @@

-# Official Sentry SDK for Node (EXPERIMENTAL) +# Official Sentry SDK for Node -[![npm version](https://img.shields.io/npm/v/@sentry/node-experimental.svg)](https://www.npmjs.com/package/@sentry/node-experimental) -[![npm dm](https://img.shields.io/npm/dm/@sentry/node-experimental.svg)](https://www.npmjs.com/package/@sentry/node-experimental) -[![npm dt](https://img.shields.io/npm/dt/@sentry/node-experimental.svg)](https://www.npmjs.com/package/@sentry/node-experimental) - -This is a WIP, proof of concept implementation of a Node SDK that uses OpenTelemetry for performance instrumentation under the hood. - -THIS MAY/WILL BREAK IN MANY UNEXPECTED WAYS. We may remove, add, change any of the integrations, add/remove any exports, etc. -This package is **NOT READY TO USE IN ANY FORM OF PRODUCTION ENVIRONMENT**! - -This SDK is **considered experimental and in an alpha state**. It may experience breaking changes, and may be discontinued at any time. Please reach out on -[GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback/concerns. +[![npm version](https://img.shields.io/npm/v/@sentry/node.svg)](https://www.npmjs.com/package/@sentry/node) +[![npm dm](https://img.shields.io/npm/dm/@sentry/node.svg)](https://www.npmjs.com/package/@sentry/node) +[![npm dt](https://img.shields.io/npm/dt/@sentry/node.svg)](https://www.npmjs.com/package/@sentry/node) ## Installation ```bash -npm install @sentry/node-experimental +npm install @sentry/node # Or yarn -yarn add @sentry/node-experimental +yarn add @sentry/node ``` ## Usage ```js // CJS Syntax -const Sentry = require('@sentry/node-experimental'); +const Sentry = require('@sentry/node'); // ESM Syntax -import * as Sentry from '@sentry/node-experimental'; +import * as Sentry from '@sentry/node'; Sentry.init({ dsn: '__DSN__', @@ -43,65 +35,12 @@ Sentry.init({ Note that it is necessary to initialize Sentry **before you import any package that may be instrumented by us**. -## Status of this Experiment - -Currently, this SDK: - -* Will capture errors (same as @sentry/node) -* Auto-instrument for performance - see below for which performance integrations are available. -* Provide _some_ manual instrumentation APIs -* Sync OpenTelemetry Context with our Sentry Hub/Scope - -### Manual Instrumentation - -You can manual instrument using the following APIs: - -```js -const Sentry = require('@sentry/node-experimental'); - -Sentry.startSpan({ description: 'outer' }, function (span) { - span.setData(customData); - doSomethingSlow(); - Sentry.startSpan({ description: 'inner' }, function() { - // inner span is a child of outer span - doSomethingVerySlow(); - // inner span is auto-ended when this callback ends - }); - // outer span is auto-ended when this callback ends -}); -``` - -You can also create spans without marking them as the active span. -Note that for most scenarios, we recommend the `startSpan` syntax. - -```js -const Sentry = require('@sentry/node-experimental'); - -// This will _not_ be put on the scope/set as active, so no other spans will be attached to it -const span = Sentry.startInactiveSpan({ description: 'non-active span' }); - -doSomethingSlow(); - -span.end(); -``` - -Finally you can also get the currently active span, if you need to do more with it: - -```js -const Sentry = require('@sentry/node-experimental'); -const span = Sentry.getActiveSpan(); -``` - -### Async Context - -We leverage the OpenTelemetry context forking in order to ensure isolation of parallel requests. -This means that as long as you are using an OpenTelemetry instrumentation for your framework of choice -(currently: Express or Fastify), you do not need to setup any `requestHandler` or similar. +[More information on how to set up Sentry for Node in v8.](./../../docs/v8-node.md) ### ESM Support -Due to the way OpenTelemetry handles instrumentation, this only works out of the box for CommonJS (`require`) applications. - +Due to the way OpenTelemetry handles instrumentation, this only works out of the box for CommonJS (`require`) +applications. There is experimental support for running OpenTelemetry with ESM (`"type": "module"`): @@ -111,27 +50,9 @@ node --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./app.js You'll need to install `@opentelemetry/instrumentation` in your app to ensure this works. -See [OpenTelemetry Instrumentation Docs](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation#instrumentation-for-es-modules-in-nodejs-experimental) for details on this - -but note that this is a) experimental, and b) does not work with all integrations. - - -## Available (Performance) Integrations - -* Http -* Express -* Fastify -* Nest -* Mysql -* Mysql2 -* GraphQL -* Mongo -* Mongoose -* Postgres -* Prisma - -All of these are auto-discovered, you don't need to configure anything for performance. -You still need to register middlewares etc. for error capturing. -Other, non-performance integrations from `@sentry/node` are also available (except for Undici). +See +[OpenTelemetry Instrumentation Docs](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation#instrumentation-for-es-modules-in-nodejs-experimental) +for details on this - but note that this is a) experimental, and b) does not work with all integrations. ## Links diff --git a/packages/node/README.md b/packages/node/README.md index bd588bbbc34e..af6819c9a4ce 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -4,27 +4,36 @@

-# Official Sentry SDK for NodeJS +# Legacy Sentry SDK for NodeJS -[![npm version](https://img.shields.io/npm/v/@sentry/node.svg)](https://www.npmjs.com/package/@sentry/node) -[![npm dm](https://img.shields.io/npm/dm/@sentry/node.svg)](https://www.npmjs.com/package/@sentry/node) -[![npm dt](https://img.shields.io/npm/dt/@sentry/node.svg)](https://www.npmjs.com/package/@sentry/node) +[![npm version](https://img.shields.io/npm/v/@sentry/node-experimental.svg)](https://www.npmjs.com/package/@sentry/node-experimental) +[![npm dm](https://img.shields.io/npm/dm/@sentry/node-experimental.svg)](https://www.npmjs.com/package/@sentry/node-experimental) +[![npm dt](https://img.shields.io/npm/dt/@sentry/node-experimental.svg)](https://www.npmjs.com/package/@sentry/node-experimental) ## Links - [Official SDK Docs](https://docs.sentry.io/quickstart/) - [TypeDoc](http://getsentry.github.io/sentry-javascript/) +## Status + +Since v8, this is the _legacy_ SDK, and it will most likely be completely removed before v8 is fully stable. It only +exists so that Meta-SDKs like `@sentry/nextjs` or `@sentry/sveltekit` can be migrated to the new `@sentry/node` +step-by-step. + +You should instead use [@sentry/node](./../node-experimental/). + ## Usage To use this SDK, call `init(options)` as early as possible in the main entry module. This will initialize the SDK and -hook into the environment. Note that you can turn off almost all side effects using the respective options. Minimum supported Node version is Node 14. +hook into the environment. Note that you can turn off almost all side effects using the respective options. Minimum +supported Node version is Node 14. ```javascript // CJS syntax -const Sentry = require('@sentry/node'); +const Sentry = require('@sentry/node-experimental'); // ESM syntax -import * as Sentry from '@sentry/node'; +import * as Sentry from '@sentry/node-experimental'; Sentry.init({ dsn: '__DSN__', @@ -32,8 +41,8 @@ Sentry.init({ }); ``` -To set context information or send manual events, use the exported functions of `@sentry/node`. Note that these -functions will not perform any action before you have called `init()`: +To set context information or send manual events, use the exported functions of `@sentry/node-experimental`. Note that +these functions will not perform any action before you have called `init()`: ```javascript // Set user information, as well as tags and further extras diff --git a/packages/node/test/manual/memory-leak/README.md b/packages/node/test/manual/memory-leak/README.md index 3d20f607686f..844c6ffe7391 100644 --- a/packages/node/test/manual/memory-leak/README.md +++ b/packages/node/test/manual/memory-leak/README.md @@ -1,26 +1,36 @@ # Manual Tests ## How this works -`express-patient.js` is an express app with a collection of endpoints that exercise various functionalities of @sentry/node, including exception capturing, contexts, autobreadcrumbs, and the express middleware. -It uses [memwatch-next](https://www.npmjs.com/package/memwatch-next) to record memory usage after each GC. `manager.js` does some child process stuff to have a fresh patient process for each test scenario, while poke-patient.sh uses apache bench to send a bunch of traffic so we can see what happens. +`express-patient.js` is an express app with a collection of endpoints that exercise various functionalities of +@sentry/node, including exception capturing, contexts, autobreadcrumbs, and the express middleware. + +It uses [memwatch-next](https://www.npmjs.com/package/memwatch-next) to record memory usage after each GC. `manager.js` +does some child process stuff to have a fresh patient process for each test scenario, while poke-patient.sh uses apache +bench to send a bunch of traffic so we can see what happens. ## Routes and what we test + The @sentry/node express middleware is used on all endpoints, so each request constitutes its own context. + - `/hello`: just send a basic response without doing anything - `/context/basic`: `setContext` call - `/breadcrumbs/capture`: manual `captureBreadcrumb` call - `/breadcrumbs/auto/console`: console log with console autoBreadcrumbs enabled - `/breadcrumbs/auto/http`: send an http request with http autoBreadcrumbs enabled - uses nock to mock the response, not actual request -- If the request has querystring param `doError=true`, we pass an error via Express's error handling mechanism with `next(new Error(responseText))` which will then be captured by the @sentry/node express middleware error handler. +- If the request has querystring param `doError=true`, we pass an error via Express's error handling mechanism with + `next(new Error(responseText))` which will then be captured by the @sentry/node express middleware error handler. - We test all 5 above cases with and without `doError=true` -We also have a `/gc` endpoint for forcing a garbage collection; this is used at the end of each test scenario to see final memory usage. +We also have a `/gc` endpoint for forcing a garbage collection; this is used at the end of each test scenario to see +final memory usage. -Note: there's a `/capture` endpoint which does a basic `captureException` call 1000 times. That's our current problem child requiring some more investigation on its memory usage. +Note: there's a `/capture` endpoint which does a basic `captureException` call 1000 times. That's our current problem +child requiring some more investigation on its memory usage. ## How to run it + ```bash npm install memwatch-next nock node manager.js @@ -29,10 +39,17 @@ curl localhost:3000/capture ``` ## Why this can't be more automated -Some objects can have long lifecycles or not be cleaned up by GC when you think they would be, and so it isn't straightforward to make the assertion "memory usage should have returned to baseline by now". Also, when the numbers look bad, it's pretty obvious to a trained eye that they're bad, but it can be hard to quantify an exact threshold of pass or fail. + +Some objects can have long lifecycles or not be cleaned up by GC when you think they would be, and so it isn't +straightforward to make the assertion "memory usage should have returned to baseline by now". Also, when the numbers +look bad, it's pretty obvious to a trained eye that they're bad, but it can be hard to quantify an exact threshold of +pass or fail. ## Interpreting results -Starting the manager and then running `ab -c 5 -n 5000 /context/basic && sleep 1 && curl localhost:3000/gc` will get us this output: + +Starting the manager and then running `ab -c 5 -n 5000 /context/basic && sleep 1 && curl localhost:3000/gc` will get us +this output: +
``` :[/Users/lewis/dev/raven-node/test/manual]#memleak-tests?$ node manager.js @@ -52,6 +69,7 @@ gc #7: min 11673824, max 16864536, est base 11673824, curr base 11673824 This test stores some basic data in the request's Raven context, with the hope being for that context data to go out of scope and be garbage collected after the request is over. We can see that we start at a base of ~11.6MB, go up to ~16.8MB during the test, and then return to ~11.6MB. Everything checks out, no memory leak issue here. Back when we had a memory leak in `captureException`, if we started the manager and ran: + ```shell ab -c 5 -n 5000 localhost:3000/context/basic?doError=true && sleep 5 && curl localhost:3000/gc sleep 5 @@ -61,7 +79,9 @@ curl localhost:3000/gc sleep 15 curl localhost:3000/gc ``` + we'd get this output: +
``` [/Users/lewis/dev/raven-node/test/manual]#memleak-tests?$ node manager.js diff --git a/packages/opentelemetry/README.md b/packages/opentelemetry/README.md index 18ae5e9572d0..66fcb1a9e287 100644 --- a/packages/opentelemetry/README.md +++ b/packages/opentelemetry/README.md @@ -34,7 +34,8 @@ Note that `@sentry/opentelemetry` depends on the following peer dependencies: ## Usage -This package exposes a few building blocks you can add to your OpenTelemetry setup in order to capture OpenTelemetry traces to Sentry. +This package exposes a few building blocks you can add to your OpenTelemetry setup in order to capture OpenTelemetry +traces to Sentry. This is how you can use this in your app: diff --git a/packages/replay-canvas/CONTRIBUTING.md b/packages/replay-canvas/CONTRIBUTING.md index 829930e2b05e..7b4a70f075ab 100644 --- a/packages/replay-canvas/CONTRIBUTING.md +++ b/packages/replay-canvas/CONTRIBUTING.md @@ -1,4 +1,7 @@ ## Updating the rrweb dependency -When [updating the `rrweb` dependency](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/package.json?plain=1#LL55), -please be aware that [`@sentry/replay`'s README.md](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/README.md?plain=1#LL204) also needs to be updated. +When +[updating the `rrweb` dependency](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/package.json?plain=1#LL55), +please be aware that +[`@sentry/replay`'s README.md](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/README.md?plain=1#LL204) +also needs to be updated. diff --git a/packages/replay-canvas/README.md b/packages/replay-canvas/README.md index 8102f12d9575..75e2f26a0290 100644 --- a/packages/replay-canvas/README.md +++ b/packages/replay-canvas/README.md @@ -12,8 +12,9 @@ Replay with canvas requires Node 14+, and browsers newer than IE11. ## Installation -Replay and ReplayCanvas can be imported from `@sentry/browser`, or a respective SDK package like `@sentry/react` or `@sentry/vue`. -You don't need to install anything in order to use Session Replay. The minimum version that includes Replay is 7.27.0. +Replay and ReplayCanvas can be imported from `@sentry/browser`, or a respective SDK package like `@sentry/react` or +`@sentry/vue`. You don't need to install anything in order to use Session Replay. The minimum version that includes +Replay is 7.27.0. For details on using Replay when using Sentry via the CDN bundles, see [CDN bundle](#loading-replay-as-a-cdn-bundle). @@ -42,10 +43,7 @@ Sentry.init({ // sessions when an error occurs. replaysOnErrorSampleRate: 1.0, - integrations: [ - Sentry.replayIntegration(), - Sentry.replayCanvasIntegration(), - ], + integrations: [Sentry.replayIntegration(), Sentry.replayCanvasIntegration()], // ... }); ``` diff --git a/packages/replay-worker/README.md b/packages/replay-worker/README.md index 731b289800b8..970a0b3defb1 100644 --- a/packages/replay-worker/README.md +++ b/packages/replay-worker/README.md @@ -6,8 +6,8 @@ # Sentry Session Replay Worker -This is an internal package that is used by @sentry/replay. -It generates a web worker and converts it to a string, so that we can process it easier in replay. +This is an internal package that is used by @sentry/replay. It generates a web worker and converts it to a string, so +that we can process it easier in replay. By extracting this into a dedicated (private, internal) package, we can streamline the build of replay. @@ -15,4 +15,5 @@ By extracting this into a dedicated (private, internal) package, we can streamli You can find an example worker for if you want to self-host the compression worker in [/examples](./examples/). -This is generated from the actual soure via `yarn build:examples`, which should be run manually whenever replay-worker is updated. +This is generated from the actual soure via `yarn build:examples`, which should be run manually whenever replay-worker +is updated. diff --git a/packages/replay/CONTRIBUTING.md b/packages/replay/CONTRIBUTING.md index 829930e2b05e..7b4a70f075ab 100644 --- a/packages/replay/CONTRIBUTING.md +++ b/packages/replay/CONTRIBUTING.md @@ -1,4 +1,7 @@ ## Updating the rrweb dependency -When [updating the `rrweb` dependency](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/package.json?plain=1#LL55), -please be aware that [`@sentry/replay`'s README.md](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/README.md?plain=1#LL204) also needs to be updated. +When +[updating the `rrweb` dependency](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/package.json?plain=1#LL55), +please be aware that +[`@sentry/replay`'s README.md](https://github.com/getsentry/sentry-javascript/blob/a493aa6a46555b944c8d896a2164bcd8b11caaf5/packages/replay/README.md?plain=1#LL204) +also needs to be updated. diff --git a/packages/replay/MIGRATION.md b/packages/replay/MIGRATION.md index ba6326939970..0fe6160cc56d 100644 --- a/packages/replay/MIGRATION.md +++ b/packages/replay/MIGRATION.md @@ -2,8 +2,9 @@ Sentry Replay is now out of Beta. This means that the usual stability guarantees apply. -Because of experimentation and rapid iteration, during the Beta period some bugs and problems came up which have since been fixed/improved. -We **strongly** recommend anyone using Replay in a version before 7.39.0 to update to 7.39.0 or newer, in order to prevent running Replay with known problems that have since been fixed. +Because of experimentation and rapid iteration, during the Beta period some bugs and problems came up which have since +been fixed/improved. We **strongly** recommend anyone using Replay in a version before 7.39.0 to update to 7.39.0 or +newer, in order to prevent running Replay with known problems that have since been fixed. Below you can find a list of relevant replay issues that have been resolved until 7.39.0: @@ -33,7 +34,7 @@ Below you can find a list of relevant replay issues that have been resolved unti - Handle removed attributes ([#65](https://github.com/getsentry/rrweb/pull/65)) - Change LCP calculation (#7187, #7225) - Fix debounced flushes not respecting `maxWait` (#7207, #7208) -- Fix svgs not getting unblocked (#7132) +- Fix svgs not getting unblocked (#7132) - Fix missing fetch/xhr requests (#7134) - Fix feature detection of PerformanceObserver (#7029) - Fix `checkoutEveryNms` (#6722) @@ -44,14 +45,18 @@ Below you can find a list of relevant replay issues that have been resolved unti # Upgrading Replay from 7.34.0 to 7.35.0 - #6645 -This release will remove the ability to change the default rrweb recording options (outside of privacy options). The following are the new configuration values all replays will use: -`slimDOMOptions: 'all'` - Removes `script`, comments, `favicon`, whitespace in `head`, and a few `meta` tags in `head` -`recordCanvas: false` - This option did not do anything as playback of recorded canvas means we would have to remove the playback sandbox (which is a security concern). -`inlineStylesheet: true` - Inlines styles into the recording itself instead of attempting to fetch it remotely. This means that styles in the replay will reflect the styles at the time of recording and not the current styles of the remote stylesheet. -`collectFonts: true` - Attempts to load custom fonts. -`inlineImages: false` - Does not inline images to recording and instead loads the asset remotely. During playback, images may not load due to CORS (add sentry.io as an origin). +This release will remove the ability to change the default rrweb recording options (outside of privacy options). The +following are the new configuration values all replays will use: `slimDOMOptions: 'all'` - Removes `script`, comments, +`favicon`, whitespace in `head`, and a few `meta` tags in `head` `recordCanvas: false` - This option did not do anything +as playback of recorded canvas means we would have to remove the playback sandbox (which is a security concern). +`inlineStylesheet: true` - Inlines styles into the recording itself instead of attempting to fetch it remotely. This +means that styles in the replay will reflect the styles at the time of recording and not the current styles of the +remote stylesheet. `collectFonts: true` - Attempts to load custom fonts. `inlineImages: false` - Does not inline images +to recording and instead loads the asset remotely. During playback, images may not load due to CORS (add sentry.io as an +origin). -Additionally, we have streamlined the privacy options. The following table lists the deprecated value, and what it is replaced by: +Additionally, we have streamlined the privacy options. The following table lists the deprecated value, and what it is +replaced by: | deprecated key | replaced by | description | | ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -64,17 +69,17 @@ Additionally, we have streamlined the privacy options. The following table lists # Upgrading Replay from 7.31.0 to 7.32.0 -In 7.32.0, we have removed the default values for the replay sample rates. -Previously, they were: +In 7.32.0, we have removed the default values for the replay sample rates. Previously, they were: -* `replaysSessionSampleRate: 0.1` -* `replaysOnErrorSampleRate: 1.0` +- `replaysSessionSampleRate: 0.1` +- `replaysOnErrorSampleRate: 1.0` Now, you have to explicitly set the sample rates, otherwise they default to 0. # Upgrading Replay from 0.6.x to 7.24.0 -The Sentry Replay integration was moved to the Sentry JavaScript SDK monorepo. Hence we're jumping from version 0.x to the monorepo's 7.x version which is shared across all JS SDK packages. +The Sentry Replay integration was moved to the Sentry JavaScript SDK monorepo. Hence we're jumping from version 0.x to +the monorepo's 7.x version which is shared across all JS SDK packages. ## Replay sample rates are defined on top level (https://github.com/getsentry/sentry-javascript/issues/6351) @@ -87,7 +92,7 @@ Sentry.init({ new Replay({ sessionSampleRate: 0.1, errorSampleRate: 1.0, - }) + }), ], // ... }); @@ -103,23 +108,25 @@ Sentry.init({ integrations: [ new Replay({ // other replay config still goes in here - }) + }), ], }); ``` -Note that the sample rate options inside of `new Replay({})` have been deprecated and will be removed in a future update. +Note that the sample rate options inside of `new Replay({})` have been deprecated and will be removed in a future +update. ## Removed deprecated options (https://github.com/getsentry/sentry-javascript/pull/6370) Two options, which have been deprecated for some time, have been removed: -* `replaysSamplingRate` - instead use `sessionSampleRate` -* `captureOnlyOnError` - instead use `errorSampleRate` +- `replaysSamplingRate` - instead use `sessionSampleRate` +- `captureOnlyOnError` - instead use `errorSampleRate` ## New NPM package structure (https://github.com/getsentry/sentry-javascript/issues/6280) -The internal structure of the npm package has changed. This is unlikely to affect you, unless you have imported something from e.g.: +The internal structure of the npm package has changed. This is unlikely to affect you, unless you have imported +something from e.g.: ```js import something from '@sentry/replay/submodule'; @@ -134,8 +141,8 @@ Unless you manually imported this and used it somewhere in your codebase, this w ## Session object is now a plain object (https://github.com/getsentry/sentry-javascript/pull/6417) -The `Session` object exported from Replay is now a plain object, instead of a class. -This should not affect you unless you specifically accessed this class & did custom things with it. +The `Session` object exported from Replay is now a plain object, instead of a class. This should not affect you unless +you specifically accessed this class & did custom things with it. ## Reduce public API of Replay integration (https://github.com/getsentry/sentry-javascript/pull/6407) diff --git a/packages/replay/README.md b/packages/replay/README.md index 751ed2e9870c..8673bcdecd56 100644 --- a/packages/replay/README.md +++ b/packages/replay/README.md @@ -16,15 +16,15 @@ ## Installation -Replay can be imported from `@sentry/browser`, or a respective SDK package like `@sentry/react` or `@sentry/vue`. -You don't need to install anything in order to use Session Replay. The minimum version that includes Replay is 7.27.0. +Replay can be imported from `@sentry/browser`, or a respective SDK package like `@sentry/react` or `@sentry/vue`. You +don't need to install anything in order to use Session Replay. The minimum version that includes Replay is 7.27.0. For details on using Replay when using Sentry via the CDN bundles, see [CDN bundle](#loading-replay-as-a-cdn-bundle). ## Setup -To set up the integration, add the following to your Sentry initialization. Several options are supported and passable via the integration constructor. -See the [configuration section](#configuration) below for more details. +To set up the integration, add the following to your Sentry initialization. Several options are supported and passable +via the integration constructor. See the [configuration section](#configuration) below for more details. ```javascript import * as Sentry from '@sentry/browser'; @@ -45,9 +45,9 @@ Sentry.init({ Sentry.replayIntegration({ // Additional SDK configuration goes in here, for example: maskAllText: true, - blockAllMedia: true + blockAllMedia: true, // See below for all available options - }) + }), ], // ... }); @@ -55,9 +55,8 @@ Sentry.init({ ### Lazy loading Replay -Replay will start automatically when you add the integration. -If you do not want to start Replay immediately (e.g. if you want to lazy-load it), -you can also use `addIntegration` to load it later: +Replay will start automatically when you add the integration. If you do not want to start Replay immediately (e.g. if +you want to lazy-load it), you can also use `addIntegration` to load it later: ```js import * as Sentry from "@sentry/react"; @@ -78,17 +77,20 @@ client?.addIntegration(Sentry.replayIntegration()); ### Identifying Users -If you have only followed the above instructions to setup session replays, you will only see IP addresses in Sentry's UI. In order to associate a user identity to a session replay, use [`setUser`](https://docs.sentry.io/platforms/javascript/enriching-events/identify-user/). +If you have only followed the above instructions to setup session replays, you will only see IP addresses in Sentry's +UI. In order to associate a user identity to a session replay, use +[`setUser`](https://docs.sentry.io/platforms/javascript/enriching-events/identify-user/). ```javascript -import * as Sentry from "@sentry/browser"; +import * as Sentry from '@sentry/browser'; -Sentry.setUser({ email: "jane.doe@example.com" }); +Sentry.setUser({ email: 'jane.doe@example.com' }); ``` ### Stopping & starting Replays manually -Replay recording only starts when it is included in the `integrations` array when calling `Sentry.init` or calling `addIntegration` from the a Sentry client instance. To stop recording you can call `stop()`. +Replay recording only starts when it is included in the `integrations` array when calling `Sentry.init` or calling +`addIntegration` from the a Sentry client instance. To stop recording you can call `stop()`. ```js import * as Sentry from "@sentry/react"; @@ -109,20 +111,19 @@ client?.addIntegration(replay); replay.stop(); ``` -When both `replaysSessionSampleRate` and `replaysOnErrorSampleRate` are `0`, recording will _not_ start. -In this case, you can manually start recording: +When both `replaysSessionSampleRate` and `replaysOnErrorSampleRate` are `0`, recording will _not_ start. In this case, +you can manually start recording: ```js replay.start(); // Will start a session in "session" mode, regardless of sample rates replay.startBuffering(); // Will start a session in "buffer" mode, regardless of sample rates ``` - - ## Loading Replay as a CDN Bundle -As an alternative to the NPM package, you can use Replay as a CDN bundle. -Please refer to the [Session Replay installation guide](https://docs.sentry.io/platforms/javascript/session-replay/#install) for CDN bundle instructions. +As an alternative to the NPM package, you can use Replay as a CDN bundle. Please refer to the +[Session Replay installation guide](https://docs.sentry.io/platforms/javascript/session-replay/#install) for CDN bundle +instructions.
Deprecated Replay integration bundle @@ -131,44 +132,47 @@ complete CDN bundles that already contain the replay integration. No need to kee The `replay.(min.)js` bundle will be removed in v8 of the JS SDKs. ```html - - + + ``` +
## Sessions -A session starts when the Session Replay SDK is first loaded and initialized. The session will continue until 5 minutes passes without any user interactions[^1] with the application *OR* until a maximum of 30 minutes have elapsed. Closing the browser tab will end the session immediately according to the rules for [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage). +A session starts when the Session Replay SDK is first loaded and initialized. The session will continue until 5 minutes +passes without any user interactions[^1] with the application _OR_ until a maximum of 30 minutes have elapsed. Closing +the browser tab will end the session immediately according to the rules for +[SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage). [^1]: An 'interaction' refers to either a mouse click or a browser navigation event. ### Accessing the Replay Session ID -You can get the ID of the currently running session via `replay.getReplayId()`. -This will return `undefined` if no session is ongoing. +You can get the ID of the currently running session via `replay.getReplayId()`. This will return `undefined` if no +session is ongoing. ### Replay Captures Only on Errors -Alternatively, rather than recording an entire session, you can capture a replay only when an error occurs. In this case, the integration will buffer up to one minute worth of events prior to the error being thrown. It will continue to record the session following the rules above regarding session life and activity. Read the [sampling](#Sampling) section for configuration options. +Alternatively, rather than recording an entire session, you can capture a replay only when an error occurs. In this +case, the integration will buffer up to one minute worth of events prior to the error being thrown. It will continue to +record the session following the rules above regarding session life and activity. Read the [sampling](#Sampling) section +for configuration options. ## Sampling -Sampling allows you to control how much of your website's traffic will result in a Session Replay. There are two sample rates you can adjust to get the replays more relevant to your interests: +Sampling allows you to control how much of your website's traffic will result in a Session Replay. There are two sample +rates you can adjust to get the replays more relevant to your interests: -- `replaysSessionSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the user's session. -- `replaysOnErrorSampleRate` - The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends. +- `replaysSessionSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the + user's session. +- `replaysOnErrorSampleRate` - The sample rate for replays that are recorded when an error happens. This type of replay + will record up to a minute of events prior to the error and continue recording until the session ends. -When Replay is initialized, we check the `replaysSessionSampleRate`. -If it is sampled, then we start recording & sending Replay data immediately. -Else, if `replaysOnErrorSampleRate > 0`, we'll start recording in buffering mode. -In this mode, whenever an error occurs we'll check `replaysOnErrorSampleRate`. -If it is sampled, when we'll upload the Replay to Sentry and continue recording normally. +When Replay is initialized, we check the `replaysSessionSampleRate`. If it is sampled, then we start recording & sending +Replay data immediately. Else, if `replaysOnErrorSampleRate > 0`, we'll start recording in buffering mode. In this mode, +whenever an error occurs we'll check `replaysOnErrorSampleRate`. If it is sampled, when we'll upload the Replay to +Sentry and continue recording normally. ## Configuration @@ -176,76 +180,87 @@ If it is sampled, when we'll upload the Replay to Sentry and continue recording The following options can be configured on the root level of your browser-based Sentry SDK, in `init({})`: - -| key | type | default | description | -| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| replaysSessionSampleRate | number | `0` | The sample rate for replays that begin recording immediately and last the entirety of the user's session. 1.0 will collect all replays, 0 will collect no replays. | -| replaysOnErrorSampleRate | number | `0` |The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends. 1.0 capturing all sessions with an error, and 0 capturing none. +| key | type | default | description | +| ------------------------ | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| replaysSessionSampleRate | number | `0` | The sample rate for replays that begin recording immediately and last the entirety of the user's session. 1.0 will collect all replays, 0 will collect no replays. | +| replaysOnErrorSampleRate | number | `0` | The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends. 1.0 capturing all sessions with an error, and 0 capturing none. | ### General Integration Configuration The following options can be configured as options to the integration, in `Sentry.replayIntegration({})`: -| key | type | default | description | -| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| stickySession | boolean | `true` | Keep track of the user across page loads. Note a single user using multiple tabs will result in multiple sessions. Closing a tab will result in the session being closed as well. | - +| key | type | default | description | +| ------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| stickySession | boolean | `true` | Keep track of the user across page loads. Note a single user using multiple tabs will result in multiple sessions. Closing a tab will result in the session being closed as well. | ### Privacy Configuration The following options can be configured as options to the integration, in `Sentry.replayIntegration({})`: -| key | type | default | description | -| ---------------- | ------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| maskAllText | boolean | `true` | Mask _all_ text content. Will pass text content through `maskFn` before sending to server. | -| maskAllInputs | boolean | `true` | Mask values of `` elements. Passes input values through `maskInputFn` before sending to server. | -| blockAllMedia | boolean | `true` | Block _all_ media elements (`img, svg, video, object, picture, embed, map, audio`) | -| maskFn | (text: string) => string | `(text) => '*'.repeat(text.length)` | Function to customize how text content is masked before sending to server. By default, masks text with `*`. | -| block | Array | `.sentry-block, [data-sentry-block]` | Redact any elements that match the DOM selectors. See [privacy](#blocking) section for an example. | -| unblock | Array | `.sentry-unblock, [data-sentry-unblock]`| Do not redact any elements that match the DOM selectors. Useful when using `blockAllMedia`. See [privacy](#blocking) section for an example. | -| mask | Array | `.sentry-mask, [data-sentry-mask]` | Mask all elements that match the given DOM selectors. See [privacy](#masking) section for an example. | -| unmask | Array | `.sentry-unmask, [data-sentry-unmask]` | Unmask all elements that match the given DOM selectors. Useful when using `maskAllText`. See [privacy](#masking) section for an example. | -| ignore | Array | `.sentry-ignore, [data-sentry-ignore]` | Ignores all events on the matching input fields. See [privacy](#ignoring) section for an example. | +| key | type | default | description | +| ------------- | ------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| maskAllText | boolean | `true` | Mask _all_ text content. Will pass text content through `maskFn` before sending to server. | +| maskAllInputs | boolean | `true` | Mask values of `` elements. Passes input values through `maskInputFn` before sending to server. | +| blockAllMedia | boolean | `true` | Block _all_ media elements (`img, svg, video, object, picture, embed, map, audio`) | +| maskFn | (text: string) => string | `(text) => '*'.repeat(text.length)` | Function to customize how text content is masked before sending to server. By default, masks text with `*`. | +| block | Array | `.sentry-block, [data-sentry-block]` | Redact any elements that match the DOM selectors. See [privacy](#blocking) section for an example. | +| unblock | Array | `.sentry-unblock, [data-sentry-unblock]` | Do not redact any elements that match the DOM selectors. Useful when using `blockAllMedia`. See [privacy](#blocking) section for an example. | +| mask | Array | `.sentry-mask, [data-sentry-mask]` | Mask all elements that match the given DOM selectors. See [privacy](#masking) section for an example. | +| unmask | Array | `.sentry-unmask, [data-sentry-unmask]` | Unmask all elements that match the given DOM selectors. Useful when using `maskAllText`. See [privacy](#masking) section for an example. | +| ignore | Array | `.sentry-ignore, [data-sentry-ignore]` | Ignores all events on the matching input fields. See [privacy](#ignoring) section for an example. | #### Deprecated options -In order to streamline our privacy options, the following have been deprecated in favor for the respective options above. - -| deprecated key | replaced by | description | -| ---------------- | ----------- | ----------- | -| maskInputOptions | mask | Use CSS selectors in `mask` in order to mask all inputs of a certain type. For example, `input[type="address"]` | -| blockSelector | block | The selector(s) can be moved directly in the `block` array. | -| blockClass | block | Convert the class name to a CSS selector and add to `block` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | -| maskClass | mask | Convert the class name to a CSS selector and add to `mask` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | -| maskSelector | mask | The selector(s) can be moved directly in the `mask` array. | + +In order to streamline our privacy options, the following have been deprecated in favor for the respective options +above. + +| deprecated key | replaced by | description | +| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| maskInputOptions | mask | Use CSS selectors in `mask` in order to mask all inputs of a certain type. For example, `input[type="address"]` | +| blockSelector | block | The selector(s) can be moved directly in the `block` array. | +| blockClass | block | Convert the class name to a CSS selector and add to `block` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | +| maskClass | mask | Convert the class name to a CSS selector and add to `mask` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | +| maskSelector | mask | The selector(s) can be moved directly in the `mask` array. | | ignoreClass | ignore | Convert the class name to a CSS selector and add to `ignore` array. For example, `first-name` becomes `.first-name`. Regexes can be moved as-is. | ## Privacy -There are several ways to deal with PII. By default, the integration will mask all text content with `*` and block all media elements (`img, svg, video, object, picture, embed, map, audio`). This can be disabled by setting `maskAllText` to `false`. It is also possible to add the following CSS classes to specific DOM elements to prevent recording its contents: `sentry-block`, `sentry-ignore`, and `sentry-mask`. The following sections will show examples of how content is handled by the differing methods. + +There are several ways to deal with PII. By default, the integration will mask all text content with `*` and block all +media elements (`img, svg, video, object, picture, embed, map, audio`). This can be disabled by setting `maskAllText` to +`false`. It is also possible to add the following CSS classes to specific DOM elements to prevent recording its +contents: `sentry-block`, `sentry-ignore`, and `sentry-mask`. The following sections will show examples of how content +is handled by the differing methods. ### Masking -Masking replaces the text content with something else. The default masking behavior is to replace each character with a `*`. In this example the relevant html code is: `...
`. + +Masking replaces the text content with something else. The default masking behavior is to replace each character with a +`*`. In this example the relevant html code is: `...
`. ![Masking example](https://user-images.githubusercontent.com/79684/193118192-dee1d3d8-5813-47e8-b532-f9ee1c8714b3.png) ### Blocking -Blocking replaces the element with a placeholder that has the same dimensions. The recording will show an empty space where the content was. In this example the relevant html code is: `...
`. + +Blocking replaces the element with a placeholder that has the same dimensions. The recording will show an empty space +where the content was. In this example the relevant html code is: `...
`. ![Blocking example](https://user-images.githubusercontent.com/79684/193118084-51a589fc-2160-476a-a8dc-b681eddb136c.png) ### Ignoring -Ignoring only applies to form inputs. Events will be ignored on the input element so that the replay does not show what occurs inside of the input. In the below example, notice how the results in the table below the input changes, but no text is visible in the input. + +Ignoring only applies to form inputs. Events will be ignored on the input element so that the replay does not show what +occurs inside of the input. In the below example, notice how the results in the table below the input changes, but no +text is visible in the input. https://user-images.githubusercontent.com/79684/192815134-a6451c3f-d3cb-455f-a699-7c3fe04d0a2e.mov ## Error Linking -Currently, errors that happen on the page while a replay is running are linked to the Replay, -making it as easy as possible to jump between related issues/replays. -However, please note that it is _possible_ that the error count reported on the Replay Detail page -does not match the actual errors that have been captured. -The reason for that is that errors _can_ be lost, e.g. a network request fails, or similar. -This should not happen to often, but be aware that it is theoretically possible. +Currently, errors that happen on the page while a replay is running are linked to the Replay, making it as easy as +possible to jump between related issues/replays. However, please note that it is _possible_ that the error count +reported on the Replay Detail page does not match the actual errors that have been captured. The reason for that is that +errors _can_ be lost, e.g. a network request fails, or similar. This should not happen to often, but be aware that it is +theoretically possible. ## Manually sending replay data -You can use `replay.flush()` to immediately send all currently captured replay data. -When Replay is currently in buffering mode, this will send up to the last 60 seconds of replay data, -and also continue sending afterwards, similar to when an error happens & is recorded. +You can use `replay.flush()` to immediately send all currently captured replay data. When Replay is currently in +buffering mode, this will send up to the last 60 seconds of replay data, and also continue sending afterwards, similar +to when an error happens & is recorded. diff --git a/packages/sveltekit/README.md b/packages/sveltekit/README.md index 84970cca7954..895c8dad23e1 100644 --- a/packages/sveltekit/README.md +++ b/packages/sveltekit/README.md @@ -16,26 +16,30 @@ ## Compatibility -The minimum supported version of SvelteKit is `1.0.0`. -The SDK works best with Vite 4.2 and newer. -Older Vite versions might not generate source maps correctly. +The minimum supported version of SvelteKit is `1.0.0`. The SDK works best with Vite 4.2 and newer. Older Vite versions +might not generate source maps correctly. The SDK supports the following SvelteKit adapters: -- `@sveltejs/adapter-auto` - for Vercel with the Node runtime. Other deployment targets might work but we don't guarantee compatibility. + +- `@sveltejs/adapter-auto` - for Vercel with the Node runtime. Other deployment targets might work but we don't + guarantee compatibility. - `@sveltejs/adapter-vercel` - only for Node (Lambda) runtimes, not yet Vercel's edge runtime - `@sveltejs/adapter-node` -If you use the SDK with other adapters, we cannot guarantee that everything works as expected. -You might need to [manually configure source maps upload](#-configuring-source-maps-upload). -The SDK is currently not compatible with none-Node server runtimes, such as Vercel's Edge runtime or Cloudflare workers. +If you use the SDK with other adapters, we cannot guarantee that everything works as expected. You might need to +[manually configure source maps upload](#-configuring-source-maps-upload). The SDK is currently not compatible with +none-Node server runtimes, such as Vercel's Edge runtime or Cloudflare workers. ## General -This package is a wrapper around `@sentry/node` for the server and `@sentry/svelte` for the client side, with added functionality related to SvelteKit. +This package is a wrapper around `@sentry/node` for the server and `@sentry/svelte` for the client side, with added +functionality related to SvelteKit. ## Automatic Setup -We recommend installing the SDK by running the [Sentry wizard](https://docs.sentry.io/platforms/javascript/guides/sveltekit/#install) in the root directory of your project: +We recommend installing the SDK by running the +[Sentry wizard](https://docs.sentry.io/platforms/javascript/guides/sveltekit/#install) in the root directory of your +project: ```sh npx @sentry/wizard@latest -i sveltekit @@ -61,39 +65,40 @@ If the setup through the wizard doesn't work for you, you can also set up the SD ### 2. Client-side Setup -The Sentry SvelteKit SDK mostly relies on [SvelteKit Hooks](https://kit.svelte.dev/docs/hooks) to capture error and performance data. +The Sentry SvelteKit SDK mostly relies on [SvelteKit Hooks](https://kit.svelte.dev/docs/hooks) to capture error and +performance data. -1. If you don't already have a client hooks file, create a new one in `src/hooks.client.(js|ts)`. +1. If you don't already have a client hooks file, create a new one in `src/hooks.client.(js|ts)`. 2. On the top of your `hooks.client.(js|ts)` file, initialize the Sentry SDK: ```javascript - // hooks.client.(js|ts) - import * as Sentry from '@sentry/sveltekit'; - - Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - // For instance, initialize Session Replay: - replaysSessionSampleRate: 0.1, - replaysOnErrorSampleRate: 1.0, - integrations: [Sentry.replayIntegration()], - }); + // hooks.client.(js|ts) + import * as Sentry from '@sentry/sveltekit'; + + Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + // For instance, initialize Session Replay: + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + integrations: [Sentry.replayIntegration()], + }); ``` 3. Add our `handleErrorWithSentry` function to the `handleError` hook: ```javascript - // hooks.client.(js|ts) - import { handleErrorWithSentry } from '@sentry/sveltekit'; + // hooks.client.(js|ts) + import { handleErrorWithSentry } from '@sentry/sveltekit'; - const myErrorHandler = (({ error, event }) => { - console.error('An error occurred on the client side:', error, event); - }); + const myErrorHandler = ({ error, event }) => { + console.error('An error occurred on the client side:', error, event); + }; - export const handleError = handleErrorWithSentry(myErrorHandler); - // or alternatively, if you don't have a custom error handler: - // export const handleError = handleErrorWithSentry(); + export const handleError = handleErrorWithSentry(myErrorHandler); + // or alternatively, if you don't have a custom error handler: + // export const handleError = handleErrorWithSentry(); ``` ### 3. Server-side Setup @@ -102,47 +107,47 @@ The Sentry SvelteKit SDK mostly relies on [SvelteKit Hooks](https://kit.svelte.d 2. On the top of your `hooks.server.(js|ts)` file, initialize the Sentry SDK: - ```javascript - // hooks.server.(js|ts) - import * as Sentry from '@sentry/sveltekit'; + ```javascript + // hooks.server.(js|ts) + import * as Sentry from '@sentry/sveltekit'; - Sentry.init({ - dsn: '__DSN__', - tracesSampleRate: 1.0, - }); + Sentry.init({ + dsn: '__DSN__', + tracesSampleRate: 1.0, + }); ``` 3. Add our `handleErrorWithSentry` function to the `handleError` hook: ```javascript - // hooks.server.(js|ts) - import { handleErrorWithSentry } from '@sentry/sveltekit'; + // hooks.server.(js|ts) + import { handleErrorWithSentry } from '@sentry/sveltekit'; - const myErrorHandler = (({ error, event }) => { - console.error('An error occurred on the server side:', error, event); - }); + const myErrorHandler = ({ error, event }) => { + console.error('An error occurred on the server side:', error, event); + }; - export const handleError = handleErrorWithSentry(myErrorHandler); - // or alternatively, if you don't have a custom error handler: - // export const handleError = handleErrorWithSentry(); + export const handleError = handleErrorWithSentry(myErrorHandler); + // or alternatively, if you don't have a custom error handler: + // export const handleError = handleErrorWithSentry(); ``` 4. Add our request handler to the `handle` hook in `hooks.server.ts`: ```javascript - // hooks.server.(js|ts) - import { sentryHandle } from '@sentry/sveltekit'; + // hooks.server.(js|ts) + import { sentryHandle } from '@sentry/sveltekit'; - export const handle = sentryHandle(); - // or alternatively, if you already have a handler defined, use the `sequence` function - // see: https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks-sequence - // export const handle = sequence(sentryHandle(), yourHandler()); + export const handle = sentryHandle(); + // or alternatively, if you already have a handler defined, use the `sequence` function + // see: https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks-sequence + // export const handle = sequence(sentryHandle(), yourHandler()); ``` ### 4. Vite Setup -Add `sentrySvelteKit` to your Vite plugins in `vite.config.(js|ts)` file so that the Sentry SDK can apply build-time features. -Make sure that it is added _before_ the `sveltekit` plugin: +Add `sentrySvelteKit` to your Vite plugins in `vite.config.(js|ts)` file so that the Sentry SDK can apply build-time +features. Make sure that it is added _before_ the `sveltekit` plugin: ```javascript // vite.config.(js|ts) @@ -155,7 +160,9 @@ export default { }; ``` -This adds the [Sentry Vite Plugin](https://github.com/getsentry/sentry-javascript-bundler-plugins/tree/main/packages/vite-plugin) to your Vite config to automatically upload source maps to Sentry. +This adds the +[Sentry Vite Plugin](https://github.com/getsentry/sentry-javascript-bundler-plugins/tree/main/packages/vite-plugin) to +your Vite config to automatically upload source maps to Sentry. --- @@ -194,8 +201,8 @@ export default { ### Configuring Source maps upload Under `sourceMapsUploadOptions`, you can also specify all additional options supported by the -[Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin). -This might be useful if you're using adapters other than the Node adapter or have a more customized build setup. +[Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin). This might be useful if you're using adapters +other than the Node adapter or have a more customized build setup. ```js // vite.config.(js|ts) @@ -244,15 +251,21 @@ export default { ## Configure Auto-Instrumentation -The SDK mostly relies on [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks) to collect error and performance data. However, SvelteKit doesn't yet offer a hook for universal or server-only `load` function calls. Therefore, the SDK uses a Vite plugin to auto-instrument `load` functions so that you don't have to add a Sentry wrapper to each function manually. Auto-instrumentation is enabled by default, as soon as you add the `sentrySvelteKit()` function call to your `vite.config.(js|ts)`. However, you can customize the behavior, or disable it entirely. In this case, you can still manually wrap specific `load` functions with the `withSentry` function. - -Note: The SDK will only auto-instrument `load` functions in `+page` or `+layout` files that do not yet contain any Sentry code. -If you already have custom Sentry code in such files, you'll have to [manually](#instrument-load-functions-manually) add our wrapper to your `load` functions. +The SDK mostly relies on [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks) to collect error and performance data. +However, SvelteKit doesn't yet offer a hook for universal or server-only `load` function calls. Therefore, the SDK uses +a Vite plugin to auto-instrument `load` functions so that you don't have to add a Sentry wrapper to each function +manually. Auto-instrumentation is enabled by default, as soon as you add the `sentrySvelteKit()` function call to your +`vite.config.(js|ts)`. However, you can customize the behavior, or disable it entirely. In this case, you can still +manually wrap specific `load` functions with the `withSentry` function. +Note: The SDK will only auto-instrument `load` functions in `+page` or `+layout` files that do not yet contain any +Sentry code. If you already have custom Sentry code in such files, you'll have to +[manually](#instrument-load-functions-manually) add our wrapper to your `load` functions. ### Customize Auto-instrumentation -By passing the `autoInstrument` option to `sentrySvelteKit` you can disable auto-instrumentation entirely, or customize which `load` functions should be instrumented: +By passing the `autoInstrument` option to `sentrySvelteKit` you can disable auto-instrumentation entirely, or customize +which `load` functions should be instrumented: ```javascript // vite.config.(js|ts) @@ -275,7 +288,8 @@ export default { ### Disable Auto-instrumentation -If you set the `autoInstrument` option to `false`, the SDK won't auto-instrument any `load` function. You can still [manually instrument](#instrument-load-functions-manually) specific `load` functions. +If you set the `autoInstrument` option to `false`, the SDK won't auto-instrument any `load` function. You can still +[manually instrument](#instrument-load-functions-manually) specific `load` functions. ```javascript // vite.config.(js|ts) @@ -295,25 +309,27 @@ export default { ### Instrument `load` Functions Manually -If you don't want to use auto-instrumentation, you can also manually instrument specific `load` functions with our load function wrappers: +If you don't want to use auto-instrumentation, you can also manually instrument specific `load` functions with our load +function wrappers: -To instrument your universal `load` functions in `+(page|layout).(js|ts)`, wrap our `wrapLoadWithSentry` function around your load code: +To instrument your universal `load` functions in `+(page|layout).(js|ts)`, wrap our `wrapLoadWithSentry` function around +your load code: ```javascript import { wrapLoadWithSentry } from '@sentry/sveltekit'; -export const load = wrapLoadWithSentry((event) => { +export const load = wrapLoadWithSentry(event => { //... your load code }); ``` -To instrument server `load` functions in `+(page|layout).server.(js|ts)`, wrap our `wrapServerLoadWithSentry` function around your load code: +To instrument server `load` functions in `+(page|layout).server.(js|ts)`, wrap our `wrapServerLoadWithSentry` function +around your load code: ```javascript import { wrapServerLoadWithSentry } from '@sentry/sveltekit'; -export const load = wrapServerLoadWithSentry((event) => { +export const load = wrapServerLoadWithSentry(event => { //... your server load code }); ``` - diff --git a/packages/tracing-internal/README.md b/packages/tracing-internal/README.md index 89fb3d609619..76f035499f0d 100644 --- a/packages/tracing-internal/README.md +++ b/packages/tracing-internal/README.md @@ -8,4 +8,5 @@ This is an internal package that is being used to migrate @sentry/tracing code to its respective runtime packages. -For v8, @sentry/tracing will be dropped and the code in this package will be split into @sentry/browser and @sentry/node. +For v8, @sentry/tracing will be dropped and the code in this package will be split into @sentry/browser and +@sentry/node. diff --git a/packages/tracing-internal/src/browser/web-vitals/README.md b/packages/tracing-internal/src/browser/web-vitals/README.md index 09add37239aa..73a0a72c2e4b 100644 --- a/packages/tracing-internal/src/browser/web-vitals/README.md +++ b/packages/tracing-internal/src/browser/web-vitals/README.md @@ -4,7 +4,8 @@ This was vendored from: https://github.com/GoogleChrome/web-vitals: v3.0.4 -The commit SHA used is: [7f0ed0bfb03c356e348a558a3eda111b498a2a11](https://github.com/GoogleChrome/web-vitals/tree/7f0ed0bfb03c356e348a558a3eda111b498a2a11) +The commit SHA used is: +[7f0ed0bfb03c356e348a558a3eda111b498a2a11](https://github.com/GoogleChrome/web-vitals/tree/7f0ed0bfb03c356e348a558a3eda111b498a2a11) Current vendored web vitals are: @@ -14,8 +15,9 @@ Current vendored web vitals are: ## Notable Changes from web-vitals library -This vendored web-vitals library is meant to be used in conjunction with the `@sentry/tracing` `BrowserTracing` integration. -As such, logic around `BFCache` and multiple reports were removed from the library as our web-vitals only report once per pageload. +This vendored web-vitals library is meant to be used in conjunction with the `@sentry/tracing` `BrowserTracing` +integration. As such, logic around `BFCache` and multiple reports were removed from the library as our web-vitals only +report once per pageload. ## License @@ -24,16 +26,21 @@ As such, logic around `BFCache` and multiple reports were removed from the libra ## CHANGELOG https://github.com/getsentry/sentry-javascript/pull/5987 + - Bumped from Web Vitals v2.1.0 to v3.0.4 https://github.com/getsentry/sentry-javascript/pull/3781 + - Bumped from Web Vitals v0.2.4 to v2.1.0 https://github.com/getsentry/sentry-javascript/pull/3515 + - Remove support for Time to First Byte (TTFB) https://github.com/getsentry/sentry-javascript/pull/2964 + - Added support for Cumulative Layout Shift (CLS) and Time to First Byte (TTFB) https://github.com/getsentry/sentry-javascript/pull/2909 + - Added support for FID (First Input Delay) and LCP (Largest Contentful Paint) diff --git a/packages/typescript/README.md b/packages/typescript/README.md index 4068d701a7a6..94eb1cbba7e6 100644 --- a/packages/typescript/README.md +++ b/packages/typescript/README.md @@ -46,4 +46,5 @@ Add the following config files to your project's root directory: } ``` -For an example of how to use this package in a monorepo, check out this package's own parent repo, https://github.com/getsentry/sentry-javascript. +For an example of how to use this package in a monorepo, check out this package's own parent repo, +https://github.com/getsentry/sentry-javascript. diff --git a/packages/utils/README.md b/packages/utils/README.md index afa50827741b..812bb86a3525 100644 --- a/packages/utils/README.md +++ b/packages/utils/README.md @@ -19,4 +19,5 @@ Common utilities used by the Sentry JavaScript SDKs. -Note: This package is only meant to be used internally, and as such is not part of our public API contract and does not follow semver. +Note: This package is only meant to be used internally, and as such is not part of our public API contract and does not +follow semver. diff --git a/packages/utils/src/buildPolyfills/README.md b/packages/utils/src/buildPolyfills/README.md index eedea6db9959..bdae9c65c89d 100644 --- a/packages/utils/src/buildPolyfills/README.md +++ b/packages/utils/src/buildPolyfills/README.md @@ -1,15 +1,30 @@ ## Build Polyfills -This is a collection of syntax and import/export polyfills either copied directly from or heavily inspired by those used by [Rollup](https://github.com/rollup/rollup) and [Sucrase](https://github.com/alangpierce/sucrase). When either tool uses one of these polyfills during a build, it injects the function source code into each file needing the function, which can lead to a great deal of duplication. For our builds, we have therefore implemented something similar to [`tsc`'s `importHelpers` behavior](https://www.typescriptlang.org/tsconfig#importHelpers): Instead of leaving the polyfills injected in multiple places, we instead replace each injected function with an `import` or `require` statement. +This is a collection of syntax and import/export polyfills either copied directly from or heavily inspired by those used +by [Rollup](https://github.com/rollup/rollup) and [Sucrase](https://github.com/alangpierce/sucrase). When either tool +uses one of these polyfills during a build, it injects the function source code into each file needing the function, +which can lead to a great deal of duplication. For our builds, we have therefore implemented something similar to +[`tsc`'s `importHelpers` behavior](https://www.typescriptlang.org/tsconfig#importHelpers): Instead of leaving the +polyfills injected in multiple places, we instead replace each injected function with an `import` or `require` +statement. -Note that not all polyfills are currently used by the SDK, but all are included here for future compatitibility, should they ever be needed. Also, since we're never going to be calling these directly from within another TS file, their types are fairly generic. In some cases testing required more specific types, which can be found in the test files. +Note that not all polyfills are currently used by the SDK, but all are included here for future compatitibility, should +they ever be needed. Also, since we're never going to be calling these directly from within another TS file, their types +are fairly generic. In some cases testing required more specific types, which can be found in the test files. --------- +--- _Code from both Rollup and Sucrase is used under the MIT license, copyright 2017 and 2012-2018, respectively._ -_Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:_ +_Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the Software without restriction, including without limitation the +rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit +persons to whom the Software is furnished to do so, subject to the following conditions:_ -_The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software._ +_The above copyright notice and this permission notice shall be included in all copies or substantial portions of the +Software._ -_THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE._ +_THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE._ diff --git a/packages/vue/README.md b/packages/vue/README.md index 378b15eafd0d..21f980cfb2c8 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -28,7 +28,7 @@ const app = createApp({ Sentry.init({ app, dsn: '__PUBLIC_DSN__', - integrations: [ + integrations: [ // Or omit `router` if you're not using vue-router Sentry.browserTracingIntegration({ router }), ], @@ -38,10 +38,10 @@ Sentry.init({ ### Vue 2 ```javascript -import Vue from 'vue' -import App from './App' -import router from './router' -import * as Sentry from '@sentry/vue' +import Vue from 'vue'; +import App from './App'; +import router from './router'; +import * as Sentry from '@sentry/vue'; Sentry.init({ Vue: Vue, @@ -56,6 +56,6 @@ new Vue({ el: '#app', router, components: { App }, - template: '' + template: '', }); ```