📡 feat: Add Configurable HyperDX Browser Real User Monitoring (#13287)

client/src/lib/rum/WithRum.tsx

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import useRum from './useRum';
+
+export default function WithRum({ children }: { children: ReactNode }) {
+  useRum();
+
+  return <>{children}</>;
+}

client/src/lib/rum/early.spec.ts

@@ -0,0 +1,152 @@
+describe('RUM early interceptor', () => {
+  const originalFetch = window.fetch;
+  const OriginalXMLHttpRequest = window.XMLHttpRequest;
+
+  beforeEach(() => {
+    jest.resetModules();
+    window.fetch = jest.fn(() => Promise.resolve({} as Response)) as unknown as typeof fetch;
+    window.XMLHttpRequest = OriginalXMLHttpRequest;
+  });
+
+  afterEach(() => {
+    window.fetch = originalFetch;
+    window.XMLHttpRequest = OriginalXMLHttpRequest;
+    window.__libreChatRumInterceptor?.clear();
+    delete window.__libreChatRumInterceptor;
+  });
+
+  it('adds auth only to the configured RUM origin and path', async () => {
+    await import('./early');
+
+    window.__libreChatRumInterceptor?.configure({
+      url: 'https://rum.example.com/ingest',
+      authHeaderScheme: 'Bearer',
+      tokenProvider: () => 'token-123',
+    });
+
+    await fetch('https://rum.example.com/ingest/v1/traces');
+    await fetch('https://rum.example.com.attacker.com/ingest/v1/traces');
+    await fetch('https://rum.example.com/other');
+
+    const calls = (window.fetch as jest.MockedFunction<typeof fetch>).mock.calls;
+    expect(new Headers(calls[0][1]?.headers).get('authorization')).toBe('Bearer token-123');
+    expect(calls[1][1]?.headers).toBeUndefined();
+    expect(calls[2][1]?.headers).toBeUndefined();
+  });
+
+  it('supports Basic auth when configured', async () => {
+    await import('./early');
+
+    window.__libreChatRumInterceptor?.configure({
+      url: 'https://rum.example.com',
+      authHeaderScheme: 'Basic',
+      tokenProvider: () => 'token-123',
+    });
+
+    await fetch('https://rum.example.com/v1/traces');
+
+    const calls = (window.fetch as jest.MockedFunction<typeof fetch>).mock.calls;
+    expect(new Headers(calls[0][1]?.headers).get('authorization')).toBe('Basic token-123');
+  });
+
+  it('leaves requests unchanged when token is unavailable', async () => {
+    await import('./early');
+
+    window.__libreChatRumInterceptor?.configure({
+      url: 'https://rum.example.com',
+      tokenProvider: () => undefined,
+    });
+
+    await fetch('https://rum.example.com/v1/traces');
+
+    const calls = (window.fetch as jest.MockedFunction<typeof fetch>).mock.calls;
+    expect(calls[0][1]?.headers).toBeUndefined();
+  });
+
+  it('preserves XMLHttpRequest constructor constants', async () => {
+    await import('./early');
+
+    expect(window.XMLHttpRequest.DONE).toBe(OriginalXMLHttpRequest.DONE);
+    expect(window.XMLHttpRequest.prototype).toBe(OriginalXMLHttpRequest.prototype);
+  });
+
+  it('falls back to SDK-set XHR auth when the token provider is empty', async () => {
+    const instances: Array<{ headers: Map<string, string> }> = [];
+
+    class FakeXMLHttpRequest {
+      static DONE = 4;
+      headers = new Map<string, string>();
+
+      constructor() {
+        instances.push(this);
+      }
+
+      open() {
+        return undefined;
+      }
+
+      setRequestHeader(name: string, value: string) {
+        this.headers.set(name.toLowerCase(), value);
+      }
+
+      send() {
+        return undefined;
+      }
+    }
+
+    window.XMLHttpRequest = FakeXMLHttpRequest as unknown as typeof XMLHttpRequest;
+    await import('./early');
+
+    window.__libreChatRumInterceptor?.configure({
+      url: 'https://rum.example.com/ingest',
+      tokenProvider: () => undefined,
+    });
+
+    const xhr = new XMLHttpRequest();
+    xhr.open('POST', 'https://rum.example.com/ingest/v1/traces');
+    xhr.setRequestHeader('authorization', 'Bearer sdk-key');
+    xhr.send();
+
+    expect(instances[0].headers.get('authorization')).toBe('Bearer sdk-key');
+  });
+
+  it('preserves XHR credentials when async is omitted', async () => {
+    const openCalls: unknown[][] = [];
+
+    class FakeXMLHttpRequest {
+      static DONE = 4;
+
+      open(...args: unknown[]) {
+        openCalls.push(args);
+      }
+
+      setRequestHeader() {
+        return undefined;
+      }
+
+      send() {
+        return undefined;
+      }
+    }
+
+    window.XMLHttpRequest = FakeXMLHttpRequest as unknown as typeof XMLHttpRequest;
+    await import('./early');
+
+    const xhr = new XMLHttpRequest();
+    (xhr.open as unknown as (...args: unknown[]) => void)(
+      'GET',
+      'https://api.example.com/resource',
+      undefined,
+      'user',
+      'password',
+    );
+
+    expect(openCalls[0]).toEqual([
+      'GET',
+      'https://api.example.com/resource',
+      true,
+      'user',
+      'password',
+    ]);
+  });
+});

client/src/lib/rum/early.ts

@@ -0,0 +1,163 @@
+type TokenProvider = () => string | undefined;
+
+type RumInterceptorConfig = {
+  url?: string;
+  tokenProvider?: TokenProvider;
+  authHeaderScheme?: 'Bearer' | 'Basic';
+};
+
+declare global {
+  interface Window {
+    __libreChatRumInterceptor?: {
+      configure: (config: RumInterceptorConfig) => void;
+      clear: () => void;
+    };
+  }
+}
+
+let rumUrl: URL | undefined;
+let tokenProvider: TokenProvider | undefined;
+let authHeaderScheme: 'Bearer' | 'Basic' = 'Bearer';
+
+const originalFetch = window.fetch.bind(window);
+const OriginalXMLHttpRequest = window.XMLHttpRequest;
+
+function isRequest(input: RequestInfo | URL): input is Request {
+  return typeof Request !== 'undefined' && input instanceof Request;
+}
+
+function parseUrl(value: string | URL): URL | undefined {
+  try {
+    return value instanceof URL ? value : new URL(value, window.location.origin);
+  } catch {
+    return undefined;
+  }
+}
+
+function matchesRumUrl(value: string | URL): boolean {
+  if (!rumUrl) {
+    return false;
+  }
+
+  const requestUrl = parseUrl(value);
+  if (!requestUrl || requestUrl.origin !== rumUrl.origin) {
+    return false;
+  }
+
+  const basePath = rumUrl.pathname.endsWith('/') ? rumUrl.pathname : `${rumUrl.pathname}/`;
+  return requestUrl.pathname === rumUrl.pathname || requestUrl.pathname.startsWith(basePath);
+}
+
+function getAuthorization(): string | undefined {
+  const token = tokenProvider?.();
+  return token ? `${authHeaderScheme} ${token}` : undefined;
+}
+
+const interceptedFetch = function interceptedFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const requestUrl = isRequest(input) ? input.url : input;
+
+  if (!matchesRumUrl(requestUrl)) {
+    return originalFetch(input, init);
+  }
+
+  const authorization = getAuthorization();
+  if (!authorization) {
+    return originalFetch(input, init);
+  }
+
+  const headers = new Headers(isRequest(input) ? input.headers : init?.headers);
+  headers.set('authorization', authorization);
+
+  return originalFetch(input, {
+    ...init,
+    headers,
+  });
+};
+
+window.fetch = Object.assign(interceptedFetch, window.fetch);
+
+function InterceptedXMLHttpRequest(): XMLHttpRequest {
+  const xhr = new OriginalXMLHttpRequest();
+  const originalOpen = xhr.open;
+  const originalSend = xhr.send;
+  const originalSetRequestHeader = xhr.setRequestHeader;
+  let isRumRequest = false;
+  let rumSdkAuthorization: string | undefined;
+
+  xhr.open = function open(
+    method: string,
+    url: string | URL,
+    async?: boolean,
+    username?: string | null,
+    password?: string | null,
+  ): void {
+    isRumRequest = matchesRumUrl(url);
+
+    if (arguments.length >= 5) {
+      originalOpen.call(
+        this,
+        method,
+        url,
+        async ?? true,
+        username ?? undefined,
+        password ?? undefined,
+      );
+      return;
+    }
+
+    if (arguments.length === 4) {
+      originalOpen.call(this, method, url, async ?? true, username ?? undefined);
+      return;
+    }
+
+    if (arguments.length === 3) {
+      originalOpen.call(this, method, url, async ?? true);
+      return;
+    }
+
+    originalOpen.call(this, method, url);
+  };
+
+  xhr.setRequestHeader = function setRequestHeader(name: string, value: string): void {
+    if (isRumRequest && name.toLowerCase() === 'authorization') {
+      // HyperDX sets its own API key header; userJwt mode replaces it with the LibreChat auth token.
+      rumSdkAuthorization = value;
+      return;
+    }
+
+    originalSetRequestHeader.call(this, name, value);
+  };
+
+  xhr.send = function send(body?: Document | XMLHttpRequestBodyInit | null): void {
+    const authorization = isRumRequest ? (getAuthorization() ?? rumSdkAuthorization) : undefined;
+    if (authorization) {
+      originalSetRequestHeader.call(this, 'authorization', authorization);
+    }
+
+    originalSend.call(this, body);
+  };
+
+  return xhr;
+}
+
+Object.setPrototypeOf(InterceptedXMLHttpRequest, OriginalXMLHttpRequest);
+InterceptedXMLHttpRequest.prototype = OriginalXMLHttpRequest.prototype;
+window.XMLHttpRequest = InterceptedXMLHttpRequest as unknown as typeof XMLHttpRequest;
+
+window.__libreChatRumInterceptor = {
+  configure(config: RumInterceptorConfig) {
+    rumUrl = config.url ? parseUrl(config.url) : undefined;
+    tokenProvider = config.tokenProvider;
+    authHeaderScheme = config.authHeaderScheme ?? 'Bearer';
+  },
+  clear() {
+    rumUrl = undefined;
+    tokenProvider = undefined;
+    authHeaderScheme = 'Bearer';
+  },
+};
+
+export {};

client/src/lib/rum/routes.spec.ts

@@ -0,0 +1,19 @@
+import { normalizeRumPath } from './routes';
+
+describe('normalizeRumPath', () => {
+  it('normalizes dynamic LibreChat route identifiers', () => {
+    expect(normalizeRumPath('/c/65a5e0a7d1c2b3a4f5e6d789')).toBe('/c/:conversationId');
+    expect(normalizeRumPath('/share/65a5e0a7d1c2b3a4f5e6d789')).toBe('/share/:shareId');
+    expect(normalizeRumPath('/assistants/asst_123')).toBe('/assistants/:assistantId');
+  });
+
+  it('normalizes generic UUID and ObjectId path segments', () => {
+    expect(normalizeRumPath('/files/550e8400-e29b-41d4-a716-446655440000')).toBe('/files/:id');
+    expect(normalizeRumPath('/files/65a5e0a7d1c2b3a4f5e6d789/preview')).toBe('/files/:id/preview');
+  });
+
+  it('preserves static routes', () => {
+    expect(normalizeRumPath('/search')).toBe('/search');
+    expect(normalizeRumPath('/')).toBe('/');
+  });
+});

client/src/lib/rum/routes.ts

@@ -0,0 +1,31 @@
+const OBJECT_ID = /^[0-9a-f]{24}$/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function normalizeSegment(segment: string, previous: string | undefined): string {
+  if (previous === 'c') {
+    return ':conversationId';
+  }
+
+  if (previous === 'share') {
+    return ':shareId';
+  }
+
+  if (previous === 'assistants') {
+    return ':assistantId';
+  }
+
+  if (UUID.test(segment) || OBJECT_ID.test(segment)) {
+    return ':id';
+  }
+
+  return segment;
+}
+
+export function normalizeRumPath(pathname: string): string {
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length === 0) {
+    return '/';
+  }
+
+  return `/${segments.map((segment, index) => normalizeSegment(segment, segments[index - 1])).join('/')}`;
+}

client/src/lib/rum/useRum.spec.tsx

@@ -0,0 +1,123 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import useRum from './useRum';
+
+const mockInit = jest.fn();
+const mockSetGlobalAttributes = jest.fn();
+const mockUseGetStartupConfig = jest.fn();
+const mockUseAuthContext = jest.fn();
+const mockUseLocation = jest.fn();
+
+jest.mock('@hyperdx/browser', () => ({
+  __esModule: true,
+  default: {
+    init: (...args: unknown[]) => mockInit(...args),
+    setGlobalAttributes: (...args: unknown[]) => mockSetGlobalAttributes(...args),
+  },
+}));
+
+jest.mock('~/data-provider', () => ({
+  useGetStartupConfig: () => mockUseGetStartupConfig(),
+}));
+
+jest.mock('~/hooks/AuthContext', () => ({
+  useAuthContext: () => mockUseAuthContext(),
+}));
+
+jest.mock('react-router-dom', () => ({
+  ...jest.requireActual('react-router-dom'),
+  useLocation: () => mockUseLocation(),
+}));
+
+describe('useRum', () => {
+  beforeEach(() => {
+    mockUseLocation.mockReturnValue({ pathname: '/c/conversation-123' });
+    mockUseAuthContext.mockReturnValue({
+      isAuthenticated: true,
+      token: 'jwt-token',
+      user: {
+        id: 'user-123',
+        role: 'USER',
+        tenantId: 'org-123',
+        email: 'user@example.com',
+      },
+    });
+    delete window.__libreChatRumInterceptor;
+  });
+
+  it('initializes HyperDX public-token RUM with privacy defaults and safe attributes', async () => {
+    mockUseGetStartupConfig.mockReturnValue({
+      data: {
+        rum: {
+          provider: 'hyperdx',
+          enabled: true,
+          url: 'https://rum.example.com',
+          serviceName: 'librechat-web',
+          authMode: 'publicToken',
+          publicToken: 'public-token',
+          tracePropagationTargets: ['https://librechat.example.com'],
+        },
+      },
+    });
+
+    renderHook(() => useRum());
+
+    await waitFor(() => {
+      expect(mockInit).toHaveBeenCalledWith({
+        advancedNetworkCapture: false,
+        apiKey: 'public-token',
+        consoleCapture: false,
+        disableReplay: true,
+        service: 'librechat-web',
+        tracePropagationTargets: ['https://librechat.example.com'],
+        url: 'https://rum.example.com',
+      });
+    });
+
+    expect(mockSetGlobalAttributes).toHaveBeenCalledWith({
+      route: '/c/:conversationId',
+      role: 'USER',
+      userId: 'user-123',
+      orgId: 'org-123',
+      serviceName: 'librechat-web',
+    });
+    expect(mockSetGlobalAttributes).not.toHaveBeenCalledWith(
+      expect.objectContaining({ email: 'user@example.com' }),
+    );
+  });
+
+  it('configures the early interceptor and uses a placeholder api key for userJwt mode', async () => {
+    const configure = jest.fn();
+    const clear = jest.fn();
+    window.__libreChatRumInterceptor = { configure, clear };
+    mockUseGetStartupConfig.mockReturnValue({
+      data: {
+        rum: {
+          provider: 'hyperdx',
+          enabled: true,
+          url: 'https://rum.example.com/ingest',
+          serviceName: 'librechat-web',
+          authMode: 'userJwt',
+          authHeaderScheme: 'Basic',
+        },
+      },
+    });
+
+    renderHook(() => useRum());
+
+    expect(configure).toHaveBeenCalledWith({
+      url: 'https://rum.example.com/ingest',
+      authHeaderScheme: 'Basic',
+      tokenProvider: expect.any(Function),
+    });
+    expect(configure.mock.calls[0][0].tokenProvider()).toBe('jwt-token');
+
+    await waitFor(() => {
+      expect(mockInit).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiKey: 'placeholder',
+          url: 'https://rum.example.com/ingest',
+        }),
+      );
+    });
+  });
+});

client/src/lib/rum/useRum.ts

@@ -0,0 +1,163 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useLocation } from 'react-router-dom';
+import type { TRumConfig, TUser } from 'librechat-data-provider';
+import { useGetStartupConfig } from '~/data-provider';
+import { useAuthContext } from '~/hooks/AuthContext';
+import { normalizeRumPath } from './routes';
+
+type HyperDXBrowser = {
+  init: (config: {
+    advancedNetworkCapture: boolean;
+    apiKey: string;
+    consoleCapture: boolean;
+    disableReplay: boolean;
+    service: string;
+    tracePropagationTargets?: string[];
+    url: string;
+  }) => void;
+  setGlobalAttributes: (attributes: Record<string, string>) => void;
+};
+
+function shouldInitializeRum(config: TRumConfig | undefined, token: string | undefined): boolean {
+  if (!config?.enabled || config.provider !== 'hyperdx' || !config.url || !config.serviceName) {
+    return false;
+  }
+
+  if (config.authMode === 'publicToken') {
+    return !!config.publicToken;
+  }
+
+  return !!token;
+}
+
+function getApiKey(config: TRumConfig): string {
+  return config.authMode === 'publicToken' ? (config.publicToken ?? '') : 'placeholder';
+}
+
+function buildGlobalAttributes(
+  user: TUser | undefined,
+  config: TRumConfig,
+  route: string,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries({
+      route,
+      role: user?.role,
+      userId: user?.id,
+      orgId: user?.tenantId,
+      serviceName: config.serviceName,
+      environment: config.environment,
+    }).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1] !== '',
+    ),
+  );
+}
+
+async function loadHyperDX(): Promise<HyperDXBrowser> {
+  const module = await import('@hyperdx/browser');
+  return module.default;
+}
+
+export default function useRum(): void {
+  const { data: startupConfig } = useGetStartupConfig();
+  const { isAuthenticated, token, user } = useAuthContext();
+  const location = useLocation();
+  const initializedKeyRef = useRef<string | undefined>(undefined);
+  const sampledInitKeyRef = useRef<string | undefined>(undefined);
+  const sampledInRef = useRef<boolean>(true);
+  const hyperDxRef = useRef<HyperDXBrowser | undefined>(undefined);
+  const tokenRef = useRef<string | undefined>(token);
+  const rumConfig = startupConfig?.rum;
+  const route = useMemo(() => normalizeRumPath(location.pathname), [location.pathname]);
+  const routeRef = useRef<string>(route);
+
+  useEffect(() => {
+    tokenRef.current = token;
+  }, [token]);
+
+  useEffect(() => {
+    routeRef.current = route;
+  }, [route]);
+
+  useEffect(() => {
+    if (!rumConfig || rumConfig.authMode !== 'userJwt') {
+      window.__libreChatRumInterceptor?.clear();
+      return;
+    }
+
+    window.__libreChatRumInterceptor?.configure({
+      url: rumConfig.url,
+      authHeaderScheme: rumConfig.authHeaderScheme,
+      tokenProvider: () => tokenRef.current,
+    });
+
+    return () => {
+      window.__libreChatRumInterceptor?.clear();
+    };
+  }, [rumConfig]);
+
+  useEffect(() => {
+    if (!rumConfig) {
+      return;
+    }
+
+    if (
+      !shouldInitializeRum(rumConfig, token) ||
+      (rumConfig.authMode === 'userJwt' && !isAuthenticated)
+    ) {
+      return;
+    }
+
+    const config = rumConfig;
+
+    const initKey = [config.url, config.serviceName, config.authMode, config.publicToken].join(':');
+
+    if (initializedKeyRef.current === initKey) {
+      return;
+    }
+
+    if (sampledInitKeyRef.current !== initKey) {
+      sampledInitKeyRef.current = initKey;
+      sampledInRef.current =
+        typeof config.sampleRate === 'number' ? Math.random() < config.sampleRate : true;
+    }
+
+    if (!sampledInRef.current) {
+      return;
+    }
+
+    let cancelled = false;
+
+    loadHyperDX()
+      .then((HyperDX) => {
+        if (cancelled || initializedKeyRef.current === initKey) {
+          return;
+        }
+
+        HyperDX.init({
+          advancedNetworkCapture: config.advancedNetworkCapture ?? false,
+          apiKey: getApiKey(config),
+          consoleCapture: config.consoleCapture ?? false,
+          disableReplay: config.disableReplay ?? true,
+          service: config.serviceName,
+          tracePropagationTargets: config.tracePropagationTargets,
+          url: config.url,
+        });
+
+        hyperDxRef.current = HyperDX;
+        initializedKeyRef.current = initKey;
+        HyperDX.setGlobalAttributes(buildGlobalAttributes(user, config, routeRef.current));
+      })
+      .catch(() => undefined);
+
+    return () => {
+      cancelled = true;
+    };
+  }, [isAuthenticated, rumConfig, token, user]);
+
+  useEffect(() => {
+    hyperDxRef.current?.setGlobalAttributes(
+      rumConfig ? buildGlobalAttributes(user, rumConfig, route) : { route },
+    );
+  }, [route, rumConfig, user]);
+}

client/src/main.jsx

@@ -1,3 +1,4 @@
+import './lib/rum/early';
 import 'regenerator-runtime/runtime';
 import { createRoot } from 'react-dom/client';
 import './locales/i18n';

client/src/routes/index.tsx

@@ -12,6 +12,7 @@ import { MarketplaceProvider } from '~/components/Agents/MarketplaceContext';
 import AgentMarketplace from '~/components/Agents/Marketplace';
 import { OAuthSuccess, OAuthError } from '~/components/OAuth';
 import { AuthContextProvider } from '~/hooks/AuthContext';
+import WithRum from '~/lib/rum/WithRum';
 import RouteErrorBoundary from './RouteErrorBoundary';
 import StartupLayout from './Layouts/Startup';
 import LoginLayout from './Layouts/Login';
@@ -23,7 +24,9 @@ import Root from './Root';
 
 const AuthLayout = () => (
   <AuthContextProvider>
-    <Outlet />
+    <WithRum>
+      <Outlet />
+    </WithRum>
     <ApiErrorWatcher />
   </AuthContextProvider>
 );