feat: extend guides in docs and add simpler way to enable Replay (#559)

Author: rchl

docs/content/en/sentry/options.md renamed to docs/content/en/configuration/options.md

@@ -1,16 +1,16 @@
 ---
 title: Options
 description: 'Options can be passed to Sentry using either environment variables'
-position: 4
-category: Sentry
+position: 15
+category: Configuration
 ---
 
 Options can be passed using either:
  - environment variables
  - `sentry` object in `nuxt.config.js`
  - when registering the module: `modules: [['@nuxtjs/sentry', {/*options*/}]]`
 
-The `config`, `serverConfig` and `clientConfig` options can also be configured using [Runtime Config](/sentry/runtime-config).
+The `config`, `serverConfig` and `clientConfig` options can also be configured using [Runtime Config](/configuration/runtime-config).
 
 The `dsn` is the only option that is required to enable Sentry reporting.
 
@@ -123,13 +123,13 @@ The `dsn` is the only option that is required to enable Sentry reporting.
 - Default: `sentry`
 - Specified object in Nuxt config in `publicRuntimeConfig[runtimeConfigKey]` will override some options at runtime. See documentation at https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-runtime-config/
 - Used to define the environment at runtime for example
-- See also [Runtime Config](/sentry/runtime-config) documentation.
+- See also [Runtime Config](/configuration/runtime-config) documentation.
 
 ### disabled
 
 - Type: `Boolean`
 - Default: `process.env.SENTRY_DISABLED || false`
-- Sentry will not be initialised if set to `true`.
+- Sentry will not be initialized if set to `true`.
 
 ### disableClientSide
 
@@ -207,22 +207,22 @@ Note that the module sets the following defaults when publishing is enabled:
 
 - Type: `String`
 - Default: `source-map`
-- Only has effect when `publishRelease = true`
+- Only has effect when `publishRelease` is enabled
 - The type of source maps generated when publishing release to Sentry. See https://webpack.js.org/configuration/devtool for a list of available options
 - **Note**: Consider using `hidden-source-map` instead. For most people, that should be a better option but due to it being a breaking change, it won't be set as the default until next major release
 
 ### disableServerRelease
 
 - Type: `Boolean`
 - Default: `process.env.SENTRY_DISABLE_SERVER_RELEASE || false`
-- Only has effect when `publishRelease = true`
+- Only has effect when `publishRelease` is enabled
 - See https://docs.sentry.io/workflow/releases for more information
 
 ### disableClientRelease
 
 - Type: `Boolean`
 - Default: `process.env.SENTRY_DISABLE_CLIENT_RELEASE || false`
-- Only has effect when `publishRelease = true`
+- Only has effect when `publishRelease` is enabled
 - See https://docs.sentry.io/workflow/releases for more information
 
 ### clientIntegrations
@@ -238,9 +238,9 @@ Note that the module sets the following defaults when publishing is enabled:
   ```
 - Sentry by default also enables the following browser integrations: `Breadcrumbs`, `Dedupe`, `FunctionToString`, `GlobalHandlers`, `HttpContext`, `InboundFilters`, `LinkedErrors`, `TryCatch`.
 - When `tracing` option is enabled then the [Vue Router Instrumentation](https://docs.sentry.io/platforms/javascript/guides/vue/configuration/integrations/vue-router/) is also enabled.
-- The full list of client integrations that are supported: `Breadcrumbs`, `CaptureConsole`, `Debug`, `Dedupe`, `ExtraErrorData`, `FunctionToString`, `GlobalHandlers`, `HttpClient`, `HttpContext`, `InboundFilters`, `LinkedErrors`, `ReportingObserver`, `RewriteFrames`, `TryCatch`.
+- The full list of client integrations that are supported: `Breadcrumbs`, `CaptureConsole`, `Debug`, `Dedupe`, `ExtraErrorData`, `FunctionToString`, `GlobalHandlers`, `HttpClient`, `HttpContext`, `InboundFilters`, `LinkedErrors`, `Reply`, `ReportingObserver`, `RewriteFrames`, `TryCatch`.
 - Integration options can be specified in the object value corresponding to the individual integration key.
-- To disable integration that is enabled by default, pass `false` as a value. For example to disable `ExtraErrorData` integration (only), set the option to:
+- To disable integration that is enabled by default, pass `false` as a value. For example to disable `ExtraErrorData` integration (only) set the option to:
   ```js
   {
     ExtraErrorData: false,
@@ -265,7 +265,7 @@ Note that the module sets the following defaults when publishing is enabled:
 - Sentry by default enables the following server integrations: `Console`, `ContextLines`, `Context`, `FunctionToString`, `Http`,  `InboundFilters`, `LinkedErrors`, `Modules`,`OnUncaughtException`, `OnUnhandledRejection`, `RequestData`.
 - The full list of server integrations that are supported includes the ones above plus: `CaptureConsole`, `Debug`, `Dedupe`, `ExtraErrorData`, `RewriteFrames`, `Transaction`.
 - Integration options can be specified in the object value corresponding to the individual integration key.
-- To disable integration that is enabled by default, pass `false` as a value. For example to disable `ExtraErrorData` integration (only), set the option to:
+- To disable integration that is enabled by default, pass `false` as a value. For example to disable `ExtraErrorData` integration (only) set the option to:
   ```js
   {
     Dedupe: {},
@@ -313,7 +313,7 @@ export default function () {
 - Type: `Boolean` or `Object`
 - Default: `false`
 
-- Enables Sentry Performance Monitoring on the [server](https://docs.sentry.io/platforms/node/performance/) and [browser](https://docs.sentry.io/platforms/javascript/guides/vue/performance/) side.
+- Enables Sentry Performance Monitoring on the [server](https://docs.sentry.io/platforms/node/guides/express/performance/) and [browser](https://docs.sentry.io/platforms/javascript/guides/vue/performance/) side.
 - Takes the following object configuration format (default values shown):
   ```js
   {
@@ -326,6 +326,8 @@ export default function () {
   ```
 - On the browser side the `BrowserTracing` integration is enabled by default and adds automatic instrumentation for monitoring the performance of the application. The [Vue Router Integration](https://docs.sentry.io/platforms/javascript/guides/vue/configuration/integrations/vue-router/) is also automatically enabled. See all available [`BrowserTracing` options](https://docs.sentry.io/platforms/javascript/guides/vue/performance/instrumentation/automatic-instrumentation/).
 - On the browser side extra options for [Tracking Vue components](https://docs.sentry.io/platforms/javascript/guides/vue/features/component-tracking/) can be passed through the `vueOptions` object.
+- On the server side the `Http` integration is enabled to trace HTTP requests and [tracingHandler](https://docs.sentry.io/platforms/node/guides/express/performance/) is enabled to trace `connect` and `express` routes.
+- See also the [Performance Monitoring](/guide/performance) section for more information.
 
 <alert type="info">
 
@@ -377,27 +379,8 @@ export default function () {
 - Default: `{}`
 - Sentry SDK [Basic Browser Options](https://docs.sentry.io/platforms/javascript/guides/vue/configuration/options/).
 - The specified keys will override common options set in the `config` key.
-- The value can be a string in which case it needs to be a file path (can use [webpack aliases](https://nuxtjs.org/docs/2.x/directory-structure/assets#aliases)) pointing to a javascript file whose default export (a function) returns the configuration object. This is necessary in case some of the options rely on imported values or can't be serialized. The function is passed a `Nuxt Context` argument and can be `async`. Example of how to enable [User Feedback](https://docs.sentry.io/platforms/javascript/enriching-events/user-feedback/) dialog:
-  ```js [nuxt.config.js]
-  sentry: {
-    dsn: '...',
-    clientConfig: '~/config/sentry-client-config.js',
-  }
-  ```
-  ```js [~/config/sentry-client-config.js]
-  import { showReportDialog } from '@sentry/vue'
-
-  export default function(context) {
-    return {
-      beforeSend (event, hint) {
-        if (event.exception) {
-          showReportDialog({ eventId: event.event_id })
-        }
-        return event
-      },
-    }
-  }
-  ```
+- The value can be a string in which case it needs to be a file path (can use [webpack aliases](https://nuxtjs.org/docs/2.x/directory-structure/assets#aliases)) pointing to a javascript file whose default export (a function) returns the configuration object. This is necessary in case some of the options rely on imported values or can't be serialized. The function is passed a `Nuxt Context` argument and can be `async`.
+- See an example usage on the [User Feedback](/guide/user-feedback) page.
 
 ### requestHandlerConfig
 

docs/content/en/sentry/runtime-config.md renamed to docs/content/en/configuration/runtime-config.md

@@ -1,13 +1,13 @@
 ---
 title: Runtime config
 description: "Load Sentry configuration at runtime"
-position: 5
-category: Sentry
+position: 16
+category: Configuration
 ---
 
 Defining options using the [Nuxt Runtime Config](https://nuxtjs.org/docs/2.x/configuration-glossary/configuration-runtime-config/) functionality allows them to be runtime-based rather than build-time based, as is the case by default.
 
-Currently only the `config`, `clientConfig` and `serverConfig` [options](/sentry/options) can be configured using the runtime config.
+Currently, only the `config`, `clientConfig` and `serverConfig` [options](/configuration/options) can be configured using the runtime config.
 
 In the Nuxt configuration file define a `publicRuntimeConfig.sentry` configuration object with settings that will be applied at runtime. For example:
 
@@ -27,6 +27,6 @@ publicRuntimeConfig: {
 }
 ```
 
-You can customize the key that is used to access settings from `publicRuntimeConfig` by setting [`runtimeConfigKey`](/sentry/options#runtimeconfigkey) in the non-runtime options.
+You can customize the key that is used to access settings from `publicRuntimeConfig` by setting [`runtimeConfigKey`](/configuration/options#runtimeconfigkey) in the non-runtime options.
 
 This functionality is supported from Nuxt 2.13 and up.

docs/content/en/guide/setup.md renamed to docs/content/en/getting-started/setup.md

@@ -1,13 +1,13 @@
 ---
 title: Setup
 description: 'Setup the sentry module into Nuxt'
-position: 2
-category: Guide
+position: 10
+category: Getting Started
 ---
 
 Check the [Nuxt.js documentation](https://nuxtjs.org/guides/configuration-glossary/configuration-modules) for more information about installing and using modules in Nuxt.js.
 
-> Nuxt.js v2.4.0+ is required, earlier versions are not supported
+> Nuxt.js v2.16.0+ is required, earlier versions are not supported.
 
 ## Installation
 
@@ -44,7 +44,7 @@ Then, add `@nuxtjs/sentry` to the `modules` section of `nuxt.config.js` and set
 }
 ```
 
-See [Options](/sentry/options) for a list of available options.
+See [Options](/configuration/options) for a list of available options.
 
 Note that the Sentry SDK dependencies (`@sentry/*`) are not pinned and can be updated independently from the module itself by running `npm upgrade @nuxtjs/sentry` or `yarn upgrade @nuxtjs/sentry`. That means you don't have to wait for a new module release if you want to update to the latest SDK version.
 
@@ -67,6 +67,6 @@ In Typescript or type-checked JavaScript projects, add `@nuxtjs/sentry` to the `
 
   The otherwise optional package `@sentry/webpack-plugin` has to be installed for types to be fully working.
 
-  If not using the relevant functionality (`tracing` and `publishRelease` options are not enabled) then those packages can be installed as dev-only dependencies.
+  If not using the relevant functionality (`publishRelease` option is not enabled) then this package can be installed as dev-only dependency.
 
 </alert>

docs/content/en/guide/enrich-events.md

@@ -0,0 +1,16 @@
+---
+title: Enriching Events
+description: Enriching Reported Events
+position: 21
+category: Guide
+---
+
+Sentry SDK provides API for enhancing events that are being reported. For example, you can:
+  - set user information like IP address or username using `Sentry.setUser` API
+  - add custom structured data using `Sentry.setContext` API
+  - set custom key/value pairs (tags) that get indexed and can be used for filtering and searching using `Sentry.setTag` API
+  - add file attachments using `scope.addAttachment` API
+  - manually add breadcrumbs using `Sentry.addBreadcrumb` API
+  - and other...
+
+Read more about [Enriching Events](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/).

docs/content/en/sentry/lazy-loading.md renamed to docs/content/en/guide/lazy-loading.md

@@ -1,13 +1,13 @@
 ---
 title: Lazy-Loading (client-side)
-description: 'Load Sentry module lazily on the client'
-position: 6
-category: Sentry
+description: Load Sentry module lazily on the client
+position: 22
+category: Guide
 ---
 
 Set `lazy: true` in your module options to load Sentry lazily on the client. This will prevent Sentry from being included in your main bundle and should result in a faster initial page load.
 
-You can also pass a lazy config object in your module options (see [options](/sentry/options#lazy) for more information).
+You can also pass a lazy config object in your module options (see [options](/configuration/options#lazy) for more information).
 
 <alert type="info">
 
@@ -22,7 +22,7 @@ You can also pass a lazy config object in your module options (see [options](/se
 
 Normally `$sentry` would always refer to the `@sentry/vue` API. But if we lazy load Sentry this API wont be available until Sentry has loaded. If you don't want to worry about whether Sentry is loaded or not, a mocked Sentry API is injected into the Nuxt.js context that will execute all Sentry API calls once Sentry is loaded
 
-See: [`injectMock`](/sentry/options#lazy) and [`mockApiMethods`](/sentry/options#lazy) options.
+See: [`injectMock`](/configuration/options#lazy) and [`mockApiMethods`](/configuration/options#lazy) options.
 
 #### `$sentryReady`
 - Type `Function`

docs/content/en/guide/migration.md

@@ -1,7 +1,7 @@
 ---
 title: Migration guide
 description: Follow this guide to upgrade from one major version to the other.
-position: 10
+position: 29
 category: Guide
 ---
 

docs/content/en/guide/performance.md

@@ -0,0 +1,20 @@
+---
+title: Performance Monitoring
+description: Track performance metrics
+position: 23
+category: Guide
+---
+
+To automatically configure and enable performance monitoring, enable the [tracing](/configuration/options#tracing) option.
+
+This enables various additional integrations for monitoring and instrumentation. On the client-side it enables [`BrowserTracing`](https://docs.sentry.io/platforms/javascript/guides/vue/performance/instrumentation/automatic-instrumentation/) and [`Vue Router Instrumentation`](https://docs.sentry.io/platforms/javascript/guides/vue/configuration/integrations/vue-router/) integrations. On the server-side it enables the [`Http` and `tracingHandler`](https://docs.sentry.io/platforms/node/guides/express/performance/instrumentation/automatic-instrumentation/) integrations for tracing HTTP requests and `connect`/`express` routes.
+
+See the description of the [tracing](/configuration/options#tracing) option if you want to customize some aspect of that functionality like the percentage of requests to capture.
+
+<alert type="info">
+
+  Note that the `tracesSampleRate` value can be between 0.0 and 1.0 (percentage of requests to capture) and Sentry documentation strongly recommends reducing the value from the default 1.0.
+
+</alert>
+
+See also Sentry's SDK [client](https://docs.sentry.io/platforms/javascript/guides/vue/performance/) and [server](https://docs.sentry.io/platforms/node/guides/express/performance/) Performance Monitoring pages for additional information about those integrations.

docs/content/en/guide/session-replay.md

@@ -0,0 +1,47 @@
+---
+title: Session Replay
+description: Record and replay user interactions that lead to an error
+position: 24
+category: Guide
+---
+
+Session Replay helps you get to the root cause of an error or latency issue faster by providing you with a video-like reproduction of what was happening in the user's browser before, during, and after the issue.
+
+### Setup
+
+Session Replay comes as a separate integration that is not enabled by default. To enable it, add `Replay: {}` to the [`clientIntegrations`](/configuration/options#clientintegrations) option like so:
+
+```js [nuxt.config.js]
+sentry: {
+  dsn: '...',
+  clientIntegrations: [
+    Reply: {},
+  ],
+  clientConfig: {
+    // This sets the sample rate to be 10%. You may want this to be 100% while
+    // in development and sample at a lower rate in production
+    replaysSessionSampleRate: 0.1,
+    // If the entire session is not sampled, use the below sample rate to sample
+    // sessions when an error occurs.
+    replaysOnErrorSampleRate: 1.0,
+  }
+}
+```
+
+You can customize integration options by passing them within the `{}` object.
+
+<alert type="info">
+
+  Note that the `replaysSessionSampleRate` and `replaysOnErrorSampleRate` options are part of the global client options and not options of the `Replay` integration itself.
+
+</alert>
+
+<alert type="info">
+
+  Refer to the Sentry documentation below to make sure that Content Security Policy (CSP) is configured properly for allowing `Replay` integration to do its work.
+
+</alert>
+
+### Documentation
+
+See Sentry's [Session Replay](https://docs.sentry.io/platforms/javascript/guides/vue/session-replay/) pages for additional information.

docs/content/en/guide/usage.md

@@ -1,26 +1,14 @@
 ---
 title: Usage / API
-description: 'Usage of Sentry in Nuxt'
-position: 3
+description: Usage of Sentry in Nuxt
+position: 20
 category: Guide
 ---
 
 ### Automatic Capturing
 
 Once enabled, Sentry automatically reports errors, uncaught exceptions and unhandled rejections. No need for further steps, unless you like to report (certain) exceptions manually or have deactivated integrations like `GlobalError`. In this case, find out below how to send reports manually.
 
-### Enriching Reported Events
-
-Sentry SDK provides API for enhancing events that are being reported. For example, you can:
-  - set user information like IP address or username using `Sentry.setUser` API
-  - add custom structured data using `Sentry.setContext` API
-  - set custom key/value pairs (tags) that get indexed and can be used for filtering and searching using `Sentry.setTag` API
-  - add file attachments using `scope.addAttachment` API
-  - manually add breadcrumbs using `Sentry.addBreadcrumb` API
-  - and other...
-
-Read more about [Enriching Events](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/).
-
 ### Usage in Vue components
 
 In a Vue component, `Sentry` is available as `this.$sentry`, so we can call functions like

docs/content/en/guide/user-feedback.md

@@ -0,0 +1,44 @@
+---
+title: User Feedback
+description: A feedback dialog for providing additional user information
+position: 25
+category: Guide
+---
+
+When a user experiences an error, Sentry provides the ability to collect additional feedback through a feedback dialog.
+
+### Setup
+
+`showReportDialog` is a function that should be called to trigger the User Feedback dialog. Due to how Nuxt works, we can't reference it directly from within Nuxt config as Sentry configuration is strinigified and the function reference does not survive that. We have to use the `clientConfig` option with a path to a custom client configuration that imports the function like so:
+
+```js [nuxt.config.js]
+sentry: {
+  dsn: '...',
+  clientConfig: '~/config/sentry-client-config.js',
+}
+```
+
+```js [~/config/sentry-client-config.js]
+import { showReportDialog } from '@sentry/vue'
+
+export default function(context) {
+  return {
+    beforeSend (event, hint) {
+      if (event.exception) {
+        showReportDialog({ eventId: event.event_id })
+      }
+      return event
+    },
+  }
+}
+```
+
+<alert type="info">
+
+  The configuration provided through `clientConfig` is merged with the configuration provided in the Nuxt config so other configuration options can (but don't have to) be defined in Nuxt config.
+
+</alert>
+
+### Documentation
+
+See Sentry's [User Feedback](https://docs.sentry.io/platforms/javascript/guides/vue/enriching-events/user-feedback/) pages for additional information.