edit connecting front to back section and add sentry-trace header to it

lobsterkatie · lobsterkatie · commit 0ae4b8fe0f7f · 2020-09-30T13:56:26.000-07:00
diff --git a/src/platforms/javascript/common/performance/index.mdx b/src/platforms/javascript/common/performance/index.mdx
@@ -78,34 +78,36 @@ Without sampling, our atomatic instrumenation will send a transaction any time a
 
 </markdown></Alert>
 
-### Connecting Backend and Frontend Transactions
+## Connecting Backend and Frontend Transactions
 
-When instrumenting both frontend and backend with Sentry, you can connect the
-`pageload` transaction on the frontend with the request transaction that rendered the page on the backend.
+To connect backend and frontend transactions into a single choherent trace, Sentry uses a `trace_id` value which is propagated between frontend and backend. Depending on the circumstance, this id is transmitted either in a request/response header or in an HTML `<meta>` tag. Linking transactions in this way makes it possible for you to navigate between them in the Sentry UI, so you can better understand how the different parts of your system are affecting each other.
 
-Once connected, the backend and frontend transactions will share the same `trace_id`, allowing you to navigate from one transaction to the other in Sentry.
+### Pageload
 
-In your backend code, include a `<meta>` tag in the `<head>` of the rendered HTML document as in this example:
+When enabling tracing in both frontend and backend and taking advantage of the automatic frontend instrumentation, 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.
 
 ```html
 <html>
-<head>
-  <meta name="sentry-trace" content="{{ span.toTraceparent() }}">
-  <!-- ... -->
+  <head>
+    <meta name="sentry-trace" content="{{ span.toTraceparent() }}" />
+    <!-- ... -->
+  </head>
+</html>
 ```
 
-The `name` attribute must be the string `"sentry-trace"` and the `content` attribute must be generated by your backend's Sentry SDK using `span.toTraceparent()` (or equivalent, depending on the backend platform).
+The `name` attribute must be the string `"sentry-trace"` and the `content` attribute must be generated by your backend's Sentry SDK using `span.toTraceparent()` (or equivalent, depending on the backend platform). This guarantees that a new and unique value will be generated for each request.
 
-The `span` reference is either the transaction that rendered the page or any of its child spans. It defines the parent of the `pageload` transaction.
+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.
 
-For the correct association of transactions in a trace, make sure your backend will render a new and unique value for the `content` attribute for every request. Reusing the same value will cause unrelated traces to incorrectly share the same `trace_id`.
+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 get linked to automatically-generated `navigation` transactions, that is, those which 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`.)
 
-<Alert level="info" title="Note"><markdown>
+### Navigation and Other XHR Requests
 
-JavaScript code running on a browser cannot read the response headers of the current page. Therefore, the `<meta>` tag is used to propagate tracing metadata from the backend instead of the `sentry-trace` HTTP header described earlier.
+Once a page is loaded, any requests it makes and any responses your backend generates as a result are linked through a request/response header.
 
-</markdown></Alert>
+As is the case with the `<meta>` tag discussed above, the header's name is `sentry-trace` and its value is obtained by calling `span.toTraceparent()` (or the equivalent), where `span` is either the relevant transaction or any of its children.
 
+All of Sentry's tracing-related integrations (`BrowserTracing`, `Http`, and `Express`) either generate or pick up and propagate this header automatically as appropriate, for all transactions and spans which they generate. You can also attach and read the header yourself, in any case in which you've manually created either a transaction or a span and it makes sense to do so.
 
 ## Retrieving an Active Transaction
 
