ref(js): Rewrite outdated "Transaction Name" documentation #12091
+120
−16
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
2 Skipped Deployments
|
Lms24
force-pushed
the
lms/feat-updateSpanName
branch
from
99ec67e to
e5d3f66
Compare
Bundle ReportChanges will decrease total bundle size by 255.91kB (-1.26%) ⬇️. This is within the configured threshold ✅ Detailed changes
|
3 tasks
Lms24
commented
Dec 11, 2024
docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx
Outdated
Show resolved
Hide resolved
lizokm
approved these changes
Dec 12, 2024
| @@ -1,19 +1,37 @@ | |||
| --- | |||
| 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 trace grouping." | |||
There was a problem hiding this comment.
Suggested change
| 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." |
Comment on lines
+11
to
+12
| The Sentry SDK sets a "transaction name" which is used to annotate error events with their point of failure. | ||
| Furthermore, if you use <PlatformLink to="/tracing/">Tracing</PlatformLink>, Sentry refers to the root spans of your application as a "transaction" and groups traces based on the root span's "transaction" name. |
There was a problem hiding this comment.
Suggested change
| The Sentry SDK sets a "transaction name" which is used to annotate error events with their point of failure. | |
| Furthermore, if you use <PlatformLink to="/tracing/">Tracing</PlatformLink>, 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 <PlatformLink to="/tracing/">Tracing</PlatformLink>, Sentry will also mark the root span in your application with a _root span transaction name_, which will group traces around that name. |
Comment on lines
+14
to
+19
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. |
Comment on lines
+20
to
+26
|
|
||
| <PlatformCategorySection supported={['browser']}> | ||
|
|
||
| You need to add `browserTracingIntegration` when initializing the SDK to automatically set a transaction name. | ||
|
|
||
| </PlatformCategorySection> | ||
|
|
There was a problem hiding this comment.
Suggested change
| <PlatformCategorySection supported={['browser']}> | |
| You need to add `browserTracingIntegration` when initializing the SDK to automatically set a transaction name. | |
| </PlatformCategorySection> |
Comment on lines
+27
to
+34
| 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: |
There was a problem hiding this comment.
Suggested change
| 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: | |
| 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: |
Comment on lines
+131
to
+133
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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. |
Comment on lines
+135
to
+137
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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). |
Comment on lines
+139
to
+141
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. |
I understand why you added it, but I'm not sure this section is necessary. I think it might add more confusion. But let me know if you disagree :)
| @@ -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. | |||
There was a problem hiding this comment.
Suggested change
| 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. |
s1gr1d
approved these changes
Dec 13, 2024
|
|
||
| ## Setting the Error Transaction Name | ||
|
|
||
| There are several ways to set the transaction name for error events sent to Sentry. |
There was a problem hiding this comment.
In "Setting the Root Span Name", you mention where this name is displayed and used for. You could include this information here as well.
|
|
||
| ## 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 was a problem hiding this comment.
Maybe specify where in the Sentry UI it is used.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
This PR rewrites the "Enriching Events"->"Transaction Name" page which is was fairly outdated and misleading for JavaScript.
Most importantly, it now mentions that
scope.setTransactionNameonly applies to error events and has nothing to do with spans and root span names. The page now disambiguates the two concepts and lists ways how to update both names individually.As an experiment, I added a "Further Information" section at the bottom of the page which tries to explain the historic context of why these two names are convoluted and appear ambiguous. I'm happy to remove this but this question and the confusion around the two names is coming up repeatedly on GitHub, in Discord as well as internally. While reviewing, feel free to let me know your thoughts if we should keep the section or reword it.
I decided to rewrite this page while triaging an older issue in the SDK repo where the two names were mixed up multiple times.
closes getsentry/sentry-javascript#13391
IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
LEGAL BOILERPLATE
Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.
EXTRA RESOURCES