理解会话

了解如何使用 Session Replay SDK 自定义会话。

在大多数情况下,设置 Replay 采样率将是您开始捕获所需录制数据所需的全部操作。对于更复杂的情况,了解会话的工作原理以及如何手动控制它们会很有帮助。

默认情况下,当 replayIntegration() 集成实例添加到 SDK 客户端时,Replay 会立即启动一个会话。根据您的 replaysSessionSampleRatereplaysOnErrorSampleRate 设置,会话将处于 sessionbuffer 模式。

当 Replay 初始化时,我们会检查 replaysSessionSampleRate。如果被采样,我们将立即开始记录并发送 Replay 数据。

如果 replaysOnErrorSampleRate > 0,我们将在缓冲模式下开始记录,并在每次发生错误时检查 replaysOnErrorSampleRate。一旦发现它被采样,我们将上传 Replay 到 Sentry 并继续正常记录。

如果 replaysSessionSampleRatereplaysOnErrorSampleRate 都为 0,记录不会开始,但您可以 手动记录

session 模式下,Replay 将持续记录并向 Sentry 发送数据。经过 15 分钟的用户不活动或最长 60 分钟后,会话将结束,并根据上述规则初始化新会话。

buffer 模式下,Replay 将持续记录数据,但不会发送任何数据。相反,它会在内存中保留最近的 60 秒数据。当发生错误时,将检查 replaysOnErrorSampleRate,如果被采样,重放将上传到 Sentry 并继续正常记录。经过 15 分钟的用户不活动或最长 60 分钟后,会话将结束,重放将停止。

也可以延迟 Replay 集成的初始化和加载。这对于将 SDK 初始化与 Replay 配置解耦很有帮助。例如,如果您有一个外部采样服务不可立即使用。

Copied
async function init(sessionSampleRate, errorSampleRate) {
  const client = Sentry.getClient();
  const options = client.getOptions();
  options.replaysSessionSampleRate = sessionSampleRate;
  options.replaysOnErrorSampleRate = errorSampleRate;

  const replay = Sentry.replayIntegration({
    maskAllText: true,
    // additional SDK config, see https://docs.sentry.io/platforms/javascript/session-replay/configuration/
  });

  client.addIntegration(replay);
}

您可以使用以下方法手动启动一个 Replay 会话:

Copied
Sentry.init({
  dsn: "...",
  // This initializes Replay without starting any session
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
  integrations: [Sentry.replayIntegration()],
});

// You can access the active replay instance from anywhere in your code like this:
const replay = Sentry.getReplay();

// This starts in `session` mode, regardless of sample rates
replay.start();

// OR

// This starts in `buffer` mode, regardless of sample rates
replay.startBuffering();

如果 replaysSessionSampleRatereplaysOnErrorSampleRate 都为 0,则您需要手动启动会话重放,如上所示。这在您之前停止了一个会话并希望启动一个新的会话时也非常有用(见下文)。如果当前已经有会话在运行,start()startBuffering() 是安全的且不会产生任何效果。在这种情况下,它们将 记录一条调试消息

您可以随时使用以下方法停止正在运行的会话:

Copied
await replay.stop();

这将刷新所有待处理的录制数据,停止重放并结束会话。

您可以使用以下方法刷新所有待处理的录制数据:

Copied
await replay.flush();

session 模式下,这将上传所有待处理的录制数据到 Sentry。在 buffer 模式下,这将上传所有待处理的录制数据到 Sentry 并继续记录,类似于当 replaysOnErrorSampleRate 采样到错误时的行为。

在 Session Replay 已停止的情况下调用 flush() 将启动一个新的会话录制。

如果您有兴趣跟踪特定操作或群体(例如,特定用户群或有问题的 URL),可以启用自定义采样。

您可以设置重放以自动为特定用户组录制。以下是一个示例,我们希望为所有员工用户录制基于会话的重放。user 对象有一个 isEmployee 字段来标识员工状态。

Copied
const replay = Sentry.replayIntegration();

/**
 * Initialize the Sentry SDK as normal.
 *
 * `replaysSessionSampleRate` is set to its default value of "0.1" so that only ~10% of users are sampled
 * `replaysOnErrorSampleRate` is set to its default value of "1.0" to always record a replay when an error occurs
 */
Sentry.init({
  dsn: "...",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [replay],
});

// ...
// After a user has been authenticated, check if they're an employee
// If they are, we'll call `replay.flush()` to either flush the replay as normal if it's a session-based replay, or if it's buffering due to error sampling, the flush will send the first segment of the replay.

// Since `replaysOnErrorSampleRate` is > 0, we know that a replay has been buffered and `flush()` will flush the contents of that buffer. If only `replaysSessionSampleRate` is > 0, then there is a chance that a replay has not been recording/buffering.
// In this case, you can check that `replay.getReplayId()` returns a value, if it does, it means replay is active and you can call `replay.flush()`, other call `replay.start()` to start recording a new replay.
// ...

// Check if user is an employee, if so, always record a replay
if (loggedInUser.isEmployee) {
  // You can get a reference to the Sentry Replay integration like so:
  const replay = Sentry.getReplay();

  replay.flush();
}

您还可以选择在用户每次访问指定 URL 时录制重放。这可以帮助开发人员调试有问题的页面。为此,您可以使用 Navigation API,它可以通过监听特定 URL 的导航事件并启动重放录制。

Copied
const replay = Sentry.replayIntegration();

/**
 * Initialize the Sentry SDK as normal.
 *
 * `replaysSessionSampleRate` and `replaysOnErrorSampleRate` are both set to
 * "0" so that we have manual control over session-based replays
 */
Sentry.init({
  dsn: "...",
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
  integrations: [replay],
});

// Listen to navigation events for when users land on our buggy URL, appropriately named: "/buggy-page/"
// and then start recording a replay.
navigation.addEventListener("navigate", (event) => {
  const url = new URL(event.destination.url);

  if (url.pathname.startsWith("/buggy-page/")) {
    // User navigates to the buggy page, let's start recording
    replay.start();
  }
});

当使用 replaysOnErrorSampleRate 时,我们会对任何捕获并发送到 Sentry 的错误进行采样。 如果您希望跳过为某些错误捕获重放,可以使用 beforeErrorSampling 回调:

Copied
replayIntegration({
  beforeErrorSampling: (error) => {
    return error.message?.includes("drop me");
  },
});

如果在此方法中针对某个错误返回 false,我们将不会为此错误检查错误采样率。 如果返回 true,我们将继续正常检查错误采样率。

重放不需要与应用程序错误关联,也可以用于补充您的支持工单。 根据您的支持小部件提供的自定义程度,可以在用户打开支持小部件时将重放发送到 Sentry。请注意,Sentry 的 用户反馈 默认提供此功能!然后您可以将重放的 ID 与用户提交的支持工单一起发送。该 ID 可用于在 Sentry 中引用重放。或者,您可以通过用户标识符(如电子邮件)搜索重放。

下面的示例提供了一个模板,展示了如何将重放与您的支持小部件关联。

Copied
/**
 * Initialize the Sentry SDK as normal.
 *
 * `replaysOnErrorSampleRate` needs to be > 0 so that replays are always buffering and only sent when necessary
 */
Sentry.init({
  dsn: "...",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 0.5,
  integrations: [Sentry.replayIntegration()],
});

/**
 * Your widget will need to have an event/hook to trigger flushing the replay to
 * Sentry.
 */
MySupportWidget.on("open", () => {
  const replay = Sentry.getReplay();
  // Send replay to Sentry
  replay.flush();
  // Retrieve the replay id that was saved and attach it to your support widget
  const replayId = replay.getReplayId();
  MySupportWidget.setTag("replayId", replayId);
});

/**
 * If your support application allows you to send custom data with the support
 * ticket, you may want to include a link to the replay URL in Sentry. That
 * way, you'll be able to open the replay directly from the ticket itself.
 * Replay URLs have the following format:
 *
 *   https://<org-slug>.sentry.io/replays/<replay-id>/
 *
 */