docs: Add docs for node setup in v8

.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 }}

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.

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`

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
 

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

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

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: <https://developer.chrome.com/docs/devtools/evaluate-performance/#get-started>
+- Originally coming from
+  [devtools-samples](https://github.com/GoogleChrome/devtools-samples/tree/4818abc9dbcdb954d0eb9b70879f4ea18756451f/jank),
+  licensed under Apache 2.0.
+- Linking article: <https://developer.chrome.com/docs/devtools/evaluate-performance/#get-started>

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.

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.
 

docs/migration/v6-to-v7.md

@@ -541,4 +541,3 @@ const levelA = Severity.error;
 
 const levelB: SeverityLevel = "error"
 ```
-

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<SpanMetadata>;
+  forceTransaction?: boolean;
 }
 ```
 

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);
+```