Observability: Server-side instrumentation

[chargome]

Hey there!

I'd like to open the discussion on instrumenting the React Router server runtime for emitting telemetry signals.

Current Problem

At Sentry, we've been running into difficulties instrumenting React Router Framework on the server-side since the switch from Remix. The problem boils down to this:

• With react-router v7 the server-runtime package has been moved to the core react-router package which is where our instrumentation needs to take place now.
• We cannot patch the createRequestHandler function anymore, details on this can be found in this issue.

Background on ESM instrumentation

Further, since React Router is emitting ESM (like many other frameworks), we and potentially other OpenTelementry SDKs rely on Node's register hooks for instrumenting server code. Unfortunately this comes with the downside that some deployment providers do not expose these options (e.g. Vercel or Netlify). In case anyone is interested this is well documented in this observability guide.

Two Potential Solutions for a more stable way forward

React Router OTEL support

• The framework could expose an instrumentation entrypoint for the server. This could likely be a standardized instrumentation.ts file which is guaranteed to run before any server code. An example for this approach would be Next.js.
• Building on top of this, the framework could natively support emitting OTEL spans from within the framework itself for crucial observability signals e.g. within createRequestHandler. This way 3rd parties could simply pick up these spans without having to patch any internals.

Diagnostics Channel

Leveraging the native Node diagnostics channel functionality, React Router could emit signals via this channel for requests, server-loaders, server-actions, etc. – which could then be picked up by third party observability providers. This feature is also runtime agnostic (e.g. Node, Bun, Deno, Cloudflare). We could even build and maintain an official OpenTelemetry instrumentation around this approach.

A good example for this approach would be fastify.

Impact

The React Router community would benefit from having more structured guidance on observability, as current resources on best practices in this area are still quite limited.

I would appreciate any thoughts on this topic and would also offer help contributing this feature to the framework once we identify a clear way forward!

[brophdawg11]

Have you seen the Events proposal? That is along the lines of what I've been envisioning to give devs client-side hooks to know when certain things are happening inside the router. This feels like the server-side equivalent of that?

I think ideally we'd end up with an API that is consistent on the server and client and agnostic of how it's gets consumed. So if we had a generic set of events that fired on both the server and the client, they could be transformed into OTEL on the server (via a userland/community adapter) and window.performance.mark/measure calls on the client for dev tools profiling.

Do you think a generic events approach could meet the needs here?

[chargome]

This looks pretty much like what we're looking for yes! Depending on the implementation details this would be great for observability providers like us if we can consume these events on the server.

Any rough estimates when you plan on starting to work on this? Would you be open for contributions on this topic?

[brophdawg11]

Yeah I'm interested in getting something like this added and so consider this a 👍 from me in our new feature process. I probably won't have time to work on this in the very near future so I'd love community help.

We need one more SC member to express interest before moving this to Stage 1 where we'll accept a PR but feel free to start a investigating in a fork and share back here until we get to an official PR. You should be able to test out your changes locally in playground/framework-express.

I'd love to start with something very simple that maybe just tracks the start/end of a request (on the server) and a navigation (on the client) through a generic JS event setup (not tied to OTEL or node diagnostics etc.).

// client
createBrowserRouter(routes, {
  onEvent(event) {
    console.log(event)
  },
});

// server
createRequestHandler({
  build,
  onEvent(event) {
    console.log(event)
  }  
});

Once we proof that out and align on an API and ensure it can be adapted for OREL and performance.mark/measure we can start expanding it deeper to track loaders, actions, redirects, errors, etc.

Another thing I was wondering is whether RR should be in charge of the event/trace ID generation process - that feels like something maybe better left to app code so it can use whatever the app uses elsewhere and/or prefix ids with a user id or something. Maybe we could expand the API to something like:

createBrowserRouter(routes, {
  events: {
    getId(request) {
      // app code to generate an id
    },
    onEvent(event) {
      // event.id would be populated using the above
      console.log(event)
    }
  },
});

[brookslybrand]

Seems reasonable to me! I also wouldn't be implementing, but I'd love to see us move forward with a stage 1 issue and open up to community help 👍

[brophdawg11]

cc: @rossipedia who I know has done a bunch with RR+OTEL so probably has some thoughts on this API too

[rossipedia]

👍 to onEvent from me. Although I'm wondering if it might be more idiomatic to pass in an EventTarget:

const events = new EventTarget();
events.addEventListener('navigate', (e) => {
  // ...
});

events.addEventListener('error', (e) => {
  // ...
});

// etc

createRequestHandler(routes, { events });

which would be consistent with relying on Standard Primitives.

In the browser it might make even more sense to make the router itself an EventTarget:

const router = createBrowserRouter(routes);

router.addEventListener(...);

<RouterProvider router={router} />

In framework mode, you could expose an events: EventEmitter prop to <HydratedRouter /> so you could set that up in your entry.client.tsx (that's where we're currently setting up client-side error monitoring, so IMO it makes sense to expose telemetry hooks from there).

Another thing I was wondering is whether RR should be in charge of the event/trace ID generation process - that feels like something maybe better left to app code so it can use whatever the app uses elsewhere and/or prefix ids with a user id or something.

100%. In the OTEL world at least, that's a concern of the Context Propagation utilities. When you enter into a new context, you either inherit the current trace ID or you get assigned a new one. Generally you already have one by the time the React Router handler gets invoked.

[brophdawg11]

yeah I'm on board with standard primitives. It would be nice if they all felt the same so maybe events: EventTarget can be used in all locations instead of switching between EventTarget and EventEmitter?

// data - client
createBrowserRouter(routes, { events })

// data - server
createStaticHandler(routes, { events })

// framework - server
createRequestHandler(routes, { events });

// framework - client
<HydratedRouter events={events} />

[rossipedia]

I believe that should be a viable approach. I think all of the major runtimes have built-in support for Event / EventTarget 🤔

[rossipedia]

I've started working on implementing a solution to this using the pattern outlined here, initial results look promising (Event even comes with high-ish resolution timestamps 💪).

Screen.Recording.2025-08-17.at.7.09.50.PM.mov

[chargome]

Hey @rossipedia that is great! I could carve out some time to see how this might work on the server-side this week as this would help us a lot to move forward with a stable SDK version for @sentry/react-router

[rossipedia]

SGTM. My goal here is to put some primitives in place for RR so that a stable OTEL (or any other o11y stack, really) can be built on top of it without needing to patch internals.

The guts of this are actually pretty simple, it's mainly about finding the right points in the react-router codebase to invoke dispatchEvent() and making sure we have the right data attached to those events.

[chargome]

Ok had a go at this yesterday and it's indeed pretty straightforward. Looking a bit deeper on how we can build an OTEL instrumentation around just these events we'll face some issues with loosing context as any child spans from e.g. a loader or an action will not get the context from the spans we start in the event listeners. We basically always need to wrap the execution logic so we would need an API similar like on('request:start', (ctx, next) => { ... }