@grafana/faro-instrumentation-replay

中文文档
2.14.0发布于 2026/11/10Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 23.2万

Faro instrumentation for session replay with rrweb

原始使用文档
文档目录8 节
  1. Installation
  2. Usage
  3. Configuration Options
  4. Privacy & Masking Options
  5. Recording Options
  6. Hooks
  7. Privacy and Security
  8. Example: Advanced Privacy Configuration

@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

KeyTypeDefaultDescription
sanitizeMetaHrefbooleantrueStrip 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
maskAllInputsbooleantrueMask all input content
maskInputOptionsMaskInputOptions{ password: true }Selectively mask specific input types (used only when maskAllInputs is false)
maskInputFn(value: string, element: HTMLElement) => stringFixed-length '******'Customize mask input content recording logic. The default returns a fixed-length mask regardless of input length to prevent length leakage
maskTextSelectorstring'*'CSS selector for elements whose text content should be masked
maskTextFn(text: string, element: HTMLElement | null) => stringundefinedTransform text matched by maskTextSelector or grafana-mask. When omitted, rrweb replaces non-whitespace characters with *
blockSelectorstringundefinedCSS selector for elements that should be blocked from recording. Blocked elements are replaced with a placeholder of the same dimensions
ignoreSelectorstringundefinedCSS selector for elements whose input events should be ignored

Built-in CSS classes

These classes work without configuration and remain active alongside custom selectors:

ClassBehavior
grafana-maskMasks text in the element and its descendants, not input values or attributes.
grafana-blockExcludes the subtree's content and replaces it with a layout placeholder.
grafana-ignoreSuppresses 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

KeyTypeDescription
passwordbooleanPassword inputs
textbooleanText inputs
emailbooleanEmail inputs
telbooleanTelephone inputs
numberbooleanNumber inputs
searchbooleanSearch inputs
urlbooleanURL inputs
datebooleanDate inputs
datetime-localbooleanDatetime-local inputs
monthbooleanMonth inputs
weekbooleanWeek inputs
timebooleanTime inputs
colorbooleanColor inputs
rangebooleanRange inputs
textareabooleanTextarea elements
selectbooleanSelect dropdowns

Recording Options

KeyTypeDefaultDescription
samplingRatenumber1Fraction 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
recordCrossOriginIframesbooleanfalseWhether to record cross-origin iframes. rrweb must be injected in each child iframe for this to work
collectFontsbooleanfalseWhether to collect fonts used in the website
inlineImagesbooleanfalseWhether to record image content
inlineStylesheetbooleanfalseWhether to inline stylesheets in the recording events
inactivityThresholdMsnumber60000Pause 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

KeyTypeDefaultDescription
beforeSend(event: eventWithTime) => eventWithTime | null | undefinedundefinedTransform 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:

  1. 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, and maskTextSelector
  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

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',
});

版本与发布记录

@grafana/faro-instrumentation-replay 共发布 26 个版本,首次发布于 2025/12/17;过去 12 个月发布了 26 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.14.0latest2026/11/107 天前
2.13.02026/10/2225 天前
2.12.12026/09/221 个月前
2.12.02026/09/181 个月前
2.11.02026/08/272 个月前
2.10.02026/08/182 个月前

关于 @grafana/faro-instrumentation-replay 的常见问题

@grafana/faro-instrumentation-replay 是什么?

Faro instrumentation for session replay with rrweb

如何安装 @grafana/faro-instrumentation-replay?

在项目目录运行 npm install @grafana/faro-instrumentation-replay,或使用 pnpm add / yarn add / bun add。

@grafana/faro-instrumentation-replay 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grafana/faro-instrumentation-replay 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@grafana/faro-instrumentation-replay 可以商用吗?

@grafana/faro-instrumentation-replay 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@grafana/faro-instrumentation-replay 的下载量有多少?

根据 npm 官方下载统计,@grafana/faro-instrumentation-replay 在 2026/10/17 – 2026/11/15 这 30 天内被下载 232,403 次,日均约 7,747 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grafana/faro-instrumentation-replay 还在维护吗?

最新版本 2.14.0 发布于 2026/11/10(7 天前);至今共发布 26 个版本,其中过去 12 个月发布了 26 个;首次发布于 2025/12/17。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。