Restructure Node SDK docs. (#5710)

Summary:

- Removed references to client-side usage / snippets.
- Restructured the sidebar to match the flow of other JavaScript docs.
- Moved parts to `platform-includes` when possible.
- Removed outdated remarks / warnings about old versions.

Co-authored-by: Isabel <[email protected]>
Co-authored-by: Francesco Novy <[email protected]>

Author: 3 people

src/platform-includes/capture-error/node.mdx

@@ -1,8 +1,10 @@
-You can pass an error object to `captureException()` to get it captured as event. It's possible to throw strings as errors in which case no stacktrace can be recorded.
+You can pass an `Error` object to `captureException()` to have it captured as event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stack trace.
 
 ```javascript
+import * as Sentry from '@sentry/node';
+
 try {
-  // ...
+  aFunctionThatMightFail()
 } catch (e) {
   Sentry.captureException(e);
 }

src/platform-includes/configuration/breadcrumb-hints/_default.mdx

@@ -0,0 +1,19 @@
+`event`
+
+: For breadcrumbs created from browser events, the Sentry SDK often supplies the event to the breadcrumb as a hint. This can be used to extract data from the target DOM element into a breadcrumb, for example.
+
+`level` / `input`
+
+: For breadcrumbs created from console log interceptions. This holds the original console log level and the original input data to the log function.
+
+`response` / `input`
+
+: For breadcrumbs created from HTTP requests. This holds the response object (from the fetch API) and the input parameters to the fetch function.
+
+`request` / `response` / `event`
+
+: For breadcrumbs created from HTTP requests. This holds the request and response object (from the node HTTP API) as well as the node event (`response` or `error`).
+
+`xhr`
+
+: For breadcrumbs created from HTTP requests made using the legacy `XMLHttpRequest` API. This holds the original `xhr` object.

src/platform-includes/configuration/breadcrumb-hints/node.mdx

@@ -0,0 +1,7 @@
+`level` / `input`
+
+: For breadcrumbs created from console log interceptions. This holds the original console log level and the original input data to the log function.
+
+`request` / `response` / `event`
+
+: For breadcrumbs created from HTTP requests. This holds the request and response object (from the node HTTP API) as well as the node event (`response` or `error`).

src/platform-includes/configuration/capture-console/node.mdx

@@ -0,0 +1,15 @@
+```javascript {tabTitle: JavaScript}
+import * as Sentry from "@sentry/node";
+import { CaptureConsole as CaptureConsoleIntegration } from "@sentry/integrations";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new CaptureConsoleIntegration(
+    {
+      // array of methods that should be captured
+      // defaults to ['log', 'info', 'warn', 'error', 'debug', 'assert']
+      levels: string[];
+    }
+  )],
+});
+```

src/platform-includes/configuration/decluttering/javascript.mdx

@@ -12,7 +12,7 @@ You can also use `denyUrls` if you want to block specific URLs forever.
 
 <Alert level="warning" title="Note">
 
-Prior to version 5.17.0, `allowUrls` and `denyUrls` were called `whitelistUrls` and `blacklistUrls` respectively. These options are still supported for backwards compatibility reasons, but they will be removed in version 7.0. For more information, please see our [Inclusive Language Policy](https://develop.sentry.dev/inclusion/).
+Previously, `allowUrls` and `denyUrls` were called `whitelistUrls` and `blacklistUrls` respectively. These options are removed in version 7.0. For more information, please see our [Inclusive Language Policy](https://develop.sentry.dev/inclusion/).
 
 </Alert>
 

src/platform-includes/configuration/enable-pluggable-integrations/node.mdx

@@ -0,0 +1,28 @@
+```javascript {tabTitle: JavaScript}
+import * as Sentry from "@sentry/browser";
+import { ReportingObserver as ReportingObserverIntegration } from "@sentry/integrations";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new ReportingObserverIntegration()],
+});
+```
+
+```javascript {tabTitle: CDN}
+<script
+  src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/bundle.min.js"
+  integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'bundle.min.js', 'sha384-base64') }}"
+  crossorigin="anonymous"
+></script>
+
+<script
+  src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/reportingobserver.min.js"
+  integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'reportingobserver.min.js', 'sha384-base64') }}"
+  crossorigin="anonymous"
+></script>
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new Sentry.Integrations.ReportingObserver()],
+});
+```

src/platform-includes/configuration/rewrite-frames/node.mdx

@@ -0,0 +1,30 @@
+```javascript {tabTitle: JavaScript}
+import * as Sentry from "@sentry/node";
+import { RewriteFrames as RewriteFramesIntegration } from "@sentry/integrations";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new RewriteFramesIntegration(
+    {
+      // root path that will be stripped from the current frame's filename by the default iteratee if the filename is an absolute path
+      root: string;
+
+      // a custom prefix that will be used by the default iteratee (default: `app://`)
+      prefix: string;
+
+      // function that takes the frame, applies a transformation, and returns it
+      iteratee: (frame) => frame;
+    }
+  )],
+});
+```
+
+#### Usage Examples
+
+For example, if the full path to your file is `/www/src/app/file.js`:
+
+| Usage                             | Path in Stack Trace      | Description                                                                                                                   |
+| --------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `RewriteFrames()`                 | `app:///file.js`         | The default behavior is to replace the absolute path, except the filename, and prefix it with the default prefix (`app:///`). |
+| `RewriteFrames({prefix: 'foo/'})` | `foo/file.js`            | Prefix `foo/` is used instead of the default prefix `app:///`.                                                                |
+| `RewriteFrames({root: '/www'})`   | `app:///src/app/file.js` | `root` is defined as `/www`, so only that part is trimmed from beginning of the path.                                         |

src/platform-includes/performance/configure-sample-rate/node.mdx

@@ -0,0 +1,15 @@
+```javascript {tabTitle: JavaScript}
+import * as Sentry from "@sentry/node";
+import * as _ from "@sentry/tracing"
+// Note: You MUST import the package in some way for tracing to work
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+
+  // To set a uniform sample rate
+  tracesSampleRate: 0.2
+
+  // Alternatively, to control sampling dynamically
+  tracesSampler: samplingContext => { ... }
+});
+```

src/platform-includes/performance/connect-services/node.mdx

@@ -24,4 +24,4 @@ const transaction = Sentry.startTransaction({
   name: 'transaction_name',
   ...traceparentData,
 });
-```
+```

src/platform-includes/sourcemaps/best-practices/javascript.mdx

@@ -29,7 +29,7 @@ plugins: [
     authToken: process.env.SENTRY_AUTH_TOKEN,
     org: "___ORG_SLUG___",
     project: "___PROJECT_SLUG___",
-      include: "build",
+    include: "build",
     configFile: "sentry.properties",
     release: process.env.SENTRY_RELEASE,
   }),

src/platforms/common/configuration/filtering.mdx

@@ -69,25 +69,7 @@ In this example, the fingerprint is forced to a common value if an exception of
 
 #### Hints for Breadcrumbs
 
-`event`
-
-: For breadcrumbs created from browser events, the Sentry SDK often supplies the event to the breadcrumb as a hint. This, for instance, can be used to extract data from the target DOM element into a breadcrumb.
-
-`level` / `input`
-
-: For breadcrumbs created from console log interceptions. This holds the original console log level and the original input data to the log function.
-
-`response` / `input`
-
-: For breadcrumbs created from HTTP requests. This holds the response object (from the fetch API) and the input parameters to the fetch function.
-
-`request` / `response` / `event`
-
-: For breadcrumbs created from HTTP requests. This holds the request and response object (from the node HTTP API) as well as the node event (`response` or `error`).
-
-`xhr`
-
-: For breadcrumbs created from HTTP requests done via the legacy `XMLHttpRequest` API. This holds the original xhr object.
+<PlatformContent includePath="configuration/breadcrumb-hints" />
 
 </PlatformSection>
 

src/platforms/common/performance/index.mdx

@@ -20,6 +20,7 @@ supported:
   - rust
   - native
   - php
+  - node
 notSupported:
   - javascript.cordova
   - native.breakpad
@@ -89,7 +90,7 @@ Learn more about how the options work in <PlatformLink to="/configuration/sampli
 
 ## Verify
 
-<PlatformSection supported={["react-native", "java.spring", "java.spring-boot", "android", "javascript", "apple", "dart", "rust"]} >
+<PlatformSection supported={["react-native", "java.spring", "java.spring-boot", "android", "javascript", "apple", "dart", "rust"]}>
 
 Verify that performance monitoring is working correctly by using our <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">automatic instrumentation</PlatformLink> or by starting and finishing a transaction using <PlatformLink to="/performance/instrumentation/custom-instrumentation/">custom instrumentation</PlatformLink>.
 

src/platforms/common/performance/instrumentation/custom-instrumentation.mdx

@@ -4,6 +4,7 @@ sidebar_order: 20
 supported:
   - javascript
   - javascript.cordova
+  - node
   - react-native
   - dotnet
   - python

src/platforms/common/performance/instrumentation/index.mdx

@@ -4,7 +4,6 @@ sidebar_order: 20
 description: "Learn how to instrument performance in your app."
 notSupported:
   - javascript.cordova
-  - node
   - native.breakpad
   - native.crashpad
   - native.minidumps

src/platforms/javascript/common/configuration/integrations/default.mdx

@@ -7,9 +7,7 @@ redirect_from:
   - /platforms/javascript/default-integrations/
 ---
 
-All of Sentry’s SDKs provide integrations, which extend functionality of the SDK.
-
-System integrations are enabled by default to integrate into the standard library or the interpreter itself. They are documented so you can be both aware of what they do and disable them if they cause issues.
+System integrations are enabled by default to integrate into the standard library or the interpreter itself. They're documented so you can understand what they do and disable them if they cause issues.
 
 ## Enabled by Default
 
@@ -22,15 +20,15 @@ message, or URLs in a given exception.
 
 It ignores errors that start with `Script error` or `Javascript error: Script error` by default.
 
-To configure this integration, use `ignoreErrors`, `denyUrls`,
+To configure this integration, use the `ignoreErrors`, `denyUrls`,
 and `allowUrls` SDK options directly. Keep in mind that `denyURLs` and `allowURLs`
-work only for captured exceptions, not raw message events.
+only work for captured exceptions, not raw message events.
 
 ### FunctionToString
 
 _Import name: `Sentry.Integrations.FunctionToString`_
 
-This integration allows the SDK to provide original functions and method names, even when our error or breadcrumbs handlers wrap them.
+This integration allows the SDK to provide original functions and method names, even when those functions or methods are wrapped by our error or breadcrumb handlers.
 
 ### TryCatch
 
@@ -92,7 +90,7 @@ Available options:
 
 _Import name: `Sentry.Integrations.LinkedErrors`_
 
-This integration allows you to configure linked errors. They’ll be recursively read up to a specified limit and lookup will be performed by a specific key. By default, the Sentry SDK sets the limit to five and the key used is `cause`.
+This integration allows you to configure linked errors. They’ll be recursively read up to a specified limit, and lookup will be performed by a specific key. By default, the Sentry SDK sets the limit to five and the key used is `"cause"`.
 
 Available options:
 
@@ -122,35 +120,49 @@ document
   });
 ```
 
-### HttpContext (previously: UserAgent)
+### HttpContext
+
+_(Previously: `UserAgent`)_
 
 _Import name: `Sentry.Integrations.HttpContext`_
 
 <Note>
 
 Before version 7.0.0 of the Sentry SDK, this integration was called `UserAgent`.
-It was renamed because the integration handles more than just user-agent data.
+It was renamed because the integration handles more than user-agent data.
 
 _Import name: `Sentry.Integrations.UserAgent`_
 
 </Note>
 
-This integration attaches HTTP request information, such as URL, user-agent, referrer and other headers to the event.
+This integration attaches HTTP request information, such as URL, user-agent, referrer, and other headers to the event.
 It allows us to correctly catalog and tag events with specific OS, browser, and version information.
 
 ### Dedupe
 
 _Import name: `Sentry.Integrations.Dedupe`_
 
-This integration deduplicates certain events. It can be helpful if you are receiving many duplicate errors. Note that Sentry will only compare stack traces and fingerprints. This integration is enabled by default for Browser.
+This integration deduplicates certain events. It can be helpful if you're receiving many duplicate errors. Note that Sentry only compares stack traces and fingerprints. This integration is enabled by default for Browser.
 
 <PlatformContent includePath="configuration/dedupe" />
 
 ## Modifying System Integrations
 
-To disable system integrations set `defaultIntegrations: false` when calling `init()`.
+To disable system integrations, set `defaultIntegrations: false` when calling `init()`.
+
+To override their settings, provide a new instance with your config to the `integrations` option. For example, to turn off browser capturing console calls: 
+
+```javascript
+Sentry.init({
+  dsn: '___PUBLIC_DSN___',
 
-To override their settings, provide a new instance with your config to `integrations` option. For example, to turn off browser capturing console calls: `integrations: [new Sentry.Integrations.Breadcrumbs({ console: false })]`.
+  integrations: [
+    new Sentry.Integrations.Breadcrumbs({
+      console: false
+    })
+  ]
+});
+```
 
 ### Removing an Integration
 

src/platforms/javascript/common/configuration/integrations/plugin.mdx

@@ -6,39 +6,43 @@ redirect_from:
   - /platforms/javascript/pluggable-integrations/
 ---
 
-These pluggable integrations are snippets of code that augment functionality for specific applications and/or frameworks. We document them so you can see what they do and that they can be enabled.
+These pluggable integrations are snippets of code that augment functionality for specific applications and/or frameworks. We document them so you can understand what they do and enable them, if needed.
 
 ## How to Enable
 
-Install the `@sentry/integrations` package and provide a new instance with your config to `integrations` option. Include the plugin after the SDK has been loaded.
+Install the `@sentry/integrations` package and provide a new instance with your config to the `integrations` option. Include the plugin after the SDK has been loaded.
 
 For example:
 
 <PlatformContent includePath="configuration/enable-pluggable-integrations" />
 
+<PlatformSection supported={["javascript"]}>
+
 ### ExtraErrorData
 
 _Import name: `Sentry.Integrations.ExtraErrorData`_
 
-This integration extracts all non-native attributes from the Error object and attaches them to the event as the `extra` data. If the error object has a `.toJSON()` method, the `ExtraErrorData` integration will run it to extract additional information.
+This integration extracts all non-native attributes from the `error` object and attaches them to the event as the `extra` data. If the error object has a `.toJSON()` method, the `ExtraErrorData` integration will run it to extract additional information.
 
 Available options:
 
 <PlatformContent includePath="configuration/extra-error-data" />
 
+</PlatformSection>
+
 ### CaptureConsole
 
 _Import name: `Sentry.Integrations.CaptureConsole`_
 
-This integration captures all `Console API` calls and redirects them to Sentry using the SDK's `captureMessage` or `captureException` call depending on the log level. It then retriggers to preserve default native behavior.
+This integration captures all `Console API` calls and redirects them to Sentry using the SDK's `captureMessage` or `captureException` call, depending on the log level. It then re-triggers to preserve default native behavior:
 
 <PlatformContent includePath="configuration/capture-console" />
 
 ### Debug
 
 _Import name: `Sentry.Integrations.Debug`_
 
-This integration allows you to inspect the content of the processed event, that will be passed to `beforeSend` and effectively send to the Sentry SDK. It will *always* run as the last integration, no matter when it was registered.
+This integration allows you to inspect the content of the processed event that will be passed to `beforeSend`, and effectively send it to the Sentry SDK. It will *always* run as the last integration, no matter when it was registered.
 
 Available options:
 
@@ -50,9 +54,9 @@ Available options:
 
 _Import name: `Sentry.Integrations.Offline`_
 
-This integration uses the web browser's [online and offline events](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/Online_and_offline_events) to detect when no network connectivity is available. If offline, it saves events to the web browser's client-side storage (typically IndexedDB) then automatically uploads events when network connectivity is restored.
+This integration uses the web browser's [online and offline events](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/Online_and_offline_events) to detect when no network connectivity is available. If offline, it saves events to the web browser's client-side storage (typically IndexedDB), then automatically uploads events when network connectivity is restored.
 
-This plugin does not attempt to provide local storage or retries for other scenarios. For example, if the browser has a local area connection but no internet connection, then it may report that it's online, and Sentry's `Offline` plugin will not attempt to save or retry any send failures in this case.
+This plugin does not attempt to provide local storage or retries for other scenarios. For example, if the browser has a local area connection but no internet connection, then it may report that it's online, and Sentry's `Offline` plugin will not attempt to save or retry any send failures in this case:
 
 <PlatformContent includePath="configuration/offline" />
 
@@ -64,7 +68,7 @@ _Import name: `Sentry.Integrations.RewriteFrames`_
 
 This integration allows you to apply a transformation to each frame of the stack trace. In the streamlined scenario, it can be used to change the name of the file frame it originates from, or it can be fed with an iterated function to apply any arbitrary transformation.
 
-On Windows machines, you have to use Unix paths and skip the volume letter in `root` option to enable. For example `C:\\Program Files\\Apache\\www` won’t work, however, `/Program Files/Apache/www` will.
+On Windows machines, you have to use Unix paths and skip the volume letter in the `root` option to enable it. For example, `C:\\Program Files\\Apache\\www` won’t work, however, `/Program Files/Apache/www` will.
 
 Available options: