Update distributed tracing docs with detailed CORS and trace propagation guidance

Co-authored-by: dgriesser <[email protected]>

Author: cursoragent

docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx

@@ -16,8 +16,94 @@ notSupported:
   - javascript.nestjs
 ---
 
-If your frontend and backend are hosted on different domains (for example, your frontend is on `https://example.com` and your backend is on `https://api.example.com`), and the frontend does XHR/fetch requests to your backend, you'll need to configure your backend [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) headers to ensure requests aren't blocked.
+If your frontend and backend are hosted on different domains (for example, your frontend is on `https://example.com` and your backend is on `https://api.example.com`), you may need to configure your backend [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) headers to ensure distributed tracing works properly.
 
-Configure your backend CORS to allow the `sentry-trace` and `baggage` headers.
+## Understanding Trace Propagation
 
-Your server's response header configuration might look like: `"Access-Control-Allow-Headers: sentry-trace, baggage"`. Your configuration will be specific to your setup.
+Sentry doesn't attach the `sentry-trace` and `baggage` headers to every outgoing request. Instead, it only attaches these headers to requests whose URLs match the patterns specified in the `tracePropagationTargets` configuration option.
+
+**By default**, `tracePropagationTargets` is set to `['localhost', /^\//]`, which means trace headers are only attached to:
+- Requests containing `localhost` in their URL (e.g., `http://localhost:3000/api`)
+- Requests whose URL starts with `/` (e.g., `/api/users`, `/graphql`)
+
+This default behavior helps prevent sending trace data to third-party services and reduces potential CORS issues.
+
+## Configuring Trace Propagation
+
+To enable distributed tracing across different domains, you need to configure `tracePropagationTargets` to include the URLs of your backend services:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [Sentry.browserTracingIntegration()],
+  tracePropagationTargets: [
+    "localhost",           // For local development
+    /^\/api\//,           // For same-origin API calls
+    "https://api.example.com", // For your backend domain
+    "https://auth.example.com" // For additional services
+  ],
+});
+```
+
+## Configuring CORS Headers
+
+Once you've configured `tracePropagationTargets` to include your backend domains, you need to configure your backend to allow the trace headers:
+
+```
+Access-Control-Allow-Headers: sentry-trace, baggage
+```
+
+Your server's exact configuration will depend on your setup, but the important part is allowing both the `sentry-trace` and `baggage` headers.
+
+## Example Scenarios
+
+### Single Backend Domain
+
+If your frontend calls a single backend domain:
+
+```javascript
+// Frontend configuration
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  tracePropagationTargets: [
+    "localhost",              // For development
+    "https://api.example.com" // Your backend
+  ],
+});
+```
+
+```
+# Backend CORS configuration
+Access-Control-Allow-Headers: sentry-trace, baggage
+```
+
+### Multiple Services
+
+If your frontend calls multiple backend services:
+
+```javascript
+// Frontend configuration
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  tracePropagationTargets: [
+    "localhost",
+    "https://api.example.com",
+    "https://auth.example.com",
+    "https://media.example.com"
+  ],
+});
+```
+
+Each backend service needs to allow the headers in their CORS configuration.
+
+### Disabling Trace Propagation
+
+If you want to disable distributed tracing entirely and ensure no trace headers are sent:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  // Empty array prevents all trace header propagation
+  tracePropagationTargets: [],
+});
+```