Transaction Name

The Sentry SDK uses an error transaction name to mark where something went wrong in an error event. If you use Tracing, Sentry uses the name of your root span as the root span transaction name, which will group traces around that name.

This means that there are in fact two transaction names:

1. The error transaction name which is applied to error events
2. The root span transaction name which is the name of the root span in your applications span tree.

Both are used to annotate and group error and trace events respectively and are usually set by the SDK or an integration automatically.

To automatically set transaction names, add browserTracingIntegration when initializing the SDK.

Because automatically-determined names are a good grouping mechanism, unless you have a special use-case, you won't need to set or override transaction names manually.

What's a "Good" Transaction Name?

Your transaction name can reference the current web app or server route, mobile screen or activity, or the current task being executed. For example:

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

A good transaction name shouldn't have too many variables (such as user IDs), but should still be unique enough to help you easily identify the piece of code you care about. For example, instead of naming a transaction'GET /api/users/123/details', name it 'GET /api/users/:id/details'. This will group all errors and traces for requests to the same route.

When to Set the Transaction Name

It's usually best to let the SDK set the transaction name automatically. However, if it can't or the name doesn't suit your needs, you can set it manually.

We recommend setting it as early as possible in your application code, ideally when the operation you want to track starts. This ensures that errors thrown early in the application lifecycle are annotated correctly and keeps traces consistent if you're using distributed tracing.

For example, in a server app, you can set the transaction name in middleware before handling a request. In a web app, you can set it when navigating to a new route, like in an SPA router.

Setting the Error Transaction Name

There are several ways to set the transaction name for error events sent to Sentry. This name will show up as the location of the issue next to the issue title.

Setting the Name on the Scope

Set the transaction name on the current scope when the operation you want to group starts:

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

The transaction name on the scope only applies to error events, not the active root span. Similarly, if an error happens during an active span, the span's name won’t be applied to the error's transaction name.

Setting the Name on the Event

You can use beforeSend to set the transaction name on the event:

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

Setting the Root Span Name

There are multiple options for overriding the root span name (this name shows up in the Sentry UI, for example when searching for traces or when in performance insights):

At Root Span Start

Sentry's browserTracingIntegration automatically sets the transaction name based on the current route or URL for all pageload and navigation transactions. To override the transaction name, use the beforeStartSpan callback of the integration.

While the Root Span Is Active

Available starting with: v8.47.0

Sometimes, (for example if you have a router that only emits the route change after it occurred) you might not be able to set the final root span name at span start. In this case, you can update the root span name while the span is active:

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

Sentry.updateSpanName(rootSpan, "UserListView");

Learn more about updating the span name.

After the Root Span Has Finished

If you can't determine the root span name before the span finishes, you'll be able to change it retroactively in beforeSendTransaction:

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

Further Information

You might wonder why there are two separate transaction names and why they're set independently. This is mainly due to Sentry's history and evolution. The error transaction name existed before Sentry offered tracing, and it was used solely to group error events. When tracing was introduced, the root span in a span tree was also called a "transaction," with its own name.

In later iterations, Sentry shifted focus in the UI from "transactions" to "spans" and "traces," but the older concepts remain in parts of the UI. The SDKs adapted their APIs, moving away from transaction-based designs. For example, the setTransactionName API on the Scope refers to error transaction names, not spans. Similarly, a span name doesn’t automatically apply to error events, keeping the two concepts separate.

As Sentry continues to evolve, the ambiguity between these terms is expected to decrease as the product moves away from associating "transactions" with tracing and spans.