Lacking documentation regarding distributed tracing

[jansedlon]

Hi @Lms24 ! I noticed that you're probably the project manager. You have answered to few of my issues before. I'm sorry if mentioning you here is not relevant.

Let me just say that I love Sentry and I don't mean to offend anyone, I just want to share my experience of using Sentry.

I have a React Remix project and I had setup distributed tracing a few months ago. I though it was working but today I found out that it does not. I'm trying to make sense of the documentation and there's so many information either missing or incorrect.

It's really hard to summarize it because it's been a pain for the last few days. So I'm just gonna share the parts where I had an issue.
I'm probably gonna update this post from time to time when I find something else.

Before I start, let me share my configuration

entry.client.tsx

Sentry.init({
  dsn: ENV.SENTRY_DSN,
  environment: ENV.SENTRY_ENVIRONMENT,
  integrations: [
    new Sentry.BrowserTracing({
      routingInstrumentation: Sentry.remixRouterInstrumentation(
        useEffect,
        useLocation,
        useMatches,
      ),
    }),
    Sentry.replayIntegration(),
    new Sentry.BrowserProfilingIntegration(),
    captureConsoleIntegration({ levels: ["error"] }),
  ],
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for performance monitoring.
  // We recommend adjusting this value in production
  tracesSampleRate: ENV.APP_ENV === "production" ? 0.5 : 0.1,

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  beforeSend(event) {
    if (event.request?.url) {
      const url = new URL(event.request.url);

      if (
        url.protocol === "chrome-extension:" ||
        url.protocol === "moz-extension:"
      ) {
        // This error is from a browser extension, ignore it
        return null;
      }
    }

    return event;
  },
});

entry.server.tsx

Sentry.init({
    dsn: ENV.SENTRY_DSN,
    tracesSampleRate: env.APP_ENV === "production" ? 0.5 : 0.1,
    environment: env.SENTRY_ENVIRONMENT,
    denyUrls: [
      /\/resources\/healthcheck/,
      /\/build\//,
      /\/favicons\//,
      /\/images\//,
      /\/fonts\//,
      /\/favicon.ico/,
      /\/site\.webmanifest/,
      /.*\.map$/,
    ],
    maxValueLength: 5000,
    integrations: [
      new Sentry.Integrations.Http({ tracing: true }),
      new Sentry.Integrations.Prisma({ client: prisma }),
      new ProfilingIntegration(),
      new Sentry.Integrations.RequestData(),
    ],
    beforeSendTransaction(event) {
      if (event.request?.url?.includes("/healthcheck")) return null;

      return event;
    },
  });

In my Express server I use the wrapExpressCreateRequestHandler and

app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.tracingHandler());

Setting up meta tags for sentry-trace and baggage

I had this snippet in my code for some time but I didn't know where the values are coming from.

export const meta = ({
  data,
}: Sentry.SentryMetaArgs<MetaFunction<typeof loader>>) => {
  return [
    { title: "Flixy" },
    { name: "sentry-trace", content: data?.sentryTrace },
    { name: "baggage", content: data?.sentryBaggage },
  ];
};

So I went through the documentation again and found this part

Ookay, so the important part is

For sentry-trace, use span.toSentryTrace() (or equivalent, depending on the backend platform). This guarantees that a new and unique value will be generated for each request. For baggage, use serializeBaggage(span.getBaggage()).

Nice, so in my root loader should be span.toSentryTrace(). How do I get the span? I tried

const span = Sentry.default.continueTrace(
    {
      sentryTrace: sentryTrace ?? undefined,
      baggage: baggage ?? undefined,
    },
    (context) => {
      return Sentry.startInactiveSpan({
        ...context,
        name: "rootLoader",
        op: "transaction",
      });
    },
  );

Is this correct? I have no idea. I thought that the Sentry middlewares for tracing for Express server should inject headers and I should have access to them in my root loader, but I dont. Then the second parameter of continueTrace. startTransaction is deprecated and alternatives are startInactiveSpan, startSpanManual and startSpan. Only startInactiveSpan doesn't require second argument which is a function. Again, is this correct? I have no idea 😅. Also, continueTrace could return undefined. What should i do in this case? Should I create a trace manually or a span? And how?

Right, so now I have a span which I don't is correct and then I have to return the necessary data from the loader so I can access it in meta function.

For sentry-trace, use span.toSentryTrace() (or equivalent, depending on the backend platform)

There is no function called toSentryTrace attached to Span in the Remix SDK. After some investigating I found there is a function called spanToTraceHeader coming from @sentry/core. I had to install this dependency even thought it would probably make sense to export it from the relevant SDKs.

For baggage, use serializeBaggage(span.getBaggage()).

Uhm, I don't think there is a function called serializeBaggage anywhere. I tried looking at @sentry/core, @sentry/utils, etc. I found this code in utils which has some helpers but I'm not sure which one to use. And getBaggage also doesn't exist for Span.

For now, this is where i ended up. Please note that I'm really not trying to be one of those "Karen"s and I understand that distributed tracing is hard to implement but it would be great if there was a video / article / documentation section how to implement this step by step. Making sense of errors from frontend to object is really the important part when it comes to SSR frameworks like Remix

[Lms24]

Hi @jansedlon, first of all, thank you a ton for writing in and for detailing your process! It's always easier to say nothing and move on instead of sharing such feedback so I just wanted to let you know we appreciate this a lot!

I already asked @onurtemizkan who has been working a lot on the Remix SDK to share thoughts around your experience as well so that we can find a good solution and ideally some clear points that we can improve on our end.

Let me address some things already upfront:

As far as I understand these are your main pain points:

• Lack of distributed tracing documentation: I fully agree; I had to search for the page you mentioned myself and it took me 5 attempts to find it. Not great. I'm going to wait for Onur's response to formulate a concrete action but if there's a need to add additional configuration for distributed tracing, we should already include this in the Getting Started (or manual setup) page.
• Missing exports and package confusion: IMHO, as long as you don't do very custom things, you shouldn't be required to add any additional packages besides @sentry/remix. So again, this depends on how the expected DS setup works but if some of these functions are needed indeed, we have to export them from @sentry/remix. Sorry for the confusion!
• Confusion around startSpan APIs: (+ "How do I get the span? "): Excellent question - again something that depends on the expected DS setup, so I'll wait with a final answer. For now, I don't think you should be expected to manually create a span, continue a trace or anything of the likes. Using startSpan APIs (any of the three functions) should only be necessary for custom instrumentation and I believe we should have some request transaction/root span active at the time when <meta> tags are injected.

Please let me know if there's something else I missed. I already raised your feedback internally, too. We'll soon derive some concrete action points from this.

Again, thank you for your feedback!

PS:

I noticed that you're probably the project manager.

Fortunately, I'm "just" an engineer in the JS SDK team - more coding; less meetings 😅

[onurtemizkan]

Hi @jansedlon, thanks for the detailed explanation.

Yes, the documentation lacks information about how to set up distributed tracing. We have tried a few different approaches from the early versions to make this easier to set up and had to change the user experience a few times as well.

The current implementation of Remix SDKs distributed tracing is far from ideal. We quite recently had discussions about refactoring distributed tracing to automatically continue traces from server to browser. And the good news is we now have a working prototype. With that, we are planning to implement auto-instrumented distributed tracing without the need for meta or loaders. Distributed tracing will work OOTB.

As we're now making other broad changes (mostly around how we internally create / update Spans) in Remix SDK for v8, this update will be ideally made on top of other refactors / deprecations.

Hopefully, this will be possible in 1-2 weeks.

I'll update this discussion when we have a PR ready.

Thanks again!

[jansedlon]

Hey @onurtemizkan ! If this worked, it would be a game changer! 🙌

Anyway, since I'm a big fan of Sentry, if you wanted to improve your docs for the "average user who wants to set up a project and get started", I'd be happy to share my thoughts about unclear parts or something that anyone else could come across

[microadam]

Hey @onurtemizkan! I have been trying to setup tracing on a remix project and stumbled across similar issues to @jansedlon. Just wondering if there is any updates on the improved process for doing it at all? :)

[r3dpoint]

+1 any update on how to get a current span in a loader so that i can return trace ID and baggage?

[lforst]

@r3dpoint This page should set you up for success: https://docs.sentry.io/platforms/javascript/tracing/trace-propagation/custom-instrumentation/