feat(js): Update JS tracing instrumentation docs (#13229)

---------

Co-authored-by: Lukas Stracke <[email protected]>

Author: mydea

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

@@ -30,8 +30,8 @@ With [tracing](/product/insights/overview/), Sentry automatically tracks your so
 ## Configure
 
 <PlatformSection supported={["javascript"]}>
-  Enable tracing by configuring the sampling rate for transactions. Set
-  the sample rate for your transactions by either:
+  Enable tracing by configuring the sampling rate for transactions. Set the
+  sample rate for your transactions by either:
 </PlatformSection>
 
 <PlatformSection notSupported={["javascript"]}>
@@ -66,14 +66,20 @@ If you leave your sample rate at `1.0`, a transaction will be sent every time a
 <PlatformSection notSupported={["javascript.cordova"]}>
   ## Automatic Instrumentation
 
-  See <PlatformLink to="/tracing/instrumentation/automatic-instrumentation">Automatic Instrumentation</PlatformLink> to learn about all the things that the SDK automatically instruments for you.
+See <PlatformLink to="/tracing/instrumentation/automatic-instrumentation">Automatic Instrumentation</PlatformLink> to learn about all the things that the SDK automatically instruments for you.
+
 </PlatformSection>
 
 ## Custom Instrumentation
 
 You can also manually start spans to instrument specific parts of your code. This is useful when you want to measure the performance of a specific operation or function.
 
-See <PlatformLink to="/tracing/span-metrics/">Sending Span Metrics</PlatformLink> to learn how to manually start spans.
+- <PlatformLink to="/apis/#tracing">Tracing APIs</PlatformLink>:
+  Find information about APIs for custom tracing instrumentation
+- <PlatformLink to="/tracing/instrumentation/">Instrumentation</PlatformLink>:
+  Find information about manual instrumentation with the Sentry SDK
+- <PlatformLink to="/tracing/span-metrics/">Sending Span Metrics</PlatformLink>:
+  Learn how to capture metrics on your spans
 
 ## Next Steps
 

docs/platforms/javascript/common/tracing/instrumentation/index.mdx

@@ -12,6 +12,8 @@ To capture transactions and spans customized to your organization's needs, you m
 
 To add custom performance data to your application, you need to add custom instrumentation in the form of spans. Spans are a way to measure the time it takes for a specific action to occur. For example, you can create a span to measure the time it takes for a function to execute.
 
+You can find a list of all tracing APIs in the <PlatformLink to="/apis/#tracing">Tracing API</PlatformLink> section.
+
 To get started, import the SDK.
 
 <PlatformContent includePath="enriching-events/import" />
@@ -106,7 +108,7 @@ To add spans that aren't active, you can create independent spans. This is usefu
 
 By default, any span that is started will be the child of the currently active span. If you want to have a different behavior, you can force spans to be the children of a specific span with the `parentSpan` option:
 
-```js
+```javascript
 const parentSpan = Sentry.startInactiveSpan({ name: "Parent Span" });
 const childSpan = Sentry.startInactiveSpan({ name: "Child Span", parentSpan });
 
@@ -119,74 +121,12 @@ This option is also available for `startSpan` and `startSpanManual`.
 ## Utilities To Work With Spans
 
 We expose some helpful utilities that can help you with custom instrumentation.
-
-### `getActiveSpan`
-
-Returns the currently active span.
-
-```javascript
-const activeSpan = Sentry.getActiveSpan();
-```
-
-### `getRootSpan`
-
-Returns the root span of a given span. If the span is already the root span, it will return the span itself.
-
-```javascript
-const activeSpan = Sentry.getActiveSpan();
-const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined;
-```
-
-### `withActiveSpan`
-
-This method allows you to make a span active for the duration of a callback. You can use this in combination with `startInactiveSpan` to manually associate child spans with the correct parent span:
-
-```javascript
-const span = Sentry.startInactiveSpan({ name: "Parent Span" });
-
-Sentry.withActiveSpan(span, () => {
-  // `span` is now active, any other spans will be children of it
-  Sentry.startSpan({ name: "Child Span" }, () => {
-    // Do something
-  });
-});
-```
-
-You can also pass `null` to `withActiveSpan` to ensure a span will not have any parent:
-
-```javascript
-Sentry.withActiveSpan(null, () => {
-  // This will not have a parent span, no matter what
-  Sentry.startSpan({ name: "Parent Span" }, () => {
-    // Do something
-  });
-});
-```
-
-Alternatively you can also use the `parentSpan` option to achieve the same:
-
-```javascript
-const span = Sentry.startInactiveSpan({ name: "Parent Span" });
-const childSpan = Sentry.startInactiveSpan({
-  name: "Child Span",
-  parentSpan: span,
-});
-```
-
-### `suppressTracing`
-
-Suppresses the creation of sampled spans for the duration of the callback. This is useful when you want to prevent certain spans from being captured. For example, if you do not want to create spans for a given fetch request, you can do:
-
-```javascript
-Sentry.suppressTracing(() => {
-  fetch("https://example.com");
-});
-```
+See <PlatformLink to="/apis/#tracing-utilities">Tracing Utility APIs</PlatformLink> for more information.
 
 <PlatformSection notSupported={['javascript.cordova']}>
-### Distributed Tracing
+## Distributed Tracing
 
-See <PlatformLink to="/tracing/trace-propagation/custom-instrumentation/">Distributed Tracing</PlatformLink> for details on how to manually set up distributed tracing.
+See <PlatformLink to="/tracing/trace-propagation/custom-instrumentation/">Custom Trace Propagation</PlatformLink> for details on how to manually set up distributed tracing.
 
 </PlatformSection>
 
@@ -227,32 +167,22 @@ if (span) {
 
 ### Adding attributes to all spans
 
-To add an attribute to all spans, use the `beforeSendTransaction` callback:
+To add an attribute to all spans, use the `beforeSendSpan` callback:
 
 ```javascript
 Sentry.init({
   // dsn, ...
-  beforeSendTransaction(event) {
-
-    // set the attribute on the root span
-    event.contexts.trace.data = {
-      ...event.contexts.trace.data,
-      myAttribute: "myValue",
-    }
-
-    // and on all child spans
-    event.spans.forEach(span => {
-      span.data = {
-        ...span.data,
-        myAttribute: "myValue",
-      }
-    });
-  }
+  beforeSendSpan(span) {
+    span.data = {
+      ...span.data,
+      "environment.region": "us-west-2",
+    };
+
+    return span;
+  },
 });
 ```
 
-
-
 ### Adding Span Operations ("op")
 
 Spans can have an operation associated with them, which help Sentry identify additional context about the span. For example, database related spans have the `db` span operation associated with them. The Sentry product offers additional controls, visualizations, and filters for spans with known operations.