理解会话
了解如何使用 Session Replay SDK 自定义会话。
在大多数情况下,设置 Replay 采样率将是您开始捕获所需录制数据所需的全部操作。对于更复杂的情况,了解会话的工作原理以及如何手动控制它们会很有帮助。
默认情况下,当 replayIntegration()
集成实例添加到 SDK 客户端时,Replay 会立即启动一个会话。根据您的 replaysSessionSampleRate
和 replaysOnErrorSampleRate
设置,会话将处于 session
或 buffer
模式。
当 Replay 初始化时,我们会检查 replaysSessionSampleRate
。如果被采样,我们将立即开始记录并发送 Replay 数据。
如果 replaysOnErrorSampleRate > 0
,我们将在缓冲模式下开始记录,并在每次发生错误时检查 replaysOnErrorSampleRate
。一旦发现它被采样,我们将上传 Replay 到 Sentry 并继续正常记录。
如果 replaysSessionSampleRate
和 replaysOnErrorSampleRate
都为 0
,记录不会开始,但您可以 手动记录。
在 session
模式下,Replay 将持续记录并向 Sentry 发送数据。经过 15 分钟的用户不活动或最长 60 分钟后,会话将结束,并根据上述规则初始化新会话。
在 buffer
模式下,Replay 将持续记录数据,但不会发送任何数据。相反,它会在内存中保留最近的 60 秒数据。当发生错误时,将检查 replaysOnErrorSampleRate
,如果被采样,重放将上传到 Sentry 并继续正常记录。经过 15 分钟的用户不活动或最长 60 分钟后,会话将结束,重放将停止。
也可以延迟 Replay 集成的初始化和加载。这对于将 SDK 初始化与 Replay 配置解耦很有帮助。例如,如果您有一个外部采样服务不可立即使用。
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 会话:
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();
如果 replaysSessionSampleRate
和 replaysOnErrorSampleRate
都为 0
,则您需要手动启动会话重放,如上所示。这在您之前停止了一个会话并希望启动一个新的会话时也非常有用(见下文)。如果当前已经有会话在运行,start()
和 startBuffering()
是安全的且不会产生任何效果。在这种情况下,它们将 记录一条调试消息。
您可以随时使用以下方法停止正在运行的会话:
await replay.stop();
这将刷新所有待处理的录制数据,停止重放并结束会话。
您可以使用以下方法刷新所有待处理的录制数据:
await replay.flush();
在 session
模式下,这将上传所有待处理的录制数据到 Sentry。在 buffer
模式下,这将上传所有待处理的录制数据到 Sentry 并继续记录,类似于当 replaysOnErrorSampleRate
采样到错误时的行为。
在 Session Replay 已停止的情况下调用 flush()
将启动一个新的会话录制。
如果您有兴趣跟踪特定操作或群体(例如,特定用户群或有问题的 URL),可以启用自定义采样。
您可以设置重放以自动为特定用户组录制。以下是一个示例,我们希望为所有员工用户录制基于会话的重放。user
对象有一个 isEmployee
字段来标识员工状态。
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 的导航事件并启动重放录制。
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
回调:
replayIntegration({
beforeErrorSampling: (error) => {
return error.message?.includes("drop me");
},
});
如果在此方法中针对某个错误返回 false
,我们将不会为此错误检查错误采样率。 如果返回 true
,我们将继续正常检查错误采样率。
重放不需要与应用程序错误关联,也可以用于补充您的支持工单。 根据您的支持小部件提供的自定义程度,可以在用户打开支持小部件时将重放发送到 Sentry。请注意,Sentry 的 用户反馈 默认提供此功能!然后您可以将重放的 ID 与用户提交的支持工单一起发送。该 ID 可用于在 Sentry 中引用重放。或者,您可以通过用户标识符(如电子邮件)搜索重放。
下面的示例提供了一个模板,展示了如何将重放与您的支持小部件关联。
/**
* 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>/
*
*/