自动插桩
了解启用追踪后捕获的跨度(spans)。
捕获跨度需要您首先在应用程序中设置追踪,如果您尚未这样做的话。
Sentry SDK 提供了 BrowserTracing
集成,以自动为浏览器应用程序的性能监控添加插桩。
BrowserTracing
集成会在每次页面加载和导航事件时创建一个新的事务,并在这些事务打开期间为每个 XMLHttpRequest
或 fetch
请求创建一个子跨度。了解更多关于 追踪、事务和跨度 的信息。
要启用追踪,请在 SDK 配置选项中包含 browserTracingIntegration
。
配置完成后,您将在 Sentry UI 中看到 pageload
和 navigation
事务。
// If you're using one of our framework SDK packages, like `@sentry/react`,
// substitute its name for `@sentry/browser` here
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [Sentry.browserTracingIntegration()],
// We recommend adjusting this value in production, or using tracesSampler
// for finer control
tracesSampleRate: 1.0,
});
默认情况下,browserTracingIntegration()
会在页面初次加载时创建一个 pageload
跨度,并在 URL 随后发生变化时创建一个 navigation
跨度。
为了确保自定义路由设置中跨度能正确创建,您需要通过在 browserTracingIntegration()
选项中设置 instrumentNavigation: false
和 instrumentPageLoad: false
来禁用默认的跨度创建。然后您可以手动创建跨度,如下所示:
const client = Sentry.init({
integrations: [
Sentry.browserTracingIntegration({
// disable automatic span creation
instrumentNavigation: false,
instrumentPageLoad: false,
}),
],
});
// We start the pageload span as early as possible!
let pageLoadSpan = Sentry.startBrowserTracingPageLoadSpan(client, {
name: window.location.pathname,
attributes: {
[Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "url",
},
});
// Somewhere, instrument your router like this:
myRouter.on("routeChange", (route) => {
// Make sure that the pageload span uses the route name
// After that, each route change should trigger a navigation span (which will automatically finish the previous one)
if (pageLoadSpan) {
pageLoadSpan.updateName(route.name);
pageLoadSpan.setAttribute(
Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
"route",
);
pageLoadSpan = undefined;
} else {
Sentry.startBrowserTracingNavigationSpan(client, {
op: "navigation",
name: route.name, // or what the name of the span should be
attributes: {
[Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "route",
},
});
}
});
支持的选项:
tracingOrigins
选项在 JavaScript SDK 的 7.19.0 版本 中被重命名为 tracePropagationTargets
并已弃用。tracingOrigins
将在版本 8 中移除。
这是一个字符串和正则表达式的列表。JavaScript SDK 会将 sentry-trace
和 baggage
头附加到所有目标包含列表中的字符串或匹配列表中正则表达式的 XHR/fetch 请求。如果您的前端向不同的域发送请求,您需要将其添加到此列表中,以将 sentry-trace
和 baggage
头传播到后端服务,这是将跨度链接为单个跟踪的一部分所必需的。
tracePropagationTargets
选项匹配整个请求 URL,而不仅仅是域名。使用更严格的正则表达式来匹配 URL 的某些部分可以确保请求不会不必要地附加额外的头信息。
tracePropagationTargets
的默认值是 ['localhost', /^\//]
。这意味着,默认情况下,追踪头仅附加到 URL 包含 localhost
或 URL 以 '/'
开头(例如 GET /api/v1/users
)的请求。
例如:
- 前端应用程序托管在
example.com
。 - 后端服务托管在
api.example.com
。 - 在开发过程中,后端服务托管在
localhost
。 - 前端应用程序会向后端发起 API 请求。
- 将
tracePropagationTargets
选项设置为["localhost", /^https:\/\/api\.example\.com\/]
。 - 现在,发往后端服务的 XHR/fetch 请求将附加
sentry-trace
和baggage
头。
Sentry.init({
// ...
integrations: [Sentry.browserTracingIntegration()],
// Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
});
您需要配置您的 Web 服务器 CORS,以允许 sentry-trace
和 baggage
头。配置可能类似于 "Access-Control-Allow-Headers: sentry-trace"
和 "Access-Control-Allow-Headers: baggage"
,但具体取决于您的设置。如果不允许这两个头,请求可能会被阻止。
beforeStartSpan
在每个 pageload
或 navigation
跨度开始时被调用,并传递一个包含即将启动的跨度信息的对象。通过 beforeStartSpan
,您可以修改这些数据。
一个常见的用例是参数化事务名称。对于 pageload
和 navigation
事务,browserTracingIntegration
使用浏览器的 window.location
值来生成事务名称。通过使用 beforeStartSpan
,您可以修改事务名称以使其更加通用,例如,将名为 GET /users/12312012
和 GET /users/11212012
的事务重命名为 GET /users/:userid
。这样它们可以被归为同一组。
Sentry.init({
// ...
integrations: [
Sentry.browserTracingIntegration({
beforeStartSpan: (context) => {
return {
...context,
// You could use your UI's routing library to find the matching
// route template here. We don't have one right now, so do some basic
// parameter replacements.
name: location.pathname
.replace(/\/[a-f0-9]{32}/g, "/<hash>")
.replace(/\/\d+/g, "/<digits>"),
};
},
}),
],
});
如果您使用的是 React,请阅读我们的文档以了解如何设置 React Router 集成。
此函数可用于过滤掉不需要的跨度,例如运行健康检查的 XHR 请求或类似情况。如果未指定此函数,则会为所有请求创建跨度。
Sentry.init({
// ...
integrations: [
Sentry.browserTracingIntegration({
shouldCreateSpanForRequest: (url) => {
// Do not create spans for outgoing requests to a `/health/` endpoint
return !url.match(/\/health\/?$/);
},
}),
],
});
在没有未完成的子跨度时,等待页面加载或导航跨度结束的空闲时间(以毫秒为单位)。如果在此时间内没有未完成的子跨度,页面加载或导航跨度将使用最后一个完成的子跨度的结束时间戳作为结束时间。
默认值是 1000
毫秒。
页面加载或导航跨度的最大持续时间(以毫秒为单位)。如果持续时间超过 finalTimeout
值,跨度将被结束。
默认值是 30000
毫秒。
子跨度的最大运行时间(以毫秒为单位)。如果最后一个启动的子跨度运行时间超过此值,页面加载或导航跨度将被结束。
默认值是 15000
毫秒。
此标志启用或禁用在历史记录更改时创建 navigation
跨度。
默认值是 true
。
此标志启用或禁用在首次页面加载时创建 pageload
跨度。
默认值是 true
。
此选项会在标签页移至后台时将 pageload
或 navigation
跨度标记为 "cancelled"。由于浏览器后台标签页的计时不适合精确测量操作,并且可能以不可预测的方式影响您的统计数据,我们建议启用此选项。
默认值是 true
。
此选项确定是否自动创建长任务的跨度。
默认值是 true
。
enableLongAnimationFrame
选项需要 SDK 版本 8.18.0 或更高版本。
此选项确定是否自动创建长动画帧的跨度。如果同时启用了 enableLongAnimationFrame
和 enableLongTask
,Sentry 将发送长动画帧,并在浏览器不支持长动画帧时回退到长任务。
默认值是 true
。
enableInp
选项需要 SDK 版本 7.104.0 或更高版本。
此选项确定在检测到 交互到下次绘制 (INP) 事件时,是否自动创建交互跨度。交互会进行评分并在 Web Vitals 模块中显示。
默认值在 SDK 8.x
中为 true
,在 7.x
中为 false
。
目前启用 INP 样本对 Sentry 不会产生额外费用。基本样本包含有限的信息,如交互目标、延迟和用户信息。您可以通过设置 Session Replays 和/或围绕交互元素设置 Browser Profiling 仪器化来丰富您的 INP 样本,以进一步了解最慢的交互。
请注意,这种方式使用的任何 Session Replays 和 Browser Profiles 将根据您的计划产生其标准费用,并受配置的采样率影响。
Sentry.init({
// ...
integrations: [
Sentry.browserTracingIntegration({
enableInp: true,
}),
],
});
此选项确定 INP 跨度的采样率。interactionsSampleRate
是基于 tracesSampleRate
之上的,因此如果您的 interactionsSampleRate
设置为 0.5
,而 tracesSampleRate
设置为 0.1
,最终结果将是 0.05
。
默认值是 1.0
。