@grafana/faro-instrumentation-replay

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

用 rrweb 重放会话的法罗仪器

中文使用文档
文档目录8 节
  1. 安装
  2. 使用量
  3. 配置选项
  4. 隐私和遮盖选项
  5. 记录选项
  6. 钩子
  7. 隐私和安全
  8. 示例:高级隐私配置

@grafana/faro-instrumentation-replay (英语)

用 rrweb 重放会话的法罗仪表 .

不支持 Canvas 2D 和 WebGL 内容抓取 。 Canvas 元素可以出现在 记录的 DOM ,但不支持重放其绘图内容.

安装

npm install @grafana/faro-instrumentation-replay

使用量

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

配置选项

隐私和遮盖选项

密钥类型默认说明
sanitizeMetaHrefbooleantrue脱去证书、查询字符串和碎片 window.location.href 在 rrweb Meta 事件之前发送。 URL仍然可能在传输元数据和 DOM 快照中出现
maskAllInputsbooleantrue覆盖所有输入内容
maskInputOptionsMaskInputOptions{ password: true }选择性地遮盖特定输入类型(仅在 maskAllInputs 实值 false(中文(简体) )
maskInputFn(value: string, element: HTMLElement) => string固定长度 '******'自定义口罩输入内容记录逻辑 。 默认返回一个固定长口罩,而不论输入长度,以防止长度泄漏
maskTextSelectorstring'*'CSS 文本内容应当被遮蔽的元素选择器
maskTextFn(text: string, element: HTMLElement | null) => stringundefined转换文本与匹配 maskTextSelector 或者说 grafana-mask。省略时,rrweb将非空白字符替换为 *
blockSelectorstringundefinedCSS选取器,用于应被屏蔽无法录入的元素. 被屏蔽的元素被相同尺寸的占位符所取代
ignoreSelectorstringundefined输入事件应忽略的元素 CSS 选择器

已建CSS课程

这些课程没有配置, 仍然与自定义选择器一起活动 :

类行为
grafana-mask元素及其后人中的遮盖文本,而不是输入值或属性.
grafana-block排除子树的内容,取而代之的是布局占位符.
grafana-ignore在匹配的输入、文本区或选择上禁止输入更改记录.
<span class="grafana-mask">Jane Doe</span>
<div class="grafana-block">Sensitive content</div>
<input class="grafana-ignore" type="search" />

maskInputOptions

密钥类型说明
passwordboolean密码输入
textboolean文本输入
emailboolean电子邮件输入
telboolean电话投入
numberboolean投入数量
searchboolean搜索输入
urlbooleanURL 输入
dateboolean日期投入
datetime-localboolean日期-当地投入
monthboolean月份投入
weekboolean周投入
timeboolean时间投入
colorboolean颜色输入
rangeboolean范围输入
textareaboolean文本区域元素
selectboolean选择下拉

记录选项

密钥类型默认说明
samplingRatenumber1将记录的全球抽样会议。 应用于顶端 sessionTracking.samplingRate。外部值被夹住.
recordAfter'load' | 'DOMContentLoaded''load'如果文档尚未准备好, 何时开始录制
recordCrossOriginIframesbooleanfalse是否记录跨源地的 Iframes 。 rrweb 必须在每个孩子的框中注入此功能
collectFontsbooleanfalse是否收集网站使用的字体
inlineImagesbooleanfalse是否记录图像内容
inlineStylesheetbooleanfalse是否将样式表内入记录事件
inactivityThresholdMsnumber60000在这多毫秒的无活性后暂停录入;在下个交互上自动恢复. 设定为 0 无法禁用

初始化后,a ReplayInstrumentation 实例也可以控制 明确使用 pauseRecording() 财务报告和审定财务报表 resumeRecording()恢复开始 a 新的 rrweb 记录, 并有一个新的 DOM 检查站。 明确暂停的录音 暂停至 resumeRecording() 名为.

子样本示例

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

钩子

密钥类型默认说明
beforeSend(event: eventWithTime) => eventWithTime | null | undefinedundefined在发送前转换或过滤事件 。 返回时 null 或者说 undefined 要跳过发送

隐私和安全

此仪器记录了您的网站上的用户互动 。 确保:

  1. 检查您的掩码选项 - 默认情况下,所有输入值和文本内容都会被掩盖. 如果需要的话,你可以让面具更有选择性 maskAllInputs, (中文(简体) ), maskInputOptions,以及 maskTextSelector
  2. 使用 CSS 选择器 - 使用( I) maskTextSelector 掩盖敏感内容, blockSelector 完全排除要素
  3. 执行过滤 - 用那个 beforeSend 发送前过滤或转换事件的钩头
  4. 审查您的隐私政策 - 确保会议录音有适当的用户同意
  5. 测试您的配置 - 核实记录中没有收集任何敏感信息

示例:高级隐私配置

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 是什么?

用 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 和提交记录判断。