Custom Instrumentation

On this page you will learn how to manually propagate trace information into and out of your JavaScript application.

Distributed tracing will be set up automatically if:

  • You've Set Up Performance in Sentry.
  • You're using one of the SDKs that include distributed tracing out of the box:
    • @sentry/nextjs
    • @sentry/sveltekit
    • @sentry/remix
    • @sentry/astro

If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work.

To enable distributed tracing for your frontend, add the BrowserTracing integration to your Sentry.init() options as described in the Automatic Instrumentation docs.

If you want to use distributed tracing but not performance monitoring, set the tracesSampleRate option to 0.

Copied
Sentry.init({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
  integrations: [Sentry.browserTracingIntegration()],

  // If this is 0, performance monitoring is disabled
  // but distributed tracing is not
  tracesSampleRate: 0,
});

If you don't want to use the BrowserTracing integration, you can manually extract and inject tracing data in your application to connect multiple systems. For this, you must:

  • Extract and store incoming tracing information from HTML <meta> tags when loading the page.
  • Inject tracing information to any outgoing requests.

To learn more about distributed tracing, see our Distributed Tracing docs.

If you have a server that renders your application's HTML (SSR) and is also running a Sentry SDK, you can connect your backend to your backend via tracing.

To do this, have your server render HTML <meta> tags with the Sentry trace information. In your frontend, extract that tracing information when the page is loading and use it to create new transactions connected to that incoming backend trace.

Some Sentry backend SDKs provide a built-in way to inject these <meta> tags into rendered HTML. For example:

Then, on pageload you can do the following:

Copied
// Read meta tag values
const sentryTrace = document.querySelector('meta[name=sentry-trace]')?.content;
const baggage = document.querySelector('meta[name=baggage]')?.content;

Sentry.continueTrace({sentryTrace, baggage}, transactionContext => {
  Sentry.startSpan(
    {
      ...transactionContext,
      name: `Pageload: ${window.location.pathname}`,
      op: 'pageload',
    },
    () => {
      // do something
    }
  );
});

In this example, we create a new transaction that is attached to the trace specified in the sentry-trace and baggage HTML <meta> tags.

For distributed tracing to work, the two headers that you extracted and stored in the active root span, sentry-trace and baggage, must be added to outgoing HTTP requests.

Here's an example of how to collect and inject this tracing information to outgoing requests:

Copied
const activeSpan = Sentry.getActiveSpan();
const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined;

// Create `sentry-trace` header
const sentryTraceHeader = rootSpan
  ? Sentry.spanToTraceHeader(rootSpan)
  : undefined;

// Create `baggage` header
const sentryBaggageHeader = rootSpan
  ? Sentry.spanToBaggageHeader(rootSpan)
  : undefined;

// Make outgoing request
fetch('https://example.com', {
  method: 'GET',
  headers: {
    baggage: sentryBaggageHeader,
    'sentry-trace': sentryTraceHeader,
  },
}).then(response => {
  // ...
});

In this example, tracing information is propagated to the project running at https://example.com. If this project uses a Sentry SDK, it will extract and save the tracing information for later use.

The two services are now connected with your custom distributed tracing implementation.

If you make outgoing requests from your project to other services, check if the headers sentry-trace and baggage are present in the request. If so, distributed tracing is working.

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