diff --git a/src/includes/performance/connect-services/javascript.mdx b/src/includes/performance/connect-services/javascript.mdx index 806c902c7984d6..7b4865341ad641 100644 --- a/src/includes/performance/connect-services/javascript.mdx +++ b/src/includes/performance/connect-services/javascript.mdx @@ -1,30 +1,36 @@ -### Navigation and Other XHR Requests +## Navigation and Other XHR Requests -For traces that begin in the front end, any requests made (and any requests your backend makes as a result) are linked through the request header `sentry-trace`. +For traces that begin in the front end, any requests made (and any requests your backend makes as a result) are linked through the request headers `sentry-trace` and `baggage`. The `sentry-trace` header holds information for identifying the trace, while the [W3C compliant](https://www.w3.org/TR/baggage/) `baggage` header contains additional trace-related data that is used for trace-based sampling. -All of Sentry's tracing-related integrations (`BrowserTracing`, `Http`, and `Express`), as well as the Next.JS SDK, either generate or pick up and propagate the trace header automatically, as appropriate, for all transactions and spans that they generate. + + +The `baggage` header was added with version 7 of the Sentry Javascript SDK and is not yet standardized across other Sentry SDKs. It is part of an ongoing effort to create a more frictionless and targeted sampling approach, and its content is subject to change. + + + +All of Sentry's tracing-related integrations (`BrowserTracing`, `Http`, and `Express`), as well as the Next.JS SDK, either generate or pick up and propagate the trace headers automatically, as appropriate, for all transactions and spans that they generate. -The JavaScript SDK will only attach the trace header to outgoing HTTP requests for which the destination is a substring or regex match to the tracingOrigins list. +The JavaScript SDK will only attach the trace headers to outgoing HTTP requests for which the destination is a substring or regex match to the tracingOrigins list. -You'll need to configure your web server [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) to allow the `sentry-trace` header. The configuration might look like `"Access-Control-Allow-Headers: sentry-trace"`, but the configuration depends on your setup. If you don't allow the `sentry-trace` header, the request might be blocked. +You'll need to configure your web server [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) to allow the `sentry-trace` and `baggage` headers. The configuration might look like `"Access-Control-Allow-Headers: sentry-trace"` and `"Access-Control-Allow-Headers: baggage"`, but the configuration depends on your setup. If you don't allow the `sentry-trace` and `baggage` headers, the request might be blocked. -### Pageload +## Pageload -For traces that begin in your backend, you can connect the automatically-generated `pageload` transaction on the frontend with the request transaction that serves the page on the backend. Because JavaScript code running in a browser cannot read the response headers of the current page, the `trace_id` must be transmitted in the response itself, specifically in a `` tag in the `` of the HTML sent from your backend. +For traces that begin in your backend, you can connect the automatically-generated `pageload` transaction on the frontend with the request transaction that serves the page on the backend. Because JavaScript code running in a browser cannot read the response headers of the current page, the trace data must be transmitted in the response itself, specifically in `` tags in the `` of the HTML sent from your backend. ```html + ``` -The `name` attribute must be the string `"sentry-trace"` and the `content` attribute must be generated by your backend Sentry SDK using `span.toSentryTrace()` (or equivalent, depending on the backend platform). This guarantees that a new and unique value will be generated for each request. - +The `name` attributes must be the strings `"sentry-trace"` and `"baggage"` and the `content` attributes must be generated by your backend Sentry SDK. For `sentry-trace`, use `span.toSentryTrace()` (or equivalent, depending on the backend platform). This guarantees that a new and unique value will be generated for each request. For `baggage`, use `serializeBaggage(span.getBaggage())`. The `span.toSentryTrace()` was previously called `span.toTraceparent()`, so that's what you may find depending on the SDK and version. @@ -33,4 +39,4 @@ The `span.toSentryTrace()` was previously called `span.toTraceparent()`, so that The `span` reference is either the transaction that serves the HTML or any of its child spans. It defines the parent of the `pageload` transaction. -Once the data is included in the `` tag, our `BrowserTracing` integration will pick it up automatically and link it to the transaction generated on pageload. (Note that it will not be linked to automatically-generated `navigation` transactions — that is, those that don't require a full page reload. Each of those will be the result of a different request transaction on the backend and, therefore, should have a unique `trace_id`.) +Once the data is included in the `` tags, our `BrowserTracing` integration will pick them up automatically and link them to the transaction generated on pageload. Note that they will not be linked to automatically-generated `navigation` transactions — that is, those that don't require a full page reload. Each of those will be the result of a different request transaction on the backend and, therefore, should have a unique `trace_id`.