Skip to content

Commit 41858f2

Browse files
nicohrubecclaude
andauthored
feat(tanstackstart-react): Show readable server function names in traces (#21190)
Uses `serverFnMeta` from the TanStack Start function middleware context to replace hash-based server function span names with human-readable ones (e.g. `GET /_serverFn/greet` instead of `GET /_serverFn/a10e70b3...`). Also attaches function metadata (`id`, `filename`) as span attributes. The span still gets started in `wrapFetchWithSentry` but then updated with the available metadata in the global function middleware. I only update the custom server function span itself and don't update the http span, so that one will now show up with a description of `GET /serverFn/*` (see trace below). We can certainly think about also updating the http span, but I wasn't sure how to name this if there is for instance multiple nested server function calls. Happy to hear any thoughts on this. The `tanstackstart.function.hash.sha256` span attribute has been renamed to `tanstackstart.function.id` (should be more accurate name given that that is the name the framework itself uses for the metadata). Example trace from local testing: <img width="1059" height="612" alt="Screenshot 2026-05-27 at 14 01 39" src="https://github.com/user-attachments/assets/bcb0c8ed-7877-49a3-b57b-540bc04ae213" /> <img width="393" height="122" alt="Screenshot 2026-05-27 at 14 01 58" src="https://github.com/user-attachments/assets/57e45d96-8807-4bcc-83e7-b7fc8f0ddc59" /> Fixes #21185 Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 5fe6aab commit 41858f2

8 files changed

Lines changed: 101 additions & 77 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@
1616

1717
Server transaction names are now parametrized automatically (e.g., `GET /users/123` becomes `GET /users/$userId`), improving transaction grouping in Sentry.
1818

19+
- **feat(tanstackstart-react): Show readable server function names in traces ([#21190](https://github.com/getsentry/sentry-javascript/pull/21190))**
20+
21+
Server function spans now show human-readable names (e.g., `GET /_serverFn/greet` instead of `GET /_serverFn/a10e70b3...`). The `tanstackstart.function.hash.sha256` span attribute has been renamed to `tanstackstart.function.id`.
22+
1923
## 10.54.0
2024

2125
### Important Changes

‎dev-packages/e2e-tests/test-applications/tanstackstart-react-cloudflare/tests/transaction.test.ts‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -25,14 +25,16 @@ test('Sends a server function transaction with span from wrapFetchWithSentry', a
2525
expect(transactionEvent?.spans).toHaveLength(1);
2626
expect(transactionEvent?.spans).toEqual([
2727
expect.objectContaining({
28-
description: expect.stringContaining('GET /_serverFn/'),
28+
description: 'GET /_serverFn/testLog',
2929
op: 'function.tanstackstart',
3030
origin: 'auto.function.tanstackstart.server',
31-
data: expect.objectContaining({
31+
data: {
3232
'sentry.op': 'function.tanstackstart',
3333
'sentry.origin': 'auto.function.tanstackstart.server',
34-
'tanstackstart.function.hash.sha256': expect.any(String),
35-
}),
34+
'sentry.source': 'route',
35+
'tanstackstart.function.id': expect.any(String),
36+
'tanstackstart.function.filename': 'src/routes/test-serverFn.tsx',
37+
},
3638
}),
3739
]);
3840
});
@@ -62,14 +64,16 @@ test('Sends a server function transaction for a nested server function with manu
6264
expect(transactionEvent?.spans).toEqual(
6365
expect.arrayContaining([
6466
expect.objectContaining({
65-
description: expect.stringContaining('GET /_serverFn/'),
67+
description: 'GET /_serverFn/testNestedLog',
6668
op: 'function.tanstackstart',
6769
origin: 'auto.function.tanstackstart.server',
68-
data: expect.objectContaining({
70+
data: {
6971
'sentry.op': 'function.tanstackstart',
7072
'sentry.origin': 'auto.function.tanstackstart.server',
71-
'tanstackstart.function.hash.sha256': expect.any(String),
72-
}),
73+
'sentry.source': 'route',
74+
'tanstackstart.function.id': expect.any(String),
75+
'tanstackstart.function.filename': 'src/routes/test-serverFn.tsx',
76+
},
7377
}),
7478
expect.objectContaining({
7579
description: 'testNestedLog',

‎dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/transaction.test.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,15 @@ test('Sends a server function transaction with auto-instrumentation', async ({ p
2727
expect(transactionEvent?.spans).toEqual(
2828
expect.arrayContaining([
2929
expect.objectContaining({
30-
description: expect.stringContaining('GET /_serverFn/'),
30+
description: 'GET /_serverFn/testLog',
3131
op: 'function.tanstackstart',
3232
origin: 'auto.function.tanstackstart.server',
3333
data: {
3434
'sentry.op': 'function.tanstackstart',
3535
'sentry.origin': 'auto.function.tanstackstart.server',
36-
'tanstackstart.function.hash.sha256': expect.any(String),
36+
'sentry.source': 'route',
37+
'tanstackstart.function.id': expect.any(String),
38+
'tanstackstart.function.filename': 'src/routes/test-serverFn.tsx',
3739
},
3840
status: 'ok',
3941
}),
@@ -65,13 +67,15 @@ test('Sends a server function transaction for a nested server function only if i
6567
expect(transactionEvent?.spans).toEqual(
6668
expect.arrayContaining([
6769
expect.objectContaining({
68-
description: expect.stringContaining('GET /_serverFn/'),
70+
description: 'GET /_serverFn/testNestedLog',
6971
op: 'function.tanstackstart',
7072
origin: 'auto.function.tanstackstart.server',
7173
data: {
7274
'sentry.op': 'function.tanstackstart',
7375
'sentry.origin': 'auto.function.tanstackstart.server',
74-
'tanstackstart.function.hash.sha256': expect.any(String),
76+
'sentry.source': 'route',
77+
'tanstackstart.function.id': expect.any(String),
78+
'tanstackstart.function.filename': 'src/routes/test-serverFn.tsx',
7579
},
7680
status: 'ok',
7781
}),

‎packages/tanstackstart-react/src/server/globalMiddleware.ts‎

Lines changed: 52 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,20 @@
1-
import { addNonEnumerableProperty, captureException } from '@sentry/core';
1+
import {
2+
SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
3+
addNonEnumerableProperty,
4+
captureException,
5+
getActiveSpan,
6+
spanToJSON,
7+
updateSpanName,
8+
} from '@sentry/core';
29
import type { TanStackMiddlewareBase } from '../common/types';
310
import { SENTRY_INTERNAL } from './middleware';
411

12+
type ServerFnMeta = {
13+
id?: string;
14+
name?: string;
15+
filename?: string;
16+
};
17+
518
function createSentryMiddlewareHandler(mechanismType: string) {
619
return async function sentryMiddlewareHandler({ next }: { next: () => Promise<unknown> }): Promise<unknown> {
720
try {
@@ -15,6 +28,41 @@ function createSentryMiddlewareHandler(mechanismType: string) {
1528
};
1629
}
1730

31+
function createSentryFunctionMiddlewareHandler(mechanismType: string) {
32+
return async function sentryFunctionMiddlewareHandler({
33+
next,
34+
serverFnMeta,
35+
}: {
36+
next: () => Promise<unknown>;
37+
serverFnMeta?: ServerFnMeta;
38+
}): Promise<unknown> {
39+
const activeSpan = getActiveSpan();
40+
const spanData = activeSpan ? spanToJSON(activeSpan) : undefined;
41+
if (activeSpan && spanData?.op === 'function.tanstackstart') {
42+
if (serverFnMeta?.name) {
43+
const method = spanData.description?.split(' ')[0] || 'GET';
44+
updateSpanName(activeSpan, `${method} /_serverFn/${serverFnMeta.name}`);
45+
activeSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
46+
}
47+
if (serverFnMeta?.id) {
48+
activeSpan.setAttribute('tanstackstart.function.id', serverFnMeta.id);
49+
}
50+
if (serverFnMeta?.filename) {
51+
activeSpan.setAttribute('tanstackstart.function.filename', serverFnMeta.filename);
52+
}
53+
}
54+
55+
try {
56+
return await next();
57+
} catch (e) {
58+
captureException(e, {
59+
mechanism: { type: mechanismType, handled: false },
60+
});
61+
throw e;
62+
}
63+
};
64+
}
65+
1866
/**
1967
* Global request middleware that captures errors from API route requests.
2068
* Should be added as the first entry in the `requestMiddleware` array of `createStart()`.
@@ -36,8 +84,9 @@ export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = {
3684
'~types': undefined,
3785

3886
options: {
39-
// eslint-disable-next-line @typescript-eslint/no-explicit-any
40-
server: createSentryMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (...args: any[]) => any,
87+
server: createSentryFunctionMiddlewareHandler('auto.middleware.tanstackstart.server_function') as (
88+
...args: any[] // eslint-disable-line @typescript-eslint/no-explicit-any
89+
) => any, // eslint-disable-line @typescript-eslint/no-explicit-any
4190
},
4291
};
4392

‎packages/tanstackstart-react/src/server/utils.ts‎

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,6 @@
11
import type { StartSpanOptions } from '@sentry/core';
22
import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/node';
33

4-
/**
5-
* Extracts the SHA-256 hash from a server function pathname.
6-
* Server function pathnames are structured as `/_serverFn/<hash>`.
7-
* This function matches the pattern and returns the hash if found.
8-
*
9-
* @param pathname - the pathname of the server function
10-
* @returns the sha256 of the server function
11-
*/
12-
export function extractServerFunctionSha256(pathname: string): string {
13-
const serverFnMatch = pathname.match(/\/_serverFn\/([a-f0-9]{64})/i);
14-
return serverFnMatch?.[1] ?? 'unknown';
15-
}
16-
174
/**
185
* Returns span options for TanStack Start middleware spans.
196
*/

‎packages/tanstackstart-react/src/server/wrapFetchWithSentry.ts‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ import {
66
startSpan,
77
} from '@sentry/node';
88
import { updateSpanWithRouteParametrization } from './routeParametrization';
9-
import { extractServerFunctionSha256 } from './utils';
109

1110
declare const __SENTRY_ROUTE_PATTERNS__: string[] | undefined;
1211

@@ -143,20 +142,16 @@ export function wrapFetchWithSentry(serverEntry: ServerEntry): ServerEntry {
143142

144143
// instrument server functions
145144
if (url.pathname.includes('_serverFn') || url.pathname.includes('createServerFn')) {
146-
const functionSha256 = extractServerFunctionSha256(url.pathname);
147145
const op = 'function.tanstackstart';
148146

149-
const serverFunctionSpanAttributes = {
150-
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.function.tanstackstart.server',
151-
[SEMANTIC_ATTRIBUTE_SENTRY_OP]: op,
152-
'tanstackstart.function.hash.sha256': functionSha256,
153-
};
154-
155147
return await startSpan(
156148
{
157-
op: op,
149+
op,
158150
name: `${method} ${url.pathname}`,
159-
attributes: serverFunctionSpanAttributes,
151+
attributes: {
152+
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.function.tanstackstart.server',
153+
[SEMANTIC_ATTRIBUTE_SENTRY_OP]: op,
154+
},
160155
},
161156
async () => {
162157
return target.apply(thisArg, args);
Lines changed: 12 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,16 @@
11
import { describe, expect, it } from 'vitest';
2-
import { extractServerFunctionSha256 } from '../../src/server/utils';
2+
import { getMiddlewareSpanOptions } from '../../src/server/utils';
33

4-
describe('extractServerFunctionSha256', () => {
5-
it('extracts SHA256 hash from valid server function pathname', () => {
6-
const pathname = '/_serverFn/1ac31c23f613ec7e58631cf789642e2feb86c58e3128324cf00d746474a044bf';
7-
const result = extractServerFunctionSha256(pathname);
8-
expect(result).toBe('1ac31c23f613ec7e58631cf789642e2feb86c58e3128324cf00d746474a044bf');
9-
});
10-
11-
it('extracts SHA256 hash from valid server function pathname that is a subpath', () => {
12-
const pathname = '/api/_serverFn/1ac31c23f613ec7e58631cf789642e2feb86c58e3128324cf00d746474a044bf';
13-
const result = extractServerFunctionSha256(pathname);
14-
expect(result).toBe('1ac31c23f613ec7e58631cf789642e2feb86c58e3128324cf00d746474a044bf');
15-
});
16-
17-
it('extracts SHA256 hash from valid server function pathname with query parameters', () => {
18-
const pathname = '/_serverFn/1ac31c23f613ec7e58631cf789642e2feb86c58e3128324cf00d746474a044bf?param=value';
19-
const result = extractServerFunctionSha256(pathname);
20-
expect(result).toBe('1ac31c23f613ec7e58631cf789642e2feb86c58e3128324cf00d746474a044bf');
21-
});
22-
23-
it('extracts SHA256 hash with uppercase hex characters', () => {
24-
const pathname = '/_serverFn/1AC31C23F613EC7E58631CF789642E2FEB86C58E3128324CF00D746474A044BF';
25-
const result = extractServerFunctionSha256(pathname);
26-
expect(result).toBe('1AC31C23F613EC7E58631CF789642E2FEB86C58E3128324CF00D746474A044BF');
27-
});
28-
29-
it('returns unknown for pathname without server function pattern', () => {
30-
const pathname = '/api/users/123';
31-
const result = extractServerFunctionSha256(pathname);
32-
expect(result).toBe('unknown');
33-
});
34-
35-
it('returns unknown for pathname with incomplete hash', () => {
36-
// Hash is too short (only 32 chars instead of 64)
37-
const pathname = '/_serverFn/1ac31c23f613ec7e58631cf789642e2f';
38-
const result = extractServerFunctionSha256(pathname);
39-
expect(result).toBe('unknown');
4+
describe('getMiddlewareSpanOptions', () => {
5+
it('returns correct span options', () => {
6+
const options = getMiddlewareSpanOptions('testMiddleware');
7+
expect(options).toEqual({
8+
op: 'middleware.tanstackstart',
9+
name: 'testMiddleware',
10+
attributes: {
11+
'sentry.op': 'middleware.tanstackstart',
12+
'sentry.origin': 'auto.middleware.tanstackstart',
13+
},
14+
});
4015
});
4116
});

‎packages/tanstackstart-react/test/server/wrapFetchWithSentry.test.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ describe('wrapFetchWithSentry', () => {
5050
expect(flushIfServerlessSpy).toHaveBeenCalledTimes(1);
5151
});
5252

53-
it('calls flushIfServerless after a server function request', async () => {
53+
it('creates a function.tanstackstart span for server function requests', async () => {
5454
const mockResponse = new Response('ok');
5555
const fetchFn = vi.fn().mockResolvedValue(mockResponse);
5656

@@ -59,7 +59,13 @@ describe('wrapFetchWithSentry', () => {
5959

6060
await serverEntry.fetch(request);
6161

62-
expect(startSpanSpy).toHaveBeenCalled();
62+
expect(startSpanSpy).toHaveBeenCalledWith(
63+
expect.objectContaining({
64+
op: 'function.tanstackstart',
65+
name: 'GET /_serverFn/abc123',
66+
}),
67+
expect.any(Function),
68+
);
6369
expect(flushIfServerlessSpy).toHaveBeenCalledTimes(1);
6470
});
6571

0 commit comments

Comments
 (0)