设置会话重放

了解如何在您的应用程序中启用会话重放(如果尚未设置)。

如果您有任何问题、反馈或想要报告错误,请打开一个 GitHub issue,并附上相关重放的链接,或者如果可能的话,提供一个可公开访问的页面 URL,该页面是您尝试记录重放的页面。

会话重放 可以通过提供用户浏览器在问题发生前后的行为视频重现,帮助您更快找到错误或延迟问题的根本原因。您可以回放和重播应用程序的 DOM 状态,并查看关键用户交互,如鼠标点击、滚动、网络请求和控制台条目,所有这些都在一个受浏览器 DevTools 启发的单一组合 UI 中。

默认情况下,我们的会话重放 SDK 会屏蔽所有 DOM 文本内容、图像和用户输入,确保敏感数据不会离开浏览器,从而增强您的信心。要了解更多,请参阅 会话重放隐私

为了使 sentry-replay 集成正常工作,您必须安装 Sentry 浏览器 SDK 包,或等效的框架 SDK(例如,@sentry/react)。SDK 的最低版本要求为 7.27.0。如果您使用的是较旧版本的 SDK,请查阅 迁移文档

Session Replay 需要 Node 12+ 和 IE11 之后的浏览器。

Replay 集成已包含在您的浏览器或框架 SDK NPM 包中。如果您使用的是 CDN 包而不是 NPM 包,则需要另外加载 Replay 集成的 CDN 包,除此之外还需要加载您的浏览器包:

Copied
npm install @sentry/browser --save

要设置集成,请将以下内容添加到您的 Sentry 初始化代码中。您可以传递多个选项给集成构造函数。更多详情请参阅 配置文档

Copied
// import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // This sets the sample rate to be 10%. You may want this to be 100% while
  // in development and sample at a lower rate in production
  replaysSessionSampleRate: 0.1,

  // If the entire session is not sampled, use the below sample rate to sample
  // sessions when an error occurs.
  replaysOnErrorSampleRate: 1.0,

  integrations: [
    Sentry.replayIntegration({
      // Additional SDK configuration goes in here, for example:
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
});

在测试期间,我们建议将 replaysSessionSampleRate 设置为 1.0。这可以确保每个用户会话都会发送到 Sentry。

测试完成后,我们建议在生产环境中降低此值。我们仍然建议将 replaysOnErrorSampleRate 保持设置为 1.0,以便尽可能让每个错误都有一个带有额外调试上下文的重放。

个人可识别信息 (PII) 和隐私是在启用 Session Replay 时的重要考虑因素。Sentry 提供了多种方式帮助您避免收集 PII,包括:

  • 遮罩,它会用其他内容替换文本内容(默认行为是将每个字符替换为 *)。
  • 网络请求、响应体和标头 设为可选功能,因为避免 PII 进入 Sentry 的最佳方法是不添加可能包含 PII 的端点 URL。

虽然我们已经采取了一些隐私保护措施,但 Sentry 的 Session Replay 允许您设置最适合您使用场景的 隐私配置。例如,如果您正在处理一个没有 PII 或其他类型私有数据的静态网站,您可以选择退出默认的文本遮罩和图像阻止设置。要了解更多关于 Session Replay 隐私的信息,请阅读我们的文档

一旦您添加了集成,Replay 将自动启动。如果您不想立即启动它(延迟加载),您可以使用 addIntegration

Copied
Sentry.init({
  // Note, Replay is NOT instantiated below:
  integrations: [],
});

// Sometime later
import("@sentry/browser").then((lazyLoadedSentry) => {
  Sentry.addIntegration(lazyLoadedSentry.replayIntegration());
});

如果您想录制 HTML canvas 元素,您需要在 Sentry 配置中添加一个额外的集成。Canvas 集成是从浏览器 SDK 导出的,因此不需要额外的软件包。Canvas 录制是可选的,如果未使用,它将从您的打包文件中被 tree-shaken 移除:

Copied
// import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  integrations: [
    // Keep the Replay integration as before
    Sentry.replayIntegration(),

    // The following is all you need to enable canvas recording with Replay
    Sentry.replayCanvasIntegration(),
  ],
});

Canvas 录制集成通过以每秒 2 帧的速度导出 canvas 为图像来工作。然而,为了从 3D 和 WebGL canvas 导出图像,集成需要启用 preserveDrawingBuffer,这可能会对 canvas 性能产生负面影响。如果您的 canvas 应用程序受到启用 preserveDrawingBuffer 的影响,您需要启用手动快照并在重新绘制循环中调用 snapshot() 方法。使用手动快照有两个步骤:

第一步: 在初始化 ReplayCanvas 集成时启用手动快照。

Copied
Sentry.replayCanvasIntegration({
  // Enabling the following will ensure your canvas elements are not forced
  // into `preserveDrawingBuffer`.
  enableManualSnapshot: true,
});

第二步: 在应用程序的绘制循环中调用以下 snapshot() 方法。snapshot() 需要在与 canvas 绘制命令相同的执行循环中调用,否则您可能会捕获到空的 canvas 缓冲区。这是由于在 preserveDrawingBufferfalse 时 WebGL 的工作方式。

Copied
function paint() {
  const canvasRef = document.querySelector("#my-canvas");
  Sentry.getClient()
    .getIntegrationByName("ReplayCanvas")
    .snapshot(canvasRef);
}

Session Replay 使用 WebWorker 来执行工作(例如,压缩),以避免占用主线程并影响应用程序的性能。请添加以下条目以确保可以加载 workers:

Copied
worker-src 'self' blob:

Safari 版本 <= 15.4 不支持 worker-src,您需要另外添加一个 child-src 的条目:

Copied
child-src 'self' blob:

如果您无法更新 CSP 策略以允许内联 Web Worker,您也可以 使用自定义压缩 Worker

用户会话在 Session Replay SDK 首次加载和初始化时开始。只要 SDK 在同一域名和同一浏览器标签页中每次重新初始化,会话将捕获任何页面加载、刷新或导航。会话将继续捕获数据,直到 5 分钟内没有任何用户交互 最多 60 分钟已过。根据 SessionStorage 的规则,关闭浏览器标签页将立即结束会话。

交互 指的是鼠标点击或浏览器导航事件。

如果您不希望记录整个会话,可以选择仅在发生错误时捕获重放。在这种情况下,集成将缓冲最多一分钟的事件,直到错误被抛出之前。它将继续记录会话,遵循上述关于会话生命周期和活动的规则。请阅读 采样 部分以了解配置选项。

采样允许您控制有多少网站流量会生成 Session Replay。您可以调整两个采样率以获取与您相关的重放:

  1. replaysSessionSampleRate - 立即开始并持续整个用户会话的重放缓存的采样率。
  2. replaysOnErrorSampleRate - 在发生错误时记录的重放缓存的采样率。这种类型的重放将记录错误发生前最多一分钟的事件,并继续记录直到会话结束。

采样在会话开始时立即进行。replaysSessionSampleRate 优先评估。如果被采样,重放记录将开始。否则,将评估 replaysOnErrorSampleRate,如果被采样,集成将开始缓冲重放,并且只有在发生错误时才会上传到 Sentry。其余的重放行为将类似于整个会话重放。

页面上发生错误时,如果重放正在运行,这些错误将与重放关联,使您可以在这两者之间跳转。然而,在某些情况下,重放详情页面上报告的错误数可能与实际捕获的错误数不匹配。这是因为错误可能会丢失,虽然这种情况很少见,但有几种原因可能导致这种情况发生:

  • 重放缓存被限流,无法被接受。
  • 您组织的成员删除了重放缓存。
  • 网络错误导致重放缓存未保存。

在测试期间,我们建议将 replaysSessionSampleRate 设置为 1.0。这可以确保每个用户会话都会发送到 Sentry。

测试完成后,我们建议在生产环境中降低此值。我们仍然建议将 replaysOnErrorSampleRate 保持设置为 1.0