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
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
.
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:
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
pageLoadTransaction
, sentry-trace
and baggage
, must be added to outgoing XHR/fetch requests.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
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.
Verification
If you make outgoing requests from your
sentry-trace
and baggage
are present in the request. If so, distributed 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").
- Package:
- npm:@sentry/bun
- Version:
- 7.94.1
- Repository:
- https://github.com/getsentry/sentry-javascript