Trace Propagation

Learn how to connect events across applications/services.

If the overall application landscape that you want to observe with Sentry consists of more than just a single service or application, distributed tracing can add a lot of value.

In the context of tracing events across a distributed system, distributed tracing acts as a powerful debugging tool. Imagine your application as a vast network of interconnected parts. For example, your system might be spread across different servers or your application might split into different backend and frontend services, each potentially having their own technology stack.

When an error or performance issue occurs, it can be challenging to pinpoint the root cause due to the complexity of such a system. Distributed tracing helps you follow the path of an event as it travels through this intricate web, recording every step it takes. By examining these traces, you can reconstruct the sequence of events leading up to the event of interest, identify the specific components involved, and understand their interactions. This detailed visibility enables you to diagnose and resolve issues more effectively, ultimately improving the reliability and performance of your distributed system.

Here's an example showing a distributed trace in Sentry:

A full distributed trace in Sentry

This distributed trace shows a Vue app's pageload making a request to a Python backend, which then calls the /api endpoint of a Ruby microservice.

What happens in the background is that Sentry uses reads and further propagates two HTTP headers between your applications:

  • sentry-trace
  • baggage

If you run any JavaScript applications in your distributed system, make sure that those two headers are added to your CORS allowlist and won't be blocked or stripped by your proxy servers, gateways, or firewalls.

In the browser, the SDK automatically starts a new trace in the following situations:

  • On page load: Whenever the page is (re-)loaded, a new trace is started. At the same time, a pageload span is created (see Performance Monitoring). Once this span ends, the trace remains until the next navigation or page load. In case the server serving the initial page already started a trace and sent the necessary HTML tags to the browser, the SDK will continue this trace instead of starting a new one.
  • On navigation: Whenever a user navigates (for example in a single-page application), a new trace is started. At the same time, a navigation span is created (see Performance Monitoring). Once this span ends, the trace remains until the next navigation or page load.

In both cases, this means that if you start spans after the automatic pageload and navigation spans ended, they will still be part of the same trace. This makes it easy to connect what happened before and after your span.

If necessary, you can override the default trace duration by manually starting a new trace.

If you're using the current version of our JavaScript SDK and have enabled the BrowserTracing integration, distributed tracing will work out of the box. To get around possible Browser CORS issues, define your tracePropagationTargets.

  dsn: "",
  integrations: [Sentry.browserTracingIntegration()],
  tracePropagationTargets: ["", /^\/api\//],

By default, the browserTracingIntegration will automatically continue a trace found in a <meta> tags that look like this:


If you want to continue a trace from a server, e.g. in a server rendered application, the server will have to emit these meta tags into the rendered HTML. You do not need to configure anything to continue traces from <meta> tags, if you use browserTracingIntegration.

If you don't want to use browserTracingIntegration, you can set up Custom Instrumentation for distributed tracing.

If you're using version 7.57.x or below, you'll need to have our tracing feature enabled in order for distributed tracing to work.

If you want to disable distributed tracing and ensure no Sentry trace headers are sent, you can configure your SDK like this:

  dsn: "",

  // Overwrite the defaults to ensure no trace headers are sent
  tracePropagationTargets: [],
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").