Connect Backend and Frontend Transactions

To connect backend and frontend transactions into a single coherent 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 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. You can learn more about this model in our Distributed Tracing docs.


When enabling tracing in both frontend and backend as well as taking advantage of 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.

    <meta name="sentry-trace" content="{{ span.toTraceparent() }}" />
    <!-- ... -->

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 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 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.)

Once a page is loaded, any requests it makes (and any requests your backend makes as a result) are linked through a request header.

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.

You can edit this page on GitHub.