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