Skip to content

docs(tanstackstart): Add docs for distributed tracing #17735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JPeer264 wants to merge 1 commit into
base: master
Choose a base branch
from
+72 −0
Open

docs(tanstackstart): Add docs for distributed tracing #17735

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions ...form-includes/distributed-tracing/how-to-use/javascript.tanstackstart-react.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
To connect server-side and client-side traces in TanStack Start, inject trace metadata into your HTML so the browser SDK can continue the trace started on the server.

In your root route (`routes/__root.tsx`), use `getTraceData()` to retrieve the current trace context and inject it as meta tags:

```typescript {filename:routes/__root.tsx}
import type { ReactNode } from "react";
import {
Outlet,
createRootRoute,
HeadContent,
Scripts,
} from "@tanstack/react-router";
import { getTraceData } from "@sentry/tanstackstart-react";

export const Route = createRootRoute({
head: () => {
const traceData = getTraceData();
const sentryMeta = Object.entries(traceData).map(([key, value]) => ({
name: key,
content: value,
}));

return {
meta: [
...sentryMeta,
],
};
},
component: RootComponent,
});

function RootComponent() {
return (
<RootDocument>
<Outlet />
</RootDocument>
);
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
return (
<html>
<head>
<HeadContent />
</head>
<body>
{children}
<Scripts />
</body>
</html>
);
}
```

This injects `sentry-trace` and `baggage` meta tags into the HTML. The browser SDK automatically reads these tags on page load and continues the server trace, connecting your full-stack traces in Sentry.

To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues, define `tracePropagationTargets` for client-side:

<Alert>

Note: port numbers are relevant for trace propagation and the origin. You may need to configure the `tracePropagationTargets` to ensure that traces are propagated across your services if they run on different ports.

</Alert>

```typescript {filename:sentry.client.config.ts}
Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [Sentry.tanstackRouterBrowserTracingIntegration(router)],
tracesSampleRate: 1.0,
tracePropagationTargets: ["https://myproject.org", /^\/api\//],
});
```
Comment on lines +65 to +72
Copy link
Copy Markdown
Contributor

@sentry sentry Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The Sentry.init code snippet for TanStack Start uses an undefined router variable, which will cause a ReferenceError if copied directly.
Severity: HIGH

Suggested Fix

Update the documentation to show the Sentry.init call within the correct file context, such as src/router.tsx inside the getRouter() function, where the router constant is defined. Alternatively, add a note explaining where the router variable comes from and that the snippet needs to be placed in the appropriate file where router is in scope.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location:
platform-includes/distributed-tracing/how-to-use/javascript.tanstackstart-react.mdx#L65-L72

Potential issue: The documentation snippet in
`platform-includes/distributed-tracing/how-to-use/javascript.tanstackstart-react.mdx`
demonstrates initializing Sentry using
`Sentry.tanstackRouterBrowserTracingIntegration(router)`. However, the `router` variable
is not defined or imported in the provided example file context
(`sentry.client.config.ts`). When a developer follows this guide, the application will
throw a `ReferenceError: router is not defined` at runtime because the `router` instance
is not available in that scope. The correct initialization should occur where the router
is created, typically within `src/router.tsx`.

Did we get this right? 👍 / 👎 to inform future reviews.

Loading