feat(javascript): Document new startNewTrace API (#10146)

--------

Co-authored-by: Francesco Novy <[email protected]>
Co-authored-by: vivianyentran <[email protected]>

Author: 3 people

docs/platforms/javascript/common/distributed-tracing/index.mdx

@@ -29,6 +29,30 @@ What happens in the background is that Sentry uses reads and further propagates
 
 If you run any JavaScript applications in your distributed system, make sure that those two headers are added to your CORS allowlist and won't be blocked or stripped by your proxy servers, gateways, or firewalls.
 
+## Trace Duration
+
+<PlatformCategorySection supported={["browser"]}>
+
+In the browser, the SDK automatically starts a new trace in the following situations:
+
+- 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.
+
+</PlatformCategorySection>
+
+<PlatformCategorySection supported={["server", "serverless"]}>
+
+Server-side SDKs handle traces automatically on a per-request basis. This means that SDKs will:
+
+- Continue an existing trace if the incoming request contains a trace header.
+- Start a new trace if the incoming request does not contain a trace header. This trace stays active until the response is sent.
+
+</PlatformCategorySection>
+
+If necessary, you can override the default trace duration by [manually starting a new trace](./custom-instrumentation#starting-a-new-trace).
+
 ## How to Use Distributed Tracing?
 
 <PlatformContent includePath="distributed-tracing/how-to-use/" />

platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx

@@ -173,6 +173,30 @@ In this example, tracing information is propagated to the project running at `ht
 
 The two services are now connected with your custom distributed tracing implementation.
 
+### Starting a New Trace
+
+Available since SDK version `8.5.0`.
+
+In case the SDK's [default behavior](../#trace-duration) for the trace duration does not fit your needs, you can manually start a new trace that will no longer be connected to the current (distributed) trace.
+This means that spans or errors collected by the SDK during this new trace will not be connected to spans or errors collected before or after this new trace.
+
+To start a new trace that remains valid throughout the duration of a callback, use `startNewTrace`:
+
+```javascript {2-6}
+myButton.addEventListener("click", async () => {
+  Sentry.startNewTrace(() => {
+    Sentry.startSpan(
+      { op: "ui.interaction.click", name: "fetch click" },
+      async () => {
+        await fetch("http://example.com");
+      }
+    );
+  });
+});
+```
+
+Once the callback ends, the SDK will continue the previous trace (if available).
+
 ## Verification
 
 If you make outgoing requests from your project to other services, check if the headers `sentry-trace` and `baggage` are present in the request. If so, distributed tracing is working.