Set Up Distributed Tracing

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.

What is Distributed Tracing?

Distributed tracing connects and records the path of requests as they travel through your distributed system, creating a comprehensive timeline of events that would otherwise be fragmented across different components.

This end-to-end visibility allows developers to identify bottlenecks, pinpoint the root cause of errors, and understand component interactions—turning what would be a complex debugging nightmare into a manageable process that improves system reliability and performance.

Basic Example

Here's an example showing a 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.

How to Use Distributed Tracing?

If you're using the current version of our Next.js SDK, distributed tracing will work out of the box for the client, server, and edge runtimes.

For client-side you might have to define tracePropagationTargets to get around possible Browser CORS issues.

// sentry.client.config.js
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [Sentry.browserTracingIntegration()],
  tracePropagationTargets: ["https://myproject.org", /^\/api\//],
});

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.

Disabling Distributed Tracing

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Overwrite the defaults to ensure no trace headers are sent
  tracePropagationTargets: [],
});

Trace Duration

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.

Server-side SDKs handle traces automatically on a per-request basis. This means that SDKs will:

• Continue an existing trace if the incoming request contains a trace header.
• Start a new trace if the incoming request does not contain a trace header. This trace stays active until the response is sent.

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