Custom Instrumentation
On this page, you will learn how to manually propagate trace information into and out of your Node.js application.
Distributed
- You've Set Up Performance in Sentry.
- You're using one of the platforms that include distributed tracing out of the box:
@sentry/nextjs
@sentry/sveltekit
@sentry/remix
@sentry/astro
If you're not using any of the packages above, take a look at the framework-specific Sentry integrations (like our Express integration). These integrations will also enable distributed tracing automatically for your application. If you can't find an integration for your framework, it is possible to set up distributed tracing for your application manually.
Enabling Distributed Tracing
You can setup the Http
integration in combination with tracesSampleRate: 0
to enable distributed
To enable distributed tracing for your frontend, configure the Http
or Undici
integration in 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.Integrations.Http({ tracing: true }),
// The Undici integrations instruments fetch in Node 18+
new Sentry.Integrations.Undici(),
],
// Optionally disable performance monitoring:
// tracesSampleRate: 0,
});
Enabling Distributed Tracing without Http
/Undici
Integration
If you do not want to use the Http
or Undici
integrations, you can manually extract and inject
- Extract and store incoming tracing information from incoming request headers or similar.
- Inject tracing information to any outgoing requests.
To learn more about distributed tracing, see our Distributed Tracing docs.
Extracting Incoming Tracing Information
You must extract and store incoming
continueTrace()
function to help you with this. Incoming tracing information can come from different places:- In a web environment, it's sent with HTTP headers, for example, by another Sentry SDK used in your frontend projectRepresents your service in Sentry and allows you to scope events to a distinct application..
- In a job queue, it can be retrieved from meta or header variables.
- You also can pick up tracing information from environment variables.
Here's an example of how to extract and store incoming tracing information using continueTrace()
:
const http = require("http");
http.createServer((request, response) => {
const sentryTraceHeaders = request.headers["sentry-trace"];
const sentryTrace = Array.isArray(sentryTraceHeaders)
? sentryTraceHeaders.join(",")
: sentryTraceHeaders;
const baggage = request.headers["baggage"];
const requestTransaction = Sentry.continueTrace(
{ sentryTrace, baggage },
(transactionContext) => {
return Sentry.startTransaction({
...transactionContext,
name: "my request",
op: "http.server",
});
}
);
// Your API code...
requestTransaction.finish();
});
In this example, we create a new transaction that is attached to the trace specified in the sentry-trace
and baggage
headers.
Inject Tracing Information to Outgoing Requests
For distributed
requestTransaction
, sentry-trace
and baggage
, must be added to outgoing http/fetch requests.Here's an example of how to collect and inject this tracing information to outgoing requests:
// Create `sentry-trace` header
const sentryTraceHeader = requestTransaction.toTraceparent();
// Create `baggage` header
const dynamicSamplingContext = requestTransaction.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/node
- Version:
- 7.94.1
- Repository:
- https://github.com/getsentry/sentry-javascript