feat(instrumentation-replay): add experimental replay support (#1417)

Author: Blinkuu

experimental/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Next
 
+- Added support for experimental `ReplayInstrumentation` (`@grafana/faro-instrumentation-replay`).
+
 ## 1.13.0
 
 - Improvement (`@grafana/faro-*`) Add required Node engines to package.json ()

experimental/instrumentation-replay/README.md

@@ -0,0 +1,107 @@
+# @grafana/faro-instrumentation-replay
+
+Faro instrumentation for session replay with rrweb.
+
+## Installation
+
+```bash
+npm install @grafana/faro-instrumentation-replay
+```
+
+## Usage
+
+```typescript
+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,
+      recordCrossOriginIframes: false,
+    }),
+  ],
+});
+```
+
+## Configuration Options
+
+### Privacy & Masking Options
+
+- **`maskAllInputs`** (default: `false`): Whether to mask all input elements
+- **`maskInputOptions`** (default: `{ password: true }`): Fine-grained control over which input types to mask.
+  Available options:
+  - `password` - Password inputs
+  - `text` - Text inputs
+  - `email` - Email inputs
+  - `tel` - Telephone inputs
+  - `number` - Number inputs
+  - `search` - Search inputs
+  - `url` - URL inputs
+  - `date`, `datetime-local`, `month`, `week`, `time` - Date/time inputs
+  - `color` - Color inputs
+  - `range` - Range inputs
+  - `textarea` - Textarea elements
+  - `select` - Select dropdowns
+- **`maskTextSelector`**: Custom CSS selector to mask specific elements
+- **`blockSelector`**: CSS selector to completely block elements from recording
+- **`ignoreSelector`**: CSS selector to ignore specific elements
+
+### Recording Options
+
+- **`recordCrossOriginIframes`** (default: `false`): Whether to record cross-origin iframes
+- **`recordCanvas`** (default: `false`): Whether to record canvas elements
+- **`collectFonts`** (default: `false`): Whether to collect font files
+- **`inlineImages`** (default: `false`): Whether to inline images in the recording
+- **`inlineStylesheet`** (default: `false`): Whether to inline stylesheets
+
+### Hooks
+
+- **`beforeSend`**: Custom function to transform or filter events before they are sent.
+  Return the modified event or `null`/`undefined` to skip sending
+
+## Privacy and Security
+
+This instrumentation records user interactions on your website. Make sure to:
+
+1. **Enable appropriate masking options** - By default, only password inputs are masked.
+   Configure `maskInputOptions` to mask additional sensitive fields
+2. **Use CSS selectors** - Use `maskTextSelector` to mask sensitive content, `blockSelector` to completely exclude elements
+3. **Implement filtering** - Use the `beforeSend` hook to filter or transform events before sending
+4. **Review your privacy policy** - Ensure you have proper user consent for session recording
+5. **Test your configuration** - Verify no sensitive information is captured in recordings
+
+### Example: Advanced Privacy Configuration
+
+```typescript
+new ReplayInstrumentation({
+  // 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',
+  // Filter or transform events before sending
+  beforeSend: (event) => {
+    // Example: Skip events that might contain sensitive data
+    if (event.type === 3 && event.data?.source === 'CanvasMutation') {
+      return null; // Skip this event
+    }
+    return event; // Send the event as-is
+  },
+});
+```

experimental/instrumentation-replay/jest.config.js

@@ -0,0 +1,7 @@
+const { jestBaseConfig } = require('../../jest.config.base.js');
+
+module.exports = {
+  ...jestBaseConfig,
+  roots: ['experimental/instrumentation-replay/src'],
+  testEnvironment: 'jsdom',
+};

experimental/instrumentation-replay/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@grafana/faro-instrumentation-replay",
+  "version": "2.0.2",
+  "description": "Faro instrumentation for session replay with rrweb",
+  "keywords": [
+    "observability",
+    "apm",
+    "rum",
+    "dem",
+    "session-replay",
+    "rrweb",
+    "browser"
+  ],
+  "license": "Apache-2.0",
+  "author": "Grafana Labs",
+  "homepage": "https://github.com/grafana/faro-web-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grafana/faro-web-sdk.git",
+    "directory": "experimental/instrumentation-replay"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "yarn watch",
+    "build": "run-s 'build:*'",
+    "build:compile": "run-p 'build:compile:*'",
+    "build:compile:cjs": "tsc --build tsconfig.cjs.json",
+    "build:compile:esm": "tsc --build tsconfig.esm.json",
+    "build:compile:bundle": "run-s 'build:compile:bundle:*'",
+    "build:compile:bundle:create": "rollup -c ./rollup.config.js",
+    "build:compile:bundle:remove-extras": "rimraf dist/bundle/dist",
+    "watch": "run-s watch:compile",
+    "watch:compile": "yarn build:compile:cjs -w",
+    "clean": "rimraf dist/ yarn-error.log",
+    "quality": "run-s 'quality:*'",
+    "quality:test": "jest",
+    "quality:format": "prettier --cache --cache-location=../../.cache/prettier/webSessionReplay --ignore-path ../../.prettierignore -w \"./**/*.{js,jsx,ts,tsx,css,scss,md,yaml,yml,json}\"",
+    "quality:lint": "run-s 'quality:lint:*'",
+    "quality:lint:eslint": "eslint --cache --cache-location ../../.cache/eslint/webSessionReplay \"./**/*.{js,jsx,ts,tsx}\"",
+    "quality:lint:prettier": "prettier --cache --cache-location=../../.cache/prettier/webSessionReplay --ignore-path ../../.prettierignore -c \"./**/*.{js,jsx,ts,tsx,css,scss,md,yaml,yml,json}\"",
+    "quality:lint:md": "markdownlint README.md",
+    "quality:circular-deps": "madge --circular ."
+  },
+  "dependencies": {
+    "@grafana/faro-core": "^2.0.2",
+    "rrweb": "^2.0.0-alpha.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

experimental/instrumentation-replay/rollup.config.js

@@ -0,0 +1,3 @@
+const { getRollupConfigBase } = require('../../rollup.config.base.js');
+
+module.exports = getRollupConfigBase('instrumentationReplay');

experimental/instrumentation-replay/src/const.ts

@@ -0,0 +1,17 @@
+import { type ReplayInstrumentationOptions } from './types';
+
+export const defaultReplayInstrumentationOptions: ReplayInstrumentationOptions = {
+  maskAllInputs: false,
+  maskInputOptions: {
+    password: true,
+  },
+  maskTextSelector: undefined,
+  blockSelector: undefined,
+  ignoreSelector: undefined,
+  collectFonts: false,
+  inlineImages: false,
+  inlineStylesheet: false,
+  recordCanvas: false,
+  recordCrossOriginIframes: false,
+  beforeSend: undefined,
+};

experimental/instrumentation-replay/src/index.ts

@@ -0,0 +1,2 @@
+export { ReplayInstrumentation } from './instrumentation';
+export type { ReplayInstrumentationOptions, MaskInputOptions } from './types';