Custom Instrumentation

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

Distributed

• 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.

Enabling Distributed Tracing

To enable distributed

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [new Sentry.BrowserTracing()],

  // Optionally disable performance monitoring:
  // tracesSampleRate: 0,
});

Enabling Distributed Tracing without BrowserTracing

If you don't want to use the BrowserTracing integration, you can manually extract and inject

• 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.

Extract Tracing Information From HTML meta Tags

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

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:

• Python
• Ruby
• PHP

Then, on pageload you can do the following:

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

const pageLoadTransaction = Sentry.continueTrace(
  { sentryTrace, baggage },
  (transactionContext) => {
    return Sentry.startTransaction({
      ...transactionContext,
      name: `Pageload: ${window.location.pathname}`,
      op: "pageload",
    });
  }
);

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

Inject Tracing Information to Outgoing Requests

For distributed

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

// Create `sentry-trace` header
const sentryTraceHeader = pageLoadTransaction.toTraceparent();

// Create `baggage` header
const dynamicSamplingContext = pageLoadTransaction.getDynamicSamplingContext();
const sentryBaggageHeader = dynamicSamplingContextToSentryBaggageHeader(
  dynamicSamplingContext
);

// 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

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

Verification

If you make outgoing requests from your