#React Router 7 framework mode

1 messages · Page 1 of 1 (latest)

unkempt birchBOT
#

Hi @winged oyster. I'm happy to dig into this for you! I'll check my internal sources for answers to your question! :wave:

#

Based on the official Sentry documentation and related GitHub issues, there are a few important points to consider when instrumenting traces within React Router 7 loaders in framework mode:

  1. Manual Span Creation in Loaders:
    You are using Sentry.startSpan to manually create spans inside your loader. This is a valid approach, but for these spans to be associated with a transaction and sent to Sentry, there must be an active transaction context. If there is no active transaction (for example, if the loader is not being called within a Sentry-instrumented request), the spans may not be sent or associated correctly.

  2. Recommended Loader Instrumentation:
    Sentry provides a helper specifically for instrumenting server loaders: wrapServerLoader. This helper ensures that the loader runs within the correct Sentry transaction context, so any spans you create (manually or automatically) are properly attached and sent to Sentry.
    Example:

import * as Sentry from "@sentry/react-router";

export const loader = Sentry.wrapServerLoader(
  {
    name: "Load Some Data",
    description: "Loads some data from the db",
  },
  async ({ params }) => {
    // ... your loader logic, including Sentry.startSpan if needed
  }
);

This approach is documented as the recommended way to instrument loaders in React Router 7 framework mode, especially if you want traces to appear in Sentry's dashboard Server-Side Setup.

  1. SDK Initialization:
    Ensure that Sentry is initialized on the server side (e.g., in instrument.server.mjs) before any loader code runs, and that you are using the correct Node version for automatic instrumentation (Node 20 < 20.19 or Node 22 < 22.12). If you are on a different version, you must use manual wrappers as shown above.
#
  1. Error Reporting vs. Tracing:
    The error you throw is being captured because Sentry's error instrumentation is working. However, the absence of traces suggests that the spans are not being attached to a transaction, likely due to missing context or not using the recommended wrapper.

Summary:
To get traces from your loader, wrap it with Sentry.wrapServerLoader. This will ensure that all spans (including those created with Sentry.startSpan) are properly attached to a transaction and sent to Sentry. If you only use Sentry.startSpan without the wrapper and there is no active transaction, the spans will not be sent.

If you follow this pattern and still do not see traces, double-check your Sentry server initialization and Node version compatibility as described in the documentation Server-Side Setup.

If you need to customize the loader logic, you can still use Sentry.startSpan inside the async function passed to wrapServerLoader.

References:

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@winged oyster Our robots are still learning and improving, please let us know if this response was correct by reacting below.

winged oyster
unkempt birchBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Thank you for clarifying your setup.

Based on the official Sentry documentation for React Router 7 framework mode, if you cannot use the recommended NODE_OPTIONS=--import ./instrument.server.mjs approach and instead import the instrumentation file directly in your entry.server.tsx, Sentry warns that automatic instrumentation will be incomplete. This means you may miss automatically captured spans and traces for some server-side operations, including those in loaders—even if you use Sentry.wrapServerLoader or manual Sentry.startSpan calls. This limitation is explicitly documented:

When importing the instrumentation file directly in entry.server.tsx instead of using the --import flag, automatic instrumentation will be incomplete and you'll miss automatically captured spans and traces for some of your application's server-side operations. This approach should only be used when the NODE_OPTIONS approach is not available on your hosting platform.
Alternative Setup for Hosting Platforms

In summary:

  • If you cannot use the NODE_OPTIONS import flag and must import the instrumentation file directly, you will not get full tracing support for server-side operations, including loaders.
  • This is a known limitation, and there is currently no documented workaround for full tracing in this scenario.
  • Error reporting will still work, but traces and spans may not appear as expected.

If you need full tracing, you will need to use a hosting environment that allows the NODE_OPTIONS=--import approach, as per Sentry's documentation. Otherwise, you will be limited to incomplete instrumentation.

#

If you have further constraints or need to discuss alternative approaches, Sentry recommends following updates in their documentation and GitHub issues, as this is a known pain point for ESM frameworks and certain hosting providers.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@winged oyster Our robots are still learning and improving, please let us know if this response was correct by reacting below.

winged oyster
unkempt birchBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

You are absolutely right—there is a difference between incomplete instrumentation and no instrumentation at all. According to Sentry’s documentation, when you import the instrumentation file directly in entry.server.tsx (instead of using the NODE_OPTIONS=--import flag), automatic instrumentation will be incomplete. However, the documentation does not explicitly state that manual spans (created with Sentry.startSpan or Sentry.wrapServerLoader) will be entirely non-functional in this setup.

The docs say:

When importing the instrumentation file directly in entry.server.tsx instead of using the --import flag, automatic instrumentation will be incomplete and you'll miss automatically captured spans and traces for some of your application's server-side operations. This approach should only be used when the NODE_OPTIONS approach is not available on your hosting platform.

— Alternative Setup for Hosting Platforms

This suggests that some instrumentation may still work, but you will not get the full set of automatically captured spans. The documentation does not clarify whether manual spans are always sent in this scenario, nor does it guarantee that they will be. There is an implication that some manual instrumentation might still function, but the lack of traces in your case could be due to missing transaction context or other limitations of the ESM import approach.

#

In summary:

  • The knowledge sources do not explicitly confirm whether manual spans will always be sent when importing the instrumentation file directly.
  • The documentation only guarantees that automatic instrumentation will be incomplete, not absent.
  • If you are not seeing any manual spans, it may be due to the lack of an active transaction context or other limitations not fully detailed in the docs.

If you need a definitive answer or workaround, you may need to follow up with Sentry support or monitor their GitHub issues for updates, as this is a known limitation and pain point for ESM environments and certain hosting platforms.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: