从 5.x 迁移到 6.x
学习如何从 Sentry React Native SDK 的版本 5 迁移到版本 6
Sentry React Native SDK 版本 6 的主要目标是与 Sentry JavaScript 版本 8 兼容，并改进我们的性能监控 API 和集成。此版本引入了破坏性更改，因为 JavaScript SDK 依赖升级到版本 8，并且我们移除了已弃用的 API 并重构了 npm 包内容。
Sentry React Native SDK 附带了 Sentry JavaScript SDK 作为依赖项。Sentry JavaScript SDK 已更新到版本 8。此版本包含许多破坏性更改。请遵循 JavaScript 迁移指南以完成升级。
初始版本 @sentry/react-native@6.0.0 附带 @sentry/core@8.31.0。如果手动将 JavaScript SDK 添加到项目中，请始终使用确切的 JavaScript SDK 版本。其他版本可能与 React Native SDK 不兼容。
Sentry JavaScript SDK 版本 8 的主要关注点是改进性能监控 API。因此，Tracing API 更改在独立指南中描述。请遵循 Tracing API 更改指南以完成升级。
其他通用的 JavaScript SDK 版本 8 更改在 JavaScript SDK 7.x 到 8.x 迁移指南中描述。
本节描述了 Sentry React Native SDK 版本 6 中的 API 更改。
要更改以下选项，您不再需要创建 React Native Tracing 实例。相反，您可以直接将它们传递给 Sentry.init 选项。
import * as Sentry from '@sentry/react-native';
Sentry.init({
tracesSampleRate: 1.0,
+ enableAppStartTracking: true,
+ enableNativeFramesTracking: true,
+ enableStallTracking: true,
+ enableUserInteractionTracing: true,
- integrations: [new Sentry.ReactNativeTracing({
- enableAppStartTracking: true,
- enableNativeFramesTracking: true,
- enableStallTracking: true,
- enableUserInteractionTracing: true,
- })],
});
导航 Instrumentations 现在是独立的集成。你需要将其添加到 Sentry.init 选项中的 integrations 数组。
import Sentry from '@sentry/react-native';
import { useNavigationContainerRef } from 'expo-router';
- const reactNavigationIntegration = new Sentry.ReactNavigationInstrumentation();
+ const reactNavigationIntegration = Sentry.reactNavigationIntegration();
Sentry.init({
tracesSampleRate: 1.0,
integrations: [
- new Sentry.ReactNativeTracing({ routingInstrumentation }),
+ reactNavigationIntegration,
],
});
ReactNavigationV4Instrumentation 在 SDK 的版本 6 中已被移除。如果你正在使用 React Navigation 版本 4，你需要升级到版本 5 或更新版本。
RoutingInstrumentation 在 SDK 的版本 6 中已被移除。如果你正在使用自定义导航，请使用 startIdleNavigationSpan 函数。
- const routingInstrumentation = new Sentry.RoutingInstrumentation();
Sentry.init({
tracesSampleRate: 1.0,
integrations: [
- new Sentry.ReactNativeTracing({
- routingInstrumentation,
- }),
],
})
const App = () => {
<SomeNavigationLibrary
onRouteWillChange={(newRoute) => {
- routingInstrumentation.onRouteWillChange({
+ Sentry.startIdleNavigationSpan({
name: newRoute.name,
op: 'navigation'
});
}}
/>
};
beforeNavigate 选项在 SDK 的版本 6 中已被移除。请改用 beforeStartSpan 选项。beforeStartSpan 选项是在启动导航 span 之前调用的函数。此函数无法阻止 span 启动，但可以在启动前修改 span 的启动选项。
Sentry.init({
tracesSampleRate: 1.0,
integrations: [
- new Sentry.ReactNativeTracing({
- beforeNavigate: (context) => {
+ Sentry.reactNativeTracingIntegration({
+ beforeStartSpan: (options) => {
return {
...options,
op: 'navigation',
};
},
}),
],
});
enableSpotlight 和 spotlightSidecarUrl 选项在 SDK 的版本 6 中已被移除。请改用 spotlight 选项。
import * as Sentry from '@sentry/react-native';
Sentry.init({
tracesSampleRate: 1.0,
- enableSpotlight: true,
- spotlightSidecarUrl: 'http://localhost:8969/stream',
+ spotlight: true // or 'http://localhost:8969/stream',
});
idleTimeout 和 maxTransactionDuration 选项在 SDK 的版本 6 中已被移除。请改用 JavaScript SDK 中的 idleTimeoutMs 和 finalTimeoutMs 选项。
import * as Sentry from '@sentry/react-native';
Sentry.init({
tracesSampleRate: 1.0,
integrations: [
- new Sentry.ReactNativeTracing({
- idleTimeout: 1_000,
- maxTransactionDuration: 5_000,
+ Sentry.reactNativeTracingIntegration({
+ idleTimeoutMs: 1_000,
+ finalTimeoutMs: 5_000,
}),
],
});
我们更新了当未定义 tracePropagationTargets 选项时 SDK 的行为。作为提醒，你可以提供一个字符串或正则表达式的列表，这些将与 URL 匹配，以告知 SDK 应该为哪些传出请求附加跟踪 HTTP 头。这些跟踪头用于分布式跟踪。
以前，在浏览器和 React Native 中，当 tracePropagationTargets 未定义时，默认值为： ['localhost', /^\/(?!\/)/]。这意味着所有包含 "localhost" 或以 / 开头的请求目标都会附带跟踪头。这个默认值是为了防止浏览器应用程序中的 CORS 错误。然而，这个默认值存在一些问题。
从现在开始，当未设置 tracePropagationTargets 选项时：
- 在 React Native 中，跟踪头将附加到所有传出请求
- 在浏览器（包括 WebViews）中，跟踪头也将附加到与当前源相同的传出请求
例如，如果你在 https://example.com/ 并发送请求到 https://example.com/api，该请求将被跟踪（换句话说，它将附带跟踪头）。另一方面，发送到 https://api.example.com/ 的请求不会被跟踪，因为它们属于不同的源。同样适用于所有运行在 localhost 上的应用程序。
当你提供 tracePropagationTargets 选项时，你定义的所有条目现在将与传出请求的完整 URL 进行匹配。以前，只与你调用请求 API 时提供的部分进行匹配。例如，如果你发起一个 fetch("/api/posts") 请求，提供的 tracePropagationTargets 只与 "/api/posts" 进行比较。