feat: integrate v4 waterfall

frontend/src/api/trace/getTraceAggregations.ts

@@ -0,0 +1,36 @@
+import axios from 'api';
+import { ErrorResponseHandlerV2 } from 'api/ErrorResponseHandlerV2';
+import { AxiosError } from 'axios';
+import { ErrorV2Resp, SuccessResponseV2 } from 'types/api';
+import {
+	TraceAggregationRequest,
+	TraceAggregationResponse,
+} from 'types/api/trace/getTraceAggregations';
+
+interface GetTraceAggregationsProps {
+	traceId: string;
+	aggregations: TraceAggregationRequest[];
+}
+
+const getTraceAggregations = async ({
+	traceId,
+	aggregations,
+}: GetTraceAggregationsProps): Promise<
+	SuccessResponseV2<TraceAggregationResponse[]>
+> => {
+	try {
+		const response = await axios.post(`/traces/${traceId}/aggregations`, {
+			aggregations,
+		});
+
+		return {
+			httpStatusCode: response.status,
+			data: response.data.data.aggregations,
+		};
+	} catch (error) {
+		ErrorResponseHandlerV2(error as AxiosError<ErrorV2Resp>);
+		throw error;
+	}
+};
+
+export default getTraceAggregations;

frontend/src/api/trace/getTraceV4.tsx

@@ -1,15 +1,15 @@
-import { ApiV3Instance as axios } from 'api';
+import { ApiV4Instance as axios } from 'api';
 import { omit } from 'lodash-es';
 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,21 +19,21 @@ 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 = {
+	const postData: GetTraceV4PayloadProps = {
 		...props,
 		uncollapsedSpans,
 		limit: 10000,
 	};
-	const response = await axios.post<GetTraceV3SuccessResponse>(
+	const response = await axios.post<GetTraceV4SuccessResponse>(
 		`/traces/${props.traceId}/waterfall`,
 		omit(postData, 'traceId'),
 	);
 
-	// V3 API wraps response in { status, data }
+	// API wraps response in { status, data }
 	const rawPayload = (response.data as any).data || response.data;
 
 	// Derive 'service.name' from resource for convenience — only derived field
@@ -43,7 +43,7 @@ const getTraceV3 = async (
 		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 +70,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,64 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import getTraceAggregations from 'api/trace/getTraceAggregations';
+import { ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from 'react-query';
+
+import useGetTraceAggregations from '../useGetTraceAggregations';
+
+jest.mock('api/trace/getTraceAggregations', () => ({
+	__esModule: true,
+	default: jest.fn().mockResolvedValue({ httpStatusCode: 200, data: [] }),
+}));
+
+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,37 @@
+import { useQuery, UseQueryResult } from 'react-query';
+import getTraceAggregations from 'api/trace/getTraceAggregations';
+import { REACT_QUERY_KEY } from 'constants/reactQueryKeys';
+import { SuccessResponseV2 } from 'types/api';
+import {
+	TraceAggregationRequest,
+	TraceAggregationResponse,
+} from 'types/api/trace/getTraceAggregations';
+
+interface UseGetTraceAggregationsProps {
+	traceId: string;
+	aggregations: TraceAggregationRequest[];
+	enabled: boolean;
+}
+
+type UseGetTraceAggregations = UseQueryResult<
+	SuccessResponseV2<TraceAggregationResponse[]>
+>;
+
+/**
+ * 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, 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,15 +1,21 @@
 import { useMemo } from 'react';
+import { useParams } from 'react-router-dom';
 import {
 	TabsContent,
 	TabsList,
 	TabsRoot,
 	TabsTrigger,
 } from '@signozhq/ui/tabs';
+import { Typography } from '@signozhq/ui/typography';
 import cx from 'classnames';
 import { DetailsHeader } from 'components/DetailsPanel';
+import Spinner from 'components/Spinner';
 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 { TraceAggregationRequest } from 'types/api/trace/getTraceAggregations';
+import { TraceDetailV3URLProps } from 'types/api/trace/getTraceV3';
 
 import { useTraceStore } from '../../stores/traceStore';
 import {
@@ -35,10 +41,29 @@ 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<TraceAggregationRequest[]>(
+		() => [
+			{ field: colorByField, aggregation: AGGREGATIONS.EXEC_TIME_PCT },
+			{ field: colorByField, aggregation: AGGREGATIONS.SPAN_COUNT },
+		],
+		[colorByField],
+	);
+
+	const { data, isLoading, isError } = useGetTraceAggregations({
+		traceId: traceId || '',
+		aggregations: aggregationsRequest,
+		enabled: isOpen,
+	});
+
+	const aggregations = data?.data;
+
 	const execTimePct = useMemo(
 		() =>
 			findAggregationMap(
@@ -93,6 +118,33 @@ function AnalyticsPanel({
 		return null;
 	}
 
+	// Loading / error / empty render inside the tab content so the tabs stay
+	// visible. Returns null when there are rows to show.
+	const renderState = (rowCount: number): JSX.Element | null => {
+		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 (rowCount === 0) {
+			return (
+				<div className={styles.state}>
+					<Typography.Text>No data for {colorByFieldName}</Typography.Text>
+				</div>
+			);
+		}
+		return null;
+	};
+
 	return (
 		<FloatingPanel
 			isOpen
@@ -132,65 +184,69 @@ 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)}%
+							{renderState(execTimeRows.length) ?? (
+								<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>
-									</>
-								))}
-							</div>
+											<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>
+							)}
 						</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}
+							{renderState(spanCountRows.length) ?? (
+								<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>
-									</>
-								))}
-							</div>
+											<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>
+							)}
 						</TabsContent>
 					</div>
 				</TabsRoot>

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

@@ -0,0 +1,142 @@
+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 = {
+	httpStatusCode: 200,
+	data: [
+		{
+			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: { httpStatusCode: 200, data: [] },
+			isLoading: false,
+			isError: false,
+		});
+		renderPanel();
+		expect(screen.getByText(/no data for service.name/i)).toBeInTheDocument();
+	});
+});

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,17 +1,17 @@
 import {
-	WaterfallAggregationResponse,
-	WaterfallAggregationType,
-} from 'types/api/trace/getTraceV3';
+	TraceAggregationResponse,
+	TraceAggregationType,
+} from 'types/api/trace/getTraceAggregations';
 
 export const AGGREGATIONS = {
 	EXEC_TIME_PCT: 'execution_time_percentage',
 	SPAN_COUNT: 'span_count',
 	DURATION: 'duration',
-} as const satisfies Record<string, WaterfallAggregationType>;
+} as const satisfies Record<string, TraceAggregationType>;
 
 export function getAggregationMap(
-	aggregations: WaterfallAggregationResponse[] | undefined,
-	type: WaterfallAggregationType,
+	aggregations: TraceAggregationResponse[] | undefined,
+	type: TraceAggregationType,
 	fieldName: string,
 ): Record<string, number> | undefined {
 	return aggregations?.find(

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

@@ -0,0 +1,15 @@
+import { TelemetryFieldKey } from 'types/api/v5/queryRange';
+
+export type TraceAggregationType =
+	| 'span_count'
+	| 'execution_time_percentage'
+	| 'duration';
+
+export interface TraceAggregationRequest {
+	field: TelemetryFieldKey;
+	aggregation: TraceAggregationType;
+}
+
+export interface TraceAggregationResponse extends TraceAggregationRequest {
+	value: Record<string, number>;
+}

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[];
 }