feat(javascript): Document new startNewTrace API
#10146
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Bundle ReportChanges will decrease total bundle size by 12 bytes ⬇️
|
|
|
||
| </PlatformCategorySection> | ||
|
|
||
| <PlatformCategorySection supported={["server"]}> |
There was a problem hiding this comment.
m: Should we instead make this notSupported={['browser']}? There is also serverless which I think is not covered by either of these 🤔
There was a problem hiding this comment.
Oh I had no idea that serverless isn't covered by "server". Good to know!
Yup, will change it to notSupported then.
There was a problem hiding this comment.
Oh, so turns out, <PlatformCategorySection> doesn't have a notSupported prop. So for now I just added serverless here. Tbh, this feels like a huge footgun to me. Historically we always assumed serverless===server in docs. I'm afraid we have some places where we should include serverless but don't exactly for this reason. I'll see if there's a simple improvement we can make here...
platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| In the browser, the SDK automatically starts a new trace in the following situation: | ||
|
|
||
| - On page load: Whenever the page is (re-)loaded, a new trace is started. At the same time, a `pageload` span is created (see <PlatformLink to="/performance/instrumentation/automatic-instrumentation">Performance Monitoring</PlatformLink>). Once this span ends, the trace remains until the next navigation or page load. In case the server serving the initial page already started a trace and sent the necessary [HTML tags](./custom-instrumentation/#extract-tracing-information-from-html-meta-tags) to the browser, the SDK will continue this trace instead of starting a new one. |
There was a problem hiding this comment.
In the performance monitoring link, it says that a new transaction (not trace) is started on page load and navigation. We should update that page as well to refer to trace not transaction?
There was a problem hiding this comment.
In a way both is true but the wording is not optimal. We want to phase out mentioning "transaction" at all because our SDK no longer exposes transaction in a public API. Likewise, the product is also moving more towards spans. So instead of a pageload transaction, the SDK creates a pageload span.
Additionally, the SDK also starts a trace to which the span is associated to. I hope that makes sense
| In the browser, the SDK automatically starts a new trace in the following situation: | ||
|
|
||
| - On page load: Whenever the page is (re-)loaded, a new trace is started. At the same time, a `pageload` span is created (see <PlatformLink to="/performance/instrumentation/automatic-instrumentation">Performance Monitoring</PlatformLink>). Once this span ends, the trace remains until the next navigation or page load. In case the server serving the initial page already started a trace and sent the necessary [HTML tags](./custom-instrumentation/#extract-tracing-information-from-html-meta-tags) to the browser, the SDK will continue this trace instead of starting a new one. | ||
| - On navigation: Whenever a user navigates (for example in a single-page application), a new trace is started. At the same time, a `navigation` span is created (see <PlatformLink to="/performance/instrumentation/automatic-instrumentation">Performance Monitoring</PlatformLink>). Once this span ends, the trace remains until the next navigation or page load. |
There was a problem hiding this comment.
I'm not sure what "navigation" here means and what differentiates it from a page load. Is this referring to scrolling within the same page and the URL changes? Otherwise, when you navigate within a site to another page, isn't that a page load?
There was a problem hiding this comment.
This is a bit tricky indeed. We're generally differentiating like so:
- page load: The browser actually loads a new html page. For example when you first go to a website or when you reload it. And yes, you're right, in some cases (depending on the chosen technology), clicking on a link to a different page within the same site/domain will also cause the browser to load a completely new page. So this is conceptually also a "navigation" but technically a pageload. You can generally call this type of web application Multi-Page Applications.
- navigation: The URL of the browser changes but without the browser reloading the entire page. This is what a lot of Single Page Applications, like a React app, do. They have "one" HTML page but its content and the associated URL path change as the user navigates through the application. So for SPAs, loading the first time is a pageload and every further navigation is what we refer to here as a navigation.
| - On page load: Whenever the page is (re-)loaded, a new trace is started. At the same time, a `pageload` span is created (see <PlatformLink to="/performance/instrumentation/automatic-instrumentation">Performance Monitoring</PlatformLink>). Once this span ends, the trace remains until the next navigation or page load. In case the server serving the initial page already started a trace and sent the necessary [HTML tags](./custom-instrumentation/#extract-tracing-information-from-html-meta-tags) to the browser, the SDK will continue this trace instead of starting a new one. | ||
| - On navigation: Whenever a user navigates (for example in a single-page application), a new trace is started. At the same time, a `navigation` span is created (see <PlatformLink to="/performance/instrumentation/automatic-instrumentation">Performance Monitoring</PlatformLink>). Once this span ends, the trace remains until the next navigation or page load. | ||
|
|
||
| In both cases, this means that if you start spans after the automatic `pageload` and `navigation` spans ended, they will still be part of the same trace. This makes it easy to connect what happened before and after your span. |
There was a problem hiding this comment.
I think what's missing for me is a description of what causes a trace to end.
There was a problem hiding this comment.
From the paragraphs above: "the trace remains until the next navigation or page load"
So IOW, the span only ends when users reload the page or navigate to another part of the page. Does this make sense?
platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx
Outdated
Show resolved
Hide resolved
Co-authored-by: vivianyentran <[email protected]>
See getsentry/sentry-javascript#12138 for details.