@grafana/faro-instrumentation-replay
Faro instrumentation for session replay with rrweb.
Canvas 2D and WebGL content capture is not supported. Canvas elements can appear in the recorded DOM, but replaying their drawing content is not supported.
Installation
npm install @grafana/faro-instrumentation-replay
Usage
import { ReplayInstrumentation } from '@grafana/faro-instrumentation-replay';
import { getWebInstrumentations, initializeFaro } from '@grafana/faro-web-sdk';
initializeFaro({
url: 'https://your-faro-endpoint.com',
instrumentations: [
...getWebInstrumentations(),
new ReplayInstrumentation({
maskInputOptions: {
password: true,
email: true,
},
maskAllInputs: false,
recordAfter: 'load',
recordCrossOriginIframes: false,
}),
],
});
Configuration Options
Privacy & Masking Options
| Key | Type | Default | Description |
|---|---|---|---|
sanitizeMetaHref | boolean | true | Strip credentials, query string, and fragment from window.location.href in rrweb Meta events before sending. URLs may still appear in transport metadata and DOM snapshots |
maskAllInputs | boolean | true | Mask all input content |
maskInputOptions | MaskInputOptions | { password: true } | Selectively mask specific input types (used only when maskAllInputs is false) |
maskInputFn | (value: string, element: HTMLElement) => string | Fixed-length '******' | Customize mask input content recording logic. The default returns a fixed-length mask regardless of input length to prevent length leakage |
maskTextSelector | string | '*' | CSS selector for elements whose text content should be masked |
maskTextFn | (text: string, element: HTMLElement | null) => string | undefined | Transform text matched by maskTextSelector or grafana-mask. When omitted, rrweb replaces non-whitespace characters with * |
blockSelector | string | undefined | CSS selector for elements that should be blocked from recording. Blocked elements are replaced with a placeholder of the same dimensions |
ignoreSelector | string | undefined | CSS selector for elements whose input events should be ignored |
Built-in CSS classes
These classes work without configuration and remain active alongside custom selectors:
| Class | Behavior |
|---|---|
grafana-mask | Masks text in the element and its descendants, not input values or attributes. |
grafana-block | Excludes the subtree's content and replaces it with a layout placeholder. |
grafana-ignore | Suppresses input-change recording on the matching input, textarea, or select. |
<span class="grafana-mask">Jane Doe</span>
<div class="grafana-block">Sensitive content</div>
<input class="grafana-ignore" type="search" />
maskInputOptions
| Key | Type | Description |
|---|---|---|
password | boolean | Password inputs |
text | boolean | Text inputs |
email | boolean | Email inputs |
tel | boolean | Telephone inputs |
number | boolean | Number inputs |
search | boolean | Search inputs |
url | boolean | URL inputs |
date | boolean | Date inputs |
datetime-local | boolean | Datetime-local inputs |
month | boolean | Month inputs |
week | boolean | Week inputs |
time | boolean | Time inputs |
color | boolean | Color inputs |
range | boolean | Range inputs |
textarea | boolean | Textarea elements |
select | boolean | Select dropdowns |
Recording Options
| Key | Type | Default | Description |
|---|---|---|---|
samplingRate | number | 1 | Fraction of globally-sampled sessions that will be recorded. Applied on top of sessionTracking.samplingRate. Out-of-range values are clamped. |
recordAfter | 'load' | 'DOMContentLoaded' | 'load' | When to start recording if the document is not ready yet |
recordCrossOriginIframes | boolean | false | Whether to record cross-origin iframes. rrweb must be injected in each child iframe for this to work |
collectFonts | boolean | false | Whether to collect fonts used in the website |
inlineImages | boolean | false | Whether to record image content |
inlineStylesheet | boolean | false | Whether to inline stylesheets in the recording events |
inactivityThresholdMs | number | 60000 | Pause recording after this many milliseconds of inactivity; resumes automatically on the next interaction. Set to 0 to disable |
Once initialized, a ReplayInstrumentation instance can also be controlled
explicitly with pauseRecording() and resumeRecording(). Resuming starts a
new rrweb recording with a fresh DOM checkpoint. An explicitly paused recording
stays paused until resumeRecording() is called.
Sub-sampling example
initializeFaro({
url: 'https://your-faro-endpoint.com',
sessionTracking: {
samplingRate: 1.0, // collect telemetry (logs, errors, web-vitals) for all sessions
},
instrumentations: [
...getWebInstrumentations(),
new ReplayInstrumentation({
samplingRate: 0.1, // record replay for only 10% of sessions
}),
],
});
// Effective replay coverage: 1.0 × 0.1 = 10% of globally-sampled sessions
Hooks
| Key | Type | Default | Description |
|---|---|---|---|
beforeSend | (event: eventWithTime) => eventWithTime | null | undefined | undefined | Transform or filter events before they are sent. Return null or undefined to skip sending |
Privacy and Security
This instrumentation records user interactions on your website. Make sure to:
- Review masking options for your use case - By default, all input values and text content are masked.
If needed, you can make masking more selective with
maskAllInputs,maskInputOptions, andmaskTextSelector - Use CSS selectors - Use
maskTextSelectorto mask sensitive content,blockSelectorto completely exclude elements - Implement filtering - Use the
beforeSendhook to filter or transform events before sending - Review your privacy policy - Ensure you have proper user consent for session recording
- Test your configuration - Verify no sensitive information is captured in recordings
Example: Advanced Privacy Configuration
new ReplayInstrumentation({
// Disable global input masking and use selective masking rules instead
maskAllInputs: false,
// Mask all text and email inputs, but allow number inputs
maskInputOptions: {
password: true,
text: true,
email: true,
tel: true,
textarea: true,
},
// Mask elements with specific CSS classes
maskTextSelector: '.sensitive-data, .pii',
// Block elements completely from recording
blockSelector: '.payment-form, .credit-card-info',
// Ignore certain elements (won't be recorded at all)
ignoreSelector: '.analytics-widget',
});