How does Sentry's backend SDKs (ex. next.js) track of metadata across requests?

[AbhiPrasad]

From Discord: https://discord.com/channels/621778831602221064/1185246613652910132

User jackfischer asks:

Hey, I'm wondering how it's possible for Sentry's backend SDKs (we're using next.js) to keep track of metadata like user IDs per request when there are concurrent requests happening and the data isn't obviously passed through the call tree?

Put another way, when an exception is thrown and manually captured Sentry.captureException how does it possibly know what request it is in?

[AbhiPrasad]

SDK Version at time of answer: 7.92.0

The Next.js SDK handles this automatically for you leveraging AsyncLocalStorage. Our other higher-level backend JS SDKs like SvelteKit, Remix, Serverless also handle this automatically.

If you're using Express, you need to use the Sentry request handler.

// RequestHandler creates a separate execution context, so that all
// transactions/spans/breadcrumbs are isolated across requests
app.use(Sentry.Handlers.requestHandler());

If you're using the plain Node SDK (or Bun or Deno), you'll can isolate a certain set of code via the runWithAsyncContext method. See: https://docs.sentry.io/platforms/node/configuration/async-context/ for more info.

const Sentry = require("@sentry/node");

function requestHandlerMiddleware(req, res, next) {
  // Any breadcrumbs or tags added will be isolated to the request
  return Sentry.runWithAsyncContext(() => {
    return next(req, res);
  });
}