feat: Add custom distributed tracing docs for JS/Node (#8469)

---------

Co-authored-by: Luca Forstner <[email protected]>
Co-authored-by: Shana Matthews <[email protected]>
Co-authored-by: Lukas Stracke <[email protected]>

Author: 4 people

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

@@ -1,53 +1,75 @@
-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.
+Distributed tracing will be set up automatically if:
 
-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've <PlatformLink to="/performance/">Set Up Performance</PlatformLink> in Sentry.
+- You're using one of the SDKs 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
 
-- 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 enable distributed tracing for your frontend, add the `BrowserTracing` integration to your `Sentry.init()` options as described in the <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink> docs.
 
-To learn more, see our <PlatformLink to="/distributed-tracing/">Distributed Tracing</PlatformLink> docs.
+If you want to use distributed tracing but not performance monitoring, set the `tracesSampleRate` option to `0`.
 
-## Extract Tracing Information From HTML `meta` Tags
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new Sentry.BrowserTracing()],
 
-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.
+  // Optionally disable performance monitoring:
+  // tracesSampleRate: 0,
+});
+```
 
-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.
+## Enabling Distributed Tracing without `BrowserTracing`
 
-For example, on `pageload` you could do the following:
+If you don't want to use the `BrowserTracing` integration, you can manually extract and inject tracing data in your application to connect multiple systems. For this, you must:
 
-```javascript
-// Read meta tag values
-const sentryTraceMetaTagValue = getMetaContent("sentry-trace");
-const baggageMetaTagValue = getMetaContent("baggage");
+- Extract and store incoming tracing information from HTML `<meta>` tags when loading the page.
+- Inject tracing information to any outgoing requests.
 
-// Extract Sentry trace information
-const traceParentData = extractTraceparentData(sentryTraceMetaTagValue);
+To learn more about distributed tracing, see our <PlatformLink to="/usage/distributed-tracing/">Distributed Tracing</PlatformLink> docs.
 
-// Create Dynamic Sampling Context
-const dynamicSamplingContext =
-  baggageHeaderToDynamicSamplingContext(baggageMetaTagValue);
+### Extract Tracing Information From HTML `meta` Tags
 
-// Create transaction context
-const transactionContext = {
-  ...traceParentData,
-  metadata: {
-    dynamicSamplingContext: dynamicSamplingContext,
-  },
-};
+If you have a server that renders your application's HTML (SSR) and is also running a Sentry SDK, you can connect your backend to your backend via tracing.
+
+To do this, have your server render HTML `<meta>` tags with the Sentry trace information. In your frontend, extract that tracing information when the page is loading and use it to create new transactions connected to that incoming backend trace.
 
-// Start transaction with tracing information of meta tags
-const pageLoadTransaction = startTransaction(hub, transactionContext);
+Some Sentry backend SDKs provide a built-in way to inject these `<meta>` tags into rendered HTML. For example:
+
+- [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 sentryTrace = document.querySelector("meta[name=sentry-trace]")?.content;
+const baggage = document.querySelector("meta[name=baggage]")?.content;
+
+const pageLoadTransaction = Sentry.continueTrace(
+  { sentryTrace, baggage },
+  (transactionContext) => {
+    return Sentry.startTransaction({
+      ...transactionContext,
+      name: `Pageload: ${window.location.pathname}`,
+      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.
+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,119 @@
+On this page, you will learn how to manually propagate trace information into and out of your Node.js application.
+
+Distributed tracing will be set up automatically if:
+
+- You've <PlatformLink to="/performance/">Set Up Performance</PlatformLink> in Sentry.
+- You're using one of the platforms that include distributed tracing out of the box:
+  - `@sentry/nextjs`
+  - `@sentry/sveltekit`
+  - `@sentry/remix`
+  - `@sentry/astro`
+
+If you're not using any of the packages above, take a look at the framework-specific Sentry integrations (like our [Express integration](/platforms/node/guides/express/)). These integrations will also enable distributed tracing automatically for your application.
+If you can't find an integration for your framework, it is possible to set up distributed tracing for your application manually.
+
+## Enabling Distributed Tracing
+
+You can setup the `Http` integration in combination with `tracesSampleRate: 0` to enable distributed tracing without performance monitoring:
+
+To enable distributed tracing for your frontend, configure the `Http` or `Undici` integration in your `Sentry.init()` options as described in the <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink> docs.
+
+If you want to use distributed tracing but not performance monitoring, set the `tracesSampleRate` option to `0`.
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    new Sentry.Integrations.Http({ tracing: true }),
+    // The Undici integrations instruments fetch in Node 18+
+    new Sentry.Integrations.Undici(),
+  ],
+
+  // Optionally disable performance monitoring:
+  // tracesSampleRate: 0,
+});
+```
+
+## Enabling Distributed Tracing without `Http`/`Undici` Integration
+
+If you do not want to use the `Http` or `Undici` integrations, you can manually extract and inject tracing data into your application. For this, you must:
+
+- Extract and store incoming tracing information from incoming request headers or similar.
+- Inject tracing information to any outgoing requests.
+
+To learn more about distributed tracing, see our <PlatformLink to="/usage/distributed-tracing/">Distributed Tracing</PlatformLink> docs.
+
+### Extracting Incoming Tracing Information
+
+You must extract and store incoming tracing information 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 http = require("http");
+
+http.createServer((request, response) => {
+  const sentryTraceHeaders = request.headers["sentry-trace"];
+  const sentryTrace = Array.isArray(sentryTraceHeaders)
+    ? sentryTraceHeaders.join(",")
+    : sentryTraceHeaders;
+  const baggage = request.headers["baggage"];
+
+  const requestTransaction = Sentry.continueTrace(
+    { sentryTrace, baggage },
+    (transactionContext) => {
+      return Sentry.startTransaction({
+        ...transactionContext,
+        name: "my request",
+        op: "http.server",
+      });
+    }
+  );
+
+  // Your API code...
+
+  requestTransaction.finish();
+});
+```
+
+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 don't want to use performance monitoring, you can 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 don't want to use performance monitoring, you can 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:
+  - elixir
+  - javascript.cordova
+  - kotlin-multiplatform
+  - unreal
 ---
 
 <PlatformContent includePath="distributed-tracing/custom-instrumentation/" />