feat: Add custom distributed tracing docs for JS/Node

Author: mydea

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

@@ -1,53 +1,69 @@
-On this page you will learn how to manually propagate trace information into and out of your JavaScript application. Please note, that you do not need to do this manually, if you [use one of our supported frameworks](/platforms/javascript/usage/distributed-tracing/#how-to-use-distributed-tracing), or you have our <PlatformLink to="/performance/">performance monitoring feature</PlatformLink> turned on.
+On this page you will learn how to manually propagate trace information into and out of your JavaScript application.
 
-To set it up manually, all you have to do is to make sure your application extracts incoming headers and to set those headers again when making an outgoing request within your application.
+In the following cases, distributed tracing will be set up automatically for you:
 
-To enable distributed tracing, add the `BrowserTracing` integration to your `Sentry.init` options, as described in the Performance <PlatformLink to="/performance/instrumentation/automatic-instrumentation/"> Automatic Instrumentation</PlatformLink> docs. The [Next.js](/platforms/javascript/guides/nextjs/) and [SvelteKit](/platforms/javascript/guides/sveltekit/) SDKs include this integration by default.
+- You have our <PlatformLink to="/performance/">performance monitoring feature</PlatformLink> turned on.
+- You are using one of the platforms that include distributed tracing out of the box:
+  - `@sentry/nextjs`
+  - `@sentry/sveltekit`
+  - `@sentry/remix`
+  - `@sentry/astro`
 
-If you are using one of the frameworks listed above, see the <PlatformLink to="/distributed-tracing/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink>. page on how to configure distributed tracing.
+If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work.
 
-If you prefer to implement custom distributed tracing, you must:
+## Enabling Distributed Tracing without Performance
+
+You can add the `BrowserTracing` integration in your `Sentry.init()` options, as described in the Performance <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink> docs. If you combine this with `tracesSampleRate: 0`, you will have distributed tracing without performance monitoring:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new Sentry.BrowserTracing()],
+  tracesSampleRate: 0,
+});
+```
+
+## Enabling Distributed Tracing without `BrowserTracing`
+
+If you do not want to use the `BrowserTracing` integration, you can manually extract and inject tracing information into your application. For this, you must:
 
 - Extract and store incoming tracing information from HTML `meta` tags when loading the page
 - Inject tracing information to the outgoing request when sending outgoing requests.
 
-To learn more, see our <PlatformLink to="/distributed-tracing/">Distributed Tracing</PlatformLink> docs.
+To learn more, see our <PlatformLink to="/usage/distributed-tracing/">Distributed Tracing</PlatformLink> docs.
 
-## Extract Tracing Information From HTML `meta` Tags
+### Extract Tracing Information From HTML `meta` Tags
 
 Assuming the backend that renders the HTML has injected tracing information into the HTML as `meta` tags, you can extract that tracing information on `pageload` and use it to create new transactions connected to that incoming trace.
 
-See the docs on how to [Inject Tracing Information Into Rendered HTML](/platforms/python/distributed-tracing/instrumentation/custom-instrumentation/#inject-tracing-information-into-rendered-html) to learn more about how to configure your backend to inject this information.
+Some of our backend SDKs provide a built-in way to inject tracing information into rendered HTML. For example:
 
-For example, on `pageload` you could do the following:
+- [Python](/platforms/python/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
+- [Ruby](/platforms/ruby/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
+- [PHP](/platforms/php/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
+
+Then, on `pageload` you can do the following:
 
 ```javascript
 // Read meta tag values
-const sentryTraceMetaTagValue = getMetaContent("sentry-trace");
-const baggageMetaTagValue = getMetaContent("baggage");
-
-// Extract Sentry trace information
-const traceParentData = extractTraceparentData(sentryTraceMetaTagValue);
-
-// Create Dynamic Sampling Context
-const dynamicSamplingContext =
-  baggageHeaderToDynamicSamplingContext(baggageMetaTagValue);
-
-// Create transaction context
-const transactionContext = {
-  ...traceParentData,
-  metadata: {
-    dynamicSamplingContext: dynamicSamplingContext,
-  },
-};
-
-// Start transaction with tracing information of meta tags
-const pageLoadTransaction = startTransaction(hub, transactionContext);
+const sentryTrace = getMetaContent("sentry-trace");
+const baggage = getMetaContent("baggage");
+
+const pageLoadTransaction = Sentry.continueTrace(
+  { sentryTrace, baggage },
+  (transactionContext) => {
+    return Sentry.startTransaction({
+      ...transactionContext,
+      name: "my pageload",
+      op: "pageload",
+    });
+  }
+);
 ```
 
 In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `meta` tags.
 
-## Inject Tracing Information to Outgoing Requests
+### Inject Tracing Information to Outgoing Requests
 
 For distributed tracing to work, the two headers that you extracted and stored in the `pageLoadTransaction`, `sentry-trace` and `baggage`, must be added to outgoing XHR/fetch requests.
 

src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx

@@ -0,0 +1,97 @@
+On this page you will learn how to manually propagate trace information into and out of your JavaScript application.
+
+In the following cases, distributed tracing will be set up automatically for you:
+
+- You have our <PlatformLink to="/performance/">performance monitoring feature</PlatformLink> turned on.
+- You are using one of the platforms that include distributed tracing out of the box:
+  - `@sentry/nextjs`
+  - `@sentry/sveltekit`
+  - `@sentry/remix`
+  - `@sentry/astro`
+
+If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work.
+
+## Enabling Distributed Tracing without Performance
+
+You can setup the `Http` integration in combination with `tracesSampleRate: 0` to enable distributed tracing without performance monitoring:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new Sentry.Integrations.Http({ tracing: true })],
+  tracesSampleRate: 0,
+});
+```
+
+## Enabling Distributed Tracing without `Http` Integration
+
+If you do not want to use the `Http` integration in conjuction with `tracing: true`, you can manually extract and inject tracing information into your application. For this, you must:
+
+- Extract and store incoming tracing information from incoming request headers or similar.
+- Inject tracing information to the outgoing request when sending outgoing requests.
+
+To learn more, see our <PlatformLink to="/usage/distributed-tracing/">Distributed Tracing</PlatformLink> docs.
+
+### Extracting Incoming Tracing Information
+
+Incoming tracing information has to be extracted and stored in memory for later use. Sentry provides the `continueTrace()` function to help you with this. Incoming tracing information can come from different places:
+
+- In a web environment, it's sent with HTTP headers, for example, by another Sentry SDK used in your frontend project.
+- In a job queue, it can be retrieved from meta or header variables.
+- You also can pick up tracing information from environment variables.
+
+Here's an example of how to extract and store incoming tracing information using `continueTrace()`:
+
+```javascript
+const sentryTrace = getRequestHeader("sentry-trace");
+const baggage = getRequestHeader("baggage");
+
+const requestTransaction = Sentry.continueTrace(
+  { sentryTrace, baggage },
+  (transactionContext) => {
+    return Sentry.startTransaction({
+      ...transactionContext,
+      name: "my request",
+      op: "http.server",
+    });
+  }
+);
+```
+
+In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` headers.
+
+### Inject Tracing Information to Outgoing Requests
+
+For distributed tracing to work, the two headers that you extracted and stored in the `requestTransaction`, `sentry-trace` and `baggage`, must be added to outgoing http/fetch requests.
+
+Here's an example of how to collect and inject this tracing information to outgoing requests:
+
+```javascript
+// Create `sentry-trace` header
+const sentryTraceHeader = requestTransaction.toTraceparent();
+
+// Create `baggage` header
+const dynamicSamplingContext = requestTransaction.getDynamicSamplingContext();
+const sentryBaggageHeader = dynamicSamplingContextToSentryBaggageHeader(
+  dynamicSamplingContext
+);
+
+// Make outgoing request
+fetch("https://example.com", {
+  method: "GET",
+  headers: {
+    baggage: sentryBaggageHeader,
+    "sentry-trace": sentryTraceHeader,
+  },
+}).then((response) => {
+  // ...
+});
+```
+
+In this example, tracing information is propagated to the project running at `https://example.com`. If this project uses a Sentry SDK, it will extract and save the tracing information for later use.
+
+The two services are now connected with your custom distributed tracing implementation.
+
+## 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.

src/platform-includes/distributed-tracing/how-to-use/javascript.mdx

@@ -8,4 +8,8 @@ Sentry.init({
 });
 ```
 
+### Custom Instrumentation
+
+If you do not want to use performance monitoring, you can instead set up <PlatformLink to="/usage/distributed-tracing/custom-instrumentation/">Custom Instrumentation</PlatformLink> for distributed tracing.
+
 If you're using version `7.57.x` or below, you'll need to have our <PlatformLink to="/performance/">performance monitoring feature enabled</PlatformLink> in order for distributed tracing to work.

src/platform-includes/distributed-tracing/how-to-use/node.mdx

@@ -21,4 +21,8 @@ app.use(Sentry.Handlers.requestHandler());
 app.use(Sentry.Handlers.tracingHandler());
 ```
 
+### Custom Instrumentation
+
+If you do not want to use performance monitoring, you can instead set up <PlatformLink to="/usage/distributed-tracing/custom-instrumentation/">Custom Instrumentation</PlatformLink> for distributed tracing.
+
 If you're using version `7.57.x` or below, you'll need to have our <PlatformLink to="/performance/">performance monitoring feature enabled</PlatformLink> in order for distributed tracing to work.

src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx

@@ -9,6 +9,13 @@ supported:
   - android
   - ruby
   - dotnet
+  - javascript
+  - node
+notSupported:
+  - javascript.nextjs
+  - javascript.remix
+  - javascript.sveltekit
+  - javascript.astro
 ---
 
 <PlatformContent includePath="distributed-tracing/custom-instrumentation/" />