Documentation Grafana Cloud Observe and act Monitor applications Session Replay Troubleshoot

Troubleshoot

This page covers common Session Replay issues and how to fix them.

My Session Replay appears corrupted

Applications built with React, or with a framework that uses React under the hood such as Next.js, can initialize Faro more than once as components render. This can corrupt recordings.

To prevent this, initialize Faro only once by using the provider pattern.

1. Create a provider that initializes Faro a single time:

   tsx Copy

   // provider.tsx
   'use client';
   
   import { getWebInstrumentations, initializeFaro } from '@grafana/faro-web-sdk';
   import { ReplayInstrumentation } from '@grafana/faro-instrumentation-replay';
   import { useEffect, useRef } from 'react';
   
   function FaroProvider({ children }: { children: React.ReactNode }) {
     const initializeOnce = useRef(false);
   
     useEffect(() => {
       if (!process.env.NEXT_PUBLIC_FARO_COLLECTOR_URL || initializeOnce.current) {
         return;
       }
   
       initializeOnce.current = true;
   
       initializeFaro({
         url: process.env.NEXT_PUBLIC_FARO_COLLECTOR_URL,
         app: {
           name: 'my-app',
           version: '1.0.0',
         },
         instrumentations: [...getWebInstrumentations(), new ReplayInstrumentation()],
       });
     }, []);
   
     return <>{children}</>;
   }
   
   export default FaroProvider;

2. Load the provider dynamically so that it only runs in the browser:

   tsx Copy

   // providerDynamic.tsx
   import dynamic from 'next/dynamic';
   import { Fragment } from 'react';
   
   const initFaroProvider = () => {
     if (!process.env.NEXT_PUBLIC_FARO_COLLECTOR_URL) {
       return Fragment;
     }
   
     return dynamic(() => import('./provider'));
   };
   
   const DynamicFaroProvider = initFaroProvider();
   export default DynamicFaroProvider;

3. Wrap your application with the provider:

   tsx Copy

   // app-providers.tsx
   import DynamicFaroProvider from './providerDynamic';
   
   export default function AppProviders({ children }: { children: React.ReactNode }) {
     return <DynamicFaroProvider>{children}</DynamicFaroProvider>;
   }

If recordings still don’t load correctly, verify that Session Replay is instrumented and sending data:

1. Check that Session Replay is instrumented:
   1. Load a page that should be instrumented with Session Replay.
   2. In the browser console, run window.faro.instrumentations.instrumentations.map(i => i.name) and confirm @grafana/faro-instrumentation-replay is in the returned list.
2. Check that Session Replay is sending events to the collector:
   1. Inspect the network requests to the collector and confirm the payload contains Session Replay events.

My recording is missing or incomplete

If a recording doesn’t appear on the Sessions page, or parts of it are missing or don’t play back correctly, check the following:

1. Wait up to five minutes.

   After a session is recorded, it can take up to five minutes for the recording to appear on the Sessions page in Frontend Observability. For an ongoing session, new portions of the recording also appear in intervals of up to five minutes.

2. Check that the recording data is within the collector size limits.

   The Grafana Cloud collector drops recording data that exceeds its size limits, and that part of the recording is lost:

   • Requests larger than 10 MiB are rejected with an HTTP 413 status. In your browser’s developer tools, look for failed requests to the collector URL.
   • On stacks hosted on Azure, a single recording event larger than 1 MB (1,000,000 bytes) is also dropped. The request still succeeds, so no error appears in the browser. Grafana Labs is working on raising this limit. To find out where your stack is hosted, refer to Regional availability.

3. Reduce the size of the recording data.

   Large recording data usually comes from capturing a lot of content at once, for example a very large DOM or embedded image data. To reduce it:

   • Set inlineImages to false, which is the default. Inlining images stores the image content in the recording.
   • Keep collectFonts and inlineStylesheet set to false unless you need them.
   • Use blockSelector to exclude large or complex parts of the page from the recording.

   For the full list of options, refer to Configuration options.

My session recording is missing user information

To associate user information with a recorded session, set the user metadata through the Faro Web SDK. Refer to how to use the user meta.

I need to prevent personally identifiable information (PII) from being recorded

Session Replay masks all input values and text content by default, client-side, before any data leaves the browser. To customize what’s masked, blocked, or ignored, configure the privacy and masking options. Refer to Data masking and Data privacy in Session Replay for details.