# Set Up Session Replay | Sentry for SolidStart

If you have any questions, feedback or would like to report a bug, please open a [GitHub issue](https://github.com/getsentry/sentry/issues/new.md?assignees=\&labels=\&template=bug.yml) with a link to a relevant replay or, if possible, a publicly accessible URL to the page you're attempting to record a replay of.

[Session Replay](https://docs.sentry.io/product/explore/session-replay.md) 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. You can rewind and replay your application's DOM state and see key user interactions, like mouse clicks, scrolls, network requests, and console entries, in a single combined UI inspired by your browser's DevTools.

By default, our Session Replay SDK masks all DOM text content, images, and user input, giving you heightened confidence that no sensitive data will leave the browser. To learn more, see [Session Replay Privacy](https://docs.sentry.io/platforms/javascript/guides/solidstart/session-replay/privacy.md).

## [Pre-requisites](https://docs.sentry.io/.md#pre-requisites)

For the sentry-replay integration to work, you must have the [Sentry browser SDK package](https://www.npmjs.com/package/@sentry/browser.md), or an equivalent framework SDK (for example, [@sentry/react](https://www.npmjs.com/package/@sentry/react.md)) installed. The minimum version required for the SDK is `7.27.0`. If you're on an older version of the SDK, please check the [migration document](https://github.com/getsentry/sentry-javascript/blob/master/MIGRATION.md).

Session Replay requires Node 12+, and browsers newer than IE11.

## [Install](https://docs.sentry.io/.md#install)

The Replay integration is **already included** in your browser or framework SDK NPM packages. If you're using CDN bundles instead of NPM packages, you need to load the Replay integration CDN bundle in addition to your browser bundle:

```bash
npm install @sentry/browser --save
```

## [Set Up](https://docs.sentry.io/.md#set-up)

To set up the integration, add the following to your Sentry initialization. There are several options you can pass to the integration constructor. See the [configuration documentation](https://docs.sentry.io/platforms/javascript/session-replay/configuration.md) for more details.

```javascript
// import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // 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,



  integrations: [
    Sentry.replayIntegration({
      // Additional SDK configuration goes in here, for example:
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

});
```

### [Verify](https://docs.sentry.io/.md#verify)

While you're testing, we recommend that you set `replaysSessionSampleRate` to `1.0`. This ensures that every user session will be sent to Sentry.

Once testing is complete, **we recommend lowering this value in production**. We still recommend keeping `replaysOnErrorSampleRate` set to `1.0`, so that, whenever possible, every error has an associated replay with additional debugging context.

### [PII & Privacy Considerations](https://docs.sentry.io/.md#pii--privacy-considerations)

Personally identifiable information (PII), and privacy are important considerations when enabling Session Replay. There are multiple ways in which Sentry helps you avoid collecting PII, including:

* [Masking](https://docs.sentry.io/platforms/javascript/session-replay/privacy.md#masking), which replaces the text content with something else. (The default behavior being to replace each character with a \*.)
* Making [Network request, response bodies, and headers](https://docs.sentry.io/platforms/javascript/session-replay/privacy.md#network-request-and-response-bodies-and-headers) an opt-in feature, because the best way to avoid getting PII into Sentry is by not adding URLs of endpoints that may contain PII.

While we have certain privacy considerations in place, Sentry's Session Replay allows you to set up the [privacy configurations](https://docs.sentry.io/platforms/javascript/session-replay/privacy.md#privacy-configuration) that work best for your use case. For example, if you're working on a static website that's free of PII or other types of private data, you can opt out of the default text masking and image blocking settings. To learn more about Session Replay privacy, [read our docs.](https://docs.sentry.io/platforms/javascript/session-replay/privacy.md)

### [Lazy-loading Replay](https://docs.sentry.io/.md#lazy-loading-replay)

Once you've added the integration, Replay will start automatically. If you don't want to start it immediately (lazy-load it), you can use `addIntegration`:

```javascript
Sentry.init({
  // Note, Replay is NOT instantiated below:
  integrations: [],
});

// Sometime later
import("@sentry/browser").then((lazyLoadedSentry) => {
  Sentry.addIntegration(lazyLoadedSentry.replayIntegration());
});
```

### [Canvas Recording](https://docs.sentry.io/.md#canvas-recording)

There is currently no PII scrubbing in canvas recordings!

If you want to record HTML canvas elements, you'll need to add an additional integration in your Sentry configuration. The canvas integration is exported from the browser SDK, so no additional package is required. Canvas recording is opt-in and will be tree-shaken from your bundle if it's not being used:

```javascript
// import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  integrations: [
    // Keep the Replay integration as before
    Sentry.replayIntegration(),

    // The following is all you need to enable canvas recording with Replay

    Sentry.replayCanvasIntegration(),

  ],
});
```

#### [3D and WebGL Canvases](https://docs.sentry.io/.md#3d-and-webgl-canvases)

The canvas recording integration works by exporting the canvas as an image (at a rate of 2 frames per second). However, in order to export images from 3D and WebGL canvases, the integration needs to enable `preserveDrawingBuffer` which can negatively affect canvas performance. If your canvas application is impacted by enabling `preserveDrawingBuffer`, you'll need to enable manual snapshotting and call a `snapshot()` method inside of your re-paint loop. There are two steps to using manual snapshotting:

**Step 1.** Enable manual snapshotting when initializing the `ReplayCanvas` integration.

```javascript
Sentry.replayCanvasIntegration({
  // Enabling the following will ensure your canvas elements are not forced
  // into `preserveDrawingBuffer`.
  enableManualSnapshot: true,
});
```

**Step 2** Call the following `snapshot()` method inside your application's paint loop. `snapshot()` needs to be called in the same execution loop as the canvas draw commands, otherwise you may be snapshotting empty canvas buffers. This is due to how WebGL works when `preserveDrawingBuffer` is `false`.

```javascript
function paint() {
  const canvasRef = document.querySelector("#my-canvas");
  Sentry.getClient()
    .getIntegrationByName("ReplayCanvas")
    .snapshot(canvasRef);
}
```

### [Content Security Policy (CSP)](https://docs.sentry.io/.md#content-security-policy-csp)

Session Replay uses a WebWorker to perform work (for example, compression) off the main UI thread so as not to degrade the performance of your application. Add the below entry to make sure that workers can be loaded:

```bash
worker-src 'self' blob:
```

[Safari versions <= 15.4](https://caniuse.com/.md?search=worker-src) do not support `worker-src`, you will need to additionally add an entry for `child-src`:

```bash
child-src 'self' blob:
```

If you're unable to update your CSP policy to allow inline web workers, you can also [use a custom compression worker](https://docs.sentry.io/configuration.md#using-a-custom-compression-worker) instead.

## [User Session](https://docs.sentry.io/.md#user-session)

A user session starts when the Session Replay SDK is first loaded and initialized. The session will capture any pageloads, refreshes, or navigations as long as the SDK is re-initialized on the same domain, and in the same browser tab, each time. Sessions continue capturing data until 5 minutes pass without any user interactions **or** until a maximum of 60 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.md).

An *interaction* refers to either a mouse click or a browser navigation event.

### [Replay Captures on Errors Only](https://docs.sentry.io/.md#replay-captures-on-errors-only)

If you prefer not to record an entire session, you can elect to capture a replay only if 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](https://docs.sentry.io/.md#sampling) section for configuration options.

## [Sampling](https://docs.sentry.io/.md#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 relevant to you:

1. `replaysSessionSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
2. `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.

Sampling begins as soon as a session starts. `replaysSessionSampleRate` is evaluated first. If it's sampled, the replay recording will begin. Otherwise, `replaysOnErrorSampleRate` is evaluated and if it's sampled, the integration will begin buffering the replay and will only upload it to Sentry if an error occurs. The remainder of the replay will behave similarly to a whole-session replay.

## [Error Linking](https://docs.sentry.io/.md#error-linking)

Errors that happen on the page while a replay is running will be linked to the replay, making it possible to jump between related issues and replays. However, it's **possible** that in some cases the error count reported on the **Replays Details** page won't match the actual errors that have been captured. That's because errors can be lost, and while this is uncommon, there are a few reasons why it could happen:

* The replay was rate-limited and couldn't be accepted.
* The replay was deleted by a member of your org.
* There were network errors and the replay wasn't saved.

## [Verify](https://docs.sentry.io/.md#verify)

While you're testing, we recommend that you set `replaysSessionSampleRate` to `1.0`. This ensures that every user session will be sent to Sentry.

Once testing is complete, **we recommend lowering this value in production**. We still recommend keeping `replaysOnErrorSampleRate` set to `1.0`.

## [Next Steps](https://docs.sentry.io/.md#next-steps)

* #### [Configuration](https://docs.sentry.io/platforms/javascript/guides/solidstart/session-replay/configuration.md)

  Learn about the general Session Replay configuration fields.

* #### [Privacy](https://docs.sentry.io/platforms/javascript/guides/solidstart/session-replay/privacy.md)

  Configuring Session Replay to maintain user and data privacy.

* #### [Replay Issues](https://docs.sentry.io/platforms/javascript/guides/solidstart/session-replay/issue-types.md)

  Learn about the Issue types that Session Replay can detect.

* #### [Understanding Sessions](https://docs.sentry.io/platforms/javascript/guides/solidstart/session-replay/understanding-sessions.md)

  Learn about customizing sessions with the Session Replay SDK.

* #### [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/solidstart/session-replay/troubleshooting.md)

  Troubleshooting Session Replay-specific Issues
