Connect Services

To connect backend and frontend transactions into a single coherent trace, Sentry uses a trace_id value that is propagated between frontend and backend services. 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 to navigate between them in sentry.io to better understand how the different parts of your system are affecting one another. You can learn more about this model in our Distributed Tracing docs.

For traces that begin in the front end, any requests made (and any requests your backend makes as a result) are linked through a request header.

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 JavaScript SDK will only attach the trace header to outgoing HTTP requests whose destination is a substring or regex match to the tracingOrigins list.

You will need to configure your web server CORS to allow the sentry-trace header. The configuration might look like "Access-Control-Allow-Headers: sentry-trace", but the configuration depends on your set up. If you do not allow the sentry-trace header, the request might be blocked.

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.

Copied
<html>
  <head>
    <meta name="sentry-trace" content="{{ span.toSentryTrace() }}" />
    <!-- ... -->
  </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.toSentryTrace() (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.)

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").