从 7.x 迁移到 8.x

了解如何从 Sentry JavaScript SDK 7.x 迁移到 8.x

8.x 版本的主要目标是改进我们的性能监控 API、集成 API 和 ESM 支持。此版本包含破坏性更改，因为我们移除了已弃用的 API，重构了 npm 包内容，并引入了对 OpenTelemetry 的新依赖。

在升级到 8.x SDK 之前，我们建议先升级到 7.x 的最新版本。要修复 7.x 中的大部分弃用问题，您可以使用 @sentry/migr8 codemod 自动更新您的 SDK 使用方式。@sentry/migr8 需要 Node 18+。

Copied
npx @sentry/migr8@latest

我们的迁移工具将允许您选择要运行的更新，并自动更新您的代码。在某些情况下，我们无法自动为您更改代码。这些情况将被标记为 TODO(sentry) 注释。请确保在运行 @sentry/migr8 后审查所有代码更改！有关弃用的更多详细信息，请参阅我们关于 7.x 中的弃用 的文档。尽管有 @sentry/migr8，我们仍然建议阅读迁移指南，因为 @sentry/migr8 并不涵盖所有需要的迁移更改。

8.x 简化了 Sentry SDK 的初始化，并进行了多项内部改进。

我们建议您阅读所有 重要更改，因为这些更改影响所有 SDK 用户。下面链接的 其他更改 仅影响具有更自定义 instrumentation 的用户。还有一个 故障排除 部分，涵盖了常见问题。

我们还在 GitHub 上提供了一份 详细的迁移指南，其中包含了所有更改的综合列表以及 SDK 的源代码。

SDK 现在需要 ES2018 兼容性以及对 globalThis 的支持。最低支持的浏览器版本为：

  • Chrome 71
  • Edge 79
  • Safari 12.1，iOS Safari 12.2
  • Firefox 65
  • Opera 58
  • Samsung Internet 10

对于 IE11 支持，请使用 Babel 或类似工具将代码编译为 ES5，并添加所需的 polyfills。

追踪的自定义 instrumentation API 在 8.x 中进行了彻底改造。引入了新方法，并移除了 startTransaction 和 span.startChild。更多信息请参阅 新的追踪 API 文档。

@sentry/replay 包不再需要。相反，您可以直接从 SDK 导入相关方法。此外，集成现在是函数式的，而不是基于类的。

Copied
-import { Replay } from '@sentry/replay';
-
 Sentry.init({
   dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
   integrations: [
-    new Replay(),
+    Sentry.replayIntegration(),
   ],
 });

Replay 选项 unblock 和 unmask 现在默认值为 []。这意味着如果您想使用这些选项，您需要显式地设置它们，例如：

Copied
Sentry.init({
  integrations: [
    Sentry.replayIntegration({
      unblock: [".sentry-unblock, [data-sentry-unblock]"],
      unmask: [".sentry-unmask, [data-sentry-unmask]"],
    }),
  ],
});

通过 makeXHRTransport 的 xhr 传输已被移除。现在仅提供 makeFetchTransport。这意味着 Sentry SDK 需要环境中支持 fetch API。

Offline 集成已被移除，取而代之的是 离线传输包装器。

Sentry.wrap 导出已被移除，没有替代的 API。

我们更新了当未定义 tracePropagationTargets 选项时 SDK 的行为。作为提醒，您可以提供一个字符串或正则表达式的列表，这些将与 URL 匹配，以告诉 SDK 应该向哪些传出请求附加追踪 HTTP 头。这些追踪头用于分布式追踪。

以前，在浏览器中，当未定义 tracePropagationTargets 时，默认值为 ['localhost', /^\/(?!\/)/]。这意味着所有目标 URL 包含 "localhost" 或以 / 开头的请求都会附带追踪头。这个默认值是为了防止浏览器应用程序中的 CORS 错误。然而，这个默认值存在一些问题。

从现在起，当未设置 tracePropagationTargets 选项时，追踪头将仅附加到同源的所有传出请求。例如，如果您在 https://example.com/ 上，并发送请求到 https://example.com/api，该请求将被追踪（即会附带追踪头）。发送到 https://api.example.com/ 的请求不会被追踪，因为它属于不同的源。同样适用于所有运行在 localhost 上的应用程序。

当您提供了 tracePropagationTargets 选项时，所有定义的条目现在将与传出请求的完整 URL 进行匹配。以前，它只与您调用请求 API 时提供的路径进行匹配。例如，如果您发起一个类似 fetch("/api/posts") 的请求，提供的 tracePropagationTargets 之前只会与 "/api/posts" 进行比较。

到目前为止，Hub 一直是 Sentry SDK API 中非常重要的一部分。Hubs 是 SDK 的“并发单元”，用于在不同线程之间跟踪数据，并将数据作用域限定在代码的某些部分。由于它过于复杂且容易让高级用户感到困惑，它将被一组新的 API（即“新的 Scope API”）所取代。目前，Hub 和 getCurrentHub 仍然可用，但在下一个主要版本中将被移除。

有关如何替换现有 Hub API 使用的详细信息，请参阅 弃用 Hub。

在 v7 中，集成是类，并可以像 integrations: [new Sentry.Replay()] 这样添加。在 v8 中，集成将不再是类，而是函数。使用类的方式以及从 Integrations.XXX 哈希中访问集成的方式已被弃用，取而代之的是使用新的函数式集成。例如，new Integrations.LinkedErrors() 变为 linkedErrorsIntegration()。

有关集成及其替代方案的列表，请参阅 7.x 弃用文档。

顶级 Sentry.configureScope 函数已被移除。相反，您应该使用 Sentry.getCurrentScope() 来访问和修改当前的作用域。

Copied
- Sentry.configureScope((scope) => {
-  scope.setTag("key", "value");
- });
+ Sentry.getCurrentScope().setTag("key", "value");

tracingOrigins 现已移除，取而代之的是 tracePropagationTargets 选项。tracePropagationTargets 选项应在 Sentry.init() 的选项中设置，或者在您创建自定义 Client 时在其选项中设置。

Copied
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [Sentry.browserTracingIntegration()],
  tracePropagationTargets: ["localhost", "example.com"],
});

在 7.x 中，您需要通过将 _experiments 选项设置为 { metricsAggregator: true } 来启用 metrics 聚合器。此外，在浏览器环境中，您还需要将 metricsAggregatorIntegration 添加到 integrations 数组中。

Copied
// v7 - Server (Node/Deno/Bun)
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  _experiments: {
    metricsAggregator: true,
  },
});

// v7 - Browser
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [Sentry.metricsAggregatorIntegration()],
});

Sentry.metrics.increment("my_metric");

在 8.x 中，使用 metrics API 不需要额外的配置。

Copied
// v8
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});

Sentry.metrics.increment("my_metric");

在 7.x 中，我们弃用了 Severity 枚举，转而使用 SeverityLevel 类型，这有助于减少打包大小。这一枚举在 8.x 中已被移除。您现在应直接使用 SeverityLevel 类型。

Copied
- import { Severity } from '@sentry/types';
+ import { SeverityLevel } from '@sentry/types';

- const level = Severity.error;
+ const level: SeverityLevel = "error";

在 8.x 中，我们移除了 spanStatusfromHttpCode 函数，转而使用 getSpanStatusFromHttpCode。

Copied
- const spanStatus = spanStatusfromHttpCode(200);
+ const spanStatus = getSpanStatusFromHttpCode(200);

具有 framesToPop 属性的错误将从堆栈顶部移除指定数量的帧。这与 v7 中的行为不同，在 v7 中，framesToPop 属性用于从堆栈字符串中移除顶部 n 行。

在 8.x 中，我们不再从 SDK 包中导出 Span 类。内部现在称这个类为 SentrySpan，并且不再打算让用户直接使用它。

Transport 接口上的 send 方法现在总是要求在 promise 中返回一个 TransportMakeRequestResponse。这意味着不再允许 void 返回类型。

Copied
// v7
 interface Transport {
-  send(event: Event): Promise<void | TransportMakeRequestResponse>;
+  send(event: Event): Promise<TransportMakeRequestResponse>;
 }

extraErrorDataIntegration 集成现在默认会查看 error.cause。

transactionContext 不再传递给 tracesSampler 回调函数，取而代之的是，回调函数将直接接收 name 和 attributes。请注意，attributes 仅包含在创建 span 时的属性，某些属性可能只会在 span 生命周期的后期设置（因此在采样期间不可用）。

如果调用了 Sentry.init()，getClient() 现在始终返回一个客户端。对于可能用于检查 Sentry 是否实际初始化的情况，使用 getClient() 将不再起作用。相反，您应该使用新的 Sentry.isInitialized() 工具来检查这一点。

在 8.x 中，我们移除了 addGlobalEventProcessor 函数，转而使用 addEventProcessor。

Copied
- Sentry.addGlobalEventProcessor((event) => {
+ Sentry.getGlobalScope().addEventProcessor((event) => {
   delete event.extra;
   return event;
 });

@sentry/integrations 已被移除，将不再发布。我们已将可插拔集成从其独立包 (@sentry/integrations) 移动到 @sentry/browser。此外，它们现在是函数而不是类。

集成仍然可以通过 CDN 获取，但它们将以函数形式暴露，而不是类，如下所示。

现在从 @sentry/browser 导出的客户端初始化集成包括：

  • httpClientIntegration (HTTPClient)
  • contextLinesIntegration (ContextLines)
  • reportingObserverIntegration (ReportingObserver)
  • captureConsoleIntegration (CaptureConsole)
  • debugIntegration (Debug)
  • extraErrorDataIntegration (ExtraErrorData)
  • rewriteFramesIntegration (RewriteFrames)
  • sessionTimingIntegration (SessionTiming)
  • dedupeIntegration (Dedupe) - 注意：默认启用，不可插拔

Transaction 集成已从 @sentry/integrations 中移除，没有替代的 API。

如果您在 Sentry SDK 中遇到错误，提示它尝试访问某些不可用的函数，例如 "... is not a function"，可能是安装了不匹配的版本。

Sentry JavaScript 打包插件（@sentry/webpack-plugin、@sentry/vite-plugin、@sentry/esbuild-plugin、@sentry/rollup-plugin）以前依赖于特定版本 7 的 Sentry SDK 包，这可能会与版本 8 的 SDK 发生冲突。

建议将 JavaScript 打包插件包升级到至少版本 2.14.2，这样将不再包含对版本 7 的 Sentry JavaScript SDK 的依赖。

Previous
迁移指南
Next
新的追踪 API
粤ICP备18022507号-4