Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 30, 2022
Merged

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

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b4195c9
ref(javascript): Adust docs for dealing with baggage headers (CORS an…
Lms24 May 23, 2022
349bf72
add note about baggage not yet being finalized
Lms24 May 23, 2022
d3d6620
Apply suggestions from code review
Lms24 May 24, 2022
f65f268
Apply suggestions from code review
Lms24 May 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions src/includes/performance/connect-services/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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`.