Adust docs for dealing with baggage headers (CORS and meta tags) (#5061)

Lms24 · web-flow · commit d4bc74cf0555 · 2022-05-30T14:39:39.000+02:00
Adjust the JS SDK Performance Monitoring -&gt; "Connect Services" page by adding information about the newly introduced baggage header and its propagation. It adds instructions on setting up CORS rules to accept the new header as well as how to add the baggage information to meta tags for server-originating traces.
diff --git 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.
+<Note>
+
+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.
+
+</Note>
+
+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 <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#tracingorigins">tracingOrigins</PlatformLink> 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 <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#tracingorigins">tracingOrigins</PlatformLink> list.
 
 <!-- copied from automatic-instrumentation to emphasize this point -->
 
-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 `<meta>` tag in the `<head>` 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 `<meta>` tags in the `<head>` of the HTML sent from your backend.
 
 ```html
 <html>
   <head>
     <meta name="sentry-trace" content="{{ span.toSentryTrace() }}" />
+    <meta name="baggage" content="{{ serializeBaggage(span.getBaggage()) }}" />
     <!-- ... -->
   </head>
 </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())`.
 <Note>
 
 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 `<meta>` 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 `<meta>` 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`.
