从 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 的源代码。

Sentry Angular SDK 8.x supports Angular Ivy by default and supports Angular version 14.0.0 or higher.

As a result, @sentry/angular-ivy has been removed in favor of @sentry/angular. If you are using Angular 13 or lower, we suggest upgrading your Angular version before migrating to 8.x. If you can't upgrade your Angular version to at least Angular 14, you can also continue using the 7.x of the @sentry/angular-ivy 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 文档。

The usage of TraceClassDecorator and the TraceMethodDecorator already implies that those are decorators. The word Decorator is now removed from the names to avoid multiple mentioning.

Additionally, the TraceClass and TraceMethod decorators accept an optional name parameter to set the transaction name. This was added because Angular minifies class and method names, and you might want to set a more descriptive name. If nothing provided, the name defaults to 'unnamed'.

Copied
// Before (7.x)
@Sentry.TraceClassDecorator()
export class HeaderComponent {
  @Sentry.TraceMethodDecorator()
  ngOnChanges(changes: SimpleChanges) {}
}

// After (8.x)
@Sentry.TraceClass({ name: 'HeaderComponent' })
export class HeaderComponent {
  @Sentry.TraceMethod({ name: 'ngOnChanges' })
  ngOnChanges(changes: SimpleChanges) {}
}

@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 has been removed and will no longer be published. We moved pluggable integrations from their own package (@sentry/integrations) to @sentry/angular. In addition they are now functions instead of classes.

Integrations that are now exported from @sentry/angular for client-side init:

  • httpClientIntegration (HTTPClient)
  • contextLinesIntegration (ContextLines)
  • reportingObserverIntegration (ReportingObserver)
  • captureConsoleIntegration (CaptureConsole)
  • debugIntegration (Debug)
  • extraErrorDataIntegration (ExtraErrorData)
  • rewriteFramesIntegration (RewriteFrames)
  • sessionTimingIntegration (SessionTiming)
  • dedupeIntegration (Dedupe) - Note: enabled by default, not pluggable

The Transaction integration has been removed from @sentry/integrations. There is no replacement 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