Do not downgrade from wildcard route to unparameterized route

Author: onurtemizkan

packages/react/src/reactrouter-compat-utils/instrumentation.tsx

@@ -222,7 +222,14 @@ export function updateNavigationSpan(
     );
 
     // Only update if we have a valid name and it's better than what we have
-    const isImprovement = name && (!currentName || !name.includes('*'));
+    // Never downgrade from route source to url source
+    const currentSource = spanJson.data?.[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE];
+    const isImprovement =
+      name &&
+      (!hasBeenNamed || // Span not finalized - accept any name
+        !currentName || // No current name - always set
+        (currentNameHasWildcard && source === 'route') || // Wildcard route → better route (MUST stay in route source)
+        (currentSource !== 'route' && source === 'route')); // URL → route upgrade
     if (isImprovement) {
       activeRootSpan.updateName(name);
       activeRootSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, source);
@@ -864,9 +871,13 @@ function tryUpdateSpanNameBeforeEnd(
     // Only update if we have a valid name and it's better than current
     // Upgrade conditions:
     // 1. No current name exists
-    // 2. Current name has wildcards (less specific)
+    // 2. Current name has wildcards and new source is also 'route' (never downgrade route→url)
     // 3. Upgrading from non-route source to route source (e.g., URL -> parameterized route)
-    const isImprovement = name && (!currentName || hasWildcard || (currentSource !== 'route' && source === 'route'));
+    const isImprovement =
+      name &&
+      (!currentName || // No current name - always set
+        (hasWildcard && source === 'route') || // Wildcard route → better route (MUST stay in route source)
+        (currentSource !== 'route' && source === 'route')); // URL → route upgrade
     const spanNotEnded = spanType === 'pageload' || !spanJson.timestamp;
 
     if (isImprovement && spanNotEnded) {

packages/react/test/reactrouter-compat-utils/instrumentation.test.tsx

@@ -451,7 +451,7 @@ describe('tryUpdateSpanNameBeforeEnd - source upgrade logic', () => {
     expect(mockSetAttribute).toHaveBeenCalledWith('sentry.source', 'route');
   });
 
-  it('should NOT downgrade from route source to URL source', async () => {
+  it('should not downgrade from route source to URL source', async () => {
     // Setup: Current span has route source with parameterized name (no wildcard)
     vi.mocked(spanToJSON).mockReturnValue({
       op: 'navigation',
@@ -479,7 +479,7 @@ describe('tryUpdateSpanNameBeforeEnd - source upgrade logic', () => {
       vi.fn(() => [{ route: { path: '/users/:id' } }]),
     );
 
-    // Should NOT update because span is already named
+    // Should not update because span is already named
     // The early return in tryUpdateSpanNameBeforeEnd (line 815) protects against downgrades
     // This test verifies that route->url downgrades are blocked
     expect(mockUpdateName).not.toHaveBeenCalled();
@@ -494,8 +494,10 @@ describe('tryUpdateSpanNameBeforeEnd - source upgrade logic', () => {
       data: { 'sentry.source': 'route' },
     } as any);
 
-    // Mock wildcard detection
-    vi.mocked(transactionNameHasWildcard).mockReturnValue(true);
+    // Mock wildcard detection: current name has wildcard, new name doesn't
+    vi.mocked(transactionNameHasWildcard).mockImplementation((name: string) => {
+      return name === '/users/*'; // Only the current name has wildcard
+    });
 
     // Target: Resolves to specific parameterized route
     vi.mocked(resolveRouteNameAndSource).mockReturnValue(['/users/:id', 'route']);
@@ -521,6 +523,45 @@ describe('tryUpdateSpanNameBeforeEnd - source upgrade logic', () => {
     expect(mockSetAttribute).toHaveBeenCalledWith('sentry.source', 'route');
   });
 
+  it('should not downgrade from wildcard route to URL', async () => {
+    // Setup: Current span has route source with wildcard
+    vi.mocked(spanToJSON).mockReturnValue({
+      op: 'navigation',
+      description: '/users/*',
+      data: { 'sentry.source': 'route' },
+    } as any);
+
+    // Mock wildcard detection: current name has wildcard, new name doesn't
+    vi.mocked(transactionNameHasWildcard).mockImplementation((name: string) => {
+      return name === '/users/*'; // Only the current wildcard name returns true
+    });
+
+    // Target: After timeout, resolves to URL (lazy route didn't finish loading)
+    vi.mocked(resolveRouteNameAndSource).mockReturnValue(['/users/123', 'url']);
+
+    const mockUpdateName = vi.fn();
+    const mockSetAttribute = vi.fn();
+    const testSpan = {
+      updateName: mockUpdateName,
+      setAttribute: mockSetAttribute,
+      end: vi.fn(),
+      __sentry_navigation_name_set__: true, // Mark span as already named/finalized
+    } as unknown as Span;
+
+    updateNavigationSpan(
+      testSpan,
+      { pathname: '/users/123', search: '', hash: '', state: null, key: 'test' },
+      [{ path: '/users/*', element: <div /> }],
+      false,
+      vi.fn(() => [{ route: { path: '/users/*' } }]),
+    );
+
+    // Should not update - keep wildcard route instead of downgrading to URL
+    // Wildcard routes are better than URLs for aggregation in performance monitoring
+    expect(mockUpdateName).not.toHaveBeenCalled();
+    expect(mockSetAttribute).not.toHaveBeenCalled();
+  });
+
   it('should set name when no current name exists', async () => {
     // Setup: Current span has no name (undefined)
     vi.mocked(spanToJSON).mockReturnValue({