自动 instrumentation

了解启用跟踪后捕获的事务。

@sentry/react-native 在启用跟踪时,默认提供自动性能 instrumentation。

为了充分利用我们的自动 instrumentation,您应该:

用 Sentry 包裹您的根组件,以访问更多的性能功能。

App.js
Copied
export default Sentry.wrap(App);

当未使用路由 instrumentation 时,会自动捕获一个名为 App Start 的事务。但是,一旦添加了以下任一路由集成,该事务将停止发送。相反,App Start 信息将作为跨度包含在路由 instrumentation 捕获的事务中。

我们目前默认提供三种路由 instrumentation,用于 instrument 路由变化:

Sentry 提供以下自动 instrumentation 功能。

应用启动 instrumentation 可以洞察应用程序启动所需的时间。它跟踪从 最早的原生进程初始化React Native 根组件挂载 的时间长度。

如果您没有 用 Sentry 包裹根组件,应用启动测量将在 JavaScript 代码初始化时结束,而不是在第一个组件挂载时结束。

SDK 区分冷启动和热启动,但不跟踪热启动或恢复。测量结果可以在 measurements.app_start_warmmeasurements.app_start_cold 下查看。

冷启动和热启动是移动关键指标(Mobile Vitals),您可以在 完整文档 中了解更多关于这些指标的信息。

无响应的 UI 和动画卡顿会令用户不满并降低用户体验。用于跟踪这些体验的两个指标是慢帧和冻结帧。如果您希望应用程序运行顺畅,应尽量避免这两种情况。SDK 会为捕获的事务添加这两个测量指标。

慢帧和冻结帧是移动关键指标(Mobile Vitals),您可以在 完整文档 中了解更多关于这些指标的信息。

React Native 移动应用程序不会报告 Web Vitals。这些值依赖于浏览器提供的 API,在此上下文中不可用。

Sentry 使用 androidx.core 库来检测 慢帧和冻结帧。这是为了在所有 Android 操作系统版本中产生准确的结果。

我们在运行时检查其可用性,因此如果您没有使用 androidx.core,可以从 Sentry 的传递依赖项中移除它。

Copied
api ('io.sentry:sentry-android:8.1.0') {
    exclude group: 'androidx.core', module: 'core'
}

请注意,如果您移除了这个传递依赖项,则不会报告慢帧和冻结帧。

延迟是指 JavaScript 事件循环完成时间超过了预期。JavaScript 代码中的延迟不仅会使您的 UI 无响应,还会减慢包含在 JavaScript 中的逻辑处理速度。这会拖慢整个应用程序的速度,给用户带来不良体验。

我们会在事务期间跟踪 React Native 应用程序中的延迟,并为您提供以下指标:

  • 最长延迟时间:最长事件循环延迟的时间,以毫秒为单位。
  • 总延迟时间:所有延迟的总时间,以毫秒为单位。
  • 延迟次数:事务期间发生的延迟总数。

跟踪集成会在 JavaScript 层为每个 XMLHttpRequestfetch 请求创建一个子跨度(span),这些请求发生在事务打开期间。了解更多关于 跟踪、事务和跨度 的信息。

要配置自动性能 instrumentation,您需要自己添加 ReactNativeTracing 集成。我们默认提供了许多选项,因此对于大多数应用程序来说,您无需自行配置该集成。

Copied
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  integrations: [Sentry.reactNativeTracingIntegration()],
});

tracePropagationTargets 的默认值在移动平台上是 [/.*/],在 Web 平台上是 ['localhost', /^\//]。React Native SDK 会将 sentry-trace 标头附加到移动平台上的所有传出 XHR/fetch 请求。 在 Web 上,跟踪数据仅附加到 URL 中包含 localhost 或 URL 以 '/' 开头的传出请求(例如 GET /api/v1/users)。

在 Web 上使用 React Native?以下是 `tracePropagationTargets` 的变化方式。

SDK 会将 sentry-trace 标头附加到所有目标包含列表中字符串或匹配列表中正则表达式的传出 XHR/fetch 请求。如果您的前端向不同的域名发起请求,您需要将该域名添加到列表中,以便将 sentry-trace 标头传播到后端服务,这是将事务链接为单个跟踪的一部分所必需的。tracePropagationTargets 选项匹配整个请求 URL,而不仅仅是域名。使用更严格的正则表达式来匹配 URL 的某些部分可以确保不必要的请求不会附加 sentry-trace 标头。

For example:

  • A frontend application is served from example.com
  • A backend service is served from api.example.com
  • The frontend application makes API calls to the backend
  • Therefore, the option needs to be configured like this: Sentry.init({tracePropagationTargets: ['api.example.com']})
  • Now outgoing XHR/fetch requests to api.example.com will get the sentry-trace header attached
Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  tracePropagationTargets: ["localhost", "my-site-url.com"],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

您需要配置 Web 服务器的 CORS 以允许 sentry-trace 标头。配置可能类似于 "Access-Control-Allow-Headers: sentry-trace",但具体配置取决于您的设置。如果不允许 sentry-trace 标头,请求可能会被阻止。

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

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    Sentry.reactNativeTracingIntegration({
      beforeStartSpan: (context) => {
        return {
          ...context,
          attributes: {
            ...context.attributes,
            custom: "value",
          },
        };
      },
    }),
  ],
});

此函数可用于过滤掉不需要的跨度,例如运行健康检查的 XHR 或类似请求。如果未指定此函数,则会为所有请求创建跨度。

Copied
Sentry.init({
  // ...
  integrations: [
    Sentry.reactNativeTracingIntegration({
      shouldCreateSpanForRequest: (url) => {
        // Do not create spans for outgoing requests to a `/health/` endpoint
        return !url.match(/\/health\/?$/);
      },
    }),
  ],
});

当没有未完成的跨度时,事务需要等待的空闲时间,以毫秒为单位。如果在指定的空闲时间内没有新的跨度开始,事务将使用最后一个完成的跨度的结束时间戳作为事务的结束时间。

默认值是 1_000 毫秒。

事务的最大持续时间,以毫秒为单位。如果事务的持续时间达到了 finalTimeout 值,事务将被结束。

默认值是 60_000 毫秒(即 60 秒)。

目前,默认情况下,React Native SDK 只会为 fetch/XHR 请求自动创建子跨度。这意味着在您完成路由 instrumentation 的设置后,您可能会看到只有少数 fetch/XHR 子跨度或根本没有子跨度。要了解如何自定义应用程序的 instrumentation,请参阅我们的 自定义 instrumentation

我们还从 React Native SDK 中导出了 React Profiler。更多内容请参阅 React 组件跟踪

在为应用程序的路由设置 instrumentation 后,如果您用 withProfiler 包裹在一个路由上渲染的组件,您将能够跟踪该组件的生命周期,并将其作为路由事务的子跨度进行记录。

Copied
import * as Sentry from "@sentry/react-native";

// withProfiler HOC
const SomeComponent = () => {
  // ...
};

export default Sentry.withProfiler(SomeComponent);

在为生产环境打包时,React Native 会将类和函数名称进行混淆以减小包的大小。这意味着 您在 Profiler 跨度中不会看到完整的原始组件名称,而是会看到混淆后的名称。请参阅我们的 解决生产环境中混淆名称的问题 文档以解决此问题。

如果您希望使用跟踪而不启用我们的自动 instrumentation,可以通过在 Sentry 配置选项中设置 enableAutoPerformanceTracing 并移除 ReactNativeTracing 集成(如果您添加了它)来禁用自动 instrumentation:

Copied
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  enableAutoPerformanceTracing: false,
});

UI instrumentation 会捕获事务并为触摸交互添加面包屑。使用 sentryTraceGesture 包裹,还支持通过 React Native Gesture Handler 进行的手势操作。了解更多关于 用户交互 instrumentation 的信息。