自动插桩

了解启用追踪后捕获的跨度(spans)。

捕获跨度需要您首先在应用程序中设置追踪,如果您尚未这样做的话。

Sentry SDK 提供了 BrowserTracing 集成,以自动为浏览器应用程序的性能监控添加插桩。

BrowserTracing 集成会在每次页面加载和导航事件时创建一个新的事务,并在这些事务打开期间为每个 XMLHttpRequestfetch 请求创建一个子跨度。了解更多关于 追踪、事务和跨度 的信息。

要启用追踪,请在 SDK 配置选项中包含 browserTracingIntegration

配置完成后,您将在 Sentry UI 中看到 pageloadnavigation 事务。

Copied
// 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: falseinstrumentPageLoad: false 来禁用默认的跨度创建。然后您可以手动创建跨度,如下所示:

Copied
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-tracebaggage 头附加到所有目标包含列表中的字符串或匹配列表中正则表达式的 XHR/fetch 请求。如果您的前端向不同的域发送请求,您需要将其添加到此列表中,以将 sentry-tracebaggage 头传播到后端服务,这是将跨度链接为单个跟踪的一部分所必需的。

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-tracebaggage 头。
Copied
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-tracebaggage 头。配置可能类似于 "Access-Control-Allow-Headers: sentry-trace""Access-Control-Allow-Headers: baggage",但具体取决于您的设置。如果不允许这两个头,请求可能会被阻止。

beforeStartSpan 在每个 pageloadnavigation 跨度开始时被调用,并传递一个包含即将启动的跨度信息的对象。通过 beforeStartSpan,您可以修改这些数据。

一个常见的用例是参数化事务名称。对于 pageloadnavigation 事务,browserTracingIntegration 使用浏览器的 window.location 值来生成事务名称。通过使用 beforeStartSpan,您可以修改事务名称以使其更加通用,例如,将名为 GET /users/12312012GET /users/11212012 的事务重命名为 GET /users/:userid。这样它们可以被归为同一组。

Copied
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 请求或类似情况。如果未指定此函数,则会为所有请求创建跨度。

Copied
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

此选项会在标签页移至后台时将 pageloadnavigation 跨度标记为 "cancelled"。由于浏览器后台标签页的计时不适合精确测量操作,并且可能以不可预测的方式影响您的统计数据,我们建议启用此选项。

默认值是 true

此选项确定是否自动创建长任务的跨度。

默认值是 true

enableLongAnimationFrame 选项需要 SDK 版本 8.18.0 或更高版本。

此选项确定是否自动创建长动画帧的跨度。如果同时启用了 enableLongAnimationFrameenableLongTask,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 将根据您的计划产生其标准费用,并受配置的采样率影响。

Copied
Sentry.init({
  // ...
  integrations: [
    Sentry.browserTracingIntegration({
      enableInp: true,
    }),
  ],
});

此选项确定 INP 跨度的采样率。interactionsSampleRate 是基于 tracesSampleRate 之上的,因此如果您的 interactionsSampleRate 设置为 0.5,而 tracesSampleRate 设置为 0.1,最终结果将是 0.05

默认值是 1.0