Connect Services

When tracing is enabled, the SDK will attach an outgoing header called sentry-trace to requests. This depends on the out of the box integrations we provide, but you can expect the header sentry-trace to be present. If it's not, you can manually add sentry-trace headers to any requests by learning more about its structure.

SDKs with performance monitoring support listen to incoming requests and typically automatically pick up the incoming sentry-trace header to continue the trace (with the same trace-id) from there, connecting backend and frontend transactions into a single coherent trace using the trace_id value. Depending on the circumstance, this ID is transmitted either in a request header or in an HTML <meta> tag. All your transactions that have the same trace-id are connected. Linking transactions in this way makes it possible to navigate among 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.

If the instrumentation you are using doesn't automatically pick up the sentry-trace header, you can also continue a trace manually by using the continueFromHeaders function on a Transaction, which you can learn more about in our content for the Transaction Interface.

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.

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