Events

[ryanflorence]

Overview/Problem

Setting up error monitoring, analytics, etc. is cumbersome and full of footguns (especially in Remix like double counting errors since we serialize and send it over the network so both server and client monitoring counts the error).

Scope

This is only for React Router for now, there are open questions to resolve for Remix.

Use Cases

• Sentry team creating packages for Remix and React Router
• Setting up backend and frontend analytics

API/Examples

The goal for monitoring integrations is to let them create a single function that plugs in so app developers don't have more than one entry point to deal with.

While a router emits changes to state with router.subscribe, multiple monitoring events may be triggered from a single routing event emission. For example: if two loaders fail monitoring would like to know that, even though React Router only tells the UI about the first error.

import sentry from "@sentry/react-router";

const router = createBrowserRouter(routes, {
  onEvent(event) {
    sentry(event);
  },
});

Emitted events

type RouterEvent = {
  // specific type of error
  type: string;

  // field for grouping related types
  tags: string[];

  // any other information depending on the event
  payload: any;
};

This list isn't exhaustive, but here are a few examples:

{
  "type": "LOADER_ERROR",
  "tags": ["loader", "error", "navigation"],
  "payload": { error, route }
}

{
  "type": "LOADER_ERROR",
  "tags": ["loader", "error", "fetcher"],
  "payload": { error, route }
}

{
  "type": "ACTION_ERROR",
  "tags": ["action", "error", "navigation"],
  "payload": { error, route }
}

{
  "type": "RENDER_ERROR",
  "tags": ["render", "error"],
  "payload": { error, route }
}

{
  "type": "NAVIGATION_START",
  "tags": ["navigation", "metric"],
  "payload": {
    // things that have two events like "start" and "complete" have an id to
    // track them
    id: string;
    timestamp: Date,
    from: Location,
    to: Location
  }
}

{
  "type": "NAVIGATION_COMPLETE",
  "tags": ["navigation", "metric"],
  "payload": {
    id: string;
    timestamp: Date,
    duration: Number,
    from: Location,
    to: Location
  }
}

{
  "type": "NAVIGATION_ABORTED",
  "tags": ["navigation", "metric"],
  "payload": {
    id: string;
    timestamp: Date,
    duration: Number,
    from: Location,
    to: Location
    next: Location;
  }
}

{
  "type": "LOADER_START",
  "tags": ["loader", "metric", "fetcher"],
  "payload": {
    id: string;
    timestamp: Date,
    route,
    location
  }
}

{
  "type": "LOADER_START",
  "tags": ["loader", "metric", "navigation"],
  "payload": {
    id: string;
    timestamp: Date,
    route,
    from: Location,
    to: Location
  }
}

{
  "type": "LOADER_COMPLETE",
  "tags": ["loader", "metric", "fetcher"],
  "payload": {
    id: string;
    timestamp: Date,
    duration: Number,
    route: route,
  }
}

Remix

Clientside

I'm not sure how we're hydrating after RRR work is done, but I imagine it will look like this:

// entry.client.tsx
import sentry from "@sentry/remix-react/client";

const router = createBrowserRouter(routes, {
  onEvent(event) {
    sentry(event);
  },
});

Again, not sure if createBrowserRouter is exposed in our new entry.client.tsx but I suspect it will need to be.

Serverside

I'm not sure where this stuff should shake out for Remix yet. I've long thought our entry.server needs to be revisited completely. Trying to think about implementing monitoring like sentry I'm a bit at a loss to capture everything in one place.

Perhaps exploring this later will guide that conversation or I'll realize I'm being dense. I do have a couple extra thoughts though:

It would be interesting for monitoring to track loader start/end both client and serverside so you can see the amount of time the user's network is responsible for in the client stats

Open Questions

• How will it look for remix serverside?
• How much bundle budget are we willing to spend? The payloads and extra tracking aren't free.
• Totally willing and eager to bikeshed anything in here

Implementation Notes

I think it'll be pretty straightforward, we just call the onEvent whenever stuff happens with the payload.

Issues/PRs/Discussions

#8327, #9688 (related)

[machour]

Maybe this and https://github.com/remix-run/RFC-Internal/discussions/10 should be designed together.

Also, would it make sense to allow developers to fire their own events? Do we want a generic Remix event handling system that goes beyond error reporting?

[brophdawg11]

@machour Do you recall what that was before we moved those into the public roadmap?

Also here's another related feature request: #9688

[machour]

I can't seem to find it anymore, but I believe it was a proposal from @sergiodxa about being able to subscribe to events and sent stuff to sentry. Rings any bell Sergio?

[sergiodxa]

I think it was this one remix-run/remix#2190

[machour]

No, it was something you posted on November 5th, almost a minute before Ryan's proposal. We discussed it briefly on discord, and we saw an opportunity to have a generic event/callback mechanism in Remix, where the developers could also trigger their own events..

[develra]

I would love this feature to better be able to track page-load metrics in react-router land! At the moment I don't think there is a good way to figure out NAVIGATION_START in situations where the user uses the browser forward/back to initiative navigation outside of useBlocker -

[brophdawg11]

Events will make this much easier but at the moment anytime useNavigation leaves the idle state you can track the start of a navigation. And the end of a navigation is when it returns back to idle. I played around with a way to report navigation start/end to the dev tools profiler using window.performance a while back in https://github.com/brophdawg11/remix-use-spa-metrics.

[develra]

So the issue I'm having right now is when the user navigates with the back-button navigation never leaves the idle state - but otherwise I agree with our suggestion!

[brophdawg11]

Hm - do you have loaders? If not (or if they're synchronous) then I think instead what you're likely running into is a synchronous navigation. If there are no loaders to run or if they run synchronously, then useNavigation will never leave idle since we're able to immediately render the new route. In this case, if location.key changes and navigation.state never leaves idle then it was a synchronous navigation and NAVIGATION_START and NAVIGATION_END are effectively identical. This is also common in back button routes to ancestors where we already have the loader data from prior loader and we don't have to re-run it.

Events are definitely the eventual "correct" solution to this 👍

[develra]

That makes sense - I think the situation I was trying I hadn't yet pulled the hydration code out to a loader. Good to know it should work once loaders are properly setup - I'll give that a try. Thanks!

[jrnail23]

TBH, I'm really looking forward to this Events API becoming a reality.

In my particular case, this events proposal would make scroll restore simpler and more reliable, as the locationState could be augmented with a scrollPosition, and we could depend on location state as a single source of truth for this sort of thing, rather than needing to track scroll positions separately, as is done now (in sessionStorage and in a module-level variable).

Having the NAVIGATION_START and NAVIGATION_COMPLETE events (as demonstrated above) would make it easier to capture previous location for application navigation scenarios that fall outside of the navigate(-1) approach. In my app, this takes the form of a "Back to List" link on an item detail page that brings the user back to the list from which that item detail was chosen, including that list's scroll position and applied search filters.

[brophdawg11]

Glad to help! The getKey prop may also be useful to you since that is designed to allow you to save/restore based on something other than the specific entry in the history stack, for example - based on pathname. pathname alone is probably insufficient for your case since you don't want subsequent in-page navigations which add query params to all share the same scroll restoration key. But you might be able to get away with location.pathname on the list view path and the default (location.key) on other routes.

[jrnail23]

Hey @brophdawg11 , my app uses a basename, which seems to complicate usage of getKey, as I'm seeing scroll positions getting stored as both / and /my-base-name (referring to the same page, I assume). Everything seems to work so far (beautifully, in fact), but of course I'm a bit uncomfortable not knowing why the discrepancies exist.
BTW, I'm doing this for getKey: (location) => location.pathname + location.search

[jrnail23]

@brophdawg11, to confirm, at different points, my default location is being logged as both / and /my-base-name. It looks like in useScrollRestoration, when getKey is called in the pagehide handler, the location it passes to getKey (retrieved from useLocation) has a pathname of /, but when getKey is invoked inside the router, the location.pathname is /my-base-name instead (both using the same location, with location key of default).

I'm noticing this as my tests for scroll restore on page reload are now failing -- presumably because the router is looking for the scroll position using a different key than the one under which it was stored (the pagehide handler used / as the key, while the router is looking for /my-base-name, which doesn't exist yet).

[brophdawg11]

yeah that's probably just a bug 😬 . The basename should be stripped in all cases - I'll try to take a quick look but would you mind filing that as an issue and mentioning me in it so it's on my radar?

[brophdawg11]

nvm this was a quick fix: #10550

[AlemTuzlak]

I would love if there was a way to listen to these events on the client using import.meta.hot this would allow me to write listeners in my own components/hooks and not having to create some sort of context or something along those lines