From 5e1b85f216f3287f37ce57101203b68711cf4cba Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 11 Dec 2024 11:28:27 +0100 Subject: [PATCH 1/8] ref(js): Rewrite outdated "Transaction Name" documentation --- .../transaction-name/index.mdx | 131 ++++++++++++++++-- .../set-transaction-name/javascript.mdx | 3 - .../beforeNavigate-example/javascript.mdx | 2 +- 3 files changed, 120 insertions(+), 16 deletions(-) delete mode 100644 platform-includes/enriching-events/set-transaction-name/javascript.mdx diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 524482e94dce1..98f5286ef8e44 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -1,6 +1,6 @@ --- title: Transaction Name -description: "Learn how to set or override the transaction name to capture the user and gain critical pieces of information that construct a unique identity in Sentry." +description: "Learn how to set or override the transaction name to improve issue and span grouping." supported: - javascript notSupported: @@ -8,12 +8,30 @@ notSupported: - javascript.nextjs --- -The current transaction name is used to group transactions in our -[Performance](/product/performance/) product, as well as annotate error events -with their point of failure. +The Sentry SDK sets a "transaction name" which is used to annotate error events with their point of failure. +Furthermore, if you use Tracing, Sentry refers to the root spans of your application as a "transaction" and groups traces based on the root span's "transaction" name. -The transaction name can reference the current web app route, or the current -task being executed. For example: +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. + + + +You need to add `browserTracingIntegration` when initializing the SDK to automatically set a transaction name. + + + +Generally, **you don't need to set or override the transaction name manually.** +In most cases, the automatically determined name is a good grouping mechanism. +However, if this does not work for your use case, you can set both transaction names independently. + +## What is a "Good" Transaction Name? + +The 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` @@ -22,15 +40,104 @@ task being executed. For example: Ideally, the transaction name does not contain variable values such as user IDs but has rather low cardinality while still uniquely identifying a piece of code you care about. +For example, instead of `'GET /api/users/123/details'`, set `'GET /api/users/:id/details'`. +This ensures that errors or traces for all requests made to this route are grouped together. + +### When to set the Transaction Name + +We generally recommend to let the SDK set the transaction name automatically. +However, in some cases, the SDK might not be able to set a name or the set name doesn't work for your use case. + +If you need to set the transaction name manually, we recommend setting it _as early as possible_ in your application code, specifically when the operation you want to describe with the transaction name starts. +This ensures that errors thrown early in the life cycle of your application are correctly annotated. +Furthermore, it ensures consistency across a trace if you use [distributed tracing](/concepts/key-terms/tracing/distributed-tracing/). + +For example, in a server application, you might set the transaction name in a middleware that runs before the request is processed. +In a web application, you might set the transaction name when you enter a new route (e.g. in an SPA Router). + +## Setting the Error Transaction Name + +There are several ways to set the transaction name for error events sent to Sentry. + +### Setting the Name on the Scope + +Set the transaction name on the current scope when the operation you want to group starts: + +```javascript +Sentry.getCurrentScope().setTransactionName("UserListView"); +``` + +Note that the transaction name on the scope is only applied to error events. It does not influence the name of a potentially active root span. +Likewise, if a span is active while an error is thrown, its name will not be applied to the error event's transaction name. + +### Setting the Name on the Event + +You can use `beforeSend` to set the transaction name on the event: + +```javascript {3} +Sentry.init({ + beforeSend(event) { + event.transaction = "UserListView"; + return event; + }, +}); +``` + +## Setting the Root Span Name + +To override the name of the root span name (i.e. the trace name or transaction name in the Sentry UI), you have multiple options: + + + +### 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. +If you want to override the transaction name, you can do so in the `beforeStartSpan` callback of the integration. + + + +### While the root span is active + +_Available since: v8.44.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 but a little bit later. In this case, you can update the root span name while the span is active: + +```javascript +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 finished + +If you cannot determine the root span name before the span finishes, you can retroactively change it in `beforeSendTransaction`: + +```javascript +Sentry.init({ + beforeSendTransaction(event) { + event.transaction = "UserListView"; + return event; + }, +}); +``` -A lot of our framework integrations already set a transaction name, though you can set one yourself. +We recommend to only do this, if you cannot use any of the other options to set the root span name earlier. -You'll first need to import the SDK, as usual: +## Further Information - +You might be wondering why these two types of transaction names exist and why they are set independently. +The reason is mostly historic evolvement of the Sentry product and the SDKs. +The error transaction name existed long before Sentry provided tracing capabilities and where it was only applied to error events to better group issues. -To override the name of the currently running transaction: +In the first iteration of Sentry's tracing or performance monitoring product, we decided to call the root span of a span tree within an application a "Transaction", which also had a name. +In the second, now ongoing, tracing iteration, Sentry's new UI features no longer mention "Transactions" for root spans but rather just "spans" and "traces". +However, the two concepts (error transaction name and root span name) are still ambiguous and used so throughout various older parts of the Sentry UI. - +With this product evolvement in mind, the SDKs also had to adapt their APIs around tracing, specifically moving away from transaction-based APIs in version 8. +Consequently, the SDK exposes the `setTransactionName` API on the `Scope` which—although the name might suggest differently from historic context—has nothing to do with spans. +Likewise, the span name is not automatically applied to error events either, meaning both concepts are completely [decoupled](https://github.com/getsentry/sentry-javascript/issues/10846) from each other. -Please refer to [the tracing documentation](../../tracing/) for how to start and stop transactions. +We believe that the ambiguity of these APIs will decrease over time as the Sentry product further moves away from associating the "Transaction" term with tracing and spans. diff --git a/platform-includes/enriching-events/set-transaction-name/javascript.mdx b/platform-includes/enriching-events/set-transaction-name/javascript.mdx deleted file mode 100644 index 6e4b48571cd19..0000000000000 --- a/platform-includes/enriching-events/set-transaction-name/javascript.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```javascript -Sentry.getCurrentScope().setTransactionName("UserListView"); -``` diff --git a/platform-includes/performance/beforeNavigate-example/javascript.mdx b/platform-includes/performance/beforeNavigate-example/javascript.mdx index b40561922c8b5..d80dcca930bc6 100644 --- a/platform-includes/performance/beforeNavigate-example/javascript.mdx +++ b/platform-includes/performance/beforeNavigate-example/javascript.mdx @@ -1,4 +1,4 @@ -One common use case is parameterizing transaction names. For both `pageload` and `navigation` transactions, the `BrowserTracing` integration uses the browser's `window.location` value to generate a transaction name. Using `beforeStartSpan` lets you modify the transaction name to make it more generic, so that, for example, transactions named `GET /users/12312012` and `GET /users/11212012` can both be renamed to `GET /users/:userid`. That way they'll be grouped together. +One common use case is parameterizing transaction names. For both `pageload` and `navigation` transactions, the `browserTracingIntegration` uses the browser's `window.location` value to generate a transaction name. Using `beforeStartSpan` lets you modify the transaction name to make it more generic, so that, for example, transactions named `GET /users/12312012` and `GET /users/11212012` can both be renamed to `GET /users/:userid`. That way they'll be grouped together. ```javascript Sentry.init({ From baa99409647a9c83ec656edff0bb75ce312b9665 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 11 Dec 2024 11:41:26 +0100 Subject: [PATCH 2/8] Update docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx --- .../common/enriching-events/transaction-name/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 98f5286ef8e44..5d4db11cc3ee6 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -1,6 +1,6 @@ --- title: Transaction Name -description: "Learn how to set or override the transaction name to improve issue and span grouping." +description: "Learn how to set or override the transaction name to improve issue and trace grouping." supported: - javascript notSupported: From 69acbaf32a533d44725594d3fa1552764deff8e9 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 16 Dec 2024 11:49:25 +0100 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Liza Mock --- .../transaction-name/index.mdx | 64 ++++++++----------- .../beforeNavigate-example/javascript.mdx | 2 +- 2 files changed, 27 insertions(+), 39 deletions(-) diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 5d4db11cc3ee6..d768a5fed110f 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -24,36 +24,29 @@ You need to add `browserTracingIntegration` when initializing the SDK to automat -Generally, **you don't need to set or override the transaction name manually.** -In most cases, the automatically determined name is a good grouping mechanism. -However, if this does not work for your use case, you can set both transaction names independently. +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 is a "Good" Transaction Name? +## What's a "Good" Transaction Name? -The transaction name can reference the current web app or server route, mobile screen or activity, or the current task being executed. +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` -Ideally, the transaction name does not contain variable values such as user -IDs but has rather low cardinality while still uniquely identifying a piece of -code you care about. -For example, instead of `'GET /api/users/123/details'`, set `'GET /api/users/:id/details'`. -This ensures that errors or traces for all requests made to this route are grouped together. +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 +### When to Set the Transaction Name -We generally recommend to let the SDK set the transaction name automatically. -However, in some cases, the SDK might not be able to set a name or the set name doesn't work for your use case. +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. -If you need to set the transaction name manually, we recommend setting it _as early as possible_ in your application code, specifically when the operation you want to describe with the transaction name starts. -This ensures that errors thrown early in the life cycle of your application are correctly annotated. -Furthermore, it ensures consistency across a trace if you use [distributed tracing](/concepts/key-terms/tracing/distributed-tracing/). +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](/concepts/key-terms/tracing/distributed-tracing/). -For example, in a server application, you might set the transaction name in a middleware that runs before the request is processed. -In a web application, you might set the transaction name when you enter a new route (e.g. in an SPA Router). +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 @@ -67,8 +60,7 @@ Set the transaction name on the current scope when the operation you want to gro Sentry.getCurrentScope().setTransactionName("UserListView"); ``` -Note that the transaction name on the scope is only applied to error events. It does not influence the name of a potentially active root span. -Likewise, if a span is active while an error is thrown, its name will not be applied to the error event's transaction name. +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 @@ -85,22 +77,22 @@ Sentry.init({ ## Setting the Root Span Name -To override the name of the root span name (i.e. the trace name or transaction name in the Sentry UI), you have multiple options: +There are multiple options for overriding the root span name (for example, the trace or transaction name in the Sentry UI): ### 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. -If you want to override the transaction name, you can do so in the `beforeStartSpan` callback of the integration. +To override the transaction name, use the `beforeStartSpan` callback of the integration. -### While the root span is active +### While the Root Span Is Active -_Available since: v8.44.0_ +_Available starting with: v8.44.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 but a little bit later. In this case, you can update the root span name while the span is active: +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: ```javascript const activeSpan = Sentry.getActiveSpan(); @@ -111,9 +103,9 @@ Sentry.updateSpanName(rootSpan, "UserListView"); Learn more about updating the span name. -### After the root span finished +### After the Root Span Has Finished -If you cannot determine the root span name before the span finishes, you can retroactively change it in `beforeSendTransaction`: +If you can't determine the root span name before the span finishes, you'll be able to change it retroactively in `beforeSendTransaction`: ```javascript Sentry.init({ @@ -124,20 +116,16 @@ Sentry.init({ }); ``` -We recommend to only do this, if you cannot use any of the other options to set the root span name earlier. + +Only do this if you can't set the root span name earlier using other options. + ## Further Information -You might be wondering why these two types of transaction names exist and why they are set independently. -The reason is mostly historic evolvement of the Sentry product and the SDKs. -The error transaction name existed long before Sentry provided tracing capabilities and where it was only applied to error events to better group issues. -In the first iteration of Sentry's tracing or performance monitoring product, we decided to call the root span of a span tree within an application a "Transaction", which also had a name. -In the second, now ongoing, tracing iteration, Sentry's new UI features no longer mention "Transactions" for root spans but rather just "spans" and "traces". -However, the two concepts (error transaction name and root span name) are still ambiguous and used so throughout various older parts of the Sentry UI. +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. -With this product evolvement in mind, the SDKs also had to adapt their APIs around tracing, specifically moving away from transaction-based APIs in version 8. -Consequently, the SDK exposes the `setTransactionName` API on the `Scope` which—although the name might suggest differently from historic context—has nothing to do with spans. -Likewise, the span name is not automatically applied to error events either, meaning both concepts are completely [decoupled](https://github.com/getsentry/sentry-javascript/issues/10846) from each other. +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](https://github.com/getsentry/sentry-javascript/issues/10846). -We believe that the ambiguity of these APIs will decrease over time as the Sentry product further moves away from associating the "Transaction" term with tracing and spans. + +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. diff --git a/platform-includes/performance/beforeNavigate-example/javascript.mdx b/platform-includes/performance/beforeNavigate-example/javascript.mdx index d80dcca930bc6..624e058bb141b 100644 --- a/platform-includes/performance/beforeNavigate-example/javascript.mdx +++ b/platform-includes/performance/beforeNavigate-example/javascript.mdx @@ -1,4 +1,4 @@ -One common use case is parameterizing transaction names. For both `pageload` and `navigation` transactions, the `browserTracingIntegration` uses the browser's `window.location` value to generate a transaction name. Using `beforeStartSpan` lets you modify the transaction name to make it more generic, so that, for example, transactions named `GET /users/12312012` and `GET /users/11212012` can both be renamed to `GET /users/:userid`. That way they'll be grouped together. +One common use case is parameterizing transaction names. For both `pageload` and `navigation` transactions, the `browserTracingIntegration` uses the browser's `window.location` value to generate a transaction name. Using `beforeStartSpan` lets you modify the transaction name to make it more generic, so that for example, transactions named `GET /users/12312012` and `GET /users/11212012` can both be renamed to `GET /users/:userid`. That way they'll be grouped together. ```javascript Sentry.init({ From 4818caf58108eb345f71135835fc8c6fb68ae1e1 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 16 Dec 2024 11:50:06 +0100 Subject: [PATCH 4/8] Update docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx Co-authored-by: Liza Mock --- .../common/enriching-events/transaction-name/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index d768a5fed110f..5709dcfda4e3b 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -1,6 +1,6 @@ --- title: Transaction Name -description: "Learn how to set or override the transaction name to improve issue and trace grouping." +description: "Learn how to set or override transaction names to improve issue and trace-grouping." supported: - javascript notSupported: From 34512e28215830b32f3e5fbc5eb43bac8fcad3fa Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 16 Dec 2024 11:56:35 +0100 Subject: [PATCH 5/8] further suggestions --- .../enriching-events/transaction-name/index.mdx | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 5709dcfda4e3b..1e9edaddfb09a 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -8,8 +8,7 @@ notSupported: - javascript.nextjs --- -The Sentry SDK sets a "transaction name" which is used to annotate error events with their point of failure. -Furthermore, if you use Tracing, Sentry refers to the root spans of your application as a "transaction" and groups traces based on the root span's "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: @@ -20,11 +19,11 @@ Both are used to annotate and group error and trace events respectively and are -You need to add `browserTracingIntegration` when initializing the SDK to automatically set a transaction name. +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.** +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? @@ -35,7 +34,7 @@ For example: - `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. +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. @@ -50,7 +49,7 @@ In a web app, you can set it when navigating to a new route, like in an SPA rout ## Setting the Error Transaction Name -There are several ways to set the transaction name for error events sent to Sentry. +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 @@ -117,15 +116,13 @@ Sentry.init({ ``` -Only do this if you can't set the root span name earlier using other options. + Only do this if you can't set the root span name earlier using other options. ## 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](https://github.com/getsentry/sentry-javascript/issues/10846). - 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. From 4a56229ef802ac877fab629bc710608dd10668d9 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 16 Dec 2024 11:59:07 +0100 Subject: [PATCH 6/8] further suggestion --- .../common/enriching-events/transaction-name/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 1e9edaddfb09a..d89ba78d8cced 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -76,7 +76,7 @@ Sentry.init({ ## Setting the Root Span Name -There are multiple options for overriding the root span name (for example, the trace or transaction name in the Sentry UI): +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): From a55d1f862c9fee0d6f3789a60840a13d7d0c410c Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 16 Dec 2024 16:35:22 +0100 Subject: [PATCH 7/8] Update docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx --- .../common/enriching-events/transaction-name/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index d89ba78d8cced..d7fee5ffc8e4f 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -89,7 +89,7 @@ To override the transaction name, use the