配置

了解通用的 Session Replay 配置字段。

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

以下选项可以在浏览器端 Sentry SDK 的 init({}) 中进行配置：

键	类型	默认值	描述
replaysSessionSampleRate	`number`	`0`	立即开始并持续整个用户会话的重放缓存的采样率。`1.0` 收集所有重放，`0` 不收集任何重放。
replaysOnErrorSampleRate	`number`	`0`	在发生错误时记录的重放缓存的采样率。这种类型的重放将记录错误发生前最多一分钟的事件，并继续记录直到会话结束。`1.0` 捕获所有带有错误的会话，`0` 不捕获任何会话。

以下选项可以在 replayIntegration({}) 中作为集成选项进行配置：

键	类型	默认值	描述
stickySession	`boolean`	`true`	保持跟踪用户，即使页面刷新。注意，关闭标签页会结束会话，因此单个用户使用多个标签页会被记录为多个会话。
mutationLimit	`number`	10000	在 Session Replay 停止记录以避免性能影响之前可以处理的最大突变数。参见突变限制。
mutationBreadcrumbLimit	`number`	750	在 Session Replay 发送面包屑警告大突变之前可以处理的最大突变数。参见突变限制。
minReplayDuration	`number`	5000	在 SDK 开始发送到 Sentry 之前重放的长度（以毫秒为单位）。最大值为 15000。
workerUrl	`string`	`undefined`	自托管压缩 Worker 的 URL。参见使用自定义压缩 Worker 了解更多。
networkDetailAllowUrls	`(string\|RegExp)[]`	`[]`	捕获与给定 URL 匹配的 XHR 和 fetch 请求的请求和响应详细信息。
networkDetailDenyUrls	`(string\|RegExp)[]`	`[]`	不捕获这些 URL 的请求和响应详细信息。优先于 `networkDetailAllowUrls`。
networkCaptureBodies	`boolean`	`true`	决定是否捕获 `networkDetailAllowUrls` 中定义的 URL 的请求和响应体。
networkRequestHeaders	`string[]`	`[]`	捕获 `networkDetailAllowUrls` 中定义的 URL 的额外请求头。参见网络详细信息了解更多。
networkResponseHeaders	`string[]`	`[]`	捕获 `networkDetailAllowUrls` 中定义的 URL 的额外响应头。参见网络详细信息了解更多。
beforeAddRecordingEvent	`(event) => event\|null`	`i => i`	过滤包含控制台日志和网络请求/响应的额外记录事件。
beforeErrorSampling	`(event) => boolean`	`i => true`	过滤应跳过错误采样的错误事件。如果应跳过此错误事件的错误采样，则返回 `false`，否则返回 `true` 以对此错误进行采样。
slowClickIgnoreSelectors	`string[]`	`[]`	忽略与给定 CSS 选择器匹配的元素的慢点击/愤怒点击检测。

我们非常重视隐私，因此提供了多种隐私相关的设置。请参阅我们的 Session Replay 隐私文档了解更多。

如果您正在处理一个没有个人可识别信息或其他类型私有数据的静态网站，您可以通过配置 maskAllText 和 blockAllMedia 配置选项分别选择退出默认的文本遮罩和图像阻止：

Copied

Sentry.replayIntegration({
  // NOTE: This will disable built-in masking. Only use this if your site has no sensitive data, or if you've already set up other options for masking or blocking relevant data, such as 'ignore', 'block', 'mask' and 'maskFn'.
  maskAllText: false,
  blockAllMedia: false,
});

从 v8 开始，unblock 和 unmask 选项不再添加默认的 DOM 选择器。如果您希望保持之前版本的默认行为，则应在配置中明确指定它们：

Copied

Sentry.replayIntegration({
  unblock: [".sentry-unblock, [data-sentry-unblock]"],
  unmask: [".sentry-unmask, [data-sentry-unmask]"],
});

以下是在 replayIntegration({}) 中可以使用的完整选项列表：

键	类型	默认值	描述
mask	`string[]`	`['.sentry-mask', '[data-sentry-mask]']`	遮罩与给定 DOM 选择器匹配的所有元素。请参阅遮罩部分以了解示例。注意，任何配置的选择器都将附加到默认选择器上。
maskAllText	`boolean`	`true`	遮罩所有文本内容。在发送到服务器之前，文本内容将通过 `maskFn` 进行处理。
maskAllInputs	`boolean`	`true`	遮罩 `<input>` 元素的值。在发送到服务器之前，输入值将通过 `maskFn` 进行处理。
block	`string[]`	`['.sentry-block', '[data-sentry-block]']`	红acted与给定 DOM 选择器匹配的所有元素。请参阅阻止部分以了解示例。注意，任何配置的选择器都将附加到默认选择器上。
blockAllMedia	`boolean`	`true`	阻止所有媒体元素（`img`, `svg`, `video`, `object`, `picture`, `embed`, `map`, `audio`）。
ignore	`string[]`	`['.sentry-ignore', '[data-sentry-ignore]']`	忽略与匹配输入字段上的所有事件。请参阅上方的忽略示例。
maskFn	`(text: string) => string`	`(s) => '*'.repeat(s.length)`	自定义在发送到服务器之前如何遮罩文本内容的函数。默认情况下，用 `*` 遮罩文本。
unblock	`string[]`	`[]`	不红acted与给定 DOM 选择器匹配的任何元素。用于取消 `blockAllMedia` 阻止的具体媒体元素。这不影响如 `password` 等敏感元素。
unmask	`string[]`	`[]`	取消遮罩与给定 DOM 选择器匹配的所有元素。用于取消 `maskAllText` 遮罩的具体元素。

要了解更多关于会话采样的工作原理，请查阅我们的默认会话初始化文档。

默认情况下，Replay 将捕获应用程序中所有发出的 fetch 和 XHR 请求的基本信息。这包括 URL、请求和响应体大小、方法和状态码。目的是尽量减少收集私有数据的机会。

要捕获额外的信息（如请求和响应头或主体），您需要通过 networkDetailAllowUrls 选择加入（要求 SDK 版本 >= 7.50.0）。这将使您可以选择仅添加安全的 URL 以捕获主体，并避免任何可能包含个人可识别信息 (PII) 的端点。

主体内容将在服务器端根据对象键和值进行 PII 清理。请参阅我们的 Replay 隐私部分了解更多详情。

任何与给定模式匹配的 URL 都将捕获额外的详细信息：

Copied

replayIntegration({
  networkDetailAllowUrls: [window.location.origin],
});

如果您提供一个字符串，我们将匹配任何包含该字符串的 URL。您可以使用正则表达式来处理精确或更复杂的匹配。

与配置模式匹配的 URL 的请求将增强为包含请求和响应体，以及以下默认头信息：

Content-Type
Content-Length
Accept

如果您想捕获额外的头信息，您需要通过 networkRequestHeaders 和 networkResponseHeaders 选项进行配置，例如：

Copied

replayIntegration({
  networkDetailAllowUrls: [
    window.location.origin,
    "api.example.com",
    /^https:\/\/api\.example\.com/,
  ],
  networkRequestHeaders: ["Cache-Control"],
  networkResponseHeaders: ["Referrer-Policy"],
});

捕获的主体将被截断为最多 150k 字符。

您可以使用 Sentry SDK 将用户与会话关联。请参阅我们的识别用户文档了解更多。

Copied

Sentry.setUser({ email: "jane.doe@example.com" });

默认情况下，Session Replay 会使用一个内联的 Web Worker 脚本来在网络传输之前压缩重放数据。这可以大幅减少传输的数据量，提高性能并减少网络开销。由于压缩数据是 CPU 密集型操作，我们使用 Web Worker 将此工作卸载到单独的线程。

虽然内联 Worker 对大多数应用程序来说效果很好，但存在两个主要问题：

由于 Worker 代码是内联的，它会增加应用程序的主要包大小。
使用内联 Worker 可能会导致 CSP 违规，特别是在您的应用程序具有非常严格的 CSP 策略时。请参阅我们的 CSP 文档了解更多。

为了解决这些问题，我们提供了使用自定义 Worker 脚本的能力。这允许您在自己的域名上托管 Worker 脚本，避免与内联 Worker 相关的 CSP 问题。此外，Worker 脚本可以从主应用程序包中移除，并单独提供和缓存。

按照以下步骤使用自定义压缩 Worker：

从我们的 Github 仓库下载示例 Worker 脚本。
在与您的应用程序相同的域名上托管此 Worker 脚本。例如，如果您的应用程序托管在 https://example.com，您可以将 Worker 脚本托管在 https://example.com/assets/worker.min.js。
在 Replay 中配置您的自定义 Worker 脚本：

Copied

replayIntegration({
  workerUrl: "/assets/worker.min.js",
});

（可选）为了减少包大小，您现在可以 Tree Shake 默认包含的 Worker 脚本。如果您使用的是 Sentry Bundler Plugins（版本 2.10.0 或更高版本）：

Copied

sentryPlugin({
  // other config
  bundleSizeOptimizations: {
    excludeReplayWorker: true,
  },
});

由于您自行托管此脚本，因此您有责任保持其更新。我们建议您定期检查 Worker 脚本的更新，并根据需要进行更新。Worker 脚本 API 在主要版本内保证稳定，因此任何 v7 Worker 脚本应与任何 v7 SDK 版本向后和向前兼容。但是，我们可能会对 Worker 脚本进行改进或修复错误，如果您不更新它，您将错过这些改进。

Session Replay 通过记录 Web 应用程序中发生的增量 DOM 变化来工作。通常，这些变化以小批量发生，引起的开销很小。然而，很容易忽略会导致大量 DOM 突变在单次更新中发生的场景。例如，一个具有无限选项列表的自定义下拉组件可能会导致这种情况。这不仅会影响 Session Replay 未启用时的性能，而且在启用 Session Replay 后，影响会更加明显。为了避免这种情况，如果检测到大量突变（默认：10,000），Session Replay 将停止记录，可以通过设置 mutationLimit 来配置此限制。此外，当检测到大量突变时（默认：750），我们会在重放中提供面包屑警告。

Copied

replayIntegration({
  mutationBreadcrumbLimit: 1000,
  mutationLimit: 1500,
});

我们的 SDK 允许您发送自定义面包屑，这些面包屑将显示在 Replay Details UI 中，与现有的面包屑一起出现。要了解如何发送自定义面包屑，请阅读文档。请注意，您发送的任何自定义面包屑都会反映在 Issue Details 的面包屑 UI 和 Replay Details 的面包屑标签中。

Replay Details 中的所有自定义面包屑都将显示为灰色，并可以通过终端图标识别。

在 Replay Details 中，面包屑的 message 属性优先于 data 属性。如果设置了 message 属性，则字符串将如下所示：

如果没有设置 message，则面包屑将默认显示 data 属性。例如：

面包屑的标题将是您设置的面包屑 category。如果没有设置 category，我们将使用面包屑的 message。如果该属性也不存在，我们将使用 description。最后的回退方案是使用默认标题 "Custom"。

设置会话重放

隐私