chore: add normalize for QueryRangeRequest

* feat: wire available colors on spans instead of aggregations from waterfall api

* feat: integrate aggregation api

* feat: integrate v4 waterfall

* feat: dropdown style fix

* feat: move to open api spec

* feat: move to open api spec

* feat: minor changes

frontend/src/api/trace/getTraceV4.tsx

@@ -1,15 +1,14 @@
-import { ApiV3Instance as axios } from 'api';
-import { omit } from 'lodash-es';
+import { getWaterfallV4 } from 'api/generated/services/tracedetail';
 import { ErrorResponse, SuccessResponse } from 'types/api';
 import {
-	GetTraceV3PayloadProps,
-	GetTraceV3SuccessResponse,
+	GetTraceV4PayloadProps,
+	GetTraceV4SuccessResponse,
 	SpanV3,
 } from 'types/api/trace/getTraceV3';
 
-const getTraceV3 = async (
-	props: GetTraceV3PayloadProps,
-): Promise<SuccessResponse<GetTraceV3SuccessResponse> | ErrorResponse> => {
+const getTraceV4 = async (
+	props: GetTraceV4PayloadProps,
+): Promise<SuccessResponse<GetTraceV4SuccessResponse> | ErrorResponse> => {
 	let uncollapsedSpans = [...props.uncollapsedSpans];
 	if (!props.isSelectedSpanIDUnCollapsed) {
 		uncollapsedSpans = uncollapsedSpans.filter(
@@ -19,31 +18,37 @@ const getTraceV3 = async (
 		props.selectedSpanId &&
 		!uncollapsedSpans.includes(props.selectedSpanId)
 	) {
-		// V3 backend only uses uncollapsedSpans list (unlike V2 which also interprets
+		// Backend only uses the uncollapsedSpans list (unlike V2 which also interprets
 		// isSelectedSpanIDUnCollapsed server-side), so explicitly add the selected span
 		uncollapsedSpans.push(props.selectedSpanId);
 	}
-	const postData: GetTraceV3PayloadProps = {
-		...props,
-		uncollapsedSpans,
-		limit: 10000,
-	};
-	const response = await axios.post<GetTraceV3SuccessResponse>(
-		`/traces/${props.traceId}/waterfall`,
-		omit(postData, 'traceId'),
+	const response = await getWaterfallV4(
+		{ traceID: props.traceId },
+		{
+			selectedSpanId: props.selectedSpanId,
+			uncollapsedSpans,
+			limit: 10000,
+		},
 	);
 
-	// V3 API wraps response in { status, data }
-	const rawPayload = (response.data as any).data || response.data;
+	// Generated client unwraps the axios response; .data is the waterfall payload.
+	// Wire spans carry time_unix; SpanV3's timestamp + 'service.name' are derived below.
+	type WireSpan = Omit<SpanV3, 'timestamp' | 'service.name'> & {
+		time_unix: number;
+	};
+	const rawPayload = response.data as unknown as Omit<
+		GetTraceV4SuccessResponse,
+		'spans'
+	> & { spans: WireSpan[] | null };
 
 	// Derive 'service.name' from resource for convenience — only derived field
-	const spans: SpanV3[] = (rawPayload.spans || []).map((span: any) => ({
+	const spans: SpanV3[] = (rawPayload.spans || []).map((span) => ({
 		...span,
 		'service.name': span.resource?.['service.name'] || '',
 		timestamp: span.time_unix,
 	}));
 
-	// V3 API returns startTimestampMillis/endTimestampMillis as relative durations (ms from epoch offset),
+	// API returns startTimestampMillis/endTimestampMillis as relative durations (ms from epoch offset),
 	// not absolute unix millis like V2. The span timestamps are absolute unix millis.
 	// Convert by using the first span's timestamp as the base if there's a mismatch.
 	let { startTimestampMillis, endTimestampMillis } = rawPayload;
@@ -70,4 +75,4 @@ const getTraceV3 = async (
 	};
 };
 
-export default getTraceV3;
+export default getTraceV4;

frontend/src/constants/reactQueryKeys.ts

@@ -33,7 +33,8 @@ export const REACT_QUERY_KEY = {
 	UPDATE_ALERT_RULE: 'UPDATE_ALERT_RULE',
 	GET_ACTIVE_LICENSE_V3: 'GET_ACTIVE_LICENSE_V3',
 	GET_TRACE_V2_WATERFALL: 'GET_TRACE_V2_WATERFALL',
-	GET_TRACE_V3_WATERFALL: 'GET_TRACE_V3_WATERFALL',
+	GET_TRACE_V4_WATERFALL: 'GET_TRACE_V4_WATERFALL',
+	GET_TRACE_AGGREGATIONS: 'GET_TRACE_AGGREGATIONS',
 	GET_TRACE_V2_FLAMEGRAPH: 'GET_TRACE_V2_FLAMEGRAPH',
 	GET_POD_LIST: 'GET_POD_LIST',
 	GET_NODE_LIST: 'GET_NODE_LIST',

frontend/src/hooks/trace/__tests__/useGetTraceAggregations.test.tsx

@@ -0,0 +1,66 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { getTraceAggregations } from 'api/generated/services/tracedetail';
+import { ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from 'react-query';
+
+import useGetTraceAggregations from '../useGetTraceAggregations';
+
+jest.mock('api/generated/services/tracedetail', () => ({
+	__esModule: true,
+	getTraceAggregations: jest
+		.fn()
+		.mockResolvedValue({ status: 'success', data: { aggregations: [] } }),
+}));
+
+const mockApi = getTraceAggregations as jest.Mock;
+
+const wrapper = ({ children }: { children: ReactNode }): JSX.Element => {
+	const client = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+	return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+};
+
+const aggregations = [
+	{ field: { name: 'service.name' }, aggregation: 'execution_time_percentage' },
+] as never;
+
+describe('useGetTraceAggregations', () => {
+	beforeEach(() => mockApi.mockClear());
+
+	it('fetches when enabled with a traceId and aggregations', async () => {
+		renderHook(
+			() =>
+				useGetTraceAggregations({ traceId: 't1', aggregations, enabled: true }),
+			{ wrapper },
+		);
+		await waitFor(() => expect(mockApi).toHaveBeenCalledTimes(1));
+		expect(mockApi).toHaveBeenCalledWith({ traceID: 't1' }, { aggregations });
+	});
+
+	it('does not fetch when disabled', () => {
+		renderHook(
+			() =>
+				useGetTraceAggregations({ traceId: 't1', aggregations, enabled: false }),
+			{ wrapper },
+		);
+		expect(mockApi).not.toHaveBeenCalled();
+	});
+
+	it('does not fetch without a traceId', () => {
+		renderHook(
+			() => useGetTraceAggregations({ traceId: '', aggregations, enabled: true }),
+			{ wrapper },
+		);
+		expect(mockApi).not.toHaveBeenCalled();
+	});
+
+	it('does not fetch with no aggregations requested', () => {
+		renderHook(
+			() =>
+				useGetTraceAggregations({ traceId: 't1', aggregations: [], enabled: true }),
+			{ wrapper },
+		);
+		expect(mockApi).not.toHaveBeenCalled();
+	});
+});

frontend/src/hooks/trace/useGetTraceAggregations.tsx

@@ -0,0 +1,34 @@
+import { useQuery, UseQueryResult } from 'react-query';
+import {
+	GetTraceAggregations200,
+	SpantypesSpanAggregationDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import { getTraceAggregations } from 'api/generated/services/tracedetail';
+import { REACT_QUERY_KEY } from 'constants/reactQueryKeys';
+
+interface UseGetTraceAggregationsProps {
+	traceId: string;
+	aggregations: SpantypesSpanAggregationDTO[];
+	enabled: boolean;
+}
+
+type UseGetTraceAggregations = UseQueryResult<GetTraceAggregations200>;
+
+/**
+ * Fetches trace aggregations on demand — gate via `enabled` so the request
+ * fires only when the Analytics panel is open. The query key includes the
+ * requested fields, so changing the color-by field refetches.
+ */
+const useGetTraceAggregations = ({
+	traceId,
+	aggregations,
+	enabled,
+}: UseGetTraceAggregationsProps): UseGetTraceAggregations =>
+	useQuery({
+		queryFn: () => getTraceAggregations({ traceID: traceId }, { aggregations }),
+		queryKey: [REACT_QUERY_KEY.GET_TRACE_AGGREGATIONS, traceId, aggregations],
+		enabled: enabled && !!traceId && aggregations.length > 0,
+		refetchOnWindowFocus: false,
+	});
+
+export default useGetTraceAggregations;

frontend/src/hooks/trace/useGetTraceV4.tsx

@@ -1,30 +1,29 @@
 import { useQuery, UseQueryResult } from 'react-query';
-import getTraceV3 from 'api/trace/getTraceV3';
+import getTraceV4 from 'api/trace/getTraceV4';
 import { REACT_QUERY_KEY } from 'constants/reactQueryKeys';
 import { ErrorResponse, SuccessResponse } from 'types/api';
 import {
-	GetTraceV3PayloadProps,
-	GetTraceV3SuccessResponse,
+	GetTraceV4PayloadProps,
+	GetTraceV4SuccessResponse,
 } from 'types/api/trace/getTraceV3';
 
-const useGetTraceV3 = (props: GetTraceV3PayloadProps): UseTraceV3 =>
+const useGetTraceV4 = (props: GetTraceV4PayloadProps): UseTraceV4 =>
 	useQuery({
-		queryFn: () => getTraceV3(props),
+		queryFn: () => getTraceV4(props),
 		queryKey: [
-			REACT_QUERY_KEY.GET_TRACE_V3_WATERFALL,
+			REACT_QUERY_KEY.GET_TRACE_V4_WATERFALL,
 			props.traceId,
 			props.selectedSpanId,
 			props.isSelectedSpanIDUnCollapsed,
-			props.aggregations,
 		],
 		enabled: !!props.traceId,
 		keepPreviousData: true,
 		refetchOnWindowFocus: false,
 	});
 
-type UseTraceV3 = UseQueryResult<
-	SuccessResponse<GetTraceV3SuccessResponse> | ErrorResponse,
+type UseTraceV4 = UseQueryResult<
+	SuccessResponse<GetTraceV4SuccessResponse> | ErrorResponse,
 	unknown
 >;
 
-export default useGetTraceV3;
+export default useGetTraceV4;

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/AnalyticsPanel/AnalyticsPanel.module.scss

@@ -33,6 +33,15 @@
 	scrollbar-width: none;
 }
 
+.state {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	flex: 1;
+	min-height: 120px;
+	padding: 24px 12px;
+}
+
 .list {
 	display: grid;
 	grid-template-columns: auto auto 1fr;

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/AnalyticsPanel/AnalyticsPanel.tsx

@@ -1,21 +1,28 @@
 import { useMemo } from 'react';
+import { useParams } from 'react-router-dom';
 import {
 	TabsContent,
 	TabsList,
 	TabsRoot,
 	TabsTrigger,
 } from '@signozhq/ui/tabs';
-import cx from 'classnames';
 import { DetailsHeader } from 'components/DetailsPanel';
 import { useIsDarkMode } from 'hooks/useDarkMode';
+import useGetTraceAggregations from 'hooks/trace/useGetTraceAggregations';
 import { generateColorPair } from 'pages/TraceDetailsV3/utils/generateColorPair';
 import { FloatingPanel } from 'periscope/components/FloatingPanel';
+import {
+	SpantypesSpanAggregationDTO,
+	TelemetrytypesTelemetryFieldKeyDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import { TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
 
 import { useTraceStore } from '../../stores/traceStore';
 import {
 	AGGREGATIONS,
 	getAggregationMap as findAggregationMap,
 } from '../../utils/aggregations';
+import AnalyticsTabContent, { AnalyticsRow } from './AnalyticsTabContent';
 
 import styles from './AnalyticsPanel.module.scss';
 
@@ -35,10 +42,31 @@ function AnalyticsPanel({
 	onClose,
 	onTabChange,
 }: AnalyticsPanelProps): JSX.Element | null {
-	const aggregations = useTraceStore((s) => s.aggregations);
-	const colorByFieldName = useTraceStore((s) => s.colorByField.name);
+	const { id: traceId } = useParams<TraceDetailV3URLProps>();
+	const colorByField = useTraceStore((s) => s.colorByField);
+	const colorByFieldName = colorByField.name;
 	const isDarkMode = useIsDarkMode();
 
+	// Fetch exec-time % + span count for the current color-by field only, and
+	// only while the panel is open. Changing the field refetches via the key.
+	const aggregationsRequest = useMemo<SpantypesSpanAggregationDTO[]>(() => {
+		// v5 TelemetryFieldKey and the generated DTO are runtime-identical; only
+		// the literal-union vs enum nominal types differ
+		const field = colorByField as unknown as TelemetrytypesTelemetryFieldKeyDTO;
+		return [
+			{ field, aggregation: AGGREGATIONS.EXEC_TIME_PCT },
+			{ field, aggregation: AGGREGATIONS.SPAN_COUNT },
+		];
+	}, [colorByField]);
+
+	const { data, isLoading, isError } = useGetTraceAggregations({
+		traceId: traceId || '',
+		aggregations: aggregationsRequest,
+		enabled: isOpen,
+	});
+
+	const aggregations = data?.data.aggregations;
+
 	const execTimePct = useMemo(
 		() =>
 			findAggregationMap(
@@ -55,38 +83,39 @@ function AnalyticsPanel({
 		[aggregations, colorByFieldName],
 	);
 
-	const execTimeRows = useMemo(() => {
+	const execTimeRows = useMemo<AnalyticsRow[]>(() => {
 		if (!execTimePct) {
 			return [];
 		}
 		return Object.entries(execTimePct)
+			.sort(([, a], [, b]) => b - a)
 			.map(([group, percentage]) => {
 				const pair = generateColorPair(group);
 				return {
 					group,
-					percentage,
 					color: isDarkMode ? pair.color : pair.colorDark,
+					widthPct: Math.min(percentage, 100),
+					label: `${percentage.toFixed(2)}%`,
 				};
-			})
-			.sort((a, b) => b.percentage - a.percentage);
+			});
 	}, [execTimePct, isDarkMode]);
 
-	const spanCountRows = useMemo(() => {
+	const spanCountRows = useMemo<AnalyticsRow[]>(() => {
 		if (!spanCounts) {
 			return [];
 		}
 		const max = Math.max(...Object.values(spanCounts), 1);
 		return Object.entries(spanCounts)
+			.sort(([, a], [, b]) => b - a)
 			.map(([group, count]) => {
 				const pair = generateColorPair(group);
 				return {
 					group,
-					count,
-					max,
 					color: isDarkMode ? pair.color : pair.colorDark,
+					widthPct: (count / max) * 100,
+					label: String(count),
 				};
-			})
-			.sort((a, b) => b.count - a.count);
+			});
 	}, [spanCounts, isDarkMode]);
 
 	if (!isOpen) {
@@ -132,65 +161,23 @@ function AnalyticsPanel({
 
 					<div className={styles.tabsScroll}>
 						<TabsContent value="exec-time">
-							<div className={styles.list}>
-								{execTimeRows.map((row) => (
-									<>
-										<div
-											key={`${row.group}-dot`}
-											className={styles.dot}
-											style={{ backgroundColor: row.color }}
-										/>
-										<span key={`${row.group}-name`} className={styles.serviceName}>
-											{row.group}
-										</span>
-										<div key={`${row.group}-bar`} className={styles.barCell}>
-											<div className={styles.bar}>
-												<div
-													className={styles.barFill}
-													style={{
-														width: `${Math.min(row.percentage, 100)}%`,
-														backgroundColor: row.color,
-													}}
-												/>
-											</div>
-											<span className={cx(styles.value, styles.valueWide)}>
-												{row.percentage.toFixed(2)}%
-											</span>
-										</div>
-									</>
-								))}
-							</div>
+							<AnalyticsTabContent
+								isLoading={isLoading}
+								isError={isError}
+								fieldName={colorByFieldName}
+								rows={execTimeRows}
+								valueVariant="wide"
+							/>
 						</TabsContent>
 
 						<TabsContent value="spans">
-							<div className={styles.list}>
-								{spanCountRows.map((row) => (
-									<>
-										<div
-											key={`${row.group}-dot`}
-											className={styles.dot}
-											style={{ backgroundColor: row.color }}
-										/>
-										<span key={`${row.group}-name`} className={styles.serviceName}>
-											{row.group}
-										</span>
-										<div key={`${row.group}-bar`} className={styles.barCell}>
-											<div className={styles.bar}>
-												<div
-													className={styles.barFill}
-													style={{
-														width: `${(row.count / row.max) * 100}%`,
-														backgroundColor: row.color,
-													}}
-												/>
-											</div>
-											<span className={cx(styles.value, styles.valueNarrow)}>
-												{row.count}
-											</span>
-										</div>
-									</>
-								))}
-							</div>
+							<AnalyticsTabContent
+								isLoading={isLoading}
+								isError={isError}
+								fieldName={colorByFieldName}
+								rows={spanCountRows}
+								valueVariant="narrow"
+							/>
 						</TabsContent>
 					</div>
 				</TabsRoot>

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/AnalyticsPanel/AnalyticsTabContent.tsx

@@ -0,0 +1,84 @@
+import { Fragment } from 'react';
+import { Typography } from '@signozhq/ui/typography';
+import cx from 'classnames';
+import Spinner from 'components/Spinner';
+
+import styles from './AnalyticsPanel.module.scss';
+
+export interface AnalyticsRow {
+	group: string;
+	color: string;
+	widthPct: number;
+	label: string;
+}
+
+interface AnalyticsTabContentProps {
+	isLoading: boolean;
+	isError: boolean;
+	fieldName: string;
+	rows: AnalyticsRow[];
+	valueVariant: 'wide' | 'narrow';
+}
+
+// Loading / error / empty render in place of the rows so the tabs stay visible.
+function AnalyticsTabContent({
+	isLoading,
+	isError,
+	fieldName,
+	rows,
+	valueVariant,
+}: AnalyticsTabContentProps): JSX.Element {
+	if (isLoading) {
+		return (
+			<div className={styles.state}>
+				<Spinner height="auto" />
+			</div>
+		);
+	}
+	if (isError) {
+		return (
+			<div className={styles.state}>
+				<Typography.Text>Couldn&apos;t load analytics</Typography.Text>
+			</div>
+		);
+	}
+	if (rows.length === 0) {
+		return (
+			<div className={styles.state}>
+				<Typography.Text>No data for {fieldName}</Typography.Text>
+			</div>
+		);
+	}
+
+	return (
+		<div className={styles.list}>
+			{rows.map((row) => (
+				<Fragment key={row.group}>
+					<div className={styles.dot} style={{ backgroundColor: row.color }} />
+					<span className={styles.serviceName}>{row.group}</span>
+					<div className={styles.barCell}>
+						<div className={styles.bar}>
+							<div
+								className={styles.barFill}
+								style={{
+									width: `${row.widthPct}%`,
+									backgroundColor: row.color,
+								}}
+							/>
+						</div>
+						<span
+							className={cx(
+								styles.value,
+								valueVariant === 'wide' ? styles.valueWide : styles.valueNarrow,
+							)}
+						>
+							{row.label}
+						</span>
+					</div>
+				</Fragment>
+			))}
+		</div>
+	);
+}
+
+export default AnalyticsTabContent;

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/AnalyticsPanel/__tests__/AnalyticsPanel.test.tsx

@@ -0,0 +1,144 @@
+import { screen } from '@testing-library/react';
+import useGetTraceAggregations from 'hooks/trace/useGetTraceAggregations';
+import { render } from 'tests/test-utils';
+
+import { DEFAULT_COLOR_BY_FIELD } from '../../../constants';
+import { useTraceStore } from '../../../stores/traceStore';
+import AnalyticsPanel from '../AnalyticsPanel';
+
+jest.mock('react-router-dom', () => ({
+	...jest.requireActual('react-router-dom'),
+	useParams: (): { id: string } => ({ id: 'trace-123' }),
+}));
+
+jest.mock('hooks/trace/useGetTraceAggregations', () => ({
+	__esModule: true,
+	default: jest.fn(),
+}));
+
+// Isolate the panel's own logic from the floating-panel chrome.
+jest.mock('periscope/components/FloatingPanel', () => ({
+	__esModule: true,
+	FloatingPanel: ({ children }: { children: React.ReactNode }): JSX.Element => (
+		<div>{children}</div>
+	),
+}));
+jest.mock('components/DetailsPanel', () => ({
+	__esModule: true,
+	DetailsHeader: (): JSX.Element => <div data-testid="details-header" />,
+}));
+jest.mock('components/Spinner', () => ({
+	__esModule: true,
+	default: (): JSX.Element => <div data-testid="spinner" />,
+}));
+
+const mockHook = useGetTraceAggregations as jest.Mock;
+
+const noop = (): void => undefined;
+
+const renderPanel = (isOpen = true): ReturnType<typeof render> =>
+	render(<AnalyticsPanel isOpen={isOpen} onClose={noop} onTabChange={noop} />);
+
+const aggregationsResponse = {
+	status: 'success',
+	data: {
+		aggregations: [
+			{
+				field: { name: 'service.name' },
+				aggregation: 'execution_time_percentage',
+				value: { api: 80, db: 20 },
+			},
+			{
+				field: { name: 'service.name' },
+				aggregation: 'span_count',
+				value: { api: 5, db: 2 },
+			},
+		],
+	},
+};
+
+describe('AnalyticsPanel', () => {
+	beforeEach(() => {
+		mockHook.mockReset();
+		useTraceStore.setState({ colorByField: DEFAULT_COLOR_BY_FIELD });
+	});
+
+	it('renders nothing when closed and does not enable the fetch', () => {
+		mockHook.mockReturnValue({
+			data: undefined,
+			isLoading: false,
+			isError: false,
+		});
+		const { container } = renderPanel(false);
+		expect(container).toBeEmptyDOMElement();
+		expect(mockHook).toHaveBeenCalledWith(
+			expect.objectContaining({ enabled: false }),
+		);
+	});
+
+	it('requests both aggregations for the current color-by field when open', () => {
+		mockHook.mockReturnValue({
+			data: undefined,
+			isLoading: true,
+			isError: false,
+		});
+		renderPanel();
+		expect(mockHook).toHaveBeenCalledWith(
+			expect.objectContaining({
+				traceId: 'trace-123',
+				enabled: true,
+				aggregations: [
+					{
+						field: DEFAULT_COLOR_BY_FIELD,
+						aggregation: 'execution_time_percentage',
+					},
+					{ field: DEFAULT_COLOR_BY_FIELD, aggregation: 'span_count' },
+				],
+			}),
+		);
+	});
+
+	it('shows the loading state with the tabs still visible', () => {
+		mockHook.mockReturnValue({
+			data: undefined,
+			isLoading: true,
+			isError: false,
+		});
+		renderPanel();
+		expect(screen.getByTestId('spinner')).toBeInTheDocument();
+		// tabs stay visible while loading
+		expect(screen.getByText('% exec time')).toBeInTheDocument();
+		expect(screen.getByText('Spans')).toBeInTheDocument();
+	});
+
+	it('shows an error state when the request fails', () => {
+		mockHook.mockReturnValue({
+			data: undefined,
+			isLoading: false,
+			isError: true,
+		});
+		renderPanel();
+		expect(screen.getByText(/couldn't load analytics/i)).toBeInTheDocument();
+	});
+
+	it('renders rows for the current field on success', () => {
+		mockHook.mockReturnValue({
+			data: aggregationsResponse,
+			isLoading: false,
+			isError: false,
+		});
+		renderPanel();
+		expect(screen.getByText('api')).toBeInTheDocument();
+		expect(screen.getByText('80.00%')).toBeInTheDocument();
+	});
+
+	it('shows an empty state when the field has no data', () => {
+		mockHook.mockReturnValue({
+			data: { status: 'success', data: { aggregations: [] } },
+			isLoading: false,
+			isError: false,
+		});
+		renderPanel();
+		expect(screen.getByText(/no data for service.name/i)).toBeInTheDocument();
+	});
+});

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/TraceOptionsMenu.module.scss

@@ -1,3 +1,6 @@
+// Applied to both the menu content and the submenu content (each renders in
+// its own portal with a default z-index of 50) so both stack above
+// FloatingPanel (z-index 999).
 .traceOptionsDropdown {
 	z-index: 1100;
 }

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/TraceOptionsMenu.tsx

@@ -1,7 +1,16 @@
-import { useMemo } from 'react';
-import type { MenuItem } from '@signozhq/ui/dropdown-menu';
 import { Button } from '@signozhq/ui/button';
-import { DropdownMenuSimple as Dropdown } from '@signozhq/ui/dropdown-menu';
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuLabel,
+	DropdownMenuRadioGroup,
+	DropdownMenuRadioItem,
+	DropdownMenuSub,
+	DropdownMenuSubContent,
+	DropdownMenuSubTrigger,
+	DropdownMenuTrigger,
+} from '@signozhq/ui/dropdown-menu';
 import { Settings2 } from '@signozhq/icons';
 
 import { useTraceStore } from '../stores/traceStore';
@@ -14,6 +23,9 @@ interface TraceOptionsMenuProps {
 	onOpenPreviewFields: () => void;
 }
 
+// Composed from dropdown-menu primitives (instead of DropdownMenuSimple)
+// because the simple preset offers no way to style the submenu content,
+// which renders in its own portal and needs a z-index above FloatingPanel.
 function TraceOptionsMenu({
 	showTraceDetails,
 	onToggleTraceDetails,
@@ -25,78 +37,52 @@ function TraceOptionsMenu({
 		(s) => s.availableColorByOptions,
 	);
 
-	const menuItems: MenuItem[] = useMemo(() => {
-		const items: MenuItem[] = [
-			{
-				key: 'toggle-trace-details',
-				label: showTraceDetails ? 'Hide trace details' : 'Show trace details',
-				onClick: onToggleTraceDetails,
-			},
-			{
-				key: 'preview-fields',
-				label: 'Preview fields',
-				onClick: onOpenPreviewFields,
-			},
-		];
-
-		// Only show the "Colour by" submenu if there's an actual choice to make.
-		if (availableColorByOptions.length > 1) {
-			items.push({
-				key: 'colour-by',
-				label: 'Colour by',
-				children: [
-					{
-						type: 'group',
-						label: 'COLOUR BY',
-						children: [
-							{
-								type: 'radio-group',
-								value: colorByField.name,
-								onChange: (name: string): void => {
-									const next = availableColorByOptions.find(
-										(o) => o.field.name === name,
-									);
-									if (next) {
-										setColorByField(next.field);
-									}
-								},
-								children: availableColorByOptions.map((opt) => ({
-									type: 'radio',
-									key: opt.field.name,
-									label: opt.label,
-									value: opt.field.name,
-								})),
-							},
-						],
-					},
-				],
-			});
+	const handleColorByChange = (name: string): void => {
+		const next = availableColorByOptions.find((o) => o.field.name === name);
+		if (next) {
+			setColorByField(next.field);
 		}
-
-		return items;
-	}, [
-		showTraceDetails,
-		onToggleTraceDetails,
-		onOpenPreviewFields,
-		colorByField.name,
-		setColorByField,
-		availableColorByOptions,
-	]);
+	};
 
 	return (
-		<Dropdown
-			menu={{ items: menuItems }}
-			align="start"
-			className={styles.traceOptionsDropdown}
-		>
-			<Button
-				variant="ghost"
-				size="icon"
-				color="secondary"
-				aria-label="Trace options"
-				prefix={<Settings2 size={14} />}
-			/>
-		</Dropdown>
+		<DropdownMenu>
+			<DropdownMenuTrigger asChild>
+				<Button
+					variant="ghost"
+					size="icon"
+					color="secondary"
+					aria-label="Trace options"
+					prefix={<Settings2 size={14} />}
+				/>
+			</DropdownMenuTrigger>
+			<DropdownMenuContent align="start" className={styles.traceOptionsDropdown}>
+				<DropdownMenuItem clickable onSelect={onToggleTraceDetails}>
+					{showTraceDetails ? 'Hide trace details' : 'Show trace details'}
+				</DropdownMenuItem>
+				<DropdownMenuItem clickable onSelect={onOpenPreviewFields}>
+					Preview fields
+				</DropdownMenuItem>
+				{/* Only show the "Colour by" submenu if there's an actual choice to make. */}
+				{availableColorByOptions.length > 1 && (
+					<DropdownMenuSub>
+						<DropdownMenuSubTrigger>Colour by</DropdownMenuSubTrigger>
+						<DropdownMenuSubContent className={styles.traceOptionsDropdown}>
+							<DropdownMenuLabel>COLOUR BY</DropdownMenuLabel>
+							<DropdownMenuRadioGroup
+								value={colorByField.name}
+								onValueChange={handleColorByChange}
+							>
+								{availableColorByOptions.map((opt) => (
+									<DropdownMenuRadioItem key={opt.field.name} value={opt.field.name}>
+										{opt.label}
+									</DropdownMenuRadioItem>
+								))}
+							</DropdownMenuRadioGroup>
+						</DropdownMenuSubContent>
+					</DropdownMenuSub>
+				)}
+			</DropdownMenuContent>
+		</DropdownMenu>
 	);
 }
 

frontend/src/pages/TraceDetailsV3/TraceFlamegraph/__tests__/computeVisualLayout.test.ts

@@ -1,6 +1,9 @@
 import { FlamegraphSpan } from 'types/api/trace/getTraceFlamegraph';
 
-import { computeVisualLayout } from '../computeVisualLayout';
+import {
+	computeVisualLayout,
+	WIDE_GROUP_THRESHOLD,
+} from '../computeVisualLayout';
 
 function makeSpan(
 	overrides: Partial<FlamegraphSpan> & {
@@ -472,4 +475,177 @@ describe('computeVisualLayout', () => {
 		expect(aRow).toBeGreaterThan(1); // must NOT be at row 1
 		expect(aRow).toBe(3); // next free row after B at row 2 (A overlaps B)
 	});
+
+	// --- Wide-group fast path (> WIDE_GROUP_THRESHOLD siblings) ---
+	// Past the threshold the layout switches to exact overlap-only packing to
+	// avoid the O(N^2) connector-avoidance spiral. These lock in correctness and
+	// the no-overlap invariant at scale.
+
+	function noRowHasOverlap(
+		layout: ReturnType<typeof computeVisualLayout>,
+	): void {
+		for (const row of layout.visualRows) {
+			const sorted = [...row].sort((a, b) => a.timestamp - b.timestamp);
+			for (let i = 1; i < sorted.length; i++) {
+				const prevEnd = sorted[i - 1].timestamp + sorted[i - 1].durationNano / 1e6;
+				expect(sorted[i].timestamp).toBeGreaterThanOrEqual(prevEnd);
+			}
+		}
+	}
+
+	it('should pack thousands of sequential leaf siblings into 1 row (wide path)', () => {
+		const root = makeSpan({ spanId: 'root', timestamp: 0, durationNano: 1e12 });
+		const kids: FlamegraphSpan[] = [];
+		// 2000 strictly sequential (non-overlapping) children
+		for (let i = 0; i < 2000; i++) {
+			kids.push(
+				makeSpan({
+					spanId: `k${i}`,
+					parentSpanId: 'root',
+					timestamp: i * 10,
+					durationNano: 5e6, // 5ms, ends before next starts
+				}),
+			);
+		}
+
+		const layout = computeVisualLayout([[root], kids]);
+
+		expect(layout.spanToVisualRow['root']).toBe(0);
+		expect(layout.totalVisualRows).toBe(2); // all siblings share row 1
+		for (const k of kids) {
+			expect(layout.spanToVisualRow[k.spanId]).toBe(1);
+		}
+		noRowHasOverlap(layout);
+	});
+
+	it('should pack thousands of fully-overlapping leaf siblings without violations (wide path)', () => {
+		const root = makeSpan({ spanId: 'root', timestamp: 0, durationNano: 1e12 });
+		const kids: FlamegraphSpan[] = [];
+		// 1000 children all spanning the same window → each needs its own row
+		for (let i = 0; i < 1000; i++) {
+			kids.push(
+				makeSpan({
+					spanId: `k${i}`,
+					parentSpanId: 'root',
+					timestamp: 0,
+					durationNano: 100e6,
+				}),
+			);
+		}
+
+		const layout = computeVisualLayout([[root], kids]);
+
+		expect(layout.totalVisualRows).toBe(1001); // root + 1000 stacked rows
+		expect(Object.keys(layout.spanToVisualRow)).toHaveLength(1001);
+		noRowHasOverlap(layout);
+	});
+
+	it('should keep non-leaf subtrees adjacent within a wide mixed group (wide path)', () => {
+		const root = makeSpan({ spanId: 'root', timestamp: 0, durationNano: 1e12 });
+		const kids: FlamegraphSpan[] = [];
+		for (let i = 0; i < 1000; i++) {
+			kids.push(
+				makeSpan({
+					spanId: `k${i}`,
+					parentSpanId: 'root',
+					timestamp: i * 10,
+					durationNano: 5e6,
+				}),
+			);
+		}
+		// One of the wide siblings has a child of its own
+		const grandchild = makeSpan({
+			spanId: 'gc',
+			parentSpanId: 'k500',
+			timestamp: 5000,
+			durationNano: 2e6,
+		});
+
+		const layout = computeVisualLayout([[root], kids, [grandchild]]);
+
+		const parentRow = layout.spanToVisualRow['k500'];
+		const gcRow = layout.spanToVisualRow['gc'];
+		expect(gcRow - parentRow).toBe(1); // subtree adjacency preserved
+		expect(Object.keys(layout.spanToVisualRow)).toHaveLength(1002);
+		noRowHasOverlap(layout);
+	});
+
+	// --- Regression guards for the wide-trace layout spiral ---
+	// The pre-fix algorithm's connector-avoidance checks formed a positive-
+	// feedback loop on wide SCATTERED groups (short spans spread across the
+	// parent window with modest concurrency): each pushed-down child stamped
+	// connector points on intermediate rows, pushing later children even
+	// higher. Sequential and fully-overlapping groups (tests above) do NOT
+	// trigger it — these two shapes do, and encode its failure signatures.
+
+	function makeScatteredStar(
+		childCount: number,
+		spacingMs: number,
+		durationMs: number,
+	): FlamegraphSpan[][] {
+		const root = makeSpan({
+			spanId: 'root',
+			timestamp: 0,
+			durationNano: (childCount * spacingMs + durationMs) * 1e6,
+		});
+		const kids: FlamegraphSpan[] = [];
+		for (let i = 0; i < childCount; i++) {
+			kids.push(
+				makeSpan({
+					spanId: `k${i}`,
+					parentSpanId: 'root',
+					timestamp: i * spacingMs,
+					durationNano: durationMs * 1e6,
+				}),
+			);
+		}
+		return [[root], kids];
+	}
+
+	it('should not spiral row count on a scattered group just above the threshold', () => {
+		// Children of 50ms each, starting every 10ms → max temporal concurrency
+		// is 6 (each span overlaps the next 5). The old algorithm spiraled this
+		// shape to ~1 row per child; overlap-only packing needs ~7 including the
+		// root. Sized just above WIDE_GROUP_THRESHOLD so a regression fails fast
+		// (sub-second) rather than burning CI time.
+		const count = WIDE_GROUP_THRESHOLD + 88;
+		const layout = computeVisualLayout(makeScatteredStar(count, 10, 50));
+
+		expect(Object.keys(layout.spanToVisualRow)).toHaveLength(count + 1);
+		// Generous slack over the optimal ~7 — but orders of magnitude below the
+		// one-row-per-child the spiral produced.
+		expect(layout.totalVisualRows).toBeLessThan(30);
+		noRowHasOverlap(layout);
+	});
+
+	it('should be faster through the fast path despite one extra span', () => {
+		// Identical scattered shape on both sides of the gate: THRESHOLD children
+		// run the original connector-avoidance path, THRESHOLD + 1 run the
+		// overlap-only fast path. With one MORE span to place, the fast path can
+		// only win because the algorithm is cheaper — a self-calibrating
+		// comparison (same machine, same process) with no absolute time budget.
+		// On this shape the avoidance path spirals (~tens of ms) while the fast
+		// path stays ~1ms, so the margin is well past timer noise. Also guards
+		// the gate itself: if everything routed to one path, one extra span can
+		// never be faster.
+		const avoidancePathInput = makeScatteredStar(WIDE_GROUP_THRESHOLD, 10, 50);
+		const fastPathInput = makeScatteredStar(WIDE_GROUP_THRESHOLD + 1, 10, 50);
+
+		// Warm-up runs so JIT compilation doesn't skew either side.
+		computeVisualLayout(avoidancePathInput);
+		computeVisualLayout(fastPathInput);
+
+		const timeOf = (input: FlamegraphSpan[][]): number => {
+			const start = performance.now();
+			computeVisualLayout(input);
+			return performance.now() - start;
+		};
+
+		// Best-of-3 per side to shave off GC pauses and scheduler noise.
+		const RUNS = [0, 1, 2];
+		const avoidanceMs = Math.min(...RUNS.map(() => timeOf(avoidancePathInput)));
+		const fastMs = Math.min(...RUNS.map(() => timeOf(fastPathInput)));
+
+		expect(fastMs).toBeLessThan(avoidanceMs);
+	});
 });

frontend/src/pages/TraceDetailsV3/TraceFlamegraph/computeVisualLayout.ts

@@ -18,6 +18,82 @@ export interface VisualLayout {
 	totalVisualRows: number;
 }
 
+// Above this many siblings under one parent, the connector-avoidance refinement
+// (Checks 2 & 3) is both visually meaningless — the row is already a dense wall —
+// and quadratic: every child deposits a connector point on each intermediate row,
+// which pushes later children even higher, which deposits more points. That
+// feedback loop inflates a layout needing ~50 rows to thousands and never
+// finishes on wide traces. Past the threshold we pack by overlap only.
+// Exported so the regression tests stay anchored to the real gate value.
+export const WIDE_GROUP_THRESHOLD = 512;
+
+/**
+ * Segment tree over rows that answers "lowest row index >= `from` whose smallest
+ * span start-time is >= `end`" in O(log rows). Used to place a large group of
+ * leaf siblings by overlap only: because siblings are processed in descending
+ * start order, every already-placed span on a row starts at or after the current
+ * one, so [start, end] overlaps a row iff some span there starts before `end` —
+ * i.e. the row is free iff its minimum start >= end. Each node stores the max of
+ * its subtree's per-row minimum starts so a free row can be found by descent.
+ */
+class LowestFreeRow {
+	private readonly size: number;
+
+	private readonly tree: Float64Array;
+
+	constructor(rows: number) {
+		let size = 1;
+		while (size < rows) {
+			size *= 2;
+		}
+		this.size = size;
+		this.tree = new Float64Array(size * 2).fill(Infinity);
+	}
+
+	place(row: number, start: number): void {
+		let i = row + this.size;
+		// A row's key is the minimum start among its spans. Children are processed
+		// in descending start order so a leaf's start is the new minimum, but a
+		// non-leaf subtree's descendant can land on a row out of order — take min.
+		if (start >= this.tree[i]) {
+			return;
+		}
+		this.tree[i] = start;
+		for (i >>= 1; i >= 1; i >>= 1) {
+			const next = Math.max(this.tree[2 * i], this.tree[2 * i + 1]);
+			if (this.tree[i] === next) {
+				break;
+			}
+			this.tree[i] = next;
+		}
+	}
+
+	lowestFrom(from: number, end: number): number {
+		return this.descend(1, 0, this.size - 1, from, end);
+	}
+
+	private descend(
+		node: number,
+		lo: number,
+		hi: number,
+		from: number,
+		end: number,
+	): number {
+		if (hi < from || this.tree[node] < end) {
+			return -1;
+		}
+		if (lo === hi) {
+			return lo;
+		}
+		const mid = (lo + hi) >> 1;
+		const left = this.descend(2 * node, lo, mid, from, end);
+		if (left !== -1) {
+			return left;
+		}
+		return this.descend(2 * node + 1, mid + 1, hi, from, end);
+	}
+}
+
 /**
  * Computes an overlap-safe visual layout for flamegraph spans using DFS ordering.
  *
@@ -214,7 +290,53 @@ export function computeVisualLayout(spans: FlamegraphSpan[][]): VisualLayout {
 		arr.push(point);
 	}
 
+	// Fast path for a parent with a very large group of children: pack by overlap
+	// only (descending greedy), skipping the quadratic connector-avoidance that
+	// spirals at this scale. Leaf children — the bulk of a wide trace — are placed
+	// in O(log rows) via the segment tree; the rare non-leaf subtree falls back to
+	// findPlacement against the shared interval map. Both structures are kept in
+	// sync so each placement sees all prior occupancy. Same ShapeEntry[] contract.
+	function computeWideShape(
+		rootSpan: FlamegraphSpan,
+		children: FlamegraphSpan[],
+	): ShapeEntry[] {
+		const shape: ShapeEntry[] = [{ span: rootSpan, relativeRow: 0 }];
+		const localIntervals = new Map<number, Array<[number, number]>>();
+		// Children occupy relative rows 1..children.length in the worst case.
+		const finder = new LowestFreeRow(children.length + 2);
+
+		const occupy = (row: number, span: FlamegraphSpan): void => {
+			const s = span.timestamp;
+			const e = span.timestamp + span.durationNano / 1e6;
+			shape.push({ span, relativeRow: row });
+			addIntervalTo(localIntervals, row, s, e);
+			finder.place(row, s);
+		};
+
+		for (const child of children) {
+			if (childrenMap.has(child.spanId)) {
+				// Non-leaf: place its whole subtree shape as a unit via findPlacement.
+				const childShape = computeSubtreeShape(child);
+				const offset = findPlacement(childShape, 1, localIntervals);
+				for (const entry of childShape) {
+					occupy(entry.relativeRow + offset, entry.span);
+				}
+			} else {
+				const end = child.timestamp + child.durationNano / 1e6;
+				occupy(finder.lowestFrom(1, end), child);
+			}
+		}
+
+		return shape;
+	}
+
 	function computeSubtreeShape(rootSpan: FlamegraphSpan): ShapeEntry[] {
+		const children = childrenMap.get(rootSpan.spanId);
+
+		if (children && children.length > WIDE_GROUP_THRESHOLD) {
+			return computeWideShape(rootSpan, children);
+		}
+
 		const localIntervals = new Map<number, Array<[number, number]>>();
 		const localConnectorPoints = new Map<number, number[]>();
 		const shape: ShapeEntry[] = [];
@@ -225,7 +347,6 @@ export function computeVisualLayout(spans: FlamegraphSpan[][]): VisualLayout {
 		shape.push({ span: rootSpan, relativeRow: 0 });
 		addIntervalTo(localIntervals, 0, rootStart, rootEnd);
 
-		const children = childrenMap.get(rootSpan.spanId);
 		if (children) {
 			for (const child of children) {
 				const childShape = computeSubtreeShape(child);

frontend/src/pages/TraceDetailsV3/TraceFlamegraph/hooks/useVisualLayoutWorker.ts

@@ -94,7 +94,7 @@ export function useVisualLayoutWorker(spans: FlamegraphSpan[][]): {
 			cleanup();
 		};
 
-		// Timeout: if worker doesn't respond in 30s, terminate and error
+		// Timeout: if worker doesn't respond in 15s, terminate and error
 		const WORKER_TIMEOUT_MS = 15000;
 		const timeoutId = setTimeout(() => {
 			if (requestIdRef.current === currentId && isComputingRef.current) {

frontend/src/pages/TraceDetailsV3/TraceWaterfall/TraceWaterfall.tsx

@@ -3,7 +3,7 @@ import { Skeleton } from 'antd';
 import { AxiosError } from 'axios';
 import Spinner from 'components/Spinner';
 import { ErrorResponse, SuccessResponse } from 'types/api';
-import { GetTraceV3SuccessResponse, SpanV3 } from 'types/api/trace/getTraceV3';
+import { GetTraceV4SuccessResponse, SpanV3 } from 'types/api/trace/getTraceV3';
 
 import { TraceWaterfallStates } from './constants';
 import Error from './TraceWaterfallStates/Error/Error';
@@ -22,7 +22,7 @@ interface ITraceWaterfallProps {
 	localUncollapsedNodes: Set<string>;
 	setLocalUncollapsedNodes: Dispatch<SetStateAction<Set<string>>>;
 	traceData:
-		| SuccessResponse<GetTraceV3SuccessResponse, unknown>
+		| SuccessResponse<GetTraceV4SuccessResponse, unknown>
 		| ErrorResponse
 		| undefined;
 	isFetchingTraceData: boolean;

frontend/src/pages/TraceDetailsV3/__tests__/getAvailableColorByFieldNames.test.ts

@@ -0,0 +1,34 @@
+import { SpanV3 } from 'types/api/trace/getTraceV3';
+
+import { getAvailableColorByFieldNames } from '../utils';
+
+const span = (partial: Partial<SpanV3>): SpanV3 =>
+	({ level: 1, resource: {}, attributes: {}, ...partial }) as SpanV3;
+
+describe('getAvailableColorByFieldNames', () => {
+	it('returns [] for an empty span set', () => {
+		expect(getAvailableColorByFieldNames([])).toStrictEqual([]);
+	});
+
+	it('offers a field if any span carries it, in option order', () => {
+		const spans = [
+			span({ resource: { 'service.name': 'api' } }),
+			// k8s.node.name lives on a non-root span — still offered
+			span({ resource: { 'k8s.node.name': 'node-1' } }),
+		];
+		expect(getAvailableColorByFieldNames(spans)).toStrictEqual([
+			'service.name',
+			'k8s.node.name',
+		]);
+	});
+
+	it('reads from attributes when the key is not on resource', () => {
+		const spans = [span({ attributes: { 'host.name': 'box-1' } })];
+		expect(getAvailableColorByFieldNames(spans)).toStrictEqual(['host.name']);
+	});
+
+	it('does not offer fields no span carries', () => {
+		const spans = [span({ resource: { 'service.name': 'api' } })];
+		expect(getAvailableColorByFieldNames(spans)).toStrictEqual(['service.name']);
+	});
+});

frontend/src/pages/TraceDetailsV3/index.tsx

@@ -8,23 +8,17 @@ import { Collapse } from 'antd';
 import { useDetailsPanel } from 'components/DetailsPanel';
 import WarningPopover from 'components/WarningPopover/WarningPopover';
 import { LOCALSTORAGE } from 'constants/localStorage';
-import useGetTraceV3 from 'hooks/trace/useGetTraceV3';
+import useGetTraceV4 from 'hooks/trace/useGetTraceV4';
 import { useSafeNavigate } from 'hooks/useSafeNavigate';
 import useUrlQuery from 'hooks/useUrlQuery';
 import NoData from 'pages/TraceDetailV2/NoData/NoData';
 import { ResizableBox } from 'periscope/components/ResizableBox';
-import {
-	SpanV3,
-	TraceDetailV3URLProps,
-	WaterfallAggregationRequest,
-} from 'types/api/trace/getTraceV3';
+import { SpanV3, TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
 
-import { COLOR_BY_FIELDS } from './constants';
 import { TraceDetailEventKeys, TraceDetailEvents } from './events';
 import { useTraceDetailLogEvent } from './hooks/useTraceDetailLogEvent';
 import TraceStoreSync from './stores/TraceStoreSync';
 import { useTraceStore } from './stores/traceStore';
-import { AGGREGATIONS } from './utils/aggregations';
 import { SpanDetailVariant } from './SpanDetailsPanel/constants';
 import SpanDetailsPanel from './SpanDetailsPanel/SpanDetailsPanel';
 import type { TraceMetadataForHeader } from './TraceDetailsHeader/TraceDetailsHeader';
@@ -34,6 +28,7 @@ import TraceFlamegraph from './TraceFlamegraph/TraceFlamegraph';
 import TraceWaterfall from './TraceWaterfall/TraceWaterfall';
 import { IInterestedSpan } from './TraceWaterfall/types';
 import { getAncestorSpanIds } from './TraceWaterfall/utils';
+import { getAvailableColorByFieldNames } from './utils';
 
 import cx from 'classnames';
 
@@ -103,17 +98,6 @@ function TraceDetailsV3(): JSX.Element {
 		setInterestedSpanId({ spanId, isUncollapsed: true });
 	}, [urlQuery]);
 
-	// Hardcoded for now — fetch aggregations for all 3 candidate color-by fields
-	// upfront so a future color-by-field switch doesn't need to refetch.
-	const waterfallAggregationsRequest = useMemo<WaterfallAggregationRequest[]>(
-		() =>
-			COLOR_BY_FIELDS.flatMap((field) => [
-				{ field, aggregation: AGGREGATIONS.EXEC_TIME_PCT },
-				{ field, aggregation: AGGREGATIONS.SPAN_COUNT },
-			]),
-		[],
-	);
-
 	// Once all spans are loaded (frontend mode), freeze query params so
 	// subsequent interestedSpanId changes don't trigger unnecessary refetches.
 	const fullDataLoadedRef = useRef(false);
@@ -121,7 +105,6 @@ function TraceDetailsV3(): JSX.Element {
 		selectedSpanId: interestedSpanId.spanId,
 		isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
 		uncollapsedSpans: uncollapsedNodes,
-		aggregations: waterfallAggregationsRequest,
 	});
 
 	const queryParams = fullDataLoadedRef.current
@@ -130,19 +113,17 @@ function TraceDetailsV3(): JSX.Element {
 				selectedSpanId: interestedSpanId.spanId,
 				isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
 				uncollapsedSpans: uncollapsedNodes,
-				aggregations: waterfallAggregationsRequest,
 			};
 
 	const {
 		data: traceData,
 		isFetching: isFetchingTraceData,
 		error: errorFetchingTraceData,
-	} = useGetTraceV3({
+	} = useGetTraceV4({
 		traceId,
 		uncollapsedSpans: queryParams.uncollapsedSpans,
 		selectedSpanId: queryParams.selectedSpanId,
 		isSelectedSpanIDUnCollapsed: queryParams.isSelectedSpanIDUnCollapsed,
-		aggregations: queryParams.aggregations,
 	});
 
 	const allSpans = traceData?.payload?.spans || [];
@@ -150,6 +131,13 @@ function TraceDetailsV3(): JSX.Element {
 	const isFullDataLoaded =
 		totalSpansCount > 0 && totalSpansCount <= allSpans.length;
 
+	// Color-by options, gated on fields in loaded spans. Resource attrs are
+	// trace-wide, so any window has the full set — no need to accumulate.
+	const availableColorByFields = useMemo(() => {
+		const spans = traceData?.payload?.spans;
+		return spans?.length ? getAvailableColorByFieldNames(spans) : undefined;
+	}, [traceData?.payload?.spans]);
+
 	// Lock the ref once we confirm all data is loaded
 	if (isFullDataLoaded && !fullDataLoadedRef.current) {
 		fullDataLoadedRef.current = true;
@@ -157,7 +145,6 @@ function TraceDetailsV3(): JSX.Element {
 			selectedSpanId: interestedSpanId.spanId,
 			isSelectedSpanIDUnCollapsed: interestedSpanId.isUncollapsed,
 			uncollapsedSpans: uncollapsedNodes,
-			aggregations: waterfallAggregationsRequest,
 		};
 	}
 
@@ -382,7 +369,7 @@ function TraceDetailsV3(): JSX.Element {
 	);
 
 	return (
-		<TraceStoreSync aggregations={traceData?.payload?.aggregations}>
+		<TraceStoreSync availableColorByFields={availableColorByFields}>
 			<div className={styles.root}>
 				<TraceDetailsHeader
 					filterMetadata={filterMetadata}

frontend/src/pages/TraceDetailsV3/stores/TraceStoreSync.tsx

@@ -2,21 +2,20 @@ import { ReactNode, useEffect } from 'react';
 import { useMutation } from 'react-query';
 import updateUserPreferenceAPI from 'api/v1/user/preferences/name/update';
 import { useAppContext } from 'providers/App/App';
-import { WaterfallAggregationResponse } from 'types/api/trace/getTraceV3';
 
 import {
-	setTraceStoreAggregations,
+	setTraceStoreAvailableColorByFields,
 	setTraceStoreCallbacks,
 	setTraceStoreUserPreferences,
 } from './traceStore';
 
 interface TraceStoreSyncProps {
-	aggregations: WaterfallAggregationResponse[] | undefined;
+	availableColorByFields: string[] | undefined;
 	children: ReactNode;
 }
 
 /**
- * Bridges React-managed inputs (the `aggregations` prop, `userPreferences`
+ * Bridges React-managed inputs (`availableColorByFields`, `userPreferences`
  * from AppContext, and the user-pref mutation hook) into the Zustand store.
  *
  * Renders nothing until `userPreferences` resolves so the flamegraph never
@@ -25,15 +24,15 @@ interface TraceStoreSyncProps {
  * is logged in, so this gate is usually already settled by mount time.
  */
 function TraceStoreSync({
-	aggregations,
+	availableColorByFields,
 	children,
 }: TraceStoreSyncProps): JSX.Element | null {
 	const { userPreferences, updateUserPreferenceInContext } = useAppContext();
 	const { mutate: mutateUserPreference } = useMutation(updateUserPreferenceAPI);
 
 	useEffect(() => {
-		setTraceStoreAggregations(aggregations);
-	}, [aggregations]);
+		setTraceStoreAvailableColorByFields(availableColorByFields);
+	}, [availableColorByFields]);
 
 	useEffect(() => {
 		setTraceStoreUserPreferences(userPreferences ?? null);

frontend/src/pages/TraceDetailsV3/stores/__tests__/traceStore.test.ts

@@ -0,0 +1,71 @@
+import { USER_PREFERENCES } from 'constants/userPreferences';
+import { UserPreference } from 'types/api/preferences/preference';
+
+import { COLOR_BY_OPTIONS, DEFAULT_COLOR_BY_FIELD } from '../../constants';
+import {
+	setTraceStoreAvailableColorByFields,
+	setTraceStoreUserPreferences,
+	useTraceStore,
+} from '../traceStore';
+
+const colorByPref = (fieldName: string): UserPreference[] => [
+	{
+		name: USER_PREFERENCES.SPAN_DETAILS_COLOR_BY_ATTRIBUTE,
+		value: fieldName,
+	} as UserPreference,
+];
+
+const optionNames = (): string[] =>
+	useTraceStore.getState().availableColorByOptions.map((o) => o.field.name);
+
+describe('traceStore color-by gating', () => {
+	beforeEach(() => {
+		useTraceStore.setState({
+			availableColorByFieldNames: undefined,
+			userPreferences: null,
+			colorByField: DEFAULT_COLOR_BY_FIELD,
+			availableColorByOptions: COLOR_BY_OPTIONS.filter(
+				(o) => o.field.name === DEFAULT_COLOR_BY_FIELD.name,
+			),
+		});
+	});
+
+	it('offers only the default field before spans load', () => {
+		expect(optionNames()).toStrictEqual([DEFAULT_COLOR_BY_FIELD.name]);
+		expect(useTraceStore.getState().colorByField).toStrictEqual(
+			DEFAULT_COLOR_BY_FIELD,
+		);
+	});
+
+	it('offers the default plus any field present on loaded spans', () => {
+		setTraceStoreAvailableColorByFields(['host.name']);
+		expect(optionNames()).toStrictEqual([
+			DEFAULT_COLOR_BY_FIELD.name,
+			'host.name',
+		]);
+	});
+
+	it('honors the persisted color-by field when it is available', () => {
+		setTraceStoreAvailableColorByFields(['host.name']);
+		setTraceStoreUserPreferences(colorByPref('host.name'));
+		expect(useTraceStore.getState().colorByField.name).toBe('host.name');
+	});
+
+	it('falls back to the default when the persisted field is not available', () => {
+		setTraceStoreUserPreferences(colorByPref('host.name'));
+		setTraceStoreAvailableColorByFields(['k8s.node.name']);
+		expect(useTraceStore.getState().colorByField.name).toBe(
+			DEFAULT_COLOR_BY_FIELD.name,
+		);
+		expect(optionNames()).toStrictEqual([
+			DEFAULT_COLOR_BY_FIELD.name,
+			'k8s.node.name',
+		]);
+	});
+
+	it('trusts the persisted field while spans are still loading', () => {
+		// availableColorByFieldNames stays undefined (loading) — do not flip to default
+		setTraceStoreUserPreferences(colorByPref('host.name'));
+		expect(useTraceStore.getState().colorByField.name).toBe('host.name');
+	});
+});

frontend/src/pages/TraceDetailsV3/stores/traceStore.ts

@@ -1,7 +1,6 @@
 import { USER_PREFERENCES } from 'constants/userPreferences';
 import { UserPreference } from 'types/api/preferences/preference';
 import { BaseAutocompleteData } from 'types/api/queryBuilder/queryAutocompleteResponse';
-import { WaterfallAggregationResponse } from 'types/api/trace/getTraceV3';
 import { TelemetryFieldKey } from 'types/api/v5/queryRange';
 import { create } from 'zustand';
 
@@ -11,10 +10,6 @@ import {
 	ColorByOption,
 	DEFAULT_COLOR_BY_FIELD,
 } from '../constants';
-import {
-	AGGREGATIONS,
-	getAggregationMap as findAggregationMap,
-} from '../utils/aggregations';
 import { toTelemetryFieldKey } from '../utils/previewFields';
 
 interface MutateOptions {
@@ -30,7 +25,9 @@ type MutateUserPreference = (
 
 interface TraceStoreState {
 	// --- Inputs synced from React layer via TraceStoreSync ---
-	aggregations: WaterfallAggregationResponse[] | undefined;
+	// Fields present on loaded spans; gates color-by options. `undefined` while
+	// loading so we keep trusting the persisted field.
+	availableColorByFieldNames: string[] | undefined;
 	userPreferences: UserPreference[] | null;
 	updateUserPreferenceInContext: UpdateUserPreferenceInContext | null;
 	mutateUserPreference: MutateUserPreference | null;
@@ -41,9 +38,7 @@ interface TraceStoreState {
 	previewFields: TelemetryFieldKey[];
 
 	// --- Setters used only by TraceStoreSync ---
-	setAggregations: (
-		aggregations: WaterfallAggregationResponse[] | undefined,
-	) => void;
+	setAvailableColorByFields: (fieldNames: string[] | undefined) => void;
 	setUserPreferences: (userPreferences: UserPreference[] | null) => void;
 	setCallbacks: (callbacks: {
 		updateUserPreferenceInContext: UpdateUserPreferenceInContext;
@@ -71,23 +66,18 @@ function getPersistedColorByField(
 
 /**
  * Re-derives `colorByField` + `availableColorByOptions` from the two inputs.
- * Preserves the "trust persisted while aggregations load" rule so the
- * flamegraph doesn't repaint when the aggregations response arrives.
+ * Preserves the "trust persisted while spans load" rule so the flamegraph
+ * doesn't repaint when the waterfall response arrives.
  */
 function deriveColorState(
-	aggregations: WaterfallAggregationResponse[] | undefined,
+	availableColorByFieldNames: string[] | undefined,
 	userPreferences: UserPreference[] | null,
 ): Pick<TraceStoreState, 'colorByField' | 'availableColorByOptions'> {
 	const isFieldAvailable = (fieldName: string): boolean => {
 		if (fieldName === DEFAULT_COLOR_BY_FIELD.name) {
 			return true;
 		}
-		const map = findAggregationMap(
-			aggregations,
-			AGGREGATIONS.EXEC_TIME_PCT,
-			fieldName,
-		);
-		return !!map && Object.keys(map).length > 0;
+		return !!availableColorByFieldNames?.includes(fieldName);
 	};
 
 	const availableColorByOptions = COLOR_BY_OPTIONS.filter((opt) =>
@@ -95,10 +85,10 @@ function deriveColorState(
 	);
 
 	const persistedColorByField = getPersistedColorByField(userPreferences);
-	// While aggregations are loading, trust persisted — don't flip to default
-	// just because we haven't confirmed availability yet.
+	// While loading, trust persisted — don't flip to default prematurely.
 	const colorByField =
-		aggregations === undefined || isFieldAvailable(persistedColorByField.name)
+		availableColorByFieldNames === undefined ||
+		isFieldAvailable(persistedColorByField.name)
 			? persistedColorByField
 			: DEFAULT_COLOR_BY_FIELD;
 
@@ -134,7 +124,7 @@ function derivePreviewFields(
 }
 
 export const useTraceStore = create<TraceStoreState>()((set, get) => ({
-	aggregations: undefined,
+	availableColorByFieldNames: undefined,
 	userPreferences: null,
 	updateUserPreferenceInContext: null,
 	mutateUserPreference: null,
@@ -145,19 +135,19 @@ export const useTraceStore = create<TraceStoreState>()((set, get) => ({
 	),
 	previewFields: [],
 
-	setAggregations: (aggregations): void => {
+	setAvailableColorByFields: (availableColorByFieldNames): void => {
 		const { userPreferences } = get();
 		set({
-			aggregations,
-			...deriveColorState(aggregations, userPreferences),
+			availableColorByFieldNames,
+			...deriveColorState(availableColorByFieldNames, userPreferences),
 		});
 	},
 
 	setUserPreferences: (userPreferences): void => {
-		const { aggregations } = get();
+		const { availableColorByFieldNames } = get();
 		set({
 			userPreferences,
-			...deriveColorState(aggregations, userPreferences),
+			...deriveColorState(availableColorByFieldNames, userPreferences),
 			previewFields: derivePreviewFields(userPreferences),
 		});
 	},
@@ -235,9 +225,9 @@ export const useTraceStore = create<TraceStoreState>()((set, get) => ({
 	},
 }));
 
-export const setTraceStoreAggregations = (
-	aggregations: WaterfallAggregationResponse[] | undefined,
-): void => useTraceStore.getState().setAggregations(aggregations);
+export const setTraceStoreAvailableColorByFields = (
+	fieldNames: string[] | undefined,
+): void => useTraceStore.getState().setAvailableColorByFields(fieldNames);
 
 export const setTraceStoreUserPreferences = (
 	userPreferences: UserPreference[] | null,

frontend/src/pages/TraceDetailsV3/utils.ts

@@ -1,5 +1,6 @@
 import { SpanV3 } from 'types/api/trace/getTraceV3';
 
+import { COLOR_BY_OPTIONS } from './constants';
 import {
 	ColorPair,
 	generateColorPair,
@@ -109,3 +110,14 @@ export function resolveSpanColor(
 	}
 	return generateColorPair(getSpanGroupValue(span, colorByFieldName));
 }
+
+/**
+ * Color-by fields present on any of the given spans — replaces the old
+ * server-side aggregation gating. `service.name` is always offered by the store
+ * regardless of this list.
+ */
+export function getAvailableColorByFieldNames(spans: SpanV3[]): string[] {
+	return COLOR_BY_OPTIONS.filter((opt) =>
+		spans.some((s) => getSpanAttribute(s, opt.field.name)),
+	).map((opt) => opt.field.name);
+}

frontend/src/pages/TraceDetailsV3/utils/aggregations.ts

@@ -1,19 +1,19 @@
 import {
-	WaterfallAggregationResponse,
-	WaterfallAggregationType,
-} from 'types/api/trace/getTraceV3';
+	SpantypesSpanAggregationResultDTO,
+	SpantypesSpanAggregationTypeDTO,
+} from 'api/generated/services/sigNoz.schemas';
 
 export const AGGREGATIONS = {
-	EXEC_TIME_PCT: 'execution_time_percentage',
-	SPAN_COUNT: 'span_count',
-	DURATION: 'duration',
-} as const satisfies Record<string, WaterfallAggregationType>;
+	EXEC_TIME_PCT: SpantypesSpanAggregationTypeDTO.execution_time_percentage,
+	SPAN_COUNT: SpantypesSpanAggregationTypeDTO.span_count,
+	DURATION: SpantypesSpanAggregationTypeDTO.duration,
+} as const;
 
 export function getAggregationMap(
-	aggregations: WaterfallAggregationResponse[] | undefined,
-	type: WaterfallAggregationType,
+	aggregations: SpantypesSpanAggregationResultDTO[] | undefined,
+	type: SpantypesSpanAggregationTypeDTO,
 	fieldName: string,
-): Record<string, number> | undefined {
+): Record<string, number> | null | undefined {
 	return aggregations?.find(
 		(a) => a.aggregation === type && a.field.name === fieldName,
 	)?.value;

frontend/src/types/api/trace/getTraceV3.ts

@@ -1,26 +1,9 @@
-import { TelemetryFieldKey } from 'types/api/v5/queryRange';
-
-export type WaterfallAggregationType =
-	| 'span_count'
-	| 'execution_time_percentage'
-	| 'duration';
-
-export interface WaterfallAggregationRequest {
-	field: TelemetryFieldKey;
-	aggregation: WaterfallAggregationType;
-}
-
-export interface WaterfallAggregationResponse extends WaterfallAggregationRequest {
-	value: Record<string, number>;
-}
-
-export interface GetTraceV3PayloadProps {
+export interface GetTraceV4PayloadProps {
 	traceId: string;
 	selectedSpanId: string;
 	uncollapsedSpans: string[];
 	isSelectedSpanIDUnCollapsed: boolean;
 	limit?: number; // Optional limit for number of spans to fetch, default can be set in API
-	aggregations?: WaterfallAggregationRequest[];
 }
 
 export interface TraceDetailV3URLProps {
@@ -88,7 +71,7 @@ export interface SpanV3 {
 	trace_state: string;
 }
 
-export interface GetTraceV3SuccessResponse {
+export interface GetTraceV4SuccessResponse {
 	spans: SpanV3[];
 	hasMissingSpans: boolean;
 	uncollapsedSpans: string[];
@@ -98,5 +81,4 @@ export interface GetTraceV3SuccessResponse {
 	totalErrorSpansCount: number;
 	rootServiceName: string;
 	rootServiceEntryPoint: string;
-	aggregations?: WaterfallAggregationResponse[];
 }

pkg/querier/querier.go

@@ -86,11 +86,12 @@ func New(
 
 func (q *querier) QueryRange(ctx context.Context, orgID valuer.UUID, req *qbtypes.QueryRangeRequest) (*qbtypes.QueryRangeResponse, error) {
 
-	// Coerce the window to epoch milliseconds up front so every downstream
-	// consumer (TimeRange, narrowWindowByTraceID, step interval, etc.) can
-	// safely assume ms regardless of the resolution the caller sent.
-	req.Start = querybuilder.ToMilliSecs(req.Start)
-	req.End = querybuilder.ToMilliSecs(req.End)
+	// Normalize Start/End to ms. UnmarshalJSON covers HTTP requests; callers
+	// that build the request programmatically skip it, so this is the catch-all
+	// (idempotent for the already-normalized path).
+	if err := req.Normalize(); err != nil {
+		return nil, err
+	}
 
 	tmplVars := req.Variables
 	if tmplVars == nil {
@@ -427,10 +428,12 @@ func (q *querier) resolveMetricMetadata(ctx context.Context, queries []qbtypes.Q
 
 func (q *querier) QueryRawStream(ctx context.Context, orgID valuer.UUID, req *qbtypes.QueryRangeRequest, client *qbtypes.RawStream) {
 
-	// Coerce the window to epoch milliseconds up front (End may be 0 for the
-	// open-ended stream, which ToMilliSecs leaves untouched).
-	req.Start = querybuilder.ToMilliSecs(req.Start)
-	req.End = querybuilder.ToMilliSecs(req.End)
+	// Catch-all normalization for programmatic callers (see QueryRange). End is
+	// 0 here for the open-ended stream, which Normalize leaves untouched.
+	if err := req.Normalize(); err != nil {
+		client.Error <- err
+		return
+	}
 
 	event := &qbtypes.QBEvent{
 		Version:         "v5",

pkg/querybuilder/time.go

@@ -33,28 +33,6 @@ func ToNanoSecs(epoch uint64) uint64 {
 	return temp * uint64(math.Pow(10, float64(19-count)))
 }
 
-// ToMilliSecs takes an epoch whose resolution is inferred from its magnitude
-// (s/ms/µs/ns) and returns it in milliseconds. A millisecond epoch for the
-// current era has 13 digits (e.g. ~1.7e12 in 2026), so the value is scaled so
-// its digit-width matches: smaller values (seconds) are scaled up, larger ones
-// (micro/nanoseconds) are scaled down. Zero is returned unchanged.
-func ToMilliSecs(epoch uint64) uint64 {
-	if epoch == 0 {
-		return 0
-	}
-	temp := epoch
-	count := 0
-	for epoch != 0 {
-		epoch /= 10
-		count++
-	}
-	const msDigits = 13
-	if count < msDigits {
-		return temp * uint64(math.Pow(10, float64(msDigits-count)))
-	}
-	return temp / uint64(math.Pow(10, float64(count-msDigits)))
-}
-
 // TODO(srikanthccv): should these be rounded to nearest multiple of 60 instead of 5 if step > 60?
 // That would make graph look nice but "nice" but should be less important than the usefulness.
 func RecommendedStepInterval(start, end uint64) uint64 {

pkg/querybuilder/time_test.go

@@ -60,51 +60,3 @@ func TestToNanoSecs(t *testing.T) {
 		})
 	}
 }
-
-func TestToMilliSecs(t *testing.T) {
-	tests := []struct {
-		name     string
-		epoch    uint64
-		expected uint64
-	}{
-		{
-			name:     "10-digit Unix timestamp (seconds) - 2023-01-01 00:00:00 UTC",
-			epoch:    1672531200,    // seconds
-			expected: 1672531200000, // * 10^3
-		},
-		{
-			name:     "13-digit Unix timestamp (milliseconds) - already ms",
-			epoch:    1672531200000,
-			expected: 1672531200000, // unchanged
-		},
-		{
-			name:     "16-digit Unix timestamp (microseconds)",
-			epoch:    1672531200000000, // microseconds
-			expected: 1672531200000,    // / 10^3
-		},
-		{
-			name:     "19-digit Unix timestamp (nanoseconds)",
-			epoch:    1672531200000000000, // nanoseconds
-			expected: 1672531200000,       // / 10^6
-		},
-		{
-			name:     "Unix epoch start - zero is unchanged",
-			epoch:    0,
-			expected: 0,
-		},
-		{
-			name:     "Recent timestamp in seconds - 2024-05-25 12:00:00 UTC",
-			epoch:    1716638400,
-			expected: 1716638400000,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := ToMilliSecs(tt.epoch)
-			if result != tt.expected {
-				t.Errorf("ToMilliSecs(%d) = %d, want %d", tt.epoch, result, tt.expected)
-			}
-		})
-	}
-}

pkg/types/querybuildertypes/querybuildertypesv5/req.go

@@ -12,6 +12,13 @@ import (
 	"github.com/swaggest/jsonschema-go"
 )
 
+const (
+	// minEpochMs and maxEpochMs bound a plausible ms timestamp to
+	// 1990-01-01 .. 2100-01-01, used to reject malformed Start/End values.
+	minEpochMs uint64 = 631_152_000_000
+	maxEpochMs uint64 = 4_102_444_800_000
+)
+
 type QueryEnvelope struct {
 	// Type is the type of the query.
 	Type QueryType `json:"type"` // "builder_query" | "builder_formula" | "builder_sub_query" | "builder_join" | "promql" | "clickhouse_sql"
@@ -549,7 +556,23 @@ func (r *QueryRangeRequest) SkipFillGaps(name string) bool {
 	return false
 }
 
-// UnmarshalJSON implements custom JSON unmarshaling to disallow unknown fields.
+// Normalize coerces Start and End to epoch milliseconds, inferring the source
+// resolution (s/ms/µs/ns) from each value's magnitude, and rejects non-zero
+// values outside the plausible 1990-2100 range. Lets downstream consumers
+// assume ms regardless of what the caller sent.
+func (r *QueryRangeRequest) Normalize() error {
+	start, err := toMilliSecs(r.Start)
+	if err != nil {
+		return err
+	}
+	end, err := toMilliSecs(r.End)
+	if err != nil {
+		return err
+	}
+	r.Start, r.End = start, end
+	return nil
+}
+
 func (r *QueryRangeRequest) UnmarshalJSON(data []byte) error {
 	// Define a type alias to avoid infinite recursion
 	type Alias QueryRangeRequest
@@ -609,6 +632,11 @@ func (r *QueryRangeRequest) UnmarshalJSON(data []byte) error {
 	// Copy the decoded values back to the original struct
 	*r = QueryRangeRequest(temp)
 
+	// Coerce Start/End to ms (and validate) at decode time for HTTP requests.
+	if err := r.Normalize(); err != nil {
+		return err
+	}
+
 	return nil
 }
 
@@ -662,3 +690,24 @@ func (r *QueryRangeRequest) GetQueriesSupportingZeroDefault() map[string]bool {
 
 	return canDefaultZero
 }
+
+// toMilliSecs scales an epoch to milliseconds based on its magnitude: seconds are
+// scaled up, micro/nanoseconds down, milliseconds left as-is. Zero is returned
+// unchanged. A non-zero result outside 1990-2100 is rejected as malformed.
+func toMilliSecs(epoch uint64) (uint64, error) {
+	var ms uint64
+	switch {
+	case epoch < 1e12: // seconds
+		ms = epoch * 1_000
+	case epoch < 1e15: // milliseconds
+		ms = epoch
+	case epoch < 1e18: // microseconds
+		ms = epoch / 1_000
+	default: // nanoseconds
+		ms = epoch / 1_000_000
+	}
+	if epoch != 0 && (ms < minEpochMs || ms > maxEpochMs) {
+		return 0, errors.NewInvalidInputf(errors.CodeInvalidInput, "timestamp %d is outside the supported range (1990-2100)", epoch)
+	}
+	return ms, nil
+}

pkg/types/querybuildertypes/querybuildertypesv5/req_test.go

@@ -1903,3 +1903,70 @@ func TestQueryRangeRequest_StepIntervalForQuery(t *testing.T) {
 		})
 	}
 }
+
+func TestQueryRangeRequest_Normalize(t *testing.T) {
+	tests := []struct {
+		name      string
+		start     uint64
+		end       uint64
+		wantStart uint64
+		wantEnd   uint64
+		wantErr   bool
+	}{
+		{
+			name:      "seconds are scaled up to ms",
+			start:     1672531200,    // 2023-01-01 in seconds
+			end:       1716638400,    // 2024-05-25 in seconds
+			wantStart: 1672531200000, // * 10^3
+			wantEnd:   1716638400000,
+		},
+		{
+			name:      "milliseconds pass through unchanged",
+			start:     1672531200000,
+			end:       1716638400000,
+			wantStart: 1672531200000,
+			wantEnd:   1716638400000,
+		},
+		{
+			name:      "microseconds are scaled down to ms",
+			start:     1672531200000000, // µs
+			end:       1716638400000000,
+			wantStart: 1672531200000, // / 10^3
+			wantEnd:   1716638400000,
+		},
+		{
+			name:      "nanoseconds are scaled down to ms",
+			start:     1672531200000000000, // ns
+			end:       1716638400000000000,
+			wantStart: 1672531200000, // / 10^6
+			wantEnd:   1716638400000,
+		},
+		{
+			name:      "zero end (open-ended stream) is left untouched",
+			start:     1672531200000,
+			end:       0,
+			wantStart: 1672531200000,
+			wantEnd:   0,
+		},
+		{
+			name:    "out-of-range timestamp is rejected",
+			start:   5_000_000_000_000, // ~year 2128 in ms, beyond the 2100 bound
+			end:     5_000_000_000_000,
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			r := &QueryRangeRequest{Start: tt.start, End: tt.end}
+			err := r.Normalize()
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantStart, r.Start)
+			assert.Equal(t, tt.wantEnd, r.End)
+		})
+	}
+}