Better explanation

Author: Luca Forstner

packages/tracing-internal/src/browser/request.ts

@@ -1,4 +1,3 @@
-/* eslint-disable max-lines */
 import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   getClient,
@@ -34,15 +33,20 @@ export interface RequestInstrumentationOptions {
    * List of strings and/or Regular Expressions used to determine which outgoing requests will have `sentry-trace` and `baggage`
    * headers attached.
    *
-   * By default, if this option is not provided, tracing headers will be attached to all outgoing requests to the same origin as the current page.
+   * **Default:** If this option is not provided, tracing headers will be attached to all outgoing requests.
+   * If you are using a browser SDK, by default, tracing headers will only be attached to outgoing requests to the same origin.
    *
-   * NOTE: Carelessly setting this option may result into CORS errors.
+   * **Disclaimer:** Carelessly setting this option in browser environments may result into CORS errors!
+   * Only attach tracing headers to requests to the same origin, or to requests to services you can control CORS headers of.
+   * Cross-origin requests, meaning requests to a different domain, for example a request to `https://api.example.com/` while you're on `https://example.com/`, take special care.
+   * If you are attaching headers to cross-origin requests, make sure the backend handling the request returns a `"Access-Control-Allow-Headers: sentry-trace, baggage"` header to ensure your requests aren't blocked.
    *
-   * If you provide a `tracePropagationTargets` array, the entries you provide will be matched against two values:
-   * - The entire URL of the outgoing request.
-   * - The pathname of the outgoing request (only if it is a same-origin request)
+   * If you provide a `tracePropagationTargets` array, the entries you provide will be matched against the entire URL of the outgoing request.
+   * If you are using a browser SDK, the entries will also be matched against the pathname of the outgoing requests.
+   * This is so you can have matchers for relative requests, for example, `/^\/api/` if you want to trace requests to your `/api` routes on the same domain.
    *
    * If any of the two match any of the provided values, tracing headers will be attached to the outgoing request.
+   * Both, the string values, and the RegExes you provide in the array will match if they partially match the URL or pathname.
    *
    * Examples:
    * - `tracePropagationTargets: [/^\/api/]` and request to `https://same-origin.com/api/posts`:
@@ -246,7 +250,6 @@ export function shouldAttachHeaders(
  *
  * @returns Span if a span was created, otherwise void.
  */
-// eslint-disable-next-line complexity
 export function xhrCallback(
   handlerData: HandlerDataXhr,
   shouldCreateSpan: (url: string) => boolean,

packages/types/src/options.ts

@@ -226,15 +226,20 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    * List of strings and/or Regular Expressions used to determine which outgoing requests will have `sentry-trace` and `baggage`
    * headers attached.
    *
-   * By default, if this option is not provided, tracing headers will be attached to all outgoing requests to the same origin as the current page.
+   * **Default:** If this option is not provided, tracing headers will be attached to all outgoing requests.
+   * If you are using a browser SDK, by default, tracing headers will only be attached to outgoing requests to the same origin.
    *
-   * NOTE: Carelessly setting this option may result into CORS errors.
+   * **Disclaimer:** Carelessly setting this option in browser environments may result into CORS errors!
+   * Only attach tracing headers to requests to the same origin, or to requests to services you can control CORS headers of.
+   * Cross-origin requests, meaning requests to a different domain, for example a request to `https://api.example.com/` while you're on `https://example.com/`, take special care.
+   * If you are attaching headers to cross-origin requests, make sure the backend handling the request returns a `"Access-Control-Allow-Headers: sentry-trace, baggage"` header to ensure your requests aren't blocked.
    *
-   * If you provide a `tracePropagationTargets` array, the entries you provide will be matched against two values:
-   * - The entire URL of the outgoing request.
-   * - The pathname of the outgoing request (only if it is a same-origin request)
+   * If you provide a `tracePropagationTargets` array, the entries you provide will be matched against the entire URL of the outgoing request.
+   * If you are using a browser SDK, the entries will also be matched against the pathname of the outgoing requests.
+   * This is so you can have matchers for relative requests, for example, `/^\/api/` if you want to trace requests to your `/api` routes on the same domain.
    *
    * If any of the two match any of the provided values, tracing headers will be attached to the outgoing request.
+   * Both, the string values, and the RegExes you provide in the array will match if they partially match the URL or pathname.
    *
    * Examples:
    * - `tracePropagationTargets: [/^\/api/]` and request to `https://same-origin.com/api/posts`: