事务名称

了解如何设置或覆盖事务名称以改进问题和跟踪分组。

Sentry SDK 使用 错误事务名称 来标记错误事件中出现问题的位置。如果您使用 跟踪,Sentry 会将根跨度的名称作为 根跨度事务名称,这将围绕该名称对跟踪进行分组。

这意味着实际上有两种事务名称:

  1. 应用于错误事件的 错误事务名称
  2. 您应用程序跨度树中的根跨度名称,即 根跨度事务名称

这两种名称分别用于标注和分组错误和跟踪事件,并且通常由 SDK 或集成自动设置。

要自动设置事务名称,在初始化 SDK 时添加 browserTracingIntegration

由于自动确定的名称是良好的分组机制,除非您有特殊需求,您无需手动设置或覆盖事务名称。

您的事务名称可以引用当前的 Web 应用或服务器路由、移动屏幕或活动,或当前正在执行的任务。例如:

  • GET /api/{version}/users/
  • UserListView
  • myapp.tasks.renew_all_subscriptions

一个好的事务名称不应包含过多的变量(如用户 ID),但仍应足够独特,以便帮助您轻松识别关心的代码部分。例如,不要将事务命名为 'GET /api/users/123/details',而应命名为 'GET /api/users/:id/details'。这将使所有对同一路由的请求的错误和跟踪进行分组。

通常最好让 SDK 自动设置事务名称。但是,如果 SDK 无法自动设置或生成的名称不符合您的需求,您可以手动设置。

我们建议尽可能早地在应用程序代码中设置事务名称,理想情况下是在您要跟踪的操作开始时设置。这可以确保在应用程序生命周期早期抛出的错误被正确标注,并保持跟踪的一致性(如果您使用 分布式跟踪)。

例如,在服务器应用程序中,您可以在处理请求之前在中间件中设置事务名称。 在 Web 应用程序中,您可以在导航到新路由时设置事务名称,例如在单页应用(SPA)路由器中。

有几种方法可以为发送到 Sentry 的错误事件设置事务名称。这个名称将显示为问题标题旁边的错误位置。

当您要分组的操作开始时,在当前作用域上设置事务名称:

Copied
Sentry.getCurrentScope().setTransactionName("UserListView");

作用域上的事务名称仅适用于错误事件,而不适用于活动的根跨度。同样,如果在活动跨度期间发生错误,跨度的名称也不会应用于错误的事务名称。

您可以使用 beforeSend 来为事件设置事务名称:

Copied
Sentry.init({
  beforeSend(event) {
    event.transaction = "UserListView";
    return event;
  },
});

有多种方法可以覆盖根跨度名称(此名称会在 Sentry UI 中显示,例如在搜索跟踪或在性能洞察中):

Sentry 的 browserTracingIntegration 会根据当前路由或 URL 自动为所有 pageloadnavigation 事务设置事务名称。 要覆盖事务名称,请使用集成的 beforeStartSpan 回调

从 v8.47.0 开始可用

有时(例如,如果您有一个仅在路由更改发生后才发出更改事件的路由器),您可能无法在跨度开始时设置最终的根跨度名称。在这种情况下,您可以在跨度活跃期间更新根跨度名称:

Copied
const activeSpan = Sentry.getActiveSpan();
const rootSpan = activeSpan && Sentry.getRootSpan(activeSpan);

Sentry.updateSpanName(rootSpan, "UserListView");

了解更多关于 更新跨度名称 的信息。

如果您无法在跨度结束前确定根跨度名称,您可以在 beforeSendTransaction 中追溯性地更改它:

Copied
Sentry.init({
  beforeSendTransaction(event) {
    event.transaction = "UserListView";
    return event;
  },
});

仅在无法使用其他方法提前设置根跨度名称时才这样做。

您可能会疑惑为什么存在两个独立的事务名称,以及它们为何分别设置。这主要是由于 Sentry 的历史和发展。错误事务名称在 Sentry 提供跟踪功能之前就已经存在,仅用于分组错误事件。当引入跟踪功能时,跨度树中的根跨度也被称为“事务”,并有自己的名称。

在后续迭代中,Sentry 在 UI 中将重点从“事务”转移到“跨度”和“跟踪”,但旧的概念仍然存在于 UI 的某些部分。SDK 的 API 也进行了适应性调整,逐渐远离基于事务的设计。例如,Scope 上的 setTransactionName API 指的是错误事务名称,而不是跨度。同样,跨度名称不会自动应用于错误事件,这两个概念保持 分离

随着 Sentry 的不断发展,这些术语之间的模糊性预计将减少,产品也将逐渐不再将“事务”与跟踪和跨度关联。