Merge remote-tracking branch 'origin/main' into test/qb-e2e

# Conflicts:
#	tests/e2e/helpers/alert-forms/shared.ts
#	tests/e2e/helpers/alerts/seeding.ts

.github/CODEOWNERS

@@ -302,3 +302,8 @@ go.mod @therealpandey
 /frontend/.storybook/ @H4ad
 /frontend/src/storybook/ @H4ad
 /.claude/skills/signoz-page-story/ @H4ad
+
+## AI Assistant
+/frontend/src/container/AIAssistant/ @SigNoz/nerve @SigNoz/frontend-maintainers
+/frontend/src/hooks/aiAssistant/ @SigNoz/nerve @SigNoz/frontend-maintainers
+/frontend/src/pages/AIAssistantPage/ @SigNoz/nerve @SigNoz/frontend-maintainers

frontend/.storybook/preview.tsx

@@ -143,7 +143,12 @@ const preview: Preview = {
 						'Logs',
 						['Explorer', 'Live Tail', 'Pipelines', 'Settings'],
 						'Traces',
-						['Explorer', 'Trace Details', 'Funnel Details'],
+						[
+							'Explorer',
+							['Overview', 'Span Drawer'],
+							'Trace Details',
+							'Funnel Details',
+						],
 						'Metrics',
 						['Explorer'],
 						'Infrastructure',

frontend/src/components/DetailsPanel/DetailsPanelDrawer.module.scss

@@ -0,0 +1,17 @@
+.drawer {
+	overflow: hidden;
+	border-color: var(--l2-border);
+	background: var(--l2-background);
+	box-shadow: -4px 10px 16px 2px var(--l1-shadow);
+
+	&:focus,
+	&:focus-visible {
+		outline: none;
+	}
+}
+
+.body {
+	display: flex;
+	flex-direction: column;
+	height: 100%;
+}

frontend/src/components/DetailsPanel/DetailsPanelDrawer.styles.scss

@@ -1,7 +0,0 @@
-.details-panel-drawer {
-	&__body {
-		display: flex;
-		flex-direction: column;
-		height: 100%;
-	}
-}

frontend/src/components/DetailsPanel/DetailsPanelDrawer.tsx

@@ -1,12 +1,15 @@
-import { DrawerWrapper } from '@signozhq/ui/drawer';
+import { Drawer, DrawerContent } from '@signozhq/ui/drawer';
+import cx from 'classnames';
+import { AnimatePresence } from 'motion/react';
 
-import './DetailsPanelDrawer.styles.scss';
+import styles from './DetailsPanelDrawer.module.scss';
 
 interface DetailsPanelDrawerProps {
 	isOpen: boolean;
 	onClose: () => void;
 	children: React.ReactNode;
 	className?: string;
+	testId?: string;
 }
 
 function DetailsPanelDrawer({
@@ -14,22 +17,41 @@ function DetailsPanelDrawer({
 	onClose,
 	children,
 	className,
+	testId,
 }: DetailsPanelDrawerProps): JSX.Element {
 	return (
-		<DrawerWrapper
+		<Drawer
 			open={isOpen}
 			onOpenChange={(open): void => {
 				if (!open) {
 					onClose();
 				}
 			}}
-			direction="right"
-			showOverlay={false}
-			className={`details-panel-drawer ${className || ''}`}
+			modal={false}
 		>
-			<div className="details-panel-drawer__body">{children}</div>
-		</DrawerWrapper>
+			<AnimatePresence>
+				{isOpen && (
+					<DrawerContent
+						forceMount
+						direction="right"
+						width="extra-wide"
+						showOverlay={false}
+						// Outside presses are left to the page, which knows what counts as inside.
+						onInteractOutside={(e): void => e.preventDefault()}
+						className={cx(styles.drawer, className)}
+						testId={testId}
+					>
+						<div className={styles.body}>{children}</div>
+					</DrawerContent>
+				)}
+			</AnimatePresence>
+		</Drawer>
 	);
 }
 
+DetailsPanelDrawer.defaultProps = {
+	className: undefined,
+	testId: undefined,
+};
+
 export default DetailsPanelDrawer;

frontend/src/components/TanStackTableView/useRowNavigation.ts

@@ -0,0 +1,38 @@
+import { useCallback } from 'react';
+
+export type UseRowNavigationParams<TData> = {
+	rows: TData[];
+	activeIndex: number;
+	onNavigate: (row: TData, index: number) => void;
+};
+
+export type UseRowNavigationResult = {
+	goToPrev: () => void;
+	goToNext: () => void;
+	isPrevDisabled: boolean;
+	isNextDisabled: boolean;
+};
+
+/** Steps the active row through the loaded rows; stops at either end. */
+export function useRowNavigation<TData>({
+	rows,
+	activeIndex,
+	onNavigate,
+}: UseRowNavigationParams<TData>): UseRowNavigationResult {
+	const isPrevDisabled = activeIndex <= 0;
+	const isNextDisabled = activeIndex < 0 || activeIndex >= rows.length - 1;
+
+	const goToPrev = useCallback((): void => {
+		if (!isPrevDisabled) {
+			onNavigate(rows[activeIndex - 1], activeIndex - 1);
+		}
+	}, [isPrevDisabled, onNavigate, rows, activeIndex]);
+
+	const goToNext = useCallback((): void => {
+		if (!isNextDisabled) {
+			onNavigate(rows[activeIndex + 1], activeIndex + 1);
+		}
+	}, [isNextDisabled, onNavigate, rows, activeIndex]);
+
+	return { goToPrev, goToNext, isPrevDisabled, isNextDisabled };
+}

frontend/src/constants/localStorage.ts

@@ -46,4 +46,5 @@ export enum LOCALSTORAGE {
 	DASHBOARDS_LIST_VIEWS = 'DASHBOARDS_LIST_VIEWS',
 	DASHBOARD_V2_PANEL_COLUMN_WIDTHS = 'DASHBOARD_V2_PANEL_COLUMN_WIDTHS',
 	LLM_ATTRIBUTE_MAPPING_TEST_SPAN = 'LLM_ATTRIBUTE_MAPPING_TEST_SPAN',
+	TRACES_SPAN_DRAWER_ENABLED = 'TRACES_SPAN_DRAWER_ENABLED',
 }

frontend/src/container/TracesExplorer/ListView/ListView.module.scss

@@ -6,3 +6,7 @@
 	height: calc(100vh - 240px);
 	min-height: 400px;
 }
+
+.drawerScope {
+	display: contents;
+}

frontend/src/container/TracesExplorer/ListView/__tests__/SpanDrawerNavigation.test.tsx

@@ -0,0 +1,113 @@
+import remove from 'api/browser/localstorage/remove';
+import set from 'api/browser/localstorage/set';
+import { LOCALSTORAGE } from 'constants/localStorage';
+import { server } from 'mocks-server/server';
+import { screen, userEvent, waitFor, within } from 'tests/test-utils';
+import { mockSuccess, mockTraceSummary, renderListView } from './testUtils';
+
+// globalTime starts with loading:true, which gates the list query. Force just that
+// slice's loading to false so the query fires; every other selector is untouched.
+jest.mock('react-redux', () => {
+	const actual = jest.requireActual('react-redux');
+	return {
+		...actual,
+		useSelector: (selector: (state: unknown) => unknown): unknown => {
+			const result = actual.useSelector(selector);
+			if (result && typeof result === 'object' && 'loading' in result) {
+				return { ...result, loading: false };
+			}
+			return result;
+		},
+	};
+});
+
+// List columns come from the options menu (server-synced preferences). Pin them
+// so the expected columns render, independent of that API.
+jest.mock('container/OptionsMenu/useOptionsMenu', () => ({
+	__esModule: true,
+	default: (): unknown => ({
+		options: {
+			selectColumns: [
+				{ name: 'service.name', fieldContext: 'resource' },
+				{ name: 'name', fieldContext: 'span' },
+				{ name: 'duration_nano', fieldContext: 'span' },
+				{ name: 'http_method', fieldContext: 'span' },
+				{ name: 'response_status_code', fieldContext: 'span' },
+				{ name: 'http.route', fieldContext: 'attribute' },
+				{ name: 'cache.hit', fieldContext: 'attribute' },
+			],
+		},
+		config: { addColumn: { onRemove: jest.fn() } },
+	}),
+}));
+
+describe('Traces ListView - span drawer navigation', () => {
+	beforeEach(() => {
+		set(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED, 'true');
+		mockSuccess();
+		mockTraceSummary({});
+	});
+
+	afterEach(() => {
+		remove(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED);
+		server.resetHandlers();
+	});
+
+	it('opens the clicked span and steps through rows with the arrow keys', async () => {
+		const user = userEvent.setup();
+		renderListView();
+
+		await user.click(await screen.findByText('HTTP GET'));
+
+		const drawer = await screen.findByTestId('span-details-drawer');
+		expect(within(drawer).getByText('HTTP GET')).toBeInTheDocument();
+		expect(within(drawer).getByTestId('span-details-trace-id')).toHaveTextContent(
+			'0000000000000000344ded1387b08a7e',
+		);
+
+		await user.keyboard('{ArrowDown}');
+		await expect(
+			within(drawer).findByText('authenticate_check_db'),
+		).resolves.toBeInTheDocument();
+
+		await user.keyboard('{ArrowUp}');
+		await expect(
+			within(drawer).findByText('HTTP GET'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('closes the drawer', async () => {
+		const user = userEvent.setup();
+		renderListView();
+
+		await user.click(await screen.findByText('HTTP GET'));
+		await screen.findByTestId('span-details-drawer');
+
+		await user.click(screen.getByTestId('span-drawer-close'));
+
+		await waitFor(() =>
+			expect(screen.queryByTestId('span-details-drawer')).not.toBeInTheDocument(),
+		);
+	});
+
+	it('stays open on a press in the drawer or the list, and closes on one outside', async () => {
+		const user = userEvent.setup();
+		renderListView();
+
+		await user.click(await screen.findByText('HTTP GET'));
+		const drawer = await screen.findByTestId('span-details-drawer');
+
+		await user.click(drawer);
+		// Hovering re-renders the row, so the press needs a fresh query.
+		await user.hover(screen.getByText('authenticate_check_db'));
+		await user.click(screen.getByText('authenticate_check_db'));
+		await expect(
+			within(drawer).findByText('authenticate_check_db'),
+		).resolves.toBeInTheDocument();
+
+		await user.click(document.body);
+		await waitFor(() =>
+			expect(screen.queryByTestId('span-details-drawer')).not.toBeInTheDocument(),
+		);
+	});
+});

frontend/src/container/TracesExplorer/ListView/__tests__/SpanDrawerTraceBounds.test.tsx

@@ -0,0 +1,192 @@
+import remove from 'api/browser/localstorage/remove';
+import set from 'api/browser/localstorage/set';
+import { LOCALSTORAGE } from 'constants/localStorage';
+import { server } from 'mocks-server/server';
+import { rest } from 'msw';
+import { screen, userEvent, waitFor, within } from 'tests/test-utils';
+import { QueryRangeRequestV5 } from 'types/api/v5/queryRange';
+import {
+	FIVE_MINUTES_IN_MS,
+	listResponse,
+	listRows,
+	mockSuccess,
+	mockTraceSummary,
+	QUERY_RANGE_URL,
+	renderListView,
+	TraceBounds,
+} from './testUtils';
+
+// globalTime starts with loading:true, which gates the list query. Force just that
+// slice's loading to false so the query fires; every other selector is untouched.
+jest.mock('react-redux', () => {
+	const actual = jest.requireActual('react-redux');
+	return {
+		...actual,
+		useSelector: (selector: (state: unknown) => unknown): unknown => {
+			const result = actual.useSelector(selector);
+			if (result && typeof result === 'object' && 'loading' in result) {
+				return { ...result, loading: false };
+			}
+			return result;
+		},
+	};
+});
+
+// List columns come from the options menu (server-synced preferences). Pin them
+// so the expected columns render, independent of that API.
+jest.mock('container/OptionsMenu/useOptionsMenu', () => ({
+	__esModule: true,
+	default: (): unknown => ({
+		options: {
+			selectColumns: [
+				{ name: 'service.name', fieldContext: 'resource' },
+				{ name: 'name', fieldContext: 'span' },
+				{ name: 'duration_nano', fieldContext: 'span' },
+				{ name: 'http_method', fieldContext: 'span' },
+				{ name: 'response_status_code', fieldContext: 'span' },
+				{ name: 'http.route', fieldContext: 'attribute' },
+				{ name: 'cache.hit', fieldContext: 'attribute' },
+			],
+		},
+		config: { addColumn: { onRemove: jest.fn() } },
+	}),
+}));
+
+describe('Traces ListView - span drawer trace bounds', () => {
+	beforeEach(() => {
+		set(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED, 'true');
+		mockSuccess();
+		mockTraceSummary({});
+	});
+
+	afterEach(() => {
+		remove(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED);
+		server.resetHandlers();
+	});
+
+	it('requests span logs over whole milliseconds', async () => {
+		const logsRequests: QueryRangeRequestV5[] = [];
+		server.use(
+			rest.post(QUERY_RANGE_URL, async (req, res, ctx) => {
+				const body = await req.json<QueryRangeRequestV5>();
+				const spec = body.compositeQuery.queries[0]?.spec;
+				if (spec && 'signal' in spec && spec.signal === 'logs') {
+					logsRequests.push(body);
+					// No logs, so no context queries follow to outlive the test.
+					return res(ctx.status(200), ctx.json(listResponse([])));
+				}
+				return res(ctx.status(200), ctx.json(listResponse(listRows)));
+			}),
+		);
+		const user = userEvent.setup();
+		renderListView();
+
+		// Its 790.94939 ms duration makes the span window end mid-millisecond.
+		await user.click(await screen.findByText('authenticate_check_db'));
+
+		await waitFor(() => expect(logsRequests.length).toBeGreaterThan(0));
+		logsRequests.forEach(({ start, end }) => {
+			expect(Number.isInteger(start)).toBe(true);
+			expect(Number.isInteger(end)).toBe(true);
+		});
+	});
+
+	it('reads the trace bounds from the trace summary', async () => {
+		const bounds: TraceBounds = {
+			'0000000000000000344ded1387b08a7e': {
+				start: Date.parse('2024-07-19T08:39:58.700Z'),
+				end: Date.parse('2024-07-19T08:39:58.900Z'),
+			},
+			a364a8e15af3e9a8c866e0528db8b637: {
+				start: Date.parse('2024-07-19T08:39:59.900Z'),
+				end: Date.parse('2024-07-19T08:40:01.000Z'),
+			},
+		};
+		mockTraceSummary(bounds);
+		const logsRequests: {
+			traceId: string;
+			isTraceWide: boolean;
+			start: number;
+			end: number;
+		}[] = [];
+		server.use(
+			rest.post(QUERY_RANGE_URL, async (req, res, ctx) => {
+				const body = await req.json<QueryRangeRequestV5>();
+				const spec = body.compositeQuery.queries[0]?.spec;
+				if (spec && 'signal' in spec && spec.signal === 'logs') {
+					const traceId =
+						Object.keys(bounds).find((id) => spec.filter?.expression?.includes(id)) ??
+						'';
+					// The payload carries the window in µs.
+					logsRequests.push({
+						traceId,
+						isTraceWide: !spec.filter?.expression?.includes('span_id'),
+						start: body.start / 1e3,
+						end: body.end / 1e3,
+					});
+					return res(ctx.status(200), ctx.json(listResponse([])));
+				}
+				return res(ctx.status(200), ctx.json(listResponse(listRows)));
+			}),
+		);
+		const user = userEvent.setup();
+		renderListView();
+
+		await user.click(await screen.findByText('HTTP GET'));
+		const drawer = await screen.findByTestId('span-details-drawer');
+		await expect(
+			within(drawer).findByText(/of total exec time/),
+		).resolves.toBeInTheDocument();
+
+		// The next span is in another trace, so it needs that trace's bounds.
+		// Both its span logs and its trace-wide check must land before the test ends.
+		await user.keyboard('{ArrowDown}');
+		await waitFor(() =>
+			expect(
+				logsRequests
+					.filter(({ traceId }) => traceId === 'a364a8e15af3e9a8c866e0528db8b637')
+					.map(({ isTraceWide }) => isTraceWide),
+			).toStrictEqual(expect.arrayContaining([false, true])),
+		);
+
+		// Logs wait for the bounds: no request ever goes out with another window.
+		logsRequests.forEach(({ traceId, start, end }) => {
+			expect(start).toBe(bounds[traceId].start - FIVE_MINUTES_IN_MS);
+			expect(end).toBe(bounds[traceId].end + FIVE_MINUTES_IN_MS);
+		});
+	});
+
+	it('speaks only for the span when the trace has no summary', async () => {
+		const logsFilters: string[] = [];
+		server.use(
+			rest.post(QUERY_RANGE_URL, async (req, res, ctx) => {
+				const body = await req.json<QueryRangeRequestV5>();
+				const spec = body.compositeQuery.queries[0]?.spec;
+				if (spec && 'signal' in spec && spec.signal === 'logs') {
+					logsFilters.push(spec.filter?.expression ?? '');
+					return res(ctx.status(200), ctx.json(listResponse([])));
+				}
+				return res(ctx.status(200), ctx.json(listResponse(listRows)));
+			}),
+		);
+		const user = userEvent.setup();
+		renderListView();
+
+		await user.click(await screen.findByText('HTTP GET'));
+		const drawer = await screen.findByTestId('span-details-drawer');
+
+		await user.click(within(drawer).getByRole('tab', { name: /logs/i }));
+		await expect(
+			within(drawer).findByText('No logs found for this span.'),
+		).resolves.toBeInTheDocument();
+		// Checked once the 404 has settled; before it, exec time is absent anyway.
+		expect(
+			within(drawer).queryByText(/of total exec time/),
+		).not.toBeInTheDocument();
+		// No trace-wide check: every logs request is scoped to the span.
+		expect(logsFilters.length).toBeGreaterThan(0);
+		logsFilters.forEach((expression) => {
+			expect(expression).toContain('span_id');
+		});
+	});
+});

frontend/src/container/TracesExplorer/ListView/__tests__/testUtils.tsx

@@ -0,0 +1,110 @@
+import { ENVIRONMENT } from 'constants/env';
+import { initialQueriesMap, PANEL_TYPES } from 'constants/queryBuilder';
+import { server } from 'mocks-server/server';
+import { rest } from 'msw';
+import { VirtuosoMockContext } from 'react-virtuoso';
+import { render } from 'tests/test-utils';
+import { Query } from 'types/api/queryBuilder/queryBuilderData';
+
+import ListView from '../index';
+
+const BASE_URL = ENVIRONMENT.baseURL;
+export const QUERY_RANGE_URL = `${BASE_URL}/api/v5/query_range`;
+
+export const listRows = [
+	{
+		timestamp: '2024-07-19T08:39:58.735245Z',
+		data: {
+			name: 'HTTP GET',
+			duration_nano: 55306000,
+			http_method: 'GET',
+			response_status_code: '200',
+			span_id: '772c4d29dd9076ac',
+			trace_id: '0000000000000000344ded1387b08a7e',
+			attributes: { 'http.route': '/api/cart', 'cache.hit': false },
+			resource: { 'service.name': 'frontend' },
+		},
+	},
+	{
+		timestamp: '2024-07-19T08:39:59.949129915Z',
+		data: {
+			name: 'authenticate_check_db',
+			duration_nano: 790949390,
+			// empty status fields to assert the "-" cell
+			http_method: '',
+			response_status_code: '',
+			span_id: '5704353737b6778e',
+			trace_id: 'a364a8e15af3e9a8c866e0528db8b637',
+			attributes: {},
+			resource: { 'service.name': 'demo-app' },
+		},
+	},
+];
+
+export const listResponse = (rows: unknown[]): Record<string, unknown> => ({
+	data: { type: 'raw', data: { results: [{ queryName: 'A', rows }] } },
+});
+
+export const TRACE_SUMMARY_URL = `${BASE_URL}/api/v1/traces/:traceId/summary`;
+export const FIVE_MINUTES_IN_MS = 5 * 60 * 1000;
+
+export type TraceBounds = Record<string, { start: number; end: number }>;
+
+// Traces missing from `bounds` get a 404, like a trace with no summary row.
+export const mockTraceSummary = (bounds: TraceBounds): void => {
+	server.use(
+		rest.get(TRACE_SUMMARY_URL, (req, res, ctx) => {
+			const traceBounds = bounds[req.params.traceId as string];
+			if (!traceBounds) {
+				return res(ctx.status(404), ctx.json({ status: 'error' }));
+			}
+			return res(
+				ctx.status(200),
+				ctx.json({
+					status: 'success',
+					data: {
+						startTimestampMillis: traceBounds.start,
+						endTimestampMillis: traceBounds.end,
+						hasMissingSpans: false,
+						rootServiceEntryPoint: '',
+						rootServiceName: '',
+						rootSpanStatusCode: '',
+						totalErrorSpansCount: 0,
+						totalSpansCount: 1,
+					},
+				}),
+			);
+		}),
+	);
+};
+
+export const mockSuccess = (rows: unknown[] = listRows): void => {
+	server.use(
+		rest.post(QUERY_RANGE_URL, (_req, res, ctx) =>
+			res(ctx.status(200), ctx.json(listResponse(rows))),
+		),
+	);
+};
+
+export const renderListView = (
+	stagedQuery: Query = initialQueriesMap.traces,
+): ReturnType<typeof render> =>
+	render(
+		<VirtuosoMockContext.Provider value={{ viewportHeight: 500, itemHeight: 54 }}>
+			<ListView
+				isFilterApplied={false}
+				setWarning={jest.fn()}
+				setIsLoadingQueries={jest.fn()}
+			/>
+		</VirtuosoMockContext.Provider>,
+		{},
+		{
+			initialRoute: '/traces-explorer',
+			queryBuilderOverrides: {
+				panelType: PANEL_TYPES.LIST,
+				stagedQuery,
+				currentQuery: stagedQuery,
+				redirectWithQueryBuilderData: jest.fn(),
+			} as any,
+		},
+	);

frontend/src/container/TracesExplorer/ListView/index.data.test.tsx

@@ -1,17 +1,20 @@
-import { ENVIRONMENT } from 'constants/env';
 import {
 	initialQueriesMap,
 	initialQueryBuilderFormTraceOperatorValues,
-	PANEL_TYPES,
 } from 'constants/queryBuilder';
 import { server } from 'mocks-server/server';
 import { rest } from 'msw';
-import { VirtuosoMockContext } from 'react-virtuoso';
-import { render, screen } from 'tests/test-utils';
+import { screen } from 'tests/test-utils';
 import { Query } from 'types/api/queryBuilder/queryBuilderData';
 import { QueryRangeRequestV5 } from 'types/api/v5/queryRange';
 
-import ListView from './index';
+import {
+	listResponse,
+	listRows,
+	mockSuccess,
+	QUERY_RANGE_URL,
+	renderListView,
+} from './__tests__/testUtils';
 
 // globalTime starts with loading:true, which gates the list query. Force just that
 // slice's loading to false so the query fires; every other selector is untouched.
@@ -49,74 +52,6 @@ jest.mock('container/OptionsMenu/useOptionsMenu', () => ({
 	}),
 }));
 
-const BASE_URL = ENVIRONMENT.baseURL;
-const QUERY_RANGE_URL = `${BASE_URL}/api/v5/query_range`;
-
-const listRows = [
-	{
-		timestamp: '2024-07-19T08:39:58.735245Z',
-		data: {
-			name: 'HTTP GET',
-			duration_nano: 55306000,
-			http_method: 'GET',
-			response_status_code: '200',
-			span_id: '772c4d29dd9076ac',
-			trace_id: '0000000000000000344ded1387b08a7e',
-			attributes: { 'http.route': '/api/cart', 'cache.hit': false },
-			resource: { 'service.name': 'frontend' },
-		},
-	},
-	{
-		timestamp: '2024-07-19T08:39:59.949129915Z',
-		data: {
-			name: 'authenticate_check_db',
-			duration_nano: 790949390,
-			// empty status fields to assert the "-" cell
-			http_method: '',
-			response_status_code: '',
-			span_id: '5704353737b6778e',
-			trace_id: 'a364a8e15af3e9a8c866e0528db8b637',
-			attributes: {},
-			resource: { 'service.name': 'demo-app' },
-		},
-	},
-];
-
-const listResponse = (rows: unknown[]): Record<string, unknown> => ({
-	data: { type: 'raw', data: { results: [{ queryName: 'A', rows }] } },
-});
-
-const mockSuccess = (rows: unknown[] = listRows): void => {
-	server.use(
-		rest.post(QUERY_RANGE_URL, (_req, res, ctx) =>
-			res(ctx.status(200), ctx.json(listResponse(rows))),
-		),
-	);
-};
-
-const renderListView = (
-	stagedQuery: Query = initialQueriesMap.traces,
-): ReturnType<typeof render> =>
-	render(
-		<VirtuosoMockContext.Provider value={{ viewportHeight: 500, itemHeight: 54 }}>
-			<ListView
-				isFilterApplied={false}
-				setWarning={jest.fn()}
-				setIsLoadingQueries={jest.fn()}
-			/>
-		</VirtuosoMockContext.Provider>,
-		{},
-		{
-			initialRoute: '/traces-explorer',
-			queryBuilderOverrides: {
-				panelType: PANEL_TYPES.LIST,
-				stagedQuery,
-				currentQuery: stagedQuery,
-				redirectWithQueryBuilderData: jest.fn(),
-			} as any,
-		},
-	);
-
 describe('Traces ListView - Data Loaded', () => {
 	afterEach(() => {
 		server.resetHandlers();

frontend/src/container/TracesExplorer/ListView/index.tsx

@@ -29,6 +29,8 @@ import { useOptionsMenu } from 'container/OptionsMenu';
 import { CustomTimeType } from 'container/TopNav/DateTimeSelectionV2/types';
 import TraceExplorerControls from 'container/TracesExplorer/Controls';
 import { getListViewQuery } from 'container/TracesExplorer/explorerUtils';
+import SpanDrawer from 'container/TracesExplorer/SpanDrawer/SpanDrawer';
+import { useSpanDrawer } from 'container/TracesExplorer/SpanDrawer/useSpanDrawer';
 import { useGetQueryRange } from 'hooks/queryBuilder/useGetQueryRange';
 import { useQueryBuilder } from 'hooks/queryBuilder/useQueryBuilder';
 import { Pagination } from 'hooks/queryPagination';
@@ -202,6 +204,8 @@ function ListView({
 		[queryTableData],
 	);
 
+	const { tableProps, drawerProps, onPressInside } = useSpanDrawer(rows);
+
 	const handleColumnOrderChange = useCallback(
 		(cols: TableColumnDef<TracesTableRow>[]): void => {
 			config?.addColumn?.onReorder(cols.map((c) => c.id));
@@ -253,20 +257,26 @@ function ListView({
 				/>
 			</div>
 
-			<TracesTable
-				data={rows}
-				columns={columns}
-				columnStorageKey={LOCALSTORAGE.TRACES_LIST_COLUMNS}
-				panelType="LIST"
-				getRowHref={getTraceLink}
-				isLoading={isLoading}
-				isFetching={isFetching}
-				isError={isError}
-				error={error}
-				isFilterApplied={isFilterApplied}
-				onColumnOrderChange={handleColumnOrderChange}
-				onColumnRemove={config?.addColumn?.onRemove}
-			/>
+			{/* A press in the table or the drawer (a portal) keeps the drawer open. */}
+			<div className={styles.drawerScope} onPointerDownCapture={onPressInside}>
+				<TracesTable
+					data={rows}
+					columns={columns}
+					columnStorageKey={LOCALSTORAGE.TRACES_LIST_COLUMNS}
+					panelType="LIST"
+					getRowHref={getTraceLink}
+					{...tableProps}
+					isLoading={isLoading}
+					isFetching={isFetching}
+					isError={isError}
+					error={error}
+					isFilterApplied={isFilterApplied}
+					onColumnOrderChange={handleColumnOrderChange}
+					onColumnRemove={config?.addColumn?.onRemove}
+				/>
+
+				{drawerProps && <SpanDrawer {...drawerProps} />}
+			</div>
 		</div>
 	);
 }

frontend/src/container/TracesExplorer/SpanDrawer/SpanDrawer.tsx

@@ -0,0 +1,112 @@
+import { useMemo } from 'react';
+import { Button } from '@signozhq/ui/button';
+import { ButtonGroup } from '@signozhq/ui/button-group';
+import { ChevronDown, ChevronUp, CornerUpRight } from '@signozhq/icons';
+import { useGetTraceSummary } from 'api/generated/services/tracedetail';
+import { HeaderAction } from 'components/DetailsPanel';
+import type { UseRowNavigationResult } from 'components/TanStackTableView/useRowNavigation';
+import { getTraceLink } from 'container/TracesExplorer/ListView/utils';
+import { TracesTableRow } from 'container/TracesExplorer/TracesTable/getFieldColumn';
+import { SpanDetailVariant } from 'pages/TraceDetailsV3/SpanDetailsPanel/constants';
+import SpanDetailsPanel from 'pages/TraceDetailsV3/SpanDetailsPanel/SpanDetailsPanel';
+import { openInNewTab } from 'utils/navigation';
+
+import { useArrowKeyNavigation } from './useArrowKeyNavigation';
+import { toSpanV3 } from './utils';
+
+export type SpanDrawerProps = {
+	row: TracesTableRow | null;
+	onClose: () => void;
+	navigation: UseRowNavigationResult;
+};
+
+function SpanDrawer({
+	row,
+	onClose,
+	navigation,
+}: SpanDrawerProps): JSX.Element {
+	const { goToPrev, goToNext, isPrevDisabled, isNextDisabled } = navigation;
+	const isOpen = row !== null;
+
+	useArrowKeyNavigation({ enabled: isOpen, onPrev: goToPrev, onNext: goToNext });
+
+	const panelState = useMemo(
+		() => ({ isOpen, open: (): void => {}, close: onClose }),
+		[isOpen, onClose],
+	);
+
+	const headerActions = useMemo((): HeaderAction[] => {
+		if (!row) {
+			return [];
+		}
+		return [
+			{
+				key: 'view-full-trace',
+				component: (
+					<Button
+						variant="outlined"
+						color="secondary"
+						size="md"
+						prefix={<CornerUpRight />}
+						onClick={(): void => openInNewTab(getTraceLink(row))}
+						testId="span-drawer-view-full-trace"
+					>
+						View full trace
+					</Button>
+				),
+			},
+			{
+				key: 'nav',
+				component: (
+					<ButtonGroup
+						variant="outlined"
+						color="secondary"
+						size="md"
+						testId="span-drawer-nav"
+						items={[
+							{
+								value: 'prev',
+								icon: <ChevronUp />,
+								ariaLabel: 'Previous span',
+								onClick: goToPrev,
+								disabled: isPrevDisabled,
+								disabledTooltip: 'No previous span on this page',
+							},
+							{
+								value: 'next',
+								icon: <ChevronDown />,
+								ariaLabel: 'Next span',
+								onClick: goToNext,
+								disabled: isNextDisabled,
+								disabledTooltip: 'No next span on this page',
+							},
+						]}
+					/>
+				),
+			},
+		];
+	}, [row, goToPrev, goToNext, isPrevDisabled, isNextDisabled]);
+
+	const span = useMemo(() => (row ? toSpanV3(row) : undefined), [row]);
+
+	const traceId = span?.trace_id ?? '';
+	const { data: traceSummary, isLoading: isTraceBoundsLoading } =
+		useGetTraceSummary(
+			{ traceID: traceId },
+			{ query: { enabled: !!traceId, retry: false } },
+		);
+
+	return (
+		<SpanDetailsPanel
+			panelState={panelState}
+			selectedSpan={span}
+			variant={SpanDetailVariant.DRAWER}
+			headerActions={headerActions}
+			traceStartTime={traceSummary?.data?.startTimestampMillis}
+			traceEndTime={traceSummary?.data?.endTimestampMillis}
+			isTraceBoundsLoading={isTraceBoundsLoading}
+		/>
+	);
+}
+
+export default SpanDrawer;

frontend/src/container/TracesExplorer/SpanDrawer/__tests__/useArrowKeyNavigation.test.ts

@@ -0,0 +1,39 @@
+import { renderHook } from 'tests/test-utils';
+
+import { useArrowKeyNavigation } from '../useArrowKeyNavigation';
+
+const pressArrowDown = ({ handled }: { handled: boolean }): void => {
+	const event = new KeyboardEvent('keydown', {
+		key: 'ArrowDown',
+		bubbles: true,
+		cancelable: true,
+	});
+	if (handled) {
+		event.preventDefault();
+	}
+	document.body.dispatchEvent(event);
+};
+
+describe('useArrowKeyNavigation', () => {
+	it('steps to the next span on ArrowDown', () => {
+		const onNext = jest.fn() as jest.MockedFunction<() => void>;
+		renderHook(() =>
+			useArrowKeyNavigation({ enabled: true, onPrev: jest.fn(), onNext }),
+		);
+
+		pressArrowDown({ handled: false });
+
+		expect(onNext).toHaveBeenCalledTimes(1);
+	});
+
+	it('ignores a key that a focused menu already handled', () => {
+		const onNext = jest.fn() as jest.MockedFunction<() => void>;
+		renderHook(() =>
+			useArrowKeyNavigation({ enabled: true, onPrev: jest.fn(), onNext }),
+		);
+
+		pressArrowDown({ handled: true });
+
+		expect(onNext).not.toHaveBeenCalled();
+	});
+});

frontend/src/container/TracesExplorer/SpanDrawer/__tests__/useSpanDrawer.test.ts

@@ -0,0 +1,35 @@
+import { act, renderHook } from 'tests/test-utils';
+import remove from 'api/browser/localstorage/remove';
+import set from 'api/browser/localstorage/set';
+import { LOCALSTORAGE } from 'constants/localStorage';
+import { TracesTableRow } from 'container/TracesExplorer/TracesTable/getFieldColumn';
+
+import { useSpanDrawer } from '../useSpanDrawer';
+
+const rows: TracesTableRow[] = [{ id: 'span-a' }, { id: 'span-b' }];
+
+describe('useSpanDrawer', () => {
+	beforeEach(() => {
+		set(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED, 'true');
+	});
+
+	afterEach(() => {
+		remove(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED);
+	});
+
+	it('does not reopen a span that a refetch dropped and a later one brings back', () => {
+		const { result, rerender } = renderHook(
+			({ current }: { current: TracesTableRow[] }) => useSpanDrawer(current),
+			{ initialProps: { current: rows } },
+		);
+
+		act(() => result.current.tableProps.onRowClick?.(rows[1]));
+		expect(result.current.drawerProps?.row).toBe(rows[1]);
+
+		rerender({ current: [rows[0]] });
+		expect(result.current.drawerProps?.row).toBeNull();
+
+		rerender({ current: rows });
+		expect(result.current.drawerProps?.row).toBeNull();
+	});
+});

frontend/src/container/TracesExplorer/SpanDrawer/__tests__/utils.test.ts

@@ -0,0 +1,74 @@
+import { toSpanV3 } from '../utils';
+
+describe('toSpanV3', () => {
+	const row = {
+		id: '772c4d29dd9076ac',
+		span_id: '772c4d29dd9076ac',
+		timestamp: '2024-07-19T08:39:58.735Z',
+		resource: { 'service.name': 'frontend' },
+		events: [
+			{
+				name: 'exception',
+				timeUnixNano: 1721378398735000000,
+				attributes: { 'exception.type': 'Error' },
+			},
+		],
+		links: [{ traceId: 'a364a8e15af3e9a8', spanId: '5704353737b6778e' }],
+	};
+
+	it('reshapes a list row into the span the details panel reads', () => {
+		const span = toSpanV3(row);
+
+		expect(span.timestamp).toBe(Date.UTC(2024, 6, 19, 8, 39, 58, 735));
+		expect(span['service.name']).toBe('frontend');
+		expect(span.events).toStrictEqual([
+			{
+				name: 'exception',
+				timeUnixNano: 1721378398735000000,
+				attributeMap: { 'exception.type': 'Error' },
+				isError: false,
+			},
+		]);
+		expect((span as unknown as { references: unknown }).references).toStrictEqual(
+			row.links,
+		);
+	});
+
+	it('drops the parent from the linked spans', () => {
+		const link = { traceId: 'a364a8e15af3e9a8', spanId: '5704353737b6778e' };
+		const parent = { traceId: '1f2e3d4c5b6a7980', spanId: '0aa1bb2cc3dd4ee5' };
+		const span = toSpanV3({
+			...row,
+			trace_id: parent.traceId,
+			parent_span_id: parent.spanId,
+			links: [parent, link, { ...parent, traceId: link.traceId }],
+		});
+
+		expect((span as unknown as { references: unknown }).references).toStrictEqual(
+			[link, { ...parent, traceId: link.traceId }],
+		);
+	});
+
+	it('drops the empty parent ref of a root span', () => {
+		const span = toSpanV3({
+			...row,
+			trace_id: 'a364a8e15af3e9a8',
+			parent_span_id: '',
+			links: [{ traceId: 'a364a8e15af3e9a8' }],
+		});
+
+		expect((span as unknown as { references: unknown }).references).toStrictEqual(
+			[],
+		);
+	});
+
+	it('defaults missing events, links and service name', () => {
+		const span = toSpanV3({ id: 'x', timestamp: row.timestamp });
+
+		expect(span.events).toStrictEqual([]);
+		expect(span['service.name']).toBe('');
+		expect((span as unknown as { references: unknown }).references).toStrictEqual(
+			[],
+		);
+	});
+});

frontend/src/container/TracesExplorer/SpanDrawer/useArrowKeyNavigation.ts

@@ -0,0 +1,46 @@
+import { useEffect } from 'react';
+
+const EDITABLE_TARGET = 'input, textarea, [contenteditable="true"], .cm-editor';
+
+type UseArrowKeyNavigationParams = {
+	enabled: boolean;
+	onPrev: () => void;
+	onNext: () => void;
+};
+
+export function useArrowKeyNavigation({
+	enabled,
+	onPrev,
+	onNext,
+}: UseArrowKeyNavigationParams): void {
+	useEffect(() => {
+		if (!enabled) {
+			return undefined;
+		}
+
+		const handleKeyDown = (e: KeyboardEvent): void => {
+			// A focused menu or listbox already used the key.
+			if (e.defaultPrevented) {
+				return;
+			}
+			if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) {
+				return;
+			}
+			if (e.target instanceof Element && e.target.closest(EDITABLE_TARGET)) {
+				return;
+			}
+			if (e.key === 'ArrowUp') {
+				e.preventDefault();
+				onPrev();
+			} else if (e.key === 'ArrowDown') {
+				e.preventDefault();
+				onNext();
+			}
+		};
+
+		document.addEventListener('keydown', handleKeyDown);
+		return (): void => {
+			document.removeEventListener('keydown', handleKeyDown);
+		};
+	}, [enabled, onPrev, onNext]);
+}

frontend/src/container/TracesExplorer/SpanDrawer/useSpanDrawer.ts

@@ -0,0 +1,87 @@
+import { PointerEvent, useCallback, useEffect, useMemo, useState } from 'react';
+import { useRowNavigation } from 'components/TanStackTableView/useRowNavigation';
+import { TracesTableRow } from 'container/TracesExplorer/TracesTable/getFieldColumn';
+import type { TracesTableProps } from 'container/TracesExplorer/TracesTable/TracesTable';
+import { useCloseOnOutsidePress } from 'hooks/useCloseOnOutsidePress';
+
+import type { SpanDrawerProps } from './SpanDrawer';
+import { isSpanDrawerEnabled } from './utils';
+
+type ActiveSpan = { id: string; index: number };
+
+type UseSpanDrawerResult = {
+	tableProps: Pick<
+		TracesTableProps,
+		'onRowClick' | 'isRowActive' | 'activeRowIndex'
+	>;
+	/** Null while the drawer flag is off. */
+	drawerProps: SpanDrawerProps | null;
+	/** `onPointerDownCapture` for the area a press keeps the drawer open in. */
+	onPressInside: (event: PointerEvent) => void;
+};
+
+export function useSpanDrawer(rows: TracesTableRow[]): UseSpanDrawerResult {
+	const [isEnabled] = useState(isSpanDrawerEnabled);
+	// The index lets navigation step past a duplicate span; the id survives a refetch.
+	const [activeSpan, setActiveSpan] = useState<ActiveSpan | null>(null);
+
+	const activeRowIndex = useMemo(() => {
+		if (!activeSpan) {
+			return -1;
+		}
+		return rows[activeSpan.index]?.id === activeSpan.id
+			? activeSpan.index
+			: rows.findIndex((row) => row.id === activeSpan.id);
+	}, [rows, activeSpan]);
+
+	const isRowActive = useCallback(
+		(row: TracesTableRow): boolean => row === rows[activeRowIndex],
+		[rows, activeRowIndex],
+	);
+
+	const handleNavigate = useCallback(
+		(row: TracesTableRow, index: number): void => {
+			setActiveSpan({ id: row.id, index });
+		},
+		[],
+	);
+
+	const selectRow = useCallback(
+		(row: TracesTableRow): void => handleNavigate(row, rows.indexOf(row)),
+		[handleNavigate, rows],
+	);
+
+	const clearActiveSpan = useCallback((): void => setActiveSpan(null), []);
+
+	// A refetch can drop the open span; forget it so a later page can't reopen it.
+	useEffect(() => {
+		if (activeSpan && activeRowIndex === -1) {
+			setActiveSpan(null);
+		}
+	}, [activeSpan, activeRowIndex]);
+
+	const onPressInside = useCloseOnOutsidePress(
+		isEnabled && activeRowIndex !== -1,
+		clearActiveSpan,
+	);
+
+	const navigation = useRowNavigation({
+		rows,
+		activeIndex: activeRowIndex,
+		onNavigate: handleNavigate,
+	});
+
+	if (!isEnabled) {
+		return { tableProps: {}, drawerProps: null, onPressInside };
+	}
+
+	return {
+		tableProps: { onRowClick: selectRow, isRowActive, activeRowIndex },
+		drawerProps: {
+			row: rows[activeRowIndex] ?? null,
+			onClose: clearActiveSpan,
+			navigation,
+		},
+		onPressInside,
+	};
+}

frontend/src/container/TracesExplorer/SpanDrawer/utils.ts

@@ -0,0 +1,46 @@
+import get from 'api/browser/localstorage/get';
+import { LOCALSTORAGE } from 'constants/localStorage';
+import { TracesTableRow } from 'container/TracesExplorer/TracesTable/getFieldColumn';
+import { SpanV3 } from 'types/api/trace/getTraceV3';
+
+/** Off by default; set `TRACES_SPAN_DRAWER_ENABLED` to `true` in localStorage to try it. */
+export const isSpanDrawerEnabled = (): boolean =>
+	get(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED) === 'true';
+
+type ListSpanEvent = {
+	name: string;
+	timeUnixNano: number;
+	attributes?: Record<string, string>;
+	isError?: boolean;
+};
+
+type ListSpanLink = { traceId: string; spanId: string };
+
+/**
+ * The list API returns a span in a different shape from the trace API the
+ * details panel was built on: an ISO timestamp, `attributes` on events, and
+ * `links` in place of `references`.
+ */
+export const toSpanV3 = (row: TracesTableRow): SpanV3 => {
+	const resource = (row.resource ?? {}) as Record<string, string>;
+	const events = (row.events ?? []) as ListSpanEvent[];
+	const links = (row.links ?? []) as ListSpanLink[];
+
+	return {
+		...row,
+		timestamp: new Date(row.timestamp as string).getTime(),
+		'service.name': resource['service.name'] ?? '',
+		events: events.map(({ attributes, isError, ...event }) => ({
+			...event,
+			attributeMap: attributes ?? {},
+			isError: isError ?? false,
+		})),
+		// The list API drops `refType`, so the parent ref is matched by id. A root
+		// span's parent ref has no span id.
+		references: links.filter(
+			(link) =>
+				!!link.spanId &&
+				(link.spanId !== row.parent_span_id || link.traceId !== row.trace_id),
+		),
+	} as unknown as SpanV3;
+};

frontend/src/container/TracesExplorer/TracesTable/TracesTable.tsx

@@ -24,6 +24,10 @@ export type TracesTableProps = {
 	panelType: PanelTypeKeys;
 	/** Builds the trace-detail href for a row; drives row click + cmd/ctrl-click. */
 	getRowHref: (row: TracesTableRow) => string;
+	/** Replaces the default row click, which opens the trace detail page. */
+	onRowClick?: (row: TracesTableRow) => void;
+	isRowActive?: (row: TracesTableRow) => boolean;
+	activeRowIndex?: number;
 	isLoading: boolean;
 	isFetching: boolean;
 	isError: boolean;
@@ -41,6 +45,9 @@ function TracesTable({
 	respectColumnOrder = false,
 	panelType,
 	getRowHref,
+	onRowClick,
+	isRowActive,
+	activeRowIndex,
 	isLoading,
 	isFetching,
 	isError,
@@ -57,9 +64,13 @@ function TracesTable({
 
 	const handleRowClick = useCallback(
 		(row: TracesTableRow): void => {
+			if (onRowClick) {
+				onRowClick(row);
+				return;
+			}
 			navigate(getRowHref(row));
 		},
-		[navigate, getRowHref],
+		[onRowClick, navigate, getRowHref],
 	);
 
 	const handleRowClickNewTab = useCallback(
@@ -97,6 +108,8 @@ function TracesTable({
 						onColumnRemove={onColumnRemove}
 						onRowClick={handleRowClick}
 						onRowClickNewTab={handleRowClickNewTab}
+						isRowActive={isRowActive}
+						activeRowIndex={activeRowIndex}
 						getRowTestId={(row): string => `traces-table-row-${row.id}`}
 						testId={`traces-table-${panelType.toLowerCase()}`}
 					/>
@@ -109,6 +122,9 @@ function TracesTable({
 TracesTable.defaultProps = {
 	columnStorageKey: undefined,
 	respectColumnOrder: false,
+	onRowClick: undefined,
+	isRowActive: undefined,
+	activeRowIndex: undefined,
 	onColumnOrderChange: undefined,
 	onColumnRemove: undefined,
 	cellTypographySize: 'medium',

frontend/src/hooks/__tests__/useCloseOnOutsidePress.test.tsx

@@ -0,0 +1,107 @@
+import { createPortal } from 'react-dom';
+import { render, screen, userEvent } from 'tests/test-utils';
+
+import { useCloseOnOutsidePress } from '../useCloseOnOutsidePress';
+
+function Harness({
+	enabled = true,
+	onClose,
+}: {
+	enabled?: boolean;
+	onClose: () => void;
+}): JSX.Element {
+	const onPressInside = useCloseOnOutsidePress(enabled, onClose);
+	return (
+		<>
+			<div onPointerDownCapture={onPressInside}>
+				<button type="button" data-testid="inside">
+					inside
+				</button>
+				<button
+					type="button"
+					data-testid="inside-stops"
+					onPointerDown={(e): void => e.stopPropagation()}
+				>
+					inside, stops propagation
+				</button>
+				{createPortal(
+					<button type="button" data-testid="inside-portal">
+						portal
+					</button>,
+					document.body,
+				)}
+			</div>
+			<button type="button" data-testid="outside">
+				outside
+			</button>
+			<button
+				type="button"
+				data-testid="outside-stops"
+				onPointerDown={(e): void => e.stopPropagation()}
+			>
+				outside, stops propagation
+			</button>
+		</>
+	);
+}
+
+const flush = (): Promise<void> =>
+	new Promise((resolve) => {
+		setTimeout(resolve);
+	});
+
+describe('useCloseOnOutsidePress', () => {
+	it('closes on a press outside', async () => {
+		const onClose = jest.fn() as jest.MockedFunction<() => void>;
+		render(<Harness onClose={onClose} />);
+
+		await userEvent.click(screen.getByTestId('outside'));
+		await flush();
+
+		expect(onClose).toHaveBeenCalledTimes(1);
+	});
+
+	it('stays open on a press inside, portals included', async () => {
+		const onClose = jest.fn() as jest.MockedFunction<() => void>;
+		render(<Harness onClose={onClose} />);
+
+		await userEvent.click(screen.getByTestId('inside'));
+		await userEvent.click(screen.getByTestId('inside-portal'));
+		await flush();
+
+		expect(onClose).not.toHaveBeenCalled();
+	});
+
+	it('closes when the outside element stops propagation', async () => {
+		const onClose = jest.fn() as jest.MockedFunction<() => void>;
+		render(<Harness onClose={onClose} />);
+
+		await userEvent.click(screen.getByTestId('outside-stops'));
+		await flush();
+
+		expect(onClose).toHaveBeenCalledTimes(1);
+	});
+
+	it('closes on the first outside press after an inside press stops propagation', async () => {
+		const onClose = jest.fn() as jest.MockedFunction<() => void>;
+		render(<Harness onClose={onClose} />);
+
+		await userEvent.click(screen.getByTestId('inside-stops'));
+		await flush();
+		expect(onClose).not.toHaveBeenCalled();
+
+		await userEvent.click(screen.getByTestId('outside'));
+		await flush();
+		expect(onClose).toHaveBeenCalledTimes(1);
+	});
+
+	it('does nothing while disabled', async () => {
+		const onClose = jest.fn() as jest.MockedFunction<() => void>;
+		render(<Harness enabled={false} onClose={onClose} />);
+
+		await userEvent.click(screen.getByTestId('outside'));
+		await flush();
+
+		expect(onClose).not.toHaveBeenCalled();
+	});
+});

frontend/src/hooks/useCloseOnOutsidePress.ts

@@ -0,0 +1,51 @@
+import {
+	PointerEvent as ReactPointerEvent,
+	useCallback,
+	useEffect,
+	useRef,
+} from 'react';
+
+/**
+ * Calls `onClose` on any press outside the elements given the returned handler as
+ * `onPointerDownCapture`. Menus and dialogs rendered in portals still count as
+ * inside: React events follow the component tree.
+ *
+ * The document listener runs in the capture phase, so an outside element that
+ * stops propagation still closes. It runs before React marks the press, so the
+ * check waits for the dispatch to finish.
+ */
+export function useCloseOnOutsidePress(
+	enabled: boolean,
+	onClose: () => void,
+): (event: ReactPointerEvent) => void {
+	const insidePress = useRef<Event | null>(null);
+	const onCloseRef = useRef(onClose);
+	onCloseRef.current = onClose;
+
+	useEffect(() => {
+		if (!enabled) {
+			return undefined;
+		}
+		const timeouts = new Set<ReturnType<typeof setTimeout>>();
+
+		const handlePointerDown = (event: PointerEvent): void => {
+			const timeout = setTimeout(() => {
+				timeouts.delete(timeout);
+				if (insidePress.current !== event) {
+					onCloseRef.current();
+				}
+			});
+			timeouts.add(timeout);
+		};
+
+		document.addEventListener('pointerdown', handlePointerDown, true);
+		return (): void => {
+			document.removeEventListener('pointerdown', handlePointerDown, true);
+			timeouts.forEach(clearTimeout);
+		};
+	}, [enabled]);
+
+	return useCallback((event: ReactPointerEvent): void => {
+		insidePress.current = event.nativeEvent;
+	}, []);
+}

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

@@ -13,7 +13,8 @@ import styles from './Events.module.scss';
 
 interface IEventsTableProps {
 	span: SpanV3;
-	startTime: number;
+	/** Trace start; the "since trace start" offset is hidden without it. */
+	startTime?: number;
 	isSearchVisible: boolean;
 }
 
@@ -80,17 +81,19 @@ function EventsTable(props: IEventsTableProps): JSX.Element {
 														<Typography.Text className={styles.attributeKey}>
 															Start Time
 														</Typography.Text>
-														<div className={styles.timestampContainer}>
-															<Typography.Text className={styles.attributeValue}>
-																{getYAxisFormattedValue(
-																	`${(timeUnixNano || 0) / 1e6 - startTime}`,
-																	'ms',
-																)}
-															</Typography.Text>
-															<Typography.Text className={styles.timestampText}>
-																since trace start
-															</Typography.Text>
-														</div>
+														{startTime !== undefined && (
+															<div className={styles.timestampContainer}>
+																<Typography.Text className={styles.attributeValue}>
+																	{getYAxisFormattedValue(
+																		`${(timeUnixNano || 0) / 1e6 - startTime}`,
+																		'ms',
+																	)}
+																</Typography.Text>
+																<Typography.Text className={styles.timestampText}>
+																	since trace start
+																</Typography.Text>
+															</div>
+														)}
 														<div className={styles.timestampContainer}>
 															<Typography.Text className={styles.attributeValue}>
 																{getYAxisFormattedValue(

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

@@ -0,0 +1,38 @@
+import { render, screen } from 'tests/test-utils';
+import { SpanV3 } from 'types/api/trace/getTraceV3';
+
+import Events from '../Events';
+
+const SPAN_START_MS = 1_700_000_000_000;
+
+const span = {
+	span_id: 'span-1',
+	trace_id: 'trace-1',
+	name: 'checkout',
+	timestamp: SPAN_START_MS,
+	duration_nano: 50_000_000,
+	events: [
+		{
+			name: 'cache miss',
+			timeUnixNano: (SPAN_START_MS + 3) * 1e6,
+			attributeMap: {},
+			isError: false,
+		},
+	],
+} as unknown as SpanV3;
+
+describe('Events', () => {
+	it('shows the offset from the trace start when it is known', () => {
+		render(<Events span={span} startTime={SPAN_START_MS - 10} isSearchVisible />);
+
+		expect(screen.getByText('since trace start')).toBeInTheDocument();
+		expect(screen.getByText('since span start')).toBeInTheDocument();
+	});
+
+	it('shows only the offset from the span start without a trace start', () => {
+		render(<Events span={span} isSearchVisible />);
+
+		expect(screen.queryByText('since trace start')).not.toBeInTheDocument();
+		expect(screen.getByText('since span start')).toBeInTheDocument();
+	});
+});

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

@@ -110,3 +110,15 @@
 		scrollbar-width: none;
 	}
 }
+
+.drawerPanel {
+	.panelBody,
+	.logsFooter,
+	:global(.pretty-view__search-wrapper) {
+		background: var(--l2-background);
+	}
+
+	:global(.pretty-view__search-input) {
+		background: var(--l2-background) !important;
+	}
+}

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

@@ -3,6 +3,7 @@ import { Badge } from '@signozhq/ui/badge';
 import { Tabs, type TabsItemProps } from '@signozhq/ui/tabs';
 import { Bookmark, ChartColumnBig, List, ScrollText } from '@signozhq/icons';
 import { Skeleton } from 'antd';
+import cx from 'classnames';
 import { DetailsHeader, DetailsPanelDrawer } from 'components/DetailsPanel';
 import { HeaderAction } from 'components/DetailsPanel/DetailsHeader/DetailsHeader';
 import { DetailsPanelState } from 'components/DetailsPanel/types';
@@ -49,6 +50,7 @@ import OpenInLogsExplorer from './SpanLogs/OpenInLogsExplorer';
 import SpanLogs from './SpanLogs/SpanLogs';
 import { useSpanContextLogs } from './SpanLogs/useSpanContextLogs';
 import SpanAIMessages from './SpanAIMessages/SpanAIMessages';
+import SpanDrawerHeader from './SpanDrawerHeader';
 import SpanSummary from './SpanSummary';
 
 import styles from './SpanDetailsPanel.module.scss';
@@ -58,8 +60,12 @@ interface SpanDetailsPanelProps {
 	selectedSpan: SpanV3 | undefined;
 	variant?: SpanDetailVariant;
 	onVariantChange?: (variant: SpanDetailVariant) => void;
+	/** Page-specific actions, shown before the dock mode switcher. */
+	headerActions?: HeaderAction[];
 	traceStartTime?: number;
 	traceEndTime?: number;
+	/** The trace bounds are still being fetched; logs wait for them. */
+	isTraceBoundsLoading?: boolean;
 }
 
 // At/above this panel width the summary moves inside the Overview tab (bottom
@@ -73,10 +79,12 @@ function SpanDetailsContent({
 	selectedSpan,
 	traceStartTime,
 	traceEndTime,
+	isTraceBoundsLoading = false,
 }: {
 	selectedSpan: SpanV3;
 	traceStartTime?: number;
 	traceEndTime?: number;
+	isTraceBoundsLoading?: boolean;
 }): JSX.Element {
 	const [bodyRef, { width: bodyWidth }] = useMeasure<HTMLDivElement>();
 	const spanAttributeActions = useSpanAttributeActions();
@@ -168,6 +176,31 @@ function SpanDetailsContent({
 	// 	[spanAttributeActions, setCopy],
 	// );
 
+	// Without trace bounds the panel speaks only for the span: its own logs
+	// window, and no trace-wide logs check.
+	const hasTraceBounds = !!traceStartTime && !!traceEndTime;
+	const logsTimeRange = useMemo(
+		() =>
+			traceStartTime && traceEndTime
+				? {
+						startTime: traceStartTime - FIVE_MINUTES_IN_MS,
+						endTime: traceEndTime + FIVE_MINUTES_IN_MS,
+					}
+				: {
+						startTime: selectedSpan.timestamp - FIVE_MINUTES_IN_MS,
+						// query_range rejects a fractional end.
+						endTime:
+							Math.ceil(selectedSpan.timestamp + selectedSpan.duration_nano / 1e6) +
+							FIVE_MINUTES_IN_MS,
+					},
+		[
+			traceStartTime,
+			traceEndTime,
+			selectedSpan.timestamp,
+			selectedSpan.duration_nano,
+		],
+	);
+
 	const {
 		logs,
 		isLoading: isLogsLoading,
@@ -178,11 +211,9 @@ function SpanDetailsContent({
 	} = useSpanContextLogs({
 		traceId: selectedSpan.trace_id,
 		spanId: selectedSpan.span_id,
-		timeRange: {
-			startTime: (traceStartTime || 0) - FIVE_MINUTES_IN_MS,
-			endTime: (traceEndTime || 0) + FIVE_MINUTES_IN_MS,
-		},
-		isDrawerOpen: true,
+		timeRange: logsTimeRange,
+		checkTraceLogs: hasTraceBounds,
+		enabled: !isTraceBoundsLoading,
 	});
 
 	const infraMetadata = useMemo(() => {
@@ -201,8 +232,7 @@ function SpanDetailsContent({
 	}, [selectedSpan]);
 
 	const handleExplorerPageRedirect = useCallback((): void => {
-		const startTimeMs = (traceStartTime || 0) - FIVE_MINUTES_IN_MS;
-		const endTimeMs = (traceEndTime || 0) + FIVE_MINUTES_IN_MS;
+		const { startTime: startTimeMs, endTime: endTimeMs } = logsTimeRange;
 
 		const traceIdFilter = {
 			op: 'AND',
@@ -244,14 +274,15 @@ function SpanDetailsContent({
 		searchParams.set(QueryParams.endTime, endTimeMs.toString());
 
 		openInNewTab(`${ROUTES.LOGS_EXPLORER}?${searchParams.toString()}`);
-	}, [selectedSpan.trace_id, traceStartTime, traceEndTime]);
+	}, [selectedSpan.trace_id, logsTimeRange]);
 
 	const emptyLogsStateConfig = useMemo(
 		() => ({
 			...getEmptyLogsListConfig(() => {}),
+			...(!hasTraceBounds && { title: 'No logs found for this span.' }),
 			showClearFiltersButton: false,
 		}),
-		[],
+		[hasTraceBounds],
 	);
 
 	// const keyAttributes = useMemo(() => {
@@ -321,11 +352,7 @@ function SpanDetailsContent({
 					</Badge>
 				) : undefined,
 			children: (
-				<Events
-					span={selectedSpan}
-					startTime={traceStartTime || 0}
-					isSearchVisible
-				/>
+				<Events span={selectedSpan} startTime={traceStartTime} isSearchVisible />
 			),
 		},
 		{
@@ -336,10 +363,7 @@ function SpanDetailsContent({
 				<SpanLogs
 					traceId={selectedSpan.trace_id}
 					spanId={selectedSpan.span_id}
-					timeRange={{
-						startTime: (traceStartTime || 0) - FIVE_MINUTES_IN_MS,
-						endTime: (traceEndTime || 0) + FIVE_MINUTES_IN_MS,
-					}}
+					timeRange={logsTimeRange}
 					logs={logs}
 					isLoading={isLogsLoading}
 					isError={isLogsError}
@@ -394,7 +418,10 @@ function SpanDetailsContent({
 			    with the panel's bottom edge — always visible, never scrolls. */}
 			{activeTab === 'logs' && (
 				<div className={styles.logsFooter}>
-					<OpenInLogsExplorer onClick={handleExplorerPageRedirect} />
+					<OpenInLogsExplorer
+						onClick={handleExplorerPageRedirect}
+						disabled={isTraceBoundsLoading}
+					/>
 				</div>
 			)}
 		</>
@@ -406,11 +433,14 @@ function SpanDetailsPanel({
 	selectedSpan,
 	variant = SpanDetailVariant.DIALOG,
 	onVariantChange,
+	headerActions: pageHeaderActions,
 	traceStartTime,
 	traceEndTime,
+	isTraceBoundsLoading,
 }: SpanDetailsPanelProps): JSX.Element {
 	const headerActions = useMemo((): HeaderAction[] => {
 		const actions: HeaderAction[] = [
+			...(pageHeaderActions ?? []),
 			// TODO: Add back when driven through separate config for different pages
 			// {
 			// 	key: 'view-full-trace',
@@ -440,7 +470,7 @@ function SpanDetailsPanel({
 		}
 
 		return actions;
-	}, [variant, onVariantChange]);
+	}, [pageHeaderActions, variant, onVariantChange]);
 
 	const PANEL_WIDTH = SPAN_DETAILS_PANEL_MIN_WIDTH;
 	const PANEL_MARGIN_RIGHT = 20;
@@ -449,19 +479,28 @@ function SpanDetailsPanel({
 
 	const content = (
 		<>
-			<DetailsHeader
-				title="Span details"
-				onClose={panelState.close}
-				actions={headerActions}
-				className={
-					variant === SpanDetailVariant.DIALOG ? 'floating-panel__drag-handle' : ''
-				}
-			/>
+			{variant === SpanDetailVariant.DRAWER ? (
+				<SpanDrawerHeader
+					title="Span details"
+					onClose={panelState.close}
+					actions={headerActions}
+				/>
+			) : (
+				<DetailsHeader
+					title="Span details"
+					onClose={panelState.close}
+					actions={headerActions}
+					className={
+						variant === SpanDetailVariant.DIALOG ? 'floating-panel__drag-handle' : ''
+					}
+				/>
+			)}
 			{selectedSpan ? (
 				<SpanDetailsContent
 					selectedSpan={selectedSpan}
 					traceStartTime={traceStartTime}
 					traceEndTime={traceEndTime}
+					isTraceBoundsLoading={isTraceBoundsLoading}
 				/>
 			) : (
 				<div className={styles.panelBody}>
@@ -483,7 +522,8 @@ function SpanDetailsPanel({
 			<DetailsPanelDrawer
 				isOpen={panelState.isOpen}
 				onClose={panelState.close}
-				className={styles.panel}
+				className={cx(styles.panel, styles.drawerPanel)}
+				testId="span-details-drawer"
 			>
 				{content}
 			</DetailsPanelDrawer>

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

@@ -0,0 +1,33 @@
+.header {
+	box-sizing: border-box;
+	display: flex;
+	flex-shrink: 0;
+	align-items: center;
+	gap: var(--spacing-4);
+	height: 48px;
+	padding: 0 var(--spacing-8) 0 var(--spacing-4);
+	border-bottom: 1px solid var(--l1-border);
+	background: var(--l2-background);
+}
+
+.divider {
+	height: 16px;
+	margin-inline: 0 var(--spacing-4);
+}
+
+.title {
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	font-size: 14px;
+	color: var(--l1-foreground);
+}
+
+.actions {
+	display: flex;
+	flex-shrink: 0;
+	align-items: center;
+	gap: var(--spacing-4);
+}

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

@@ -0,0 +1,43 @@
+import { Button } from '@signozhq/ui/button';
+import { Divider } from '@signozhq/ui/divider';
+import { X } from '@signozhq/icons';
+import type { HeaderAction } from 'components/DetailsPanel';
+
+import styles from './SpanDrawerHeader.module.scss';
+
+interface SpanDrawerHeaderProps {
+	title: string;
+	onClose: () => void;
+	actions: HeaderAction[];
+}
+
+function SpanDrawerHeader({
+	title,
+	onClose,
+	actions,
+}: SpanDrawerHeaderProps): JSX.Element {
+	return (
+		<div className={styles.header}>
+			<Button
+				variant="ghost"
+				color="secondary"
+				size="md"
+				icon
+				aria-label="Close"
+				onClick={onClose}
+				testId="span-drawer-close"
+			>
+				<X />
+			</Button>
+			<Divider type="vertical" className={styles.divider} />
+			<span className={styles.title}>{title}</span>
+			<div className={styles.actions}>
+				{actions.map((action) => (
+					<div key={action.key}>{action.component}</div>
+				))}
+			</div>
+		</div>
+	);
+}
+
+export default SpanDrawerHeader;

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanLogs/OpenInLogsExplorer.tsx

@@ -3,17 +3,23 @@ import { Compass } from '@signozhq/icons';
 
 interface OpenInLogsExplorerProps {
 	onClick: () => void;
+	disabled?: boolean;
 }
 
 // Opens the full Logs Explorer (new tab) filtered to this span's trace.
 // Placement/alignment is the caller's responsibility.
-function OpenInLogsExplorer({ onClick }: OpenInLogsExplorerProps): JSX.Element {
+function OpenInLogsExplorer({
+	onClick,
+	disabled,
+}: OpenInLogsExplorerProps): JSX.Element {
 	return (
 		<Button
 			variant="solid"
 			color="secondary"
 			size="md"
 			onClick={onClick}
+			disabled={disabled}
+			disabledTooltip="Loading the trace's time range"
 			prefix={<Compass size={16} />}
 			testId="open-in-explorer-button"
 		>

frontend/src/pages/TraceDetailsV3/SpanDetailsPanel/SpanLogs/useSpanContextLogs.ts

@@ -20,7 +20,8 @@ interface UseSpanContextLogsProps {
 		startTime: number;
 		endTime: number;
 	};
-	isDrawerOpen?: boolean;
+	checkTraceLogs?: boolean;
+	enabled?: boolean;
 }
 
 interface UseSpanContextLogsReturn {
@@ -112,7 +113,8 @@ export const useSpanContextLogs = ({
 	traceId,
 	spanId,
 	timeRange,
-	isDrawerOpen = true,
+	checkTraceLogs = true,
+	enabled = true,
 }: UseSpanContextLogsProps): UseSpanContextLogsReturn => {
 	const [allLogs, setAllLogs] = useState<ILog[]>([]);
 	const [spanLogIds, setSpanLogIds] = useState<Set<string>>(new Set());
@@ -142,7 +144,7 @@ export const useSpanContextLogs = ({
 			timeRange.endTime,
 		],
 		queryFn: () => GetMetricQueryRange(spanQueryPayload, ENTITY_VERSION_V5),
-		enabled: !!traceId && !!spanId,
+		enabled: enabled && !!traceId && !!spanId,
 		staleTime: FIVE_MINUTES_IN_MS,
 	});
 
@@ -311,7 +313,11 @@ export const useSpanContextLogs = ({
 		],
 		queryFn: () =>
 			GetMetricQueryRange(traceOnlyQueryPayload as any, ENTITY_VERSION_V5),
-		enabled: isDrawerOpen && !!traceOnlyQueryPayload && spanLogs.length === 0,
+		enabled:
+			enabled &&
+			checkTraceLogs &&
+			!!traceOnlyQueryPayload &&
+			spanLogs.length === 0,
 		staleTime: FIVE_MINUTES_IN_MS,
 	});
 
@@ -332,7 +338,7 @@ export const useSpanContextLogs = ({
 
 	return {
 		logs: allLogs,
-		isLoading: isSpanLoading && spanLogs.length === 0,
+		isLoading: (!enabled || isSpanLoading) && spanLogs.length === 0,
 		isError: isSpanError,
 		isFetching: isSpanFetching || isBeforeFetching || isAfterFetching,
 		spanLogIds,

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

@@ -1,7 +1,21 @@
 .traceId {
-	color: var(--accent-primary);
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-1);
+	min-width: 0;
+
+	// Sized to the icon, so the copy button sits flush against the id.
+	--button-padding: 2px;
+	--button-height: auto;
+	--button-width: auto;
+}
+
+// A block, since overflow and text-overflow do not apply to the inline span
+// Typography.Text renders.
+.value {
+	display: block;
+	min-width: 0;
+	white-space: nowrap;
 	overflow: hidden;
 	text-overflow: ellipsis;
-	white-space: nowrap;
-	display: block;
 }

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

@@ -1,11 +1,5 @@
-import { useCopyToClipboard } from 'react-use';
-import { Button } from '@signozhq/ui/button';
-import { Tooltip } from '@signozhq/ui/tooltip';
-import { toast } from '@signozhq/ui/sonner';
-import { AppLink } from 'lib/router/AppLink';
-import { matchRoute } from 'lib/router/matchRoute';
-import { useAppLocation } from 'lib/router/useAppLocation';
-import ROUTES from 'constants/routes';
+import { Typography } from '@signozhq/ui/typography';
+import CopyButton from 'periscope/components/CopyButton/CopyButton';
 import { SpanV3 } from 'types/api/trace/getTraceV3';
 
 import styles from './TraceIdField.module.scss';
@@ -14,51 +8,20 @@ interface TraceIdFieldProps {
 	span: SpanV3;
 }
 
-/**
- * Renders a span's trace id. When the user is already on the trace detail
- * page for this trace, clicking the id copies it to the clipboard (the
- * "navigate" affordance would be a no-op). Otherwise, falls back to the
- * existing link to the trace detail page.
- */
 export function TraceIdField({ span }: TraceIdFieldProps): JSX.Element {
-	const { pathname } = useAppLocation();
-	const match = matchRoute<'id'>(pathname, ROUTES.TRACE_DETAIL, { exact: true });
-	const [, setCopy] = useCopyToClipboard();
-
-	const isCurrentTrace = match?.params.id === span.trace_id;
-
-	if (isCurrentTrace) {
-		const handleCopy = (): void => {
-			setCopy(span.trace_id);
-			toast.success('Trace ID copied to clipboard', {
-				position: 'top-right',
-			});
-		};
-
-		return (
-			<Tooltip title="Click to copy trace ID">
-				<Button
-					size="md"
-					variant="link"
-					color="secondary"
-					maxWidth="100%"
-					onClick={handleCopy}
-				>
-					{span.trace_id}
-				</Button>
-			</Tooltip>
-		);
-	}
-
 	return (
-		<AppLink
-			to={{
-				pathname: `/trace/${span.trace_id}`,
-				search: window.location.search,
-			}}
-			className={styles.traceId}
-		>
-			{span.trace_id}
-		</AppLink>
+		<div className={styles.traceId}>
+			<span className={styles.value} title={span.trace_id}>
+				<Typography.Text testId="span-details-trace-id">
+					{span.trace_id}
+				</Typography.Text>
+			</span>
+			<CopyButton
+				value={span.trace_id}
+				size={12}
+				ariaLabel="Copy trace ID"
+				testId="span-details-copy-trace-id"
+			/>
+		</div>
 	);
 }

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

@@ -33,6 +33,13 @@
 	flex-shrink: 0;
 }
 
+.aiDot {
+	width: 6px;
+	height: 6px;
+	border-radius: 50%;
+	background: var(--accent-primary);
+}
+
 .filterSection {
 	display: flex;
 	align-items: center;

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

@@ -137,7 +137,7 @@ function TraceDetailsHeader({
 							badgeValue={traceID}
 							maxCharacters={100}
 						/>
-						<TraceDetailsTabs />
+						<TraceDetailsTabs hasAiSummary={!!traceSummary?.ai} />
 					</div>
 				)}
 				{isOverview && showTraceDetailsHeaderOptions && traceSummary && (

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

@@ -8,20 +8,13 @@ import { useTraceDetailsTab } from '../hooks/useTraceDetailsTab';
 
 import styles from './TraceDetailsHeader.module.scss';
 
-const TAB_ITEMS = [
-	{
-		value: TraceDetailsTab.Overview,
-		label: 'Overview',
-		testId: 'trace-details-tab-overview',
-	},
-	{
-		value: TraceDetailsTab.Thread,
-		label: 'Thread',
-		testId: 'trace-details-tab-thread',
-	},
-];
+interface TraceDetailsTabsProps {
+	hasAiSummary: boolean;
+}
 
-function TraceDetailsTabs(): JSX.Element {
+function TraceDetailsTabs({
+	hasAiSummary,
+}: TraceDetailsTabsProps): JSX.Element {
 	const { id: traceId = '' } = useAppParams<'id'>();
 	const [tab, setTab] = useTraceDetailsTab();
 	const logTraceEvent = useTraceDetailLogEvent('v3', traceId);
@@ -35,6 +28,26 @@ function TraceDetailsTabs(): JSX.Element {
 		void setTab(value as TraceDetailsTab, { history: 'push' });
 	};
 
+	const items = [
+		{
+			value: TraceDetailsTab.Overview,
+			label: 'Overview',
+			testId: 'trace-details-tab-overview',
+		},
+		{
+			value: TraceDetailsTab.Thread,
+			label: 'Thread',
+			testId: 'trace-details-tab-thread',
+			suffix: hasAiSummary ? (
+				<span
+					className={styles.aiDot}
+					aria-hidden
+					data-testid="trace-details-tab-thread-ai-dot"
+				/>
+			) : undefined,
+		},
+	];
+
 	return (
 		<div className={styles.tabs}>
 			<ToggleGroup
@@ -44,7 +57,7 @@ function TraceDetailsTabs(): JSX.Element {
 				value={tab}
 				onChange={handleChange}
 				size="sm"
-				items={TAB_ITEMS}
+				items={items}
 			/>
 		</div>
 	);

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/__tests__/TraceDetailsHeader.test.tsx

@@ -394,6 +394,27 @@ describe('TraceDetailsHeader – tabs', () => {
 		expect(screen.getByText(metadataText)).toBeInTheDocument();
 	});
 
+	it('shows the AI dot on the Thread tab only when the summary has an AI block', () => {
+		renderHeader();
+		expect(
+			screen.queryByTestId('trace-details-tab-thread-ai-dot'),
+		).not.toBeInTheDocument();
+
+		jest.mocked(useTraceSummary).mockReturnValue({
+			data: {
+				...SUMMARY,
+				ai: {
+					tokens: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, reasoning: 0 },
+				},
+			},
+			isLoading: false,
+		});
+		renderHeader();
+		expect(
+			screen.getByTestId('trace-details-tab-thread-ai-dot'),
+		).toBeInTheDocument();
+	});
+
 	it('clears the filter result when switching to the Thread tab', async () => {
 		const user = userEvent.setup({ delay: null });
 		renderHeader();

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/ThreadSpanDetails.tsx

@@ -34,7 +34,8 @@ function ThreadSpanDetails({
 	const [width, setWidth] = useState(RIGHT_DOCK_MIN);
 	const [height, setHeight] = useState(BOTTOM_DOCK_DEFAULT);
 	const { id: traceId = '' } = useAppParams<'id'>();
-	const { data: traceSummary } = useTraceSummary(traceId);
+	const { data: traceSummary, isLoading: isTraceSummaryLoading } =
+		useTraceSummary(traceId);
 
 	const panel = (
 		<SpanDetailsPanel
@@ -44,6 +45,7 @@ function ThreadSpanDetails({
 			onVariantChange={onVariantChange}
 			traceStartTime={traceSummary?.startTimestampMillis}
 			traceEndTime={traceSummary?.endTimestampMillis}
+			isTraceBoundsLoading={isTraceSummaryLoading}
 		/>
 	);
 

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/TraceDetailsThread.tsx

@@ -9,7 +9,7 @@ import { useSpanDetailVariant } from '../hooks/useSpanDetailVariant';
 import { useTraceDetailLogEvent } from '../hooks/useTraceDetailLogEvent';
 import { useTraceDetailsTab } from '../hooks/useTraceDetailsTab';
 import { SpanDetailVariant } from '../SpanDetailsPanel/constants';
-import { useThreadDataLoadedEvent } from './hooks/useThreadDataLoadedEvent';
+import { useThreadLoadedEvents } from './hooks/useThreadLoadedEvents';
 import { useThreadSpanSelection } from './hooks/useThreadSpanSelection';
 import { useThreadView } from './hooks/useThreadView';
 import { useTraceThread } from './hooks/useTraceThread';
@@ -30,10 +30,12 @@ const INITIAL_LOADER_COUNT = 4;
 interface TraceDetailsThreadProps {
 	// Owned by the page so the load event fires once per trace, not per tab visit.
 	dataLoadedFiredForRef: MutableRefObject<string>;
+	threadEmptyFiredForRef: MutableRefObject<string>;
 }
 
 function TraceDetailsThread({
 	dataLoadedFiredForRef,
+	threadEmptyFiredForRef,
 }: TraceDetailsThreadProps): JSX.Element {
 	const { id: traceId } = useAppParams<'id'>();
 	const [, setTab] = useTraceDetailsTab();
@@ -68,17 +70,24 @@ function TraceDetailsThread({
 	const interestedSpanIndex = spans.findIndex(
 		(span) => span.span_id === interestedSpanId,
 	);
+	const hasNoThread =
+		!isLoading &&
+		interestedSpanStatus !== InterestedSpanStatus.NotFound &&
+		(isError || spans.length === 0);
 
 	const selectedSpan = spans.find((span) => span.span_id === selectedSpanId);
 	const [spanDetailVariant, setSpanDetailVariant] = useSpanDetailVariant();
 	const isBottomDocked = spanDetailVariant === SpanDetailVariant.DOCKED;
 
 	const logTraceEvent = useTraceDetailLogEvent('v3', traceId || '');
-	useThreadDataLoadedEvent({
+	useThreadLoadedEvents({
 		traceId: traceId || '',
+		interestedSpanId,
 		hasSpans: spans.length > 0,
+		hasNoThread,
 		spanPanelVariant: spanDetailVariant,
-		firedForRef: dataLoadedFiredForRef,
+		dataLoadedFiredForRef,
+		threadEmptyFiredForRef,
 		logTraceEvent,
 	});
 	useSpanDetailsOpenedEvent({
@@ -96,10 +105,6 @@ function TraceDetailsThread({
 			onVariantChange={setSpanDetailVariant}
 		/>
 	);
-	const hasNoThread =
-		!isLoading &&
-		interestedSpanStatus !== InterestedSpanStatus.NotFound &&
-		(isError || spans.length === 0);
 
 	const renderBody = (): JSX.Element => {
 		if (isLoading) {

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/__tests__/threadLoadedEventsTestUtils.tsx

@@ -0,0 +1,135 @@
+import { MutableRefObject, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from 'react-query';
+import {
+	GetTraceSummary200,
+	SpantypesGettableTraceSummaryDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import { getGetTraceSummaryQueryKey } from 'api/generated/services/tracedetail';
+import { rest, server } from 'mocks-server/server';
+import { renderHook, waitFor } from 'tests/test-utils';
+
+import { TraceDetailLogEvent } from '../../../hooks/useTraceDetailLogEvent';
+import { SpanDetailVariant } from '../../../SpanDetailsPanel/constants';
+import { useThreadLoadedEvents } from '../useThreadLoadedEvents';
+
+const BASE_SUMMARY: SpantypesGettableTraceSummaryDTO = {
+	startTimestampMillis: 1_000,
+	endTimestampMillis: 4_000,
+	totalSpansCount: 12,
+	totalErrorSpansCount: 2,
+	hasMissingSpans: true,
+	rootServiceEntryPoint: 'POST /chat',
+	rootServiceName: 'agent',
+	rootSpanStatusCode: 'STATUS_CODE_ERROR',
+};
+
+const SUMMARIES: Record<string, SpantypesGettableTraceSummaryDTO> = {
+	'trace-ai': {
+		...BASE_SUMMARY,
+		ai: {
+			tokens: {
+				input: 1_200,
+				output: 300,
+				cacheRead: 50,
+				cacheWrite: 10,
+				reasoning: 40,
+			},
+			totalCost: 0.0123,
+		},
+	},
+	'trace-ai-next': {
+		...BASE_SUMMARY,
+		endTimestampMillis: 1_500,
+		totalSpansCount: 4,
+		ai: {
+			tokens: { input: 80, output: 20, cacheRead: 0, cacheWrite: 0, reasoning: 0 },
+			totalCost: 0.0004,
+		},
+	},
+	'trace-no-ai': BASE_SUMMARY,
+};
+
+export interface ThreadLoadedEventsProps {
+	traceId: string;
+	hasSpans?: boolean;
+	hasNoThread?: boolean;
+	interestedSpanId?: string;
+	spanPanelVariant?: SpanDetailVariant;
+}
+
+interface RenderOptions {
+	dataLoadedFiredForRef?: MutableRefObject<string>;
+	threadEmptyFiredForRef?: MutableRefObject<string>;
+	queryClient?: QueryClient;
+}
+
+interface RenderResult {
+	logTraceEvent: jest.MockedFunction<TraceDetailLogEvent>;
+	rerender: (props: ThreadLoadedEventsProps) => void;
+	unmount: () => void;
+	queryClient: QueryClient;
+}
+
+/** Serves the fixture summaries and returns the trace ids requested, in order. */
+export function mockTraceSummaries(): string[] {
+	const requests: string[] = [];
+	server.use(
+		rest.get('*/api/v1/traces/:traceId/summary', (req, res, ctx) => {
+			requests.push(req.params.traceId as string);
+			const body: GetTraceSummary200 = {
+				status: 'success',
+				data: SUMMARIES[req.params.traceId as string],
+			};
+			return res(ctx.status(200), ctx.json(body));
+		}),
+	);
+	return requests;
+}
+
+export function renderThreadLoadedEvents(
+	initialProps: ThreadLoadedEventsProps,
+	{
+		dataLoadedFiredForRef = { current: '' },
+		threadEmptyFiredForRef = { current: '' },
+		queryClient = new QueryClient({
+			defaultOptions: { queries: { retry: false } },
+		}),
+	}: RenderOptions = {},
+): RenderResult {
+	const logTraceEvent = jest.fn() as jest.MockedFunction<TraceDetailLogEvent>;
+	const wrapper = ({ children }: { children: ReactNode }): JSX.Element => (
+		<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+	);
+	const { rerender, unmount } = renderHook(
+		({
+			traceId,
+			hasSpans = false,
+			hasNoThread = false,
+			interestedSpanId,
+			spanPanelVariant = SpanDetailVariant.DOCKED_RIGHT,
+		}: ThreadLoadedEventsProps) =>
+			useThreadLoadedEvents({
+				traceId,
+				interestedSpanId,
+				hasSpans,
+				hasNoThread,
+				spanPanelVariant,
+				dataLoadedFiredForRef,
+				threadEmptyFiredForRef,
+				logTraceEvent,
+			}),
+		{ initialProps, wrapper },
+	);
+	return { logTraceEvent, rerender, unmount, queryClient };
+}
+
+export async function waitForSummary(
+	queryClient: QueryClient,
+	traceId: string,
+): Promise<void> {
+	await waitFor(() =>
+		expect(
+			queryClient.getQueryData(getGetTraceSummaryQueryKey({ traceID: traceId })),
+		).toBeDefined(),
+	);
+}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/__tests__/useThreadDataLoadedEvent.test.tsx

@@ -1,174 +0,0 @@
-import { MutableRefObject, ReactNode } from 'react';
-import { QueryClient, QueryClientProvider } from 'react-query';
-import {
-	GetTraceSummary200,
-	SpantypesGettableTraceSummaryDTO,
-} from 'api/generated/services/sigNoz.schemas';
-import { getGetTraceSummaryQueryKey } from 'api/generated/services/tracedetail';
-import { rest, server } from 'mocks-server/server';
-import { renderHook, waitFor } from 'tests/test-utils';
-
-import { TraceDetailsTab } from '../../../constants';
-import { TraceDetailEvents } from '../../../events';
-import { TraceDetailLogEvent } from '../../../hooks/useTraceDetailLogEvent';
-import { SpanDetailVariant } from '../../../SpanDetailsPanel/constants';
-import { useThreadDataLoadedEvent } from '../useThreadDataLoadedEvent';
-
-const SUMMARIES: Record<string, SpantypesGettableTraceSummaryDTO> = {
-	'trace-a': {
-		startTimestampMillis: 1_000,
-		endTimestampMillis: 4_000,
-		totalSpansCount: 12,
-		totalErrorSpansCount: 2,
-		hasMissingSpans: false,
-		rootServiceEntryPoint: 'POST /chat',
-		rootServiceName: 'agent',
-		rootSpanStatusCode: 'STATUS_CODE_ERROR',
-	},
-	'trace-b': {
-		startTimestampMillis: 5_000,
-		endTimestampMillis: 5_500,
-		totalSpansCount: 3,
-		totalErrorSpansCount: 0,
-		hasMissingSpans: false,
-		rootServiceEntryPoint: 'POST /chat',
-		rootServiceName: 'agent',
-		rootSpanStatusCode: 'STATUS_CODE_OK',
-	},
-};
-
-interface HookProps {
-	traceId: string;
-	hasSpans: boolean;
-	spanPanelVariant?: SpanDetailVariant;
-}
-
-function renderDataLoadedEvent(
-	initialProps: HookProps,
-	firedForRef: MutableRefObject<string> = { current: '' },
-): {
-	logTraceEvent: jest.MockedFunction<TraceDetailLogEvent>;
-	rerender: (props: HookProps) => void;
-	queryClient: QueryClient;
-} {
-	const logTraceEvent = jest.fn() as jest.MockedFunction<TraceDetailLogEvent>;
-	const queryClient = new QueryClient({
-		defaultOptions: { queries: { retry: false } },
-	});
-	const wrapper = ({ children }: { children: ReactNode }): JSX.Element => (
-		<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
-	);
-	const { rerender } = renderHook(
-		({ traceId, hasSpans, spanPanelVariant }: HookProps) =>
-			useThreadDataLoadedEvent({
-				traceId,
-				hasSpans,
-				spanPanelVariant: spanPanelVariant ?? SpanDetailVariant.DOCKED_RIGHT,
-				firedForRef,
-				logTraceEvent,
-			}),
-		{ initialProps, wrapper },
-	);
-	return { logTraceEvent, rerender, queryClient };
-}
-
-describe('useThreadDataLoadedEvent', () => {
-	beforeEach(() => {
-		server.use(
-			rest.get('*/api/v1/traces/:traceId/summary', (req, res, ctx) => {
-				const body: GetTraceSummary200 = {
-					status: 'success',
-					data: SUMMARIES[req.params.traceId as string],
-				};
-				return res(ctx.status(200), ctx.json(body));
-			}),
-		);
-	});
-
-	it('waits for the trace summary, then reports it as a thread load', async () => {
-		const { logTraceEvent } = renderDataLoadedEvent({
-			traceId: 'trace-a',
-			hasSpans: true,
-		});
-
-		expect(logTraceEvent).not.toHaveBeenCalled();
-
-		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
-		expect(logTraceEvent).toHaveBeenCalledWith(TraceDetailEvents.DataLoaded, {
-			detailsTab: TraceDetailsTab.Thread,
-			totalSpansCount: 12,
-			traceDurationMs: 3_000,
-			hadErrors: true,
-			spanPanelVariant: SpanDetailVariant.DOCKED_RIGHT,
-		});
-	});
-
-	it('waits for the thread spans even when the summary is already loaded', async () => {
-		const { logTraceEvent, rerender, queryClient } = renderDataLoadedEvent({
-			traceId: 'trace-a',
-			hasSpans: false,
-		});
-		await waitFor(() =>
-			expect(
-				queryClient.getQueryData(
-					getGetTraceSummaryQueryKey({ traceID: 'trace-a' }),
-				),
-			).toBeDefined(),
-		);
-		rerender({ traceId: 'trace-a', hasSpans: false });
-
-		expect(logTraceEvent).not.toHaveBeenCalled();
-
-		rerender({ traceId: 'trace-a', hasSpans: true });
-
-		expect(logTraceEvent).toHaveBeenCalledTimes(1);
-	});
-
-	it('reports a trace once, including when the tab is visited again', async () => {
-		const firedForRef = { current: '' };
-		const firstVisit = renderDataLoadedEvent(
-			{ traceId: 'trace-a', hasSpans: true },
-			firedForRef,
-		);
-		await waitFor(() =>
-			expect(firstVisit.logTraceEvent).toHaveBeenCalledTimes(1),
-		);
-		firstVisit.rerender({
-			traceId: 'trace-a',
-			hasSpans: true,
-			spanPanelVariant: SpanDetailVariant.DOCKED,
-		});
-
-		const secondVisit = renderDataLoadedEvent(
-			{ traceId: 'trace-a', hasSpans: true },
-			firedForRef,
-		);
-		await waitFor(() =>
-			expect(
-				secondVisit.queryClient.getQueryData(
-					getGetTraceSummaryQueryKey({ traceID: 'trace-a' }),
-				),
-			).toBeDefined(),
-		);
-		secondVisit.rerender({ traceId: 'trace-a', hasSpans: true });
-
-		expect(firstVisit.logTraceEvent).toHaveBeenCalledTimes(1);
-		expect(secondVisit.logTraceEvent).not.toHaveBeenCalled();
-	});
-
-	it('reports the next trace with its own summary', async () => {
-		const { logTraceEvent, rerender } = renderDataLoadedEvent({
-			traceId: 'trace-a',
-			hasSpans: true,
-		});
-		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
-
-		rerender({ traceId: 'trace-b', hasSpans: true });
-
-		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(2));
-		expect(logTraceEvent).toHaveBeenLastCalledWith(
-			TraceDetailEvents.DataLoaded,
-			expect.objectContaining({ totalSpansCount: 3, traceDurationMs: 500 }),
-		);
-	});
-});

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/__tests__/useThreadLoadedEvents.dataLoaded.test.tsx

@@ -0,0 +1,111 @@
+import { waitFor } from 'tests/test-utils';
+
+import { TraceDetailsTab } from '../../../constants';
+import { TraceDetailEvents } from '../../../events';
+import { SpanDetailVariant } from '../../../SpanDetailsPanel/constants';
+import {
+	mockTraceSummaries,
+	renderThreadLoadedEvents,
+	ThreadLoadedEventsProps,
+	waitForSummary,
+} from './threadLoadedEventsTestUtils';
+
+describe('useThreadLoadedEvents: data loaded', () => {
+	beforeEach(() => {
+		mockTraceSummaries();
+	});
+
+	it('waits for the trace summary, then reports it as a thread load', async () => {
+		const { logTraceEvent } = renderThreadLoadedEvents({
+			traceId: 'trace-ai',
+			hasSpans: true,
+		});
+
+		expect(logTraceEvent).not.toHaveBeenCalled();
+
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
+		expect(logTraceEvent).toHaveBeenCalledWith(TraceDetailEvents.DataLoaded, {
+			detailsTab: TraceDetailsTab.Thread,
+			totalSpansCount: 12,
+			traceDurationMs: 3_000,
+			hadErrors: true,
+			spanPanelVariant: SpanDetailVariant.DOCKED_RIGHT,
+		});
+	});
+
+	it('waits for the thread spans even when the summary is already loaded', async () => {
+		const { logTraceEvent, rerender, queryClient } = renderThreadLoadedEvents({
+			traceId: 'trace-ai',
+		});
+		await waitForSummary(queryClient, 'trace-ai');
+		rerender({ traceId: 'trace-ai' });
+
+		expect(logTraceEvent).not.toHaveBeenCalled();
+
+		rerender({ traceId: 'trace-ai', hasSpans: true });
+
+		expect(logTraceEvent).toHaveBeenCalledTimes(1);
+	});
+
+	it('reports a trace once, including when the tab is visited again', async () => {
+		const dataLoadedFiredForRef = { current: '' };
+		const props: ThreadLoadedEventsProps = {
+			traceId: 'trace-ai',
+			hasSpans: true,
+		};
+		const firstVisit = renderThreadLoadedEvents(props, { dataLoadedFiredForRef });
+		await waitFor(() =>
+			expect(firstVisit.logTraceEvent).toHaveBeenCalledTimes(1),
+		);
+		firstVisit.rerender({
+			...props,
+			spanPanelVariant: SpanDetailVariant.DOCKED,
+		});
+
+		const secondVisit = renderThreadLoadedEvents(props, {
+			dataLoadedFiredForRef,
+		});
+		await waitForSummary(secondVisit.queryClient, 'trace-ai');
+		secondVisit.rerender(props);
+
+		expect(firstVisit.logTraceEvent).toHaveBeenCalledTimes(1);
+		expect(secondVisit.logTraceEvent).not.toHaveBeenCalled();
+	});
+
+	it('reports the next trace with its own summary', async () => {
+		const { logTraceEvent, rerender } = renderThreadLoadedEvents({
+			traceId: 'trace-ai',
+			hasSpans: true,
+		});
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
+
+		rerender({ traceId: 'trace-ai-next', hasSpans: true });
+
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(2));
+		expect(logTraceEvent).toHaveBeenLastCalledWith(
+			TraceDetailEvents.DataLoaded,
+			expect.objectContaining({ totalSpansCount: 4, traceDurationMs: 500 }),
+		);
+	});
+
+	it('also reports an empty thread, once each, when an errored thread still holds spans', async () => {
+		const props: ThreadLoadedEventsProps = {
+			traceId: 'trace-ai',
+			hasSpans: true,
+			hasNoThread: true,
+		};
+		const { logTraceEvent, rerender } = renderThreadLoadedEvents(props);
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(2));
+		rerender(props);
+
+		expect(logTraceEvent).toHaveBeenCalledTimes(2);
+		expect(logTraceEvent).toHaveBeenCalledWith(
+			TraceDetailEvents.DataLoaded,
+			expect.any(Object),
+		);
+		expect(logTraceEvent).toHaveBeenCalledWith(
+			TraceDetailEvents.ThreadEmptyWithAiSummary,
+			expect.any(Object),
+		);
+	});
+});

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/__tests__/useThreadLoadedEvents.threadEmpty.test.tsx

@@ -0,0 +1,114 @@
+import { waitFor } from 'tests/test-utils';
+
+import { TraceDetailsTab } from '../../../constants';
+import { TraceDetailEvents } from '../../../events';
+import {
+	mockTraceSummaries,
+	renderThreadLoadedEvents,
+	ThreadLoadedEventsProps,
+	waitForSummary,
+} from './threadLoadedEventsTestUtils';
+
+describe('useThreadLoadedEvents: thread empty with AI summary', () => {
+	let summaryRequests: string[];
+
+	beforeEach(() => {
+		summaryRequests = mockTraceSummaries();
+	});
+
+	it('reports the trace summary when the thread is empty but the summary has AI usage', async () => {
+		const { logTraceEvent } = renderThreadLoadedEvents({
+			traceId: 'trace-ai',
+			hasNoThread: true,
+			interestedSpanId: 'span-1',
+		});
+
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
+		expect(logTraceEvent).toHaveBeenCalledWith(
+			TraceDetailEvents.ThreadEmptyWithAiSummary,
+			{
+				detailsTab: TraceDetailsTab.Thread,
+				spanId: 'span-1',
+				rootServiceName: 'agent',
+				rootServiceEntryPoint: 'POST /chat',
+				totalSpansCount: 12,
+				traceDurationMs: 3_000,
+				hadErrors: true,
+				hasMissingSpans: true,
+				inputTokens: 1_200,
+				outputTokens: 300,
+				cacheReadTokens: 50,
+				cacheWriteTokens: 10,
+				reasoningTokens: 40,
+				totalCost: 0.0123,
+			},
+		);
+	});
+
+	it('does not report when the summary has no AI usage', async () => {
+		const props: ThreadLoadedEventsProps = {
+			traceId: 'trace-no-ai',
+			hasNoThread: true,
+		};
+		const { logTraceEvent, rerender, queryClient } =
+			renderThreadLoadedEvents(props);
+		await waitForSummary(queryClient, 'trace-no-ai');
+		rerender(props);
+
+		expect(logTraceEvent).not.toHaveBeenCalled();
+	});
+
+	it('waits until the thread is known to be empty', async () => {
+		const { logTraceEvent, rerender, queryClient } = renderThreadLoadedEvents({
+			traceId: 'trace-ai',
+		});
+		await waitForSummary(queryClient, 'trace-ai');
+		rerender({ traceId: 'trace-ai' });
+
+		expect(logTraceEvent).not.toHaveBeenCalled();
+
+		rerender({ traceId: 'trace-ai', hasNoThread: true });
+
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
+	});
+
+	it('reports once per trace and reuses the loaded summary when the tab is visited again', async () => {
+		const threadEmptyFiredForRef = { current: '' };
+		const props: ThreadLoadedEventsProps = {
+			traceId: 'trace-ai',
+			hasNoThread: true,
+		};
+		const first = renderThreadLoadedEvents(props, { threadEmptyFiredForRef });
+		await waitFor(() => expect(first.logTraceEvent).toHaveBeenCalledTimes(1));
+		first.unmount();
+
+		const second = renderThreadLoadedEvents(props, {
+			threadEmptyFiredForRef,
+			queryClient: first.queryClient,
+		});
+
+		expect(second.queryClient.isFetching()).toBe(0);
+		expect(summaryRequests).toStrictEqual(['trace-ai']);
+		expect(second.logTraceEvent).not.toHaveBeenCalled();
+	});
+
+	it('reports the next trace with its own summary', async () => {
+		const { logTraceEvent, rerender } = renderThreadLoadedEvents({
+			traceId: 'trace-ai',
+			hasNoThread: true,
+		});
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(1));
+
+		rerender({ traceId: 'trace-ai-next', hasNoThread: true });
+
+		await waitFor(() => expect(logTraceEvent).toHaveBeenCalledTimes(2));
+		expect(logTraceEvent).toHaveBeenLastCalledWith(
+			TraceDetailEvents.ThreadEmptyWithAiSummary,
+			expect.objectContaining({
+				totalSpansCount: 4,
+				inputTokens: 80,
+				totalCost: 0.0004,
+			}),
+		);
+	});
+});

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/useThreadDataLoadedEvent.ts

@@ -1,45 +0,0 @@
-import { MutableRefObject, useEffect } from 'react';
-import { useGetTraceSummary } from 'api/generated/services/tracedetail';
-
-import { TraceDetailsTab } from '../../constants';
-import { TraceDetailEventKeys, TraceDetailEvents } from '../../events';
-import { TraceDetailLogEvent } from '../../hooks/useTraceDetailLogEvent';
-import { SpanDetailVariant } from '../../SpanDetailsPanel/constants';
-
-interface ThreadDataLoadedEventArgs {
-	traceId: string;
-	hasSpans: boolean;
-	spanPanelVariant: SpanDetailVariant;
-	firedForRef: MutableRefObject<string>;
-	logTraceEvent: TraceDetailLogEvent;
-}
-
-export function useThreadDataLoadedEvent({
-	traceId,
-	hasSpans,
-	spanPanelVariant,
-	firedForRef,
-	logTraceEvent,
-}: ThreadDataLoadedEventArgs): void {
-	// No keepPreviousData: a previous trace's summary must not be reported for this one.
-	const { data } = useGetTraceSummary(
-		{ traceID: traceId },
-		{ query: { enabled: !!traceId, refetchOnMount: false } },
-	);
-	const summary = data?.data;
-
-	useEffect(() => {
-		if (!traceId || firedForRef.current === traceId || !hasSpans || !summary) {
-			return;
-		}
-		firedForRef.current = traceId;
-		logTraceEvent(TraceDetailEvents.DataLoaded, {
-			[TraceDetailEventKeys.DetailsTab]: TraceDetailsTab.Thread,
-			[TraceDetailEventKeys.TotalSpansCount]: summary.totalSpansCount,
-			[TraceDetailEventKeys.TraceDurationMs]:
-				summary.endTimestampMillis - summary.startTimestampMillis,
-			[TraceDetailEventKeys.HadErrors]: summary.totalErrorSpansCount > 0,
-			[TraceDetailEventKeys.SpanPanelVariant]: spanPanelVariant,
-		});
-	}, [traceId, hasSpans, summary, spanPanelVariant, firedForRef, logTraceEvent]);
-}

frontend/src/pages/TraceDetailsV3/TraceDetailsThread/hooks/useThreadLoadedEvents.ts

@@ -0,0 +1,70 @@
+import { MutableRefObject, useEffect } from 'react';
+import { useGetTraceSummary } from 'api/generated/services/tracedetail';
+
+import { TraceDetailEvents } from '../../events';
+import { TraceDetailLogEvent } from '../../hooks/useTraceDetailLogEvent';
+import { SpanDetailVariant } from '../../SpanDetailsPanel/constants';
+import {
+	getThreadDataLoadedEventAttributes,
+	getThreadEmptyWithAiEventAttributes,
+} from '../utils';
+
+interface ThreadLoadedEventsArgs {
+	traceId: string;
+	interestedSpanId?: string;
+	hasSpans: boolean;
+	hasNoThread: boolean;
+	spanPanelVariant: SpanDetailVariant;
+	dataLoadedFiredForRef: MutableRefObject<string>;
+	threadEmptyFiredForRef: MutableRefObject<string>;
+	logTraceEvent: TraceDetailLogEvent;
+}
+
+export function useThreadLoadedEvents({
+	traceId,
+	interestedSpanId,
+	hasSpans,
+	hasNoThread,
+	spanPanelVariant,
+	dataLoadedFiredForRef,
+	threadEmptyFiredForRef,
+	logTraceEvent,
+}: ThreadLoadedEventsArgs): void {
+	// No keepPreviousData: a previous trace's summary must not be reported for this one.
+	const { data } = useGetTraceSummary(
+		{ traceID: traceId },
+		{ query: { enabled: !!traceId, refetchOnMount: false } },
+	);
+	const summary = data?.data;
+
+	useEffect(() => {
+		if (!traceId || !summary) {
+			return;
+		}
+		// Not exclusive: an errored thread can still hold spans, so each event keeps its own ref.
+		if (hasSpans && dataLoadedFiredForRef.current !== traceId) {
+			dataLoadedFiredForRef.current = traceId;
+			logTraceEvent(
+				TraceDetailEvents.DataLoaded,
+				getThreadDataLoadedEventAttributes(summary, spanPanelVariant),
+			);
+		}
+		if (hasNoThread && summary.ai && threadEmptyFiredForRef.current !== traceId) {
+			threadEmptyFiredForRef.current = traceId;
+			logTraceEvent(
+				TraceDetailEvents.ThreadEmptyWithAiSummary,
+				getThreadEmptyWithAiEventAttributes(summary, interestedSpanId),
+			);
+		}
+	}, [
+		traceId,
+		interestedSpanId,
+		hasSpans,
+		hasNoThread,
+		summary,
+		spanPanelVariant,
+		dataLoadedFiredForRef,
+		threadEmptyFiredForRef,
+		logTraceEvent,
+	]);
+}

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

@@ -1,7 +1,13 @@
-import type { SpantypesThreadSpanDTO } from 'api/generated/services/sigNoz.schemas';
+import type {
+	SpantypesGettableTraceSummaryDTO,
+	SpantypesThreadSpanDTO,
+} from 'api/generated/services/sigNoz.schemas';
 import { isAxiosError } from 'axios';
 
 import { collectToolCallKeys } from '../AIThreadMessage/utils';
+import { TraceDetailsTab } from '../constants';
+import { TraceDetailEventKeys } from '../events';
+import { SpanDetailVariant } from '../SpanDetailsPanel/constants';
 import { InterestedSpanStatus, ThreadSpan } from './types';
 
 /** Derives SpanV3's `timestamp` and `service.name`, as the waterfall does. */
@@ -47,3 +53,44 @@ export function getInterestedSpanStatus(
 		? InterestedSpanStatus.Found
 		: InterestedSpanStatus.NoIOMessages;
 }
+
+function getThreadSummaryAttributes(
+	summary: SpantypesGettableTraceSummaryDTO,
+): Record<string, unknown> {
+	return {
+		[TraceDetailEventKeys.DetailsTab]: TraceDetailsTab.Thread,
+		[TraceDetailEventKeys.TotalSpansCount]: summary.totalSpansCount,
+		[TraceDetailEventKeys.TraceDurationMs]:
+			summary.endTimestampMillis - summary.startTimestampMillis,
+		[TraceDetailEventKeys.HadErrors]: summary.totalErrorSpansCount > 0,
+	};
+}
+
+export function getThreadDataLoadedEventAttributes(
+	summary: SpantypesGettableTraceSummaryDTO,
+	spanPanelVariant: SpanDetailVariant,
+): Record<string, unknown> {
+	return {
+		...getThreadSummaryAttributes(summary),
+		[TraceDetailEventKeys.SpanPanelVariant]: spanPanelVariant,
+	};
+}
+
+export function getThreadEmptyWithAiEventAttributes(
+	summary: SpantypesGettableTraceSummaryDTO,
+	interestedSpanId: string | undefined,
+): Record<string, unknown> {
+	return {
+		...getThreadSummaryAttributes(summary),
+		[TraceDetailEventKeys.SpanId]: interestedSpanId,
+		[TraceDetailEventKeys.RootServiceName]: summary.rootServiceName,
+		[TraceDetailEventKeys.RootServiceEntryPoint]: summary.rootServiceEntryPoint,
+		[TraceDetailEventKeys.HasMissingSpans]: summary.hasMissingSpans,
+		[TraceDetailEventKeys.InputTokens]: summary.ai?.tokens.input,
+		[TraceDetailEventKeys.OutputTokens]: summary.ai?.tokens.output,
+		[TraceDetailEventKeys.CacheReadTokens]: summary.ai?.tokens.cacheRead,
+		[TraceDetailEventKeys.CacheWriteTokens]: summary.ai?.tokens.cacheWrite,
+		[TraceDetailEventKeys.ReasoningTokens]: summary.ai?.tokens.reasoning,
+		[TraceDetailEventKeys.TotalCost]: summary.ai?.totalCost,
+	};
+}

frontend/src/pages/TraceDetailsV3/events.ts

@@ -14,6 +14,7 @@ export enum TraceDetailEvents {
 	SpanPercentileAttributeChanged = 'Trace Detail: Span percentile attribute changed',
 	SpanDetailsOpened = 'Trace Detail: Span details opened',
 	DetailsTabChanged = 'Trace Detail: Details tab changed',
+	ThreadEmptyWithAiSummary = 'Trace Detail: Thread empty with AI summary',
 }
 
 export enum TraceDetailEventKeys {
@@ -48,6 +49,16 @@ export enum TraceDetailEventKeys {
 	Selected = 'selected',
 	// Data loaded / span details opened: which tab the user is on
 	DetailsTab = 'detailsTab',
+	// Thread empty with AI summary (reuses SpanId, DetailsTab, TotalSpansCount, TraceDurationMs, HadErrors)
+	RootServiceName = 'rootServiceName',
+	RootServiceEntryPoint = 'rootServiceEntryPoint',
+	HasMissingSpans = 'hasMissingSpans',
+	InputTokens = 'inputTokens',
+	OutputTokens = 'outputTokens',
+	CacheReadTokens = 'cacheReadTokens',
+	CacheWriteTokens = 'cacheWriteTokens',
+	ReasoningTokens = 'reasoningTokens',
+	TotalCost = 'totalCost',
 }
 
 export type TraceDetailView = 'v2' | 'v3';

frontend/src/pages/TraceDetailsV3/index.tsx

@@ -17,6 +17,7 @@ function TraceDetailsV3(): JSX.Element {
 	// between traces (the route component stays mounted) re-fires it once each.
 	const dataLoadedFiredForRef = useRef<string>('');
 	const threadDataLoadedFiredForRef = useRef<string>('');
+	const threadEmptyFiredForRef = useRef<string>('');
 
 	const handleFilteredSpansChange = useCallback(
 		(spanIds: string[], isActive: boolean): void => {
@@ -40,7 +41,10 @@ function TraceDetailsV3(): JSX.Element {
 					dataLoadedFiredForRef={dataLoadedFiredForRef}
 				/>
 			) : (
-				<TraceDetailsThread dataLoadedFiredForRef={threadDataLoadedFiredForRef} />
+				<TraceDetailsThread
+					dataLoadedFiredForRef={threadDataLoadedFiredForRef}
+					threadEmptyFiredForRef={threadEmptyFiredForRef}
+				/>
 			)}
 		</TraceDetailsWrapper>
 	);

frontend/src/pages/TraceDetailsV3/stories/TraceDetailsV3.stories.mocks.tsx

@@ -13,7 +13,7 @@ import type { SpantypesPostableTraceAggregationsDTO } from 'api/generated/servic
 import { LOCALSTORAGE } from 'constants/localStorage';
 import { USER_PREFERENCES } from 'constants/userPreferences';
 import { screen, userEvent, within } from 'storybook/test';
-import type { QueryRangeRequestV5 } from 'types/api/v5/queryRange';
+import type { QueryRangeRequestV5, RawRow } from 'types/api/v5/queryRange';
 
 import {
 	choiceControl,
@@ -150,6 +150,12 @@ export const traceDetailsMocks = defineStoryMocks({
 			value: 8,
 			max: 20,
 		}),
+		traceOnlyLogs: toggleControl('Logs only on the trace', {
+			group: PANEL,
+			description:
+				'The span has no logs of its own but the trace does, which is the Logs tab\'s "view logs for the current trace" state.',
+			value: false,
+		}),
 		exportState: choiceControl<ExportState>('Trace export', {
 			group: EXPORT,
 			description:
@@ -165,6 +171,12 @@ export const traceDetailsMocks = defineStoryMocks({
 			errors: values.errors,
 			traceStart: traceStartOf(),
 		};
+		const spanLogRowsFor = (body: QueryRangeRequestV5): RawRow[] => {
+			const scope = spanLogScopeOf(body);
+			const count =
+				values.traceOnlyLogs && scope !== 'trace' ? 0 : values.spanLogs;
+			return spanLogRows(count, trace, scope);
+		};
 
 		return [
 			rest.post('http://localhost/api/v1/export_raw_data', (_req, res, ctx) => {
@@ -266,9 +278,7 @@ export const traceDetailsMocks = defineStoryMocks({
 
 					if (requestType === 'raw') {
 						return queryRangeV5RawResponse(
-							signalOf(body) === 'logs'
-								? spanLogRows(values.spanLogs, trace, spanLogScopeOf(body))
-								: spanMatchRows(trace),
+							signalOf(body) === 'logs' ? spanLogRowsFor(body) : spanMatchRows(trace),
 						);
 					}
 

frontend/src/pages/TraceDetailsV3/stories/TraceDetailsV3.stories.tsx

@@ -17,7 +17,6 @@ import {
 	focusSpanIndex,
 	scenarioSpanCount,
 	spanIdAt,
-	STORY_TRACE_ID,
 } from './__story_mockdata__/traceDetails';
 import {
 	openRowMenu,
@@ -249,18 +248,35 @@ export const SpanPercentileOpen: Story = {
 	},
 };
 
-/** The span's trace id clicked in the panel, which copies it. */
-export const TraceIdCopiedToast: Story = {
+/** The span has no logs of its own but its trace does, so the Logs tab points to the trace's. */
+export const SpanPanelTraceOnlyLogs: Story = {
+	args: { traceOnlyLogs: true },
+	play: async ({ canvasElement }): Promise<void> => {
+		await userEvent.click(
+			await within(canvasElement).findByRole('tab', { name: /Logs/ }, untilLoaded),
+		);
+		await expect(
+			await within(canvasElement).findByText(
+				'No logs found for selected span. View logs for the current trace.',
+				undefined,
+				untilLoaded,
+			),
+		).toBeVisible();
+	},
+};
+
+/** The span panel's trace id copied with its copy button, which turns into a check. */
+export const TraceIdCopied: Story = {
 	play: async ({ canvasElement }): Promise<void> => {
 		await userEvent.click(
 			await within(canvasElement).findByRole(
 				'button',
-				{ name: STORY_TRACE_ID },
+				{ name: 'Copy trace ID' },
 				untilLoaded,
 			),
 		);
 		await expect(
-			await screen.findByText('Trace ID copied to clipboard'),
+			await within(canvasElement).findByRole('button', { name: 'Copied' }),
 		).toBeVisible();
 	},
 };

frontend/src/pages/TracesModulePage/stories/TracesModulePage.stories.mocks.tsx

@@ -4,9 +4,14 @@
  */
 
 import { rest } from 'msw';
+import remove from 'api/browser/localstorage/remove';
+import set from 'api/browser/localstorage/set';
+import { LOCALSTORAGE } from 'constants/localStorage';
 import { QueryParams } from 'constants/query';
 import ROUTES from 'constants/routes';
+import { USER_PREFERENCES } from 'constants/userPreferences';
 import { ExplorerViews } from 'pages/LogsExplorer/utils';
+import { spanPercentilesResponse } from 'pages/TraceDetailsV3/stories/__story_mockdata__/traceDetails';
 import type { QueryRangeRequestV5 } from 'types/api/v5/queryRange';
 import { explorerViewToPanelType } from 'utils/explorerUtils';
 
@@ -27,6 +32,10 @@ import {
 import {
 	exportDashboardsResponse,
 	savedTraceViewsResponse,
+	SPAN_LOGS_STATES,
+	spanLogRows,
+	spanLogScopeOf,
+	type SpanLogsState,
 	traceAttributeValuesResponse,
 	traceFieldKeysResponse,
 	traceFieldValues,
@@ -34,8 +43,11 @@ import {
 	traceQuickFiltersResponse,
 	traceRootSpanRows,
 	traceSpanRows,
+	TRACE_SUMMARY_STATES,
+	traceSummaryResponse,
 	TRACES_EXPLORER_VIEWS,
 	TRACES_TABS,
+	type TraceSummaryState,
 	type TracesTab,
 } from './__story_mockdata__/traces';
 
@@ -65,6 +77,8 @@ const tracesRoute = ({ tab, view }: RouteValues): string => {
 interface RawQuerySpec {
 	limit?: number;
 	offset?: number;
+	signal?: string;
+	filter?: { expression?: string };
 }
 
 const rawSpecOf = (body: QueryRangeRequestV5): RawQuerySpec => {
@@ -73,6 +87,9 @@ const rawSpecOf = (body: QueryRangeRequestV5): RawQuerySpec => {
 	return spec as RawQuerySpec;
 };
 
+// The summary has no window of its own; its bounds wrap the span the list showed.
+const listWindow = { start: 0, end: 0 };
+
 export const tracesMocks = defineStoryMocks({
 	controls: {
 		tab: choiceControl<TracesTab>('Tab', {
@@ -102,6 +119,26 @@ export const tracesMocks = defineStoryMocks({
 				'Answers 503 on the spans of the services that fail, which is what the status column and the error colouring read.',
 			value: true,
 		}),
+		spanDrawer: toggleControl('Span drawer', {
+			group: LIST,
+			description:
+				'The `TRACES_SPAN_DRAWER_ENABLED` localStorage flag the span drawer ships behind. Off, a row click opens the trace page.',
+			value: false,
+		}),
+		traceSummary: choiceControl<TraceSummaryState>('Trace summary', {
+			group: LIST,
+			description:
+				'What the span drawer gets for the trace start and end. Not found falls back to span-only logs; loading holds the logs tab.',
+			options: TRACE_SUMMARY_STATES,
+			value: 'found',
+		}),
+		spanLogs: choiceControl<SpanLogsState>('Span logs', {
+			group: LIST,
+			description:
+				"What the span drawer's Logs tab gets. `span`: the span's logs with context either side; `trace only`: none for the span but some for the trace; `none`; `loading` and `error` hold or fail only the log queries.",
+			options: SPAN_LOGS_STATES,
+			value: 'span',
+		}),
 		warning: toggleControl('Query warning', {
 			group: LIST,
 			description: 'Attaches a warning to the response, next to the toolbar.',
@@ -169,6 +206,96 @@ export const tracesMocks = defineStoryMocks({
 			response.json(exportDashboardsResponse),
 		),
 
+		rest.post(
+			'http://localhost/api/v1/span_percentile',
+			response.json(spanPercentilesResponse),
+		),
+
+		// Answers on its own control rather than the Data one, so the drawer's
+		// fallback and waiting states are reachable with the list loaded.
+		rest.get(
+			'http://localhost/api/v1/traces/:traceId/summary',
+			(req, res, ctx) => {
+				if (values.traceSummary === 'loading') {
+					return res(ctx.delay('infinite'));
+				}
+				const summary =
+					values.traceSummary === 'found'
+						? traceSummaryResponse({
+								traceId: String(req.params.traceId),
+								count: values.spans,
+								...listWindow,
+							})
+						: null;
+
+				return summary
+					? res(ctx.status(200), ctx.json(summary))
+					: res(ctx.status(404), ctx.json({ status: 'error' }));
+			},
+		),
+
+		// The drawer's percentile panel dereferences this preference without a guard.
+		rest.get(
+			'http://localhost/api/v1/user/preferences/:name',
+			response.json((req) => ({
+				status: 'success',
+				data: {
+					name: String(req.params.name),
+					description: 'storybook',
+					valueType: 'array',
+					defaultValue: [],
+					allowedValues: [],
+					allowedScopes: ['user'],
+					value:
+						String(req.params.name) ===
+						USER_PREFERENCES.SPAN_PERCENTILE_RESOURCE_ATTRIBUTES
+							? ['service.name']
+							: [],
+				},
+			})),
+		),
+
+		// The drawer's log queries answer on their own control, so they can hang or
+		// fail with the list loaded. Anything else falls through to the next handler.
+		rest.post('http://localhost/api/v5/query_range', async (req, res, ctx) => {
+			const body = (await req.json()) as QueryRangeRequestV5;
+			const { signal, filter } = rawSpecOf(body);
+			if (signal !== 'logs') {
+				return undefined;
+			}
+			if (values.spanLogs === 'loading') {
+				return res(ctx.delay('infinite'));
+			}
+			if (values.spanLogs === 'error') {
+				return res(
+					ctx.status(500),
+					ctx.json({ status: 'error', error: 'storybook logs failure' }),
+				);
+			}
+
+			const expression = filter?.expression ?? '';
+			const scope = spanLogScopeOf(expression);
+			const answers =
+				values.spanLogs === 'span' ||
+				(values.spanLogs === 'trace only' && scope === 'trace');
+
+			return res(
+				ctx.status(200),
+				ctx.json(
+					queryRangeV5RawResponse(
+						answers
+							? spanLogRows({
+									scope,
+									expression,
+									startMicros: body.start,
+									endMicros: body.end,
+								})
+							: [],
+					),
+				),
+			);
+		}),
+
 		rest.post(
 			'http://localhost/api/v5/query_range',
 			response.json(async (req) => {
@@ -195,6 +322,9 @@ export const tracesMocks = defineStoryMocks({
 					: undefined;
 
 				if (requestType === 'raw' || requestType === 'trace') {
+					listWindow.start = start;
+					listWindow.end = end;
+
 					return queryRangeV5RawResponse(
 						requestType === 'trace' ? traceRootSpanRows(rows) : traceSpanRows(rows),
 						{
@@ -232,4 +362,11 @@ export const tracesMocks = defineStoryMocks({
 		),
 	],
 	config: (values) => ({ route: tracesRoute(values) }),
+	effect: (values) => {
+		if (values.spanDrawer) {
+			set(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED, 'true');
+		} else {
+			remove(LOCALSTORAGE.TRACES_SPAN_DRAWER_ENABLED);
+		}
+	},
 });

frontend/src/pages/TracesModulePage/stories/TracesModulePage.stories.tsx

@@ -25,7 +25,7 @@ const pageStory = storyMocks(tracesMocks, { layout: 'app' });
  * Route: `/traces-explorer`.
  */
 const meta = {
-	title: 'Pages/Traces/Explorer',
+	title: 'Pages/Traces/Explorer/Overview',
 	tags: ['play'],
 	component: TracesModulePage,
 	...pageStory,

frontend/src/pages/TracesModulePage/stories/__story_mockdata__/traces.ts

@@ -17,6 +17,7 @@ import {
 } from 'api/generated/services/sigNoz.schemas';
 import type {
 	GetQuickFilters200,
+	GetTraceSummary200,
 	ListSavedViews200,
 	TelemetrytypesTelemetryFieldKeyDTO,
 } from 'api/generated/services/sigNoz.schemas';
@@ -173,6 +174,22 @@ const flatSpanRows = ({
 		};
 	});
 
+/** The list API's event shape: `attributes`, where the trace API says `attributeMap`. */
+const exceptionEvent = (
+	timestamp: string,
+): {
+	name: string;
+	timeUnixNano: number;
+	attributes: Record<string, string>;
+} => ({
+	name: 'exception',
+	timeUnixNano: new Date(timestamp).getTime() * 1_000_000,
+	attributes: {
+		'exception.type': 'UpstreamTimeoutError',
+		'exception.message': 'upstream did not answer within 1s',
+	},
+});
+
 /** The List view returns every span field, with resource and attribute fields nested in maps. */
 export const traceSpanRows = (options: SpanRowsOptions): RawRow[] =>
 	flatSpanRows(options).map(
@@ -182,6 +199,10 @@ export const traceSpanRows = (options: SpanRowsOptions): RawRow[] =>
 				...data,
 				attributes: {},
 				resource: { 'service.name': serviceName },
+				events: data.has_error ? [exceptionEvent(timestamp)] : [],
+				links: data.has_error
+					? [{ traceId: traceIdAt(0), spanId: spanIdAt(0) }]
+					: [],
 			},
 		}),
 	);
@@ -196,6 +217,122 @@ export const traceRootSpanRows = (options: SpanRowsOptions): RawRow[] =>
 		},
 	}));
 
+export const TRACE_SUMMARY_STATES = ['found', 'not found', 'loading'] as const;
+
+export type TraceSummaryState = (typeof TRACE_SUMMARY_STATES)[number];
+
+const TRACE_PADDING_MS = 250;
+
+/** Null for a trace the list never showed. */
+export const traceSummaryResponse = ({
+	traceId,
+	count,
+	start,
+	end,
+}: Pick<SpanRowsOptions, 'count' | 'start' | 'end'> & {
+	traceId: string;
+}): GetTraceSummary200 | null => {
+	const index = rowWindow({ count, offset: 0, limit: count }).find(
+		(i) => traceIdAt(i) === traceId,
+	);
+	if (index === undefined) {
+		return null;
+	}
+	const spanStart = new Date(timestampAt(index, start, end)).getTime();
+	const span = SPANS[index % SPANS.length];
+
+	return {
+		status: 'success',
+		data: {
+			startTimestampMillis: spanStart - TRACE_PADDING_MS,
+			endTimestampMillis: spanStart + span.durationMs + TRACE_PADDING_MS,
+			rootServiceName: SPANS[0].service,
+			rootServiceEntryPoint: SPANS[0].operation,
+			rootSpanStatusCode: '200',
+			totalSpansCount: SPANS.length,
+			totalErrorSpansCount: SPANS.filter(({ failing }) => failing).length,
+			hasMissingSpans: false,
+		},
+	};
+};
+
+export const SPAN_LOGS_STATES = [
+	'span',
+	'trace only',
+	'none',
+	'loading',
+	'error',
+] as const;
+
+export type SpanLogsState = (typeof SPAN_LOGS_STATES)[number];
+
+/**
+ * Which of the drawer's log queries is asking: the span's own logs, the context
+ * either side of them, or the whole trace when the span has none.
+ */
+export type SpanLogScope = 'span' | 'before' | 'after' | 'trace';
+
+export const spanLogScopeOf = (expression: string): SpanLogScope => {
+	if (expression.includes('span_id')) {
+		return 'span';
+	}
+	if (expression.includes('id <')) {
+		return 'before';
+	}
+	return expression.includes('id >') ? 'after' : 'trace';
+};
+
+const SPAN_LOG_BODIES = [
+	'request received',
+	'cache miss, querying orders',
+	'payment provider timed out',
+	'response sent',
+];
+
+const CONTEXT_OFFSET_MS: Record<SpanLogScope, number> = {
+	before: -60_000,
+	span: 0,
+	after: 60_000,
+	trace: 0,
+};
+
+/**
+ * Log rows for one of the drawer's queries, placed in the middle of the window
+ * it asked for. The span-log queries send that window in microseconds.
+ */
+export const spanLogRows = ({
+	scope,
+	expression,
+	startMicros,
+	endMicros,
+}: {
+	scope: SpanLogScope;
+	expression: string;
+	startMicros: number;
+	endMicros: number;
+}): RawRow[] => {
+	const traceId = expression.match(/trace_id = '([^']+)'/)?.[1] ?? '';
+	const spanId = expression.match(/span_id = '([^']+)'/)?.[1] ?? '';
+	const middle = (startMicros + endMicros) / 2 / 1e3;
+
+	return SPAN_LOG_BODIES.map((body, index) => ({
+		timestamp: new Date(
+			middle + CONTEXT_OFFSET_MS[scope] + index * 100,
+		).toISOString(),
+		data: {
+			body,
+			id: `storybook-${scope}-log-${index + 1}`,
+			trace_id: traceId,
+			span_id: scope === 'span' ? spanId : '',
+			severity_text: index === 2 ? 'ERROR' : 'INFO',
+			severity_number: index === 2 ? 17 : 9,
+			attributes_string: {},
+			resources_string: { 'service.name': SPANS[0].service },
+			scope_name: '',
+		},
+	}));
+};
+
 const { resource, attribute } = TelemetrytypesFieldContextDTO;
 const { string: stringType, bool } = TelemetrytypesFieldDataTypeDTO;
 

frontend/src/pages/TracesModulePage/stories/spanDrawer/SpanDrawer.stories.tsx

@@ -0,0 +1,191 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, screen, userEvent, waitFor, within } from 'storybook/test';
+
+import { storyMocks } from '@/storybook/controls/defineStoryMocks';
+import type { PageStoryArgs } from '@/storybook/runtime/resolveStory';
+
+import { tracesMocks } from '../TracesModulePage.stories.mocks';
+
+import TracesModulePage from '../../TracesModulePage';
+
+type TracesArgs = PageStoryArgs<typeof tracesMocks>;
+
+const pageStory = storyMocks(tracesMocks, { layout: 'app' });
+
+/**
+ * The span details drawer the explorer list opens on a row, one story per state
+ * of its trace summary and its Logs tab. Every story opens the same failing
+ * span; the Trace summary and Span logs controls pick what the drawer gets.
+ *
+ * Route: `/traces-explorer`.
+ */
+const meta = {
+	title: 'Pages/Traces/Explorer/Span Drawer',
+	tags: ['play'],
+	component: TracesModulePage,
+	...pageStory,
+	parameters: { ...pageStory.parameters },
+	args: { spanDrawer: true },
+} satisfies Meta<TracesArgs>;
+
+export default meta;
+
+type Story = StoryObj<TracesArgs>;
+
+/** The page fetches before it renders its rows, which outlasts the 1s default. */
+const untilLoaded = { timeout: 15_000 };
+
+// The quick filters list the same span name, so the row is found by its test
+// id; the table renders its rows a few at a time, so it waits for this one.
+const openDrawer = async (): Promise<HTMLElement> => {
+	const row = await waitFor((): HTMLElement => {
+		const match = screen
+			.getAllByTestId(/^traces-table-row-/)
+			.find((candidate) => candidate.textContent?.includes('POST /api/orders'));
+
+		expect(match).toBeDefined();
+
+		return match as HTMLElement;
+	}, untilLoaded);
+
+	await userEvent.click(within(row).getByText('POST /api/orders'));
+
+	return screen.findByTestId('span-details-drawer');
+};
+
+const openLogsTab = async (): Promise<HTMLElement> => {
+	const drawer = await openDrawer();
+
+	await userEvent.click(within(drawer).getByRole('tab', { name: /Logs/ }));
+
+	return drawer;
+};
+
+/**
+ * The drawer on a failing span: its summary with % exec time, attributes, the
+ * exception event and a linked span, with up and down stepping through the page.
+ */
+export const Default: Story = {
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		const drawer = await openDrawer();
+
+		await expect(
+			await within(drawer).findByText(
+				/of total exec time/,
+				undefined,
+				untilLoaded,
+			),
+		).toBeVisible();
+	},
+};
+
+/** The Logs tab with the span's logs, between the logs just before and after them. */
+export const Logs: Story = {
+	args: { spanLogs: 'span' },
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		const drawer = await openLogsTab();
+
+		await expect(
+			(
+				await within(drawer).findAllByText(
+					/payment provider timed out/,
+					undefined,
+					untilLoaded,
+				)
+			)[0],
+		).toBeVisible();
+	},
+};
+
+/** The span has no logs of its own but its trace does, so the tab points to the trace's. */
+export const TraceOnlyLogs: Story = {
+	args: { spanLogs: 'trace only' },
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		const drawer = await openLogsTab();
+
+		await expect(
+			await within(drawer).findByText(
+				'No logs found for selected span. View logs for the current trace.',
+				undefined,
+				untilLoaded,
+			),
+		).toBeVisible();
+	},
+};
+
+/** Neither the span nor its trace has logs. */
+export const NoLogs: Story = {
+	args: { spanLogs: 'none' },
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		const drawer = await openLogsTab();
+
+		await expect(
+			await within(drawer).findByText(
+				'No logs found for this trace.',
+				undefined,
+				untilLoaded,
+			),
+		).toBeVisible();
+	},
+};
+
+/**
+ * The trace summary 404s, so the drawer speaks only for the span: no % exec
+ * time, logs over the span's own window and no trace-wide logs check.
+ */
+export const WithoutTraceSummary: Story = {
+	args: { traceSummary: 'not found', spanLogs: 'none' },
+	// The deliberate 404 is the state under test.
+	parameters: { allowConsoleErrors: true },
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		const drawer = await openLogsTab();
+
+		await expect(
+			await within(drawer).findByText(
+				'No logs found for this span.',
+				undefined,
+				untilLoaded,
+			),
+		).toBeVisible();
+		await expect(
+			within(drawer).queryByText(/of total exec time/),
+		).not.toBeInTheDocument();
+	},
+};
+
+/** The trace summary never answers: the Logs tab waits and its explorer link is off. */
+export const TraceSummaryLoading: Story = {
+	args: { traceSummary: 'loading' },
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		await openLogsTab();
+
+		await expect(
+			await screen.findByTestId('open-in-explorer-button'),
+		).toHaveAttribute('aria-disabled', 'true');
+	},
+};
+
+/** The log queries fail while the rest of the drawer renders. */
+export const LogsError: Story = {
+	args: { spanLogs: 'error' },
+	// The deliberate 500 is the state under test.
+	parameters: { allowConsoleErrors: true },
+	play: async ({ mount }): Promise<void> => {
+		await mount();
+		const drawer = await openLogsTab();
+
+		await expect(
+			await within(drawer).findByText(
+				/Something went wrong/,
+				undefined,
+				untilLoaded,
+			),
+		).toBeVisible();
+	},
+};

tests/e2e/drivers/antd.ts

@@ -64,8 +64,17 @@ export function antdDriver(page: Page): Antd {
 		 */
 		pickByName: async (select, name) => {
 			const before = await antd.selectedTags(select).count();
-			await select.click();
-			await expect(select).toHaveClass(/ant-select-open/);
+			// A re-render of the surrounding form (e.g. after a query edit) can close
+			// the select as the click opens it; re-click only while it is still closed.
+			await expect(async () => {
+				const isOpen = await select.evaluate((node) =>
+					node.classList.contains('ant-select-open'),
+				);
+				if (!isOpen) {
+					await select.click();
+				}
+				await expect(select).toHaveClass(/ant-select-open/, { timeout: 2_000 });
+			}).toPass({ timeout: 15_000 });
 
 			// `fill` rather than `keyboard.type`: every keystroke re-runs antd's
 			// filter, so typing a ~30 character name costs seconds per pick, while

tests/e2e/drivers/query-builder.ts

@@ -0,0 +1,261 @@
+/**
+ * AI-owned. Generated and maintained by coding agents alongside the specs that
+ * use it. Do not hand-edit: regenerate it with the spec that needs the change.
+ */
+import {
+	expect,
+	type Locator,
+	type Page,
+	type Request,
+} from '@playwright/test';
+
+import { watchConsole } from './console';
+import { isQueryRange } from './query-range-mock';
+import { dismissQuickFiltersAnnouncement } from './logs/explorer';
+
+import { driver, kit } from './kit';
+import { EXPLORER, RELATIVE_TIME } from './query-builder/constants';
+import {
+	addOnsAt,
+	exactly,
+	metricAt,
+	openSelect,
+} from './query-builder/controls';
+import { afterRender, editorAt } from './query-builder/editor';
+import type { QueryBuilderDriver, V5Body } from './query-builder/types';
+
+function queryBuilderDriver(page: Page): QueryBuilderDriver {
+	const bodies: V5Body[] = [];
+	page.on('request', (request: Request) => {
+		if (isQueryRange(request.url()) && request.method() === 'POST') {
+			bodies.push(request.postDataJSON() as V5Body);
+		}
+	});
+	const consoleWatch = watchConsole(page, {
+		// ANTLR reports every partial expression on console.error, prefixed
+		// with its position (`line 1:14 ...`).
+		ignore: ['line 1:', 'line 2:', 'line 3:'],
+	});
+
+	// Waits on a request the action started: a response to one already in
+	// flight (e.g. after a structural edit) would end the wait too early.
+	const firedBy = async (action: () => Promise<void>): Promise<V5Body[]> => {
+		const before = bodies.length;
+		const answered = page
+			.waitForRequest((r) => isQueryRange(r.url()) && r.method() === 'POST')
+			.then((request) => request.response());
+		await action();
+		await answered;
+		return bodies.slice(before);
+	};
+
+	const qb: QueryBuilderDriver = {
+		async openExplorer(path, { query, raw, view } = {}) {
+			await dismissQuickFiltersAnnouncement(page);
+			const params = [`relativeTime=${RELATIVE_TIME}`];
+			if (view) {
+				params.push(`panelTypes=${encodeURIComponent(JSON.stringify(view))}`);
+			}
+			const composite =
+				raw ??
+				(query === undefined
+					? undefined
+					: encodeURIComponent(JSON.stringify(query)));
+			if (composite !== undefined) {
+				params.push(`compositeQuery=${composite}`);
+			}
+			const url = `${path}?${params.join('&')}`;
+			// The metrics explorer runs nothing until a metric is chosen; its
+			// settle point is the metric list instead.
+			if (path === EXPLORER.metrics) {
+				await Promise.all([
+					page.waitForResponse((r) => r.url().includes('/api/v2/metrics')),
+					page.goto(url),
+				]);
+				await expect(qb.query('A').filter.content()).toBeVisible();
+				return [];
+			}
+			const fired = await firedBy(async () => {
+				await page.goto(url);
+			});
+			await expect(qb.query('A').filter.content()).toBeVisible();
+			return fired;
+		},
+		query(name) {
+			const root = (): Locator => page.getByTestId(`query-${name}`);
+			// Index-suffixed testids follow screen position, not the query's
+			// name (A, C, B after a delete and re-add): match them in the block.
+			const signalSelect = (): Locator =>
+				root().locator('[data-testid^="query-data-source-selector-"]');
+			return {
+				root,
+				filter: editorAt(page, () =>
+					root().getByTestId('query-where-clause-editor'),
+				),
+				filterStatus: () => root().getByTestId('query-validation-status'),
+				aggregation: editorAt(page, () =>
+					root().getByTestId('query-aggregation-editor'),
+				),
+				step: () => root().getByTestId('input-Seconds'),
+				metric: metricAt(page, root),
+				addOns: addOnsAt(page, root),
+				actions: () => root().getByTestId('query-actions'),
+				menuItem: (action) =>
+					page.getByTestId(`query-actions-item-${action}-query`),
+				async clone() {
+					await root().getByTestId('query-actions').click();
+					await page.getByTestId('query-actions-item-clone-query').click();
+					await afterRender(page);
+				},
+				async delete() {
+					await root().getByTestId('query-actions').click();
+					await page.getByTestId('query-actions-item-delete-query').click();
+					await expect(root()).toHaveCount(0);
+					await afterRender(page);
+				},
+				async toggleVisibility() {
+					await root().getByTestId('qb-entity-visibility').click();
+					// The icon is the only visible change and carries no state.
+					await afterRender(page);
+				},
+				collapse: () => root().getByTestId('qb-entity-collapse').click(),
+				signal: () => signalSelect().locator('.ant-select-selection-item'),
+				async setSignal(label) {
+					const options = await openSelect(page, signalSelect());
+					await options.filter({ hasText: exactly(label) }).click();
+					await expect(this.signal()).toHaveText(label);
+				},
+			};
+		},
+		tab: (queryType) => page.getByTestId(`query-type-tab-${queryType}`),
+		promql: () => page.getByTestId('promql-query-input').first(),
+		async addQuery(name) {
+			await page.getByTestId('add-new-query-button').click();
+			const block = qb.query(name);
+			await expect(block.filter.content()).toBeVisible();
+			return block;
+		},
+		queryNames: () =>
+			page.locator('[data-testid^="query-"]').evaluateAll((nodes) =>
+				nodes
+					.map((node) => node.getAttribute('data-testid') ?? '')
+					.filter((id) => /^query-[A-Z]$/.test(id))
+					.map((id) => id.slice('query-'.length)),
+			),
+		formula(name) {
+			const root = (): Locator => page.getByTestId(`formula-${name}`);
+			return {
+				root,
+				expression: () => root().getByTestId('formula-expression'),
+				legend: () => root().getByTestId('formula-legend'),
+				async delete() {
+					await root().getByTestId('qb-entity-delete').click();
+					await expect(root()).toHaveCount(0);
+					// The block leaves the DOM before the editor's draft follows.
+					await afterRender(page);
+				},
+			};
+		},
+		async addFormula(name) {
+			await page.getByTestId('add-formula-button').click();
+			const formula = qb.formula(name);
+			await expect(formula.expression()).toBeVisible();
+			return formula;
+		},
+		traceOperator: {
+			root: () => page.getByTestId('trace-operator'),
+			// No testid; the label is followed by a "Beta" tag inside the button.
+			addButton: () =>
+				page.getByRole('button').filter({ hasText: /^Add Trace Matching/ }),
+			async add() {
+				await qb.traceOperator.addButton().click();
+				await expect(qb.traceOperator.editor.content()).toBeVisible();
+			},
+			async remove() {
+				// The only direct button child: the trash icon, no testid.
+				await qb.traceOperator.root().locator(':scope > button').click();
+				await expect(qb.traceOperator.root()).toHaveCount(0);
+			},
+			editor: editorAt(page, () => page.getByTestId('trace-operator-editor')),
+		},
+		async addToDashboard(title) {
+			await page.getByTestId('explorer-add-to-dashboard').click();
+			const dialog = page.getByTestId('export-panel-dialog');
+			await dialog
+				.getByTestId('export-dashboard-select')
+				.locator('input')
+				.fill(title);
+			await dialog.locator(`.ant-select-item-option[title="${title}"]`).click();
+			await dialog.getByTestId('export-panel-export').click();
+			await page.waitForURL(/\/panel\/new\?/);
+			await expect(qb.query('A').filter.content()).toBeVisible();
+		},
+		runButton: () => page.locator('[data-run-query-btn]').first(),
+		// No testid on the container.
+		logsResults: () => page.locator('.logs-explorer-views'),
+		async run() {
+			await afterRender(page);
+			return firedBy(() => qb.runButton().click());
+		},
+		async rerunUntil(read, expected) {
+			await expect(async () => {
+				await expect(qb.runButton()).toHaveText(/Run Query/);
+				await afterRender(page);
+				await qb.runButton().click();
+				await expect.poll(read, { timeout: 3_000 }).toEqual(expected);
+			}).toPass({ timeout: 25_000 });
+		},
+		async runShortcut() {
+			await afterRender(page);
+			return firedBy(() => page.keyboard.press('ControlOrMeta+Enter'));
+		},
+		quickFilter(title, value) {
+			const checkbox = (): Locator =>
+				page.getByTestId(`checkbox-${title}-${value}`);
+			return {
+				checkbox,
+				toggle: () => firedBy(() => checkbox().click()),
+			};
+		},
+		spec(fired, name) {
+			for (const body of fired) {
+				const match = body.compositeQuery?.queries?.find(
+					(q) => q.spec?.name === name,
+				);
+				if (match) {
+					return match.spec;
+				}
+			}
+			throw new Error(`no query ${name} in ${fired.length} query_range bodies`);
+		},
+		sent: () => bodies,
+		latest: (name) =>
+			[...bodies]
+				.reverse()
+				.flatMap((body) => body.compositeQuery?.queries ?? [])
+				.find((query) => query.spec?.name === name)?.spec,
+		urlQuery() {
+			const raw = new URL(page.url()).searchParams.get('compositeQuery');
+			if (!raw) {
+				return null;
+			}
+			// The app encodes before URLSearchParams encodes again.
+			return JSON.parse(decodeURIComponent(raw)) as Record<string, unknown>;
+		},
+		console: consoleWatch,
+	};
+	return qb;
+}
+
+/** Layers `qb` onto another host's test, e.g. the alert-rule fixtures. */
+export const withQueryBuilder = driver('qb', ({ page }) =>
+	queryBuilderDriver(page),
+);
+
+export const test = withQueryBuilder(kit);
+
+export { expect } from './kit';
+export * from './query-builder/constants';
+export * from './query-builder/types';
+export { reduceToLabel } from './query-builder/controls';
+export { withMetricTypes } from './query-builder/seed';

tests/e2e/drivers/query-builder/constants.ts

@@ -0,0 +1,17 @@
+/**
+ * AI-owned. Generated and maintained by coding agents alongside the specs that
+ * use it. Do not hand-edit: regenerate it with the spec that needs the change.
+ */
+export const EXPLORER = {
+	logs: '/logs/logs-explorer',
+	traces: '/traces-explorer',
+	metrics: '/metrics-explorer/explorer',
+} as const;
+
+/** A monotonic Sum in the golden dataset. */
+export const SUM_METRIC = 'signoz_calls_total';
+/** Another golden Sum, for switching between metrics of one type. */
+export const OTHER_SUM_METRIC = 'signoz_latency_count';
+
+/** Inside the golden dataset's window. */
+export const RELATIVE_TIME = '6h';

tests/e2e/drivers/query-builder/controls.ts

@@ -0,0 +1,136 @@
+/**
+ * AI-owned. Generated and maintained by coding agents alongside the specs that
+ * use it. Do not hand-edit: regenerate it with the spec that needs the change.
+ */
+import { expect, type Locator, type Page } from '@playwright/test';
+
+import { antdDriver } from '../antd';
+
+import { editorAt } from './editor';
+import type { AddOnField, AddOns, MetricControls } from './types';
+
+/**
+ * Opens the antd select inside `select` and returns its options. Scoped to the
+ * list the select owns: a previous select's list can still be mid-close.
+ */
+export async function openSelect(
+	page: Page,
+	select: Locator,
+): Promise<Locator> {
+	await select.locator('.ant-select-selector').click();
+	const list = await antdDriver(page).ownDropdown(select);
+	await expect(list).toBeVisible();
+	return list.locator('.ant-select-item-option');
+}
+
+/** antd renders select options with trailing whitespace ("Sum "). */
+export const exactly = (label: string): RegExp =>
+	new RegExp(`^\\s*${label}\\s*$`);
+
+/** A reduce-to option or value by its operator: "Sum of values in timeframe". */
+export const reduceToLabel = (operator: string): RegExp =>
+	new RegExp(`^\\s*${operator} of values`);
+
+const ADD_ON_CONTENT: Record<AddOnField, string> = {
+	group_by: 'group-by-content',
+	having: 'having-content',
+	order_by: 'order-by-content',
+	limit: 'limit-content',
+	legend_format: 'legend-format-content',
+	reduce_to: 'reduce-to-content',
+};
+
+export function addOnsAt(page: Page, root: () => Locator): AddOns {
+	const content = (field: AddOnField): Locator =>
+		root().getByTestId(ADD_ON_CONTENT[field]);
+	const groupBy = (): Locator => root().getByTestId('group-by');
+	const addOns: AddOns = {
+		toggles: () => root().locator('[data-testid^="query-add-on-"]'),
+		async open(field) {
+			if (await content(field).isVisible()) {
+				return;
+			}
+			await root().getByTestId(`query-add-on-${field}`).click();
+			await expect(content(field)).toBeVisible();
+		},
+		content,
+		groupBy: {
+			async add(key) {
+				const options = await openSelect(page, groupBy());
+				await groupBy().locator('input').fill(key);
+				await options
+					.filter({ hasText: exactly(key) })
+					.first()
+					.click();
+				await page.keyboard.press('Escape');
+				await expect(
+					groupBy().locator('.ant-select-selection-item', { hasText: key }),
+				).toBeVisible();
+			},
+			async remove(key) {
+				await groupBy()
+					.locator('.ant-select-selection-item', { hasText: key })
+					.locator('.ant-select-selection-item-remove')
+					.click();
+			},
+			async values() {
+				const texts = await groupBy()
+					.locator('.ant-select-selection-item-content')
+					.allTextContents();
+				return texts.map((text) => text.trim());
+			},
+		},
+		having: editorAt(page, () => root().getByTestId('having-editor')),
+		limit: () => content('limit').getByTestId('input-Limit'),
+		legend: () => content('legend_format').getByTestId('input-Legend format'),
+		reduceTo: {
+			value: () =>
+				root().getByTestId('reduce-to').locator('.ant-select-selection-item'),
+			// Labels read "<Op> of values in timeframe"; matched on the operator.
+			async set(label) {
+				const options = await openSelect(page, root().getByTestId('reduce-to'));
+				await options.filter({ hasText: reduceToLabel(label) }).click();
+				await expect(addOns.reduceTo.value()).toHaveText(reduceToLabel(label));
+			},
+		},
+	};
+	return addOns;
+}
+
+export function metricAt(page: Page, root: () => Locator): MetricControls {
+	const picker = (): Locator =>
+		root().locator('[data-testid^="metric-name-selector-"]');
+	const time = (): Locator => root().getByTestId('metrics-time-aggregation');
+	const space = (): Locator => root().getByTestId('metrics-space-aggregation');
+	return {
+		async select(name) {
+			// An antd AutoComplete: the testid is on a wrapper.
+			const field = picker();
+			const options = await openSelect(page, field);
+			await field.locator('input').fill(name);
+			// Options carry the metric's type and unit next to its name.
+			await options.filter({ hasText: name }).first().click();
+		},
+		// The selection item, not the root: these selects render their list
+		// inside the root, so its text includes every option.
+		input: () => picker().locator('input'),
+		timeAggregation: () => time().locator('.ant-select-selection-item'),
+		spaceAggregation: () => space().locator('.ant-select-selection-item'),
+		async setTimeAggregation(label) {
+			const options = await openSelect(page, time());
+			await options.filter({ hasText: exactly(label) }).click();
+			await expect(this.timeAggregation()).toHaveText(label);
+		},
+		async setSpaceAggregation(label) {
+			const options = await openSelect(page, space());
+			await options.filter({ hasText: exactly(label) }).click();
+			await expect(this.spaceAggregation()).toHaveText(label);
+		},
+		async spaceOptions() {
+			const options = await openSelect(page, space());
+			const labels = await options.allTextContents();
+			await page.keyboard.press('Escape');
+			return labels.map((label) => label.trim());
+		},
+	};
+}

tests/e2e/drivers/query-builder/editor.ts

@@ -0,0 +1,77 @@
+/**
+ * AI-owned. Generated and maintained by coding agents alongside the specs that
+ * use it. Do not hand-edit: regenerate it with the spec that needs the change.
+ */
+import { expect, type Locator, type Page } from '@playwright/test';
+
+import type { FilterEditor } from './types';
+
+/** CodeMirror renders its placeholder inside the empty line. */
+const EDITOR_DOC = async (root: Locator): Promise<string> => {
+	const lines = root.locator('.cm-content .cm-line');
+	const texts = await lines.allTextContents();
+	const placeholders = await lines.evaluateAll((nodes) =>
+		nodes.map((node) => node.querySelector('.cm-placeholder')?.textContent ?? ''),
+	);
+	return texts
+		.map((text, i) =>
+			placeholders[i] ? text.replace(placeholders[i], '') : text,
+		)
+		.join('\n');
+};
+
+export function editorAt(page: Page, root: () => Locator): FilterEditor {
+	const content = (): Locator => root().locator('.cm-content');
+	const editor: FilterEditor = {
+		root,
+		content,
+		async type(text) {
+			await editor.clear();
+			await page.keyboard.type(text);
+		},
+		async append(text) {
+			await content().click();
+			await page.keyboard.press('End');
+			await page.keyboard.type(text);
+		},
+		async clear() {
+			await content().click();
+			await page.keyboard.press('ControlOrMeta+a');
+			await page.keyboard.press('Backspace');
+			await expect.poll(() => EDITOR_DOC(root())).toBe('');
+		},
+		press: (key) => page.keyboard.press(key),
+		expression: () => EDITOR_DOC(root()),
+		lineCount: () => root().locator('.cm-line'),
+		suggestions: () => page.locator('.cm-tooltip-autocomplete'),
+		async openSuggestions() {
+			await expect(async () => {
+				await page.keyboard.press('Control+Space');
+				await expect(editor.suggestions()).toBeVisible({ timeout: 2_000 });
+			}).toPass({ timeout: 15_000 });
+		},
+		suggestion: (label) =>
+			page
+				.locator('.cm-tooltip-autocomplete [role="option"]')
+				.filter({ hasText: label }),
+	};
+	return editor;
+}
+
+/**
+ * Two frames: an edit reaches React state on its next scheduler task, and an
+ * action in the same frame reads the previous render. A long render delays
+ * the frame itself, so this cannot pass before the commit.
+ */
+export async function afterRender(page: Page): Promise<void> {
+	await page.evaluate(
+		() =>
+			new Promise<void>((resolve) => {
+				// Runs in the browser; the e2e tsconfig has no DOM lib.
+				const { requestAnimationFrame: frame } = globalThis as unknown as {
+					requestAnimationFrame(this: void, callback: () => void): number;
+				};
+				frame(() => frame(() => resolve()));
+			}),
+	);
+}

tests/e2e/drivers/query-builder/seed.ts

@@ -0,0 +1,50 @@
+/**
+ * AI-owned. Generated and maintained by coding agents alongside the specs that
+ * use it. Do not hand-edit: regenerate it with the spec that needs the change.
+ */
+import { postToSeeder } from '../telemetry';
+
+import { seeded } from '../kit';
+
+import type { MetricTypes } from './types';
+
+const HISTOGRAM_BOUNDS = ['1', '2', '4', '+Inf'];
+
+/** Ten minutes of a gauge and a cumulative histogram, names unique per worker. */
+export const withMetricTypes = seeded(
+	'metricTypes',
+	async ({ page, workerIndex }) => {
+		const suffix = `${workerIndex}_${Date.now()}`;
+		const types: MetricTypes = {
+			gauge: `e2e_qb_gauge_${suffix}`,
+			histogram: `e2e_qb_histogram_${suffix}`,
+		};
+		const now = Date.now();
+		const points: Record<string, unknown>[] = [];
+		for (let minute = 0; minute < 10; minute += 1) {
+			const timestamp = new Date(now - (10 - minute) * 60_000).toISOString();
+			points.push({
+				metric_name: types.gauge,
+				labels: { host: 'qb-host' },
+				timestamp,
+				value: 10 + minute,
+				type_: 'Gauge',
+				temporality: 'Unspecified',
+				is_monotonic: false,
+			});
+			HISTOGRAM_BOUNDS.forEach((le, bucket) => {
+				points.push({
+					metric_name: types.histogram,
+					labels: { le },
+					timestamp,
+					value: (minute + 1) * (bucket + 1),
+					type_: 'Histogram',
+					temporality: 'Cumulative',
+					is_monotonic: false,
+				});
+			});
+		}
+		await postToSeeder(page.request, '/telemetry/metrics', points);
+		return types;
+	},
+);

tests/e2e/drivers/query-builder/types.ts

@@ -0,0 +1,225 @@
+/**
+ * AI-owned. Generated and maintained by coding agents alongside the specs that
+ * use it. Do not hand-edit: regenerate it with the spec that needs the change.
+ */
+import type { Locator } from '@playwright/test';
+
+import type { ConsoleWatch } from '../console';
+
+/** The golden dataset has only Sums; these are seeded per worker. */
+export interface MetricTypes {
+	gauge: string;
+	histogram: string;
+}
+
+/** One entry of a v5 `query_range` body's `compositeQuery.queries`. */
+export interface V5Query {
+	type: string;
+	spec: {
+		name?: string;
+		signal?: string;
+		disabled?: boolean;
+		filter?: { expression?: string };
+		aggregations?: {
+			expression?: string;
+			metricName?: string;
+			timeAggregation?: string;
+			spaceAggregation?: string;
+			reduceTo?: string;
+		}[];
+		groupBy?: { name: string }[];
+		having?: { expression?: string };
+		order?: { key: { name: string }; direction: string }[];
+		limit?: number;
+		stepInterval?: number;
+		[key: string]: unknown;
+	};
+}
+
+export interface V5Body {
+	requestType: string;
+	compositeQuery: { queries: V5Query[] };
+}
+
+export interface FilterEditor {
+	root(): Locator;
+	/** The contenteditable CodeMirror surface. */
+	content(): Locator;
+	/** Replaces the expression by typing it key by key. */
+	type(text: string): Promise<void>;
+	/** Appends at the caret without clearing. */
+	append(text: string): Promise<void>;
+	clear(): Promise<void>;
+	press(key: string): Promise<void>;
+	/** The document text, placeholder excluded, lines joined with `\n`. */
+	expression(): Promise<string>;
+	lineCount(): Locator;
+	/** The open autocomplete popup. */
+	suggestions(): Locator;
+	/**
+	 * Ctrl+Space: opens the popup at the caret. Typing opens it only once the
+	 * debounced key fetch answers, which a loaded stack can delay past a test's
+	 * next step.
+	 */
+	openSuggestions(): Promise<void>;
+	suggestion(label: string | RegExp): Locator;
+}
+
+export interface QueryBlock {
+	root(): Locator;
+	filter: FilterEditor;
+	/** The filter's status icon: shown only while unfocused and non-empty. */
+	filterStatus(): Locator;
+	aggregation: FilterEditor;
+	/** The aggregation's "every … Seconds" input. */
+	step(): Locator;
+	metric: MetricControls;
+	addOns: AddOns;
+	/** The "…" menu: offered only where several queries are allowed. */
+	actions(): Locator;
+	/** A row of the open "…" menu. */
+	menuItem(action: 'clone' | 'delete'): Locator;
+	clone(): Promise<void>;
+	delete(): Promise<void>;
+	toggleVisibility(): Promise<void>;
+	collapse(): Promise<void>;
+	/** The data-source dropdown's value; only on hosts that let it change. */
+	signal(): Locator;
+	setSignal(label: 'Logs' | 'Traces' | 'Metrics'): Promise<void>;
+}
+
+export interface FormulaBlock {
+	root(): Locator;
+	expression(): Locator;
+	legend(): Locator;
+	delete(): Promise<void>;
+}
+
+/** `query-add-on-<field>` toggle values: a documented DOM contract. */
+export type AddOnField =
+	| 'group_by'
+	| 'having'
+	| 'order_by'
+	| 'limit'
+	| 'legend_format'
+	| 'reduce_to';
+
+export interface AddOns {
+	/** The toggle row; its children name the add-ons on offer. */
+	toggles(): Locator;
+	/** Idempotent: leaves an already-open add-on open. */
+	open(field: AddOnField): Promise<void>;
+	content(field: AddOnField): Locator;
+	groupBy: {
+		/** Types `key` and picks the suggestion with that exact name. */
+		add(key: string): Promise<void>;
+		remove(key: string): Promise<void>;
+		/** The selected keys, in order. */
+		values(): Promise<string[]>;
+	};
+	having: FilterEditor;
+	limit(): Locator;
+	legend(): Locator;
+	reduceTo: {
+		/** The selected value. */
+		value(): Locator;
+		set(label: string): Promise<void>;
+	};
+}
+
+/** The metrics aggregation section: metric picker plus time/space selects. */
+export interface MetricControls {
+	select(name: string): Promise<void>;
+	/** The metric name input. */
+	input(): Locator;
+	/** The selected value. Absent for histograms. */
+	timeAggregation(): Locator;
+	/** The selected value. */
+	spaceAggregation(): Locator;
+	setTimeAggregation(label: string): Promise<void>;
+	setSpaceAggregation(label: string): Promise<void>;
+	/** Labels offered by the space-aggregation select, as shown. */
+	spaceOptions(): Promise<string[]>;
+}
+
+export interface QuickFilterValue {
+	checkbox(): Locator;
+	/** Toggles the value; returns the query_range bodies the toggle fired. */
+	toggle(): Promise<V5Body[]>;
+}
+
+/** The explorer's tab, carried in the `panelTypes` param. */
+export type ExplorerView = 'list' | 'graph' | 'table';
+
+export interface OpenOptions {
+	/** Serialised the way the app writes it. */
+	query?: unknown;
+	/** A `compositeQuery` value sent as given, for malformed input. */
+	raw?: string;
+	view?: ExplorerView;
+}
+
+export interface QueryBuilderDriver {
+	/**
+	 * Resolves once the page's own first query_range has answered: the explorer
+	 * rewrites its URL and re-mounts the builder until then, which drops
+	 * keystrokes. Returns the bodies that load fired.
+	 */
+	openExplorer(path: string, options?: OpenOptions): Promise<V5Body[]>;
+	query(name: string): QueryBlock;
+	/** Adds the next query (B, C, …) and waits for its block. */
+	addQuery(name: string): Promise<QueryBlock>;
+	/** Builder query names, top to bottom. */
+	queryNames(): Promise<string[]>;
+	/** Panel-editor query-type tab, by its queryType (`builder`, `promql`, …). */
+	tab(queryType: string): Locator;
+	promql(): Locator;
+	formula(name: string): FormulaBlock;
+	addFormula(name: string): Promise<FormulaBlock>;
+	traceOperator: {
+		root(): Locator;
+		/** "Add Trace Matching": offered on traces hosts that allow it. */
+		addButton(): Locator;
+		add(): Promise<void>;
+		remove(): Promise<void>;
+		editor: FilterEditor;
+	};
+	/**
+	 * Explorer "Add to dashboard": picks the dashboard titled `title` and waits
+	 * for the new-panel editor the export navigates to.
+	 */
+	addToDashboard(title: string): Promise<void>;
+	runButton(): Locator;
+	/** The logs explorer's results area, below the builder. */
+	logsResults(): Locator;
+	/** Clicks Run; returns every query_range body the click fired. */
+	run(): Promise<V5Body[]>;
+	/**
+	 * Clicks Run until `read()` equals `expected`. For panel-editor structural
+	 * edits, whose draft can lag the DOM: an early Run is a cache hit that
+	 * sends nothing. Never clicks while the button is Cancel.
+	 */
+	rerunUntil(read: () => unknown, expected: unknown): Promise<void>;
+	/**
+	 * Ctrl/Cmd+Enter from the focused field; returns the fired bodies. Waits two
+	 * frames first: editor changes reach React state on its next scheduler task,
+	 * and a keypress inside the same frame as the last keystroke reads the
+	 * previous render — a gap no person can produce.
+	 */
+	runShortcut(): Promise<V5Body[]>;
+	/** A value in an explorer's checkbox quick filter, by its header title. */
+	quickFilter(title: string, value: string): QuickFilterValue;
+	/** The spec of query `name` in the first body that has it. */
+	spec(bodies: V5Body[], name: string): V5Query['spec'];
+	/** Every query_range body sent since the test started. */
+	sent(): V5Body[];
+	/**
+	 * Query `name`'s spec in the newest body that has it, whatever sent it. The
+	 * panel editor fetches on structural edits, so Run after one can be a cache
+	 * hit that sends nothing: poll this rather than waiting on Run.
+	 */
+	latest(name: string): V5Query['spec'] | undefined;
+	/** The URL's `compositeQuery`, parsed. */
+	urlQuery(): Record<string, unknown> | null;
+	console: ConsoleWatch;
+}

tests/e2e/drivers/query-range-mock.ts

@@ -272,7 +272,9 @@ export async function holdQueryRange(
 	});
 	await page.route(QUERY_RANGE_GLOB, async (route) => {
 		await gate;
-		await fulfill(route, body);
+		// A cancelled run aborts its request while it is held; there is
+		// nothing left to answer.
+		await fulfill(route, body).catch(() => undefined);
 	});
 	return { release: () => release() };
 }

tests/e2e/tests/query-builder/addons.spec.ts

@@ -0,0 +1,154 @@
+import {
+	expect,
+	EXPLORER,
+	SUM_METRIC,
+	test,
+} from '../../drivers/query-builder';
+
+const HAVING = ['count() > 10', 'count() IN [1, 2]', 'count() NOT IN [1, 2]'];
+
+test.describe('Query builder — add-ons', () => {
+	for (const explorer of ['logs', 'traces'] as const) {
+		test(`TC-21 ${explorer} group by keeps order through removal and reload`, async ({
+			qb,
+		}) => {
+			await qb.openExplorer(EXPLORER[explorer], { view: 'graph' });
+			const addOns = qb.query('A').addOns;
+			await addOns.open('group_by');
+
+			await addOns.groupBy.add('service.name');
+			await addOns.groupBy.add('deployment.environment');
+			await addOns.groupBy.add('k8s.namespace.name');
+			await addOns.groupBy.remove('service.name');
+			const fired = await qb.run();
+
+			const expected = ['deployment.environment', 'k8s.namespace.name'];
+			expect(qb.spec(fired, 'A').groupBy?.map((key) => key.name)).toEqual(
+				expected,
+			);
+			const reloaded = await qb.openExplorer(EXPLORER[explorer], {
+				view: 'graph',
+				query: qb.urlQuery(),
+			});
+			expect(qb.spec(reloaded, 'A').groupBy?.map((key) => key.name)).toEqual(
+				expected,
+			);
+			expect(await qb.query('A').addOns.groupBy.values()).toEqual(expected);
+		});
+	}
+
+	test('TC-21 metrics group by offers the metric’s own attributes', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.metrics);
+		const query = qb.query('A');
+		await query.metric.select(SUM_METRIC);
+
+		await query.addOns.groupBy.add('operation');
+		const fired = await qb.run();
+
+		expect(qb.spec(fired, 'A').groupBy?.map((key) => key.name)).toEqual([
+			'operation',
+		]);
+	});
+
+	for (const having of HAVING) {
+		test(`TC-22 having "${having}" is sent verbatim and accepted`, async ({
+			qb,
+		}) => {
+			await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+			const addOns = qb.query('A').addOns;
+			await addOns.open('group_by');
+			await addOns.groupBy.add('service.name');
+			await addOns.open('having');
+
+			await addOns.having.type(having);
+			await addOns.having.press('Escape');
+			const fired = await qb.run();
+
+			expect(qb.spec(fired, 'A').having?.expression).toBe(having);
+			expect(qb.console.failedResponses).toEqual([]);
+		});
+	}
+
+	test('TC-23 the logs list orders by timestamp then id, traces by timestamp only', async ({
+		qb,
+	}) => {
+		const logs = await qb.openExplorer(EXPLORER.logs, { view: 'list' });
+		expect(qb.spec(logs, 'A').order?.map((o) => o.key.name)).toEqual([
+			'timestamp',
+			'id',
+		]);
+
+		const traces = await qb.openExplorer(EXPLORER.traces, { view: 'list' });
+		expect(qb.spec(traces, 'A').order?.map((o) => o.key.name)).toEqual([
+			'timestamp',
+		]);
+	});
+
+	test('TC-24 a positive limit is sent; empty and zero send none', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+		const addOns = qb.query('A').addOns;
+		await addOns.open('group_by');
+		await addOns.groupBy.add('service.name');
+		await addOns.open('limit');
+
+		await addOns.limit().fill('10');
+		expect(qb.spec(await qb.run(), 'A').limit).toBe(10);
+
+		await addOns.limit().fill('');
+		expect(qb.spec(await qb.run(), 'A')).not.toHaveProperty('limit');
+
+		await addOns.limit().fill('3');
+		await qb.run();
+		await addOns.limit().fill('0');
+		expect(qb.spec(await qb.run(), 'A')).not.toHaveProperty('limit');
+	});
+
+	test('TC-24 a limit input drops the sign of a negative number', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+		const addOns = qb.query('A').addOns;
+		await addOns.open('group_by');
+		await addOns.groupBy.add('service.name');
+		await addOns.open('limit');
+		await addOns.limit().fill('10');
+		expect(qb.spec(await qb.run(), 'A').limit).toBe(10);
+
+		await addOns.limit().fill('-5');
+		await expect(addOns.limit()).toHaveValue('5');
+		expect(qb.spec(await qb.run(), 'A').limit).toBe(5);
+		expect(qb.console.failedResponses).toEqual([]);
+	});
+
+	test('TC-25 the legend prefills from group by and a custom one is kept', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+		const addOns = qb.query('A').addOns;
+		await addOns.open('group_by');
+		await addOns.groupBy.add('service.name');
+		await addOns.groupBy.add('deployment.environment');
+
+		await addOns.open('legend_format');
+		await expect(addOns.legend()).toHaveValue(
+			'service.name = {{service.name}}, deployment.environment = {{deployment.environment}}',
+		);
+
+		await addOns.legend().fill('{{service.name}} logs');
+		await addOns.groupBy.add('k8s.namespace.name');
+		await expect(addOns.legend()).toHaveValue('{{service.name}} logs');
+		expect(qb.spec(await qb.run(), 'A').legend).toBe('{{service.name}} logs');
+	});
+
+	test('TC-25 the legend opens empty without a group by', async ({ qb }) => {
+		await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+
+		await qb.query('A').addOns.open('legend_format');
+
+		await expect(qb.query('A').addOns.legend()).toHaveValue('');
+	});
+});

tests/e2e/tests/query-builder/aggregation.spec.ts

@@ -0,0 +1,80 @@
+import { expect, EXPLORER, test } from '../../drivers/query-builder';
+
+// One comma-separated term per entry in the request's `aggregations`.
+const EXPRESSIONS: Record<string, string[]> = {
+	'a count': ['count()'],
+	'a distinct count': ['count_distinct(service.name)'],
+	'a percentile of a span field': ['p99(duration_nano)'],
+	'two aggregations': ['count()', 'p99(duration_nano)'],
+};
+
+test.describe('Query builder — logs and traces aggregations', () => {
+	for (const [label, terms] of Object.entries(EXPRESSIONS)) {
+		test(`TC-17 ${label} reaches the request`, async ({ qb }) => {
+			await qb.openExplorer(EXPLORER.traces, { view: 'graph' });
+			const aggregation = qb.query('A').aggregation;
+
+			await aggregation.type(terms.join(', '));
+			await aggregation.press('Escape');
+			const fired = await qb.run();
+
+			expect(qb.spec(fired, 'A').aggregations?.map((a) => a.expression)).toEqual(
+				terms,
+			);
+		});
+	}
+
+	test('TC-18 the step interval reaches the request', async ({
+		authedPage: page,
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.traces, { view: 'graph' });
+
+		await qb.query('A').step().fill('120');
+		await page.keyboard.press('Tab');
+		const fired = await qb.run();
+
+		expect(qb.spec(fired, 'A').stepInterval).toBe(120);
+	});
+
+	test('TC-30 a trace operator replaces per-query aggregation until removed', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.traces, { view: 'graph' });
+		await (await qb.addQuery('B')).filter.type("http.status_code = '500'");
+		await qb.query('B').filter.press('Escape');
+
+		await qb.traceOperator.add();
+		await qb.traceOperator.editor.type('A => B');
+		await qb.traceOperator.editor.press('Escape');
+		for (const name of ['A', 'B']) {
+			await expect(qb.query(name).aggregation.root()).toHaveCount(0);
+			await expect(qb.query(name).addOns.toggles()).toHaveCount(0);
+		}
+		const fired = await qb.run();
+		const operator = fired
+			.flatMap((body) => body.compositeQuery.queries)
+			.find((query) => query.type === 'builder_trace_operator');
+		expect(operator?.spec).toMatchObject({ expression: 'A => B' });
+
+		await qb.traceOperator.remove();
+		await expect(qb.query('A').aggregation.root()).toBeVisible();
+		await qb.rerunUntil(
+			() =>
+				qb
+					.sent()
+					.at(-1)
+					?.compositeQuery.queries.some(
+						(query) => query.type === 'builder_trace_operator',
+					),
+			false,
+		);
+	});
+
+	test('TC-30 the logs explorer offers no trace matching', async ({ qb }) => {
+		await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+
+		await expect(qb.query('A').root()).toBeVisible();
+		await expect(qb.traceOperator.addButton()).toHaveCount(0);
+	});
+});

tests/e2e/tests/query-builder/alerts.spec.ts

@@ -0,0 +1,80 @@
+import {
+	AlertType,
+	expect,
+	test as alertsTest,
+} from '../../drivers/alerts';
+import { withQueryBuilder } from '../../drivers/query-builder';
+
+const test = withQueryBuilder(alertsTest);
+
+const FILTER_A = "http.method = 'GET'";
+const FILTER_B = "http.status_code = '500'";
+const TRACE_MATCH = 'A => B';
+
+interface SavedRule {
+	condition?: {
+		compositeQuery?: {
+			queries?: {
+				type: string;
+				spec: {
+					name?: string;
+					expression?: string;
+					filter?: { expression?: string };
+				};
+			}[];
+		};
+	};
+}
+
+test.describe('Query builder — alerts', () => {
+	test('TC-06 a trace-matching traces alert saves and reopens intact', async ({
+		authedPage: page,
+		alerts,
+		alertChannel,
+		ownedRules,
+		qb,
+	}) => {
+		await alerts.form.gotoV2({ alertType: AlertType.TRACES });
+		await alerts.form.name().fill(`e2e-qb-tc06-${Date.now()}`);
+
+		await qb.query('A').filter.type(FILTER_A);
+		await qb.query('A').filter.press('Escape');
+		const b = await qb.addQuery('B');
+		await b.filter.type(FILTER_B);
+		await b.filter.press('Escape');
+		await qb.traceOperator.add();
+		await qb.traceOperator.editor.type(TRACE_MATCH);
+		await qb.traceOperator.editor.press('Escape');
+		// Blur first: the editor's blur re-renders the condition section, which
+		// otherwise closes the channel select as its click opens it.
+		await qb.traceOperator.editor.content().blur();
+		await alerts.form.selectThresholdChannel(0, alertChannel.name);
+
+		const [response] = await Promise.all([
+			page.waitForResponse(
+				(r) => r.url().includes('/api/v2/rules') && r.request().method() === 'POST',
+			),
+			alerts.form.saveButton().click(),
+		]);
+		await ownedRules.register(response);
+		const saved = response.request().postDataJSON() as SavedRule;
+		const queries = saved.condition?.compositeQuery?.queries ?? [];
+		expect(queries).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					type: 'builder_trace_operator',
+					spec: expect.objectContaining({ expression: TRACE_MATCH }),
+				}),
+			]),
+		);
+
+		const { data } = (await response.json()) as { data: { id: string } };
+		await alerts.details.gotoOverview(String(data.id));
+
+		await expect.poll(() => qb.query('A').filter.expression()).toBe(FILTER_A);
+		await expect.poll(() => qb.query('B').filter.expression()).toBe(FILTER_B);
+		await expect
+			.poll(() => qb.traceOperator.editor.expression())
+			.toBe(TRACE_MATCH);
+	});
+});

tests/e2e/tests/query-builder/dashboards.spec.ts

@@ -0,0 +1,72 @@
+import { emptyDashboard, test as editorTest } from '../../drivers/panel-editor';
+import {
+	expect,
+	EXPLORER,
+	withQueryBuilder,
+} from '../../drivers/query-builder';
+
+const test = withQueryBuilder(editorTest);
+
+const FILTER = "severity_text = 'ERROR'";
+const AGGREGATION = 'count_distinct(service.name)';
+
+interface StoredQuery {
+	spec: {
+		filter?: { expression?: string };
+		aggregations?: { expression?: string }[];
+	};
+}
+
+/** Where a non-List panel keeps its builder queries in the v2 dashboard spec. */
+interface StoredPanel {
+	spec: {
+		queries: {
+			spec: { plugin: { kind: string; spec: { queries: StoredQuery[] } } };
+		}[];
+	};
+}
+
+test.describe('Query builder — explorer to dashboard', () => {
+	test('TC-05 a logs explorer query survives add to dashboard, save and reopen', async ({
+		dashboards,
+		editor,
+		qb,
+	}) => {
+		const dashboard = emptyDashboard();
+		const title = dashboard.spec.display.name;
+		const id = await dashboards.seed(dashboard);
+
+		await qb.openExplorer(EXPLORER.logs, { view: 'graph' });
+		await qb.query('A').filter.type(FILTER);
+		await qb.query('A').filter.press('Escape');
+		await qb.query('A').aggregation.type(AGGREGATION);
+		await qb.query('A').aggregation.press('Escape');
+		await qb.run();
+
+		await qb.addToDashboard(title);
+		await expect.poll(() => qb.query('A').filter.expression()).toBe(FILTER);
+		await expect
+			.poll(() => qb.query('A').aggregation.expression())
+			.toBe(AGGREGATION);
+
+		await editor.save();
+		// The shared spec types model only bare BuilderQuery plugins.
+		const panels = (await dashboards.get(id)).spec.panels as unknown as Record<
+			string,
+			StoredPanel
+		>;
+		const [panelId] = Object.keys(panels);
+		const plugin = panels[panelId].spec.queries[0].spec.plugin;
+		expect(plugin.kind).toBe('signoz/CompositeQuery');
+		expect(plugin.spec.queries[0].spec).toMatchObject({
+			filter: { expression: FILTER },
+			aggregations: [{ expression: AGGREGATION }],
+		});
+
+		await dashboards.openEditor(id, panelId);
+		await expect.poll(() => qb.query('A').filter.expression()).toBe(FILTER);
+		await expect
+			.poll(() => qb.query('A').aggregation.expression())
+			.toBe(AGGREGATION);
+	});
+});

tests/e2e/tests/query-builder/filter.spec.ts

@@ -0,0 +1,284 @@
+import { expect, EXPLORER, test } from '../../drivers/query-builder';
+
+// Typing is real keystrokes: the regressions here (caret jumps, swallowed
+// Enter, the run shortcut) only show up through the keyboard path.
+
+const RECENT_KEPT = "service.name = 'frontend' AND severity_text = 'WARN'";
+const RECENT_REMOVED = 'logger.name EXISTS';
+
+const COMPOUND: Record<string, string> = {
+	'NOT over a parenthesised OR':
+		"NOT (severity_text = 'INFO' OR severity_text = 'WARN') AND service.name = 'frontend'",
+	'nested groups':
+		"(service.name = 'frontend' AND (severity_text = 'ERROR' OR severity_text = 'WARN'))",
+	'NOT IN with EXISTS':
+		"service.name NOT IN ['frontend', 'adservice'] AND logger.name EXISTS",
+};
+
+const queryWithFilter = (expression: string): unknown => ({
+	queryType: 'builder',
+	builder: {
+		queryFormulas: [],
+		queryData: [
+			{
+				queryName: 'A',
+				dataSource: 'logs',
+				expression: 'A',
+				filter: { expression },
+				aggregations: [{ expression: 'count()' }],
+			},
+		],
+	},
+});
+
+const VERBATIM: Record<string, string> = {
+	'an escaped quote': "logger.name = 'it\\'s'",
+	'a double-quoted string': 'logger.name = "double quoted"',
+	'a quoted numeric string': "logger.name = '123'",
+	'a bare number': 'logger.name = 123',
+	'a boolean': 'logger.name = true',
+	'spaces and a backslash': "logger.name = 'a b\\\\c'",
+};
+
+test.describe('Query builder — filter editor', () => {
+	test('TC-07 key, operator and value suggestions build the expression', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const filter = qb.query('A').filter;
+
+		await filter.type('severity_te');
+		await filter.openSuggestions();
+		await filter.suggestion('severity_text').first().click();
+		await expect.poll(() => filter.expression()).toMatch(/^severity_text\s*$/);
+
+		await filter.openSuggestions();
+		await expect(filter.suggestion(/^=/).first()).toBeVisible();
+		await filter.append('= ');
+		await filter.openSuggestions();
+		await filter.suggestion('ERROR').first().click();
+		await expect
+			.poll(() => filter.expression())
+			.toMatch(/^severity_text = 'ERROR'\s*$/);
+
+		const fired = await qb.run();
+		expect(qb.spec(fired, 'A').filter?.expression?.trim()).toBe(
+			"severity_text = 'ERROR'",
+		);
+	});
+
+	for (const [label, expression] of Object.entries(VERBATIM)) {
+		test(`TC-08 ${label} is sent and restored verbatim`, async ({
+			authedPage: page,
+			qb,
+		}) => {
+			await qb.openExplorer(EXPLORER.logs);
+			const filter = qb.query('A').filter;
+
+			await filter.type(expression);
+			await filter.press('Escape');
+			const fired = await qb.run();
+			expect(qb.spec(fired, 'A').filter?.expression).toBe(expression);
+
+			await page.reload();
+			await expect(filter.content()).toBeVisible();
+			await expect.poll(() => filter.expression()).toBe(expression);
+			await expect(qb.query('A').filterStatus()).toHaveCount(0);
+		});
+	}
+
+	test('TC-11 the status icon shows only for an unfocused invalid filter', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const query = qb.query('A');
+
+		await query.filter.type('service.name =');
+		await expect(query.filterStatus()).toHaveCount(0);
+
+		await query.filter.content().blur();
+		await expect(query.filterStatus()).toBeVisible();
+
+		await query.filter.type("service.name = 'frontend'");
+		await query.filter.content().blur();
+		await expect(query.filterStatus()).toHaveCount(0);
+
+		await query.filter.clear();
+		await query.filter.content().blur();
+		await expect(query.filterStatus()).toHaveCount(0);
+	});
+
+	test('TC-12 Enter and Shift+Enter never insert a newline or run', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const filter = qb.query('A').filter;
+		await filter.type("severity_text = 'ERROR'");
+		await filter.press('Escape');
+		await expect(filter.suggestions()).toHaveCount(0);
+		const sentBefore = qb.sent().length;
+
+		await filter.press('Enter');
+		await filter.press('Shift+Enter');
+
+		await expect(filter.lineCount()).toHaveCount(1);
+		await expect.poll(() => filter.expression()).toBe("severity_text = 'ERROR'");
+		expect(qb.sent()).toHaveLength(sentBefore);
+	});
+
+	for (const explorer of ['logs', 'traces'] as const) {
+		test(`TC-13 Cmd/Ctrl+Enter in the ${explorer} filter runs the edited query`, async ({
+			qb,
+		}) => {
+			await qb.openExplorer(EXPLORER[explorer]);
+			const filter = qb.query('A').filter;
+			await filter.type("service.name = 'frontend'");
+
+			const fired = await qb.runShortcut();
+
+			expect(qb.spec(fired, 'A').filter?.expression).toBe(
+				"service.name = 'frontend'",
+			);
+			await expect(filter.lineCount()).toHaveCount(1);
+			expect(qb.urlQuery()).toMatchObject({ queryType: 'builder' });
+		});
+	}
+
+	test('TC-14 Escape closes suggestions and keeps the text', async ({ qb }) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const filter = qb.query('A').filter;
+
+		await filter.type('serv');
+		await filter.openSuggestions();
+		await filter.press('Escape');
+
+		await expect(filter.suggestions()).toHaveCount(0);
+		await expect.poll(() => filter.expression()).toBe('serv');
+		await filter.press('i');
+		await expect.poll(() => filter.expression()).toBe('servi');
+
+		await filter.press('Escape');
+		await filter.press('Escape');
+		await expect.poll(() => filter.expression()).toBe('servi');
+		await expect(filter.content()).toBeFocused();
+	});
+
+	test('TC-09 value suggestions fill an IN list', async ({ qb }) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const filter = qb.query('A').filter;
+
+		await filter.type('service.name IN ');
+		await filter.openSuggestions();
+		await filter.suggestion('frontend').first().click();
+		await expect
+			.poll(() => filter.expression())
+			.toBe("service.name IN ['frontend'] ");
+
+		await filter.type("service.name IN ['frontend', 'cartservice']");
+		await filter.press('Escape');
+		const fired = await qb.run();
+
+		expect(qb.spec(fired, 'A').filter?.expression).toBe(
+			"service.name IN ['frontend', 'cartservice']",
+		);
+		await expect(qb.query('A').filterStatus()).toHaveCount(0);
+	});
+
+	for (const [label, expression] of Object.entries(COMPOUND)) {
+		test(`TC-10 ${label} is valid and sent verbatim`, async ({ qb }) => {
+			await qb.openExplorer(EXPLORER.logs);
+			const query = qb.query('A');
+
+			await query.filter.type(expression);
+			await query.filter.press('Escape');
+			await query.filter.content().blur();
+			await expect(query.filterStatus()).toHaveCount(0);
+			const fired = await qb.run();
+
+			expect(qb.spec(fired, 'A').filter?.expression).toBe(expression);
+		});
+	}
+
+	test('TC-15 an expression with CRLF from the URL loads without a RangeError', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs, {
+			query: queryWithFilter("body CONTAINS 'line1\r\nline2'"),
+		});
+
+		await expect.poll(() => qb.query('A').filter.expression()).toContain('line1');
+		expect(qb.console.errors.filter((e) => e.includes('RangeError'))).toEqual([]);
+		await qb.query('A').filter.append(" AND severity_text = 'ERROR'");
+		await expect
+			.poll(() => qb.query('A').filter.expression())
+			.toMatch(/severity_text = 'ERROR'$/);
+		expect(qb.console.errors).toEqual([]);
+	});
+
+	test('TC-15 recent searches are offered, applied and deleted', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const filter = qb.query('A').filter;
+		for (const expression of [RECENT_KEPT, RECENT_REMOVED]) {
+			await filter.type(expression);
+			await filter.press('Escape');
+			await qb.run();
+		}
+
+		await filter.clear();
+		await filter.openSuggestions();
+		await expect(filter.suggestion(RECENT_KEPT)).toBeVisible();
+		await expect(filter.suggestion(RECENT_REMOVED)).toBeVisible();
+
+		await filter.suggestion(RECENT_KEPT).click();
+		await expect.poll(() => filter.expression()).toBe(RECENT_KEPT);
+
+		await filter.clear();
+		await filter.openSuggestions();
+		await filter
+			.suggestion(RECENT_REMOVED)
+			.getByRole('button', { name: 'Remove from recent searches' })
+			.click();
+		await expect(filter.suggestion(RECENT_REMOVED)).toHaveCount(0);
+	});
+
+	test('TC-15 recent searches survive a reload and stay with their signal', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		await qb.query('A').filter.type(RECENT_KEPT);
+		await qb.query('A').filter.press('Escape');
+		await qb.run();
+
+		await qb.openExplorer(EXPLORER.logs);
+		await qb.query('A').filter.clear();
+		await qb.query('A').filter.openSuggestions();
+		await expect(qb.query('A').filter.suggestion(RECENT_KEPT)).toBeVisible();
+
+		await qb.openExplorer(EXPLORER.traces);
+		await qb.query('A').filter.clear();
+		await qb.query('A').filter.openSuggestions();
+		await expect(qb.query('A').filter.suggestion(RECENT_KEPT)).toHaveCount(0);
+	});
+
+	test('TC-16 a quick-filter value toggles between excluded and cleared', async ({
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const filter = qb.query('A').filter;
+		const handTyped = "service.name = 'frontend'";
+		const excluded = `${handTyped} severity_text not in ['ERROR']`;
+		const error = qb.quickFilter('Severity Text', 'ERROR');
+		await filter.type(handTyped);
+		await qb.run();
+
+		for (const expected of [excluded, handTyped, excluded]) {
+			const fired = await error.toggle();
+
+			expect(qb.spec(fired, 'A').filter?.expression).toBe(expected);
+			await expect.poll(() => filter.expression()).toBe(expected);
+		}
+		await expect(error.checkbox()).toHaveAttribute('aria-checked', 'false');
+	});
+});

tests/e2e/tests/query-builder/metrics.spec.ts

@@ -0,0 +1,106 @@
+import {
+	expect,
+	EXPLORER,
+	type MetricTypes,
+	OTHER_SUM_METRIC,
+	SUM_METRIC,
+	test as base,
+	withMetricTypes,
+} from '../../drivers/query-builder';
+
+const test = withMetricTypes(base);
+
+const MOMENT_AGGREGATIONS = ['Sum', 'Avg', 'Min', 'Max'];
+
+interface TypeDefaults {
+	metric: (types: MetricTypes) => string;
+	time?: string;
+	space: string;
+	spaceOptions: string[];
+}
+
+const DEFAULTS: Record<string, TypeDefaults> = {
+	sum: {
+		metric: () => SUM_METRIC,
+		time: 'Rate',
+		space: 'Sum',
+		spaceOptions: MOMENT_AGGREGATIONS,
+	},
+	gauge: {
+		metric: (types) => types.gauge,
+		time: 'Avg',
+		space: 'Avg',
+		spaceOptions: MOMENT_AGGREGATIONS,
+	},
+	histogram: {
+		metric: (types) => types.histogram,
+		space: 'P90',
+		spaceOptions: ['P50', 'P75', 'P90', 'P95', 'P99'],
+	},
+};
+
+test.describe('Query builder — metric aggregations', () => {
+	for (const [type, expected] of Object.entries(DEFAULTS)) {
+		test(`TC-19 a ${type} metric gets its type's default aggregations`, async ({
+			metricTypes,
+			qb,
+		}) => {
+			const metricName = expected.metric(metricTypes);
+			await qb.openExplorer(EXPLORER.metrics);
+			const metric = qb.query('A').metric;
+
+			await metric.select(metricName);
+
+			await expect(metric.spaceAggregation()).toHaveText(expected.space);
+			expect(await metric.spaceOptions()).toEqual(expected.spaceOptions);
+			const fired = await qb.run();
+			expect(qb.spec(fired, 'A').aggregations?.[0]).toMatchObject({
+				metricName,
+				spaceAggregation: expected.space.toLowerCase(),
+				...(expected.time && { timeAggregation: expected.time.toLowerCase() }),
+			});
+		});
+	}
+
+	test('TC-19 a histogram has no time aggregation control', async ({
+		metricTypes,
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.metrics);
+
+		await qb.query('A').metric.select(metricTypes.histogram);
+
+		await expect(qb.query('A').metric.spaceAggregation()).toHaveText('P90');
+		await expect(qb.query('A').metric.timeAggregation()).toHaveCount(0);
+	});
+
+	test('TC-20 aggregations reset only when the metric type changes', async ({
+		metricTypes,
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.metrics);
+		const metric = qb.query('A').metric;
+
+		await metric.select(SUM_METRIC);
+		await metric.setTimeAggregation('Increase');
+		await metric.setSpaceAggregation('Max');
+
+		await metric.select(OTHER_SUM_METRIC);
+		await expect(metric.timeAggregation()).toHaveText('Increase');
+		await expect(metric.spaceAggregation()).toHaveText('Max');
+
+		await metric.select(metricTypes.gauge);
+		await expect(metric.timeAggregation()).toHaveText('Avg');
+		await expect(metric.spaceAggregation()).toHaveText('Avg');
+
+		await metric.select(SUM_METRIC);
+		await expect(metric.timeAggregation()).toHaveText('Rate');
+		await expect(metric.spaceAggregation()).toHaveText('Sum');
+		const fired = await qb.run();
+		expect(qb.spec(fired, 'A').aggregations?.[0]).toMatchObject({
+			metricName: SUM_METRIC,
+			timeAggregation: 'rate',
+			spaceAggregation: 'sum',
+		});
+	});
+});

tests/e2e/tests/query-builder/multi-query.spec.ts

@@ -0,0 +1,136 @@
+import {
+	logsCountQuery,
+	metricsQuery,
+	SINGLE_PANEL_ID,
+	singlePanelDashboard,
+	test as editorTest,
+} from '../../drivers/panel-editor';
+import {
+	expect,
+	OTHER_SUM_METRIC,
+	SUM_METRIC,
+	withQueryBuilder,
+} from '../../drivers/query-builder';
+
+// An added query continues the previous query's signal. On these metrics
+// panels it starts with no metric, and Run does nothing until one is picked.
+const test = withQueryBuilder(editorTest);
+
+const SIGNAL_LABEL = { logs: 'Logs', traces: 'Traces' } as const;
+
+const CLONED_FILTER = "operation = '/ads/get'";
+
+test.describe('Query builder — multiple queries', () => {
+	for (const signal of ['logs', 'traces'] as const) {
+		test(`TC-28 a query added to a ${signal} panel stays ${signal}`, async ({
+			dashboards,
+			qb,
+		}) => {
+			await dashboards.seedAndEdit(
+				singlePanelDashboard({ query: logsCountQuery({ signal }) }),
+				SINGLE_PANEL_ID,
+			);
+
+			const added = await qb.addQuery('B');
+
+			await expect(added.signal()).toHaveText(SIGNAL_LABEL[signal]);
+			await expect(added.aggregation.root()).toBeVisible();
+			await expect(added.metric.input()).toHaveCount(0);
+			await added.filter.type("service.name = 'frontend'");
+			await added.filter.press('Escape');
+			await qb.rerunUntil(() => qb.latest('B')?.signal, signal);
+		});
+	}
+
+	test('TC-28 a deleted name is reused by the next added query', async ({
+		dashboards,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: metricsQuery() }),
+			SINGLE_PANEL_ID,
+		);
+		for (const name of ['B', 'C']) {
+			await (await qb.addQuery(name)).metric.select(OTHER_SUM_METRIC);
+		}
+		expect(await qb.queryNames()).toEqual(['A', 'B', 'C']);
+
+		await qb.query('B').delete();
+		expect(await qb.queryNames()).toEqual(['A', 'C']);
+		const reAdded = await qb.addQuery('B');
+		expect(await qb.queryNames()).toEqual(['A', 'C', 'B']);
+		await reAdded.metric.select(SUM_METRIC);
+		await expect(reAdded.metric.input()).toHaveValue(SUM_METRIC);
+		await expect(qb.query('C').metric.input()).toHaveValue(OTHER_SUM_METRIC);
+	});
+
+	test('TC-28 a clone and a hidden query reach the request', async ({
+		dashboards,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: metricsQuery({ filter: CLONED_FILTER }) }),
+			SINGLE_PANEL_ID,
+		);
+		await (await qb.addQuery('B')).metric.select(OTHER_SUM_METRIC);
+
+		await qb.query('A').clone();
+		await expect
+			.poll(() => qb.query('C').filter.expression())
+			.toBe(CLONED_FILTER);
+		await qb.query('B').toggleVisibility();
+		await qb.runButton().click();
+
+		await expect.poll(() => qb.latest('B')?.disabled).toBe(true);
+		expect(qb.latest('C')).toMatchObject({
+			filter: { expression: CLONED_FILTER },
+			aggregations: [expect.objectContaining({ metricName: SUM_METRIC })],
+		});
+	});
+
+	test('TC-28 the last remaining query offers no delete', async ({
+		dashboards,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: metricsQuery() }),
+			SINGLE_PANEL_ID,
+		);
+		await (await qb.addQuery('B')).metric.select(OTHER_SUM_METRIC);
+
+		await qb.query('B').delete();
+		await qb.query('A').actions().click();
+
+		await expect(qb.query('A').menuItem('clone')).toBeVisible();
+		await expect(qb.query('A').menuItem('delete')).toHaveCount(0);
+	});
+
+	test('TC-29 a formula over two queries reaches the request', async ({
+		dashboards,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: metricsQuery() }),
+			SINGLE_PANEL_ID,
+		);
+		await (await qb.addQuery('B')).metric.select(OTHER_SUM_METRIC);
+
+		const formula = await qb.addFormula('F1');
+		await formula.expression().fill('A / B');
+		await formula.legend().fill('ratio');
+		await qb.runButton().click();
+		await expect
+			.poll(() => qb.latest('F1'))
+			.toMatchObject({ expression: 'A / B', legend: 'ratio' });
+
+		await formula.delete();
+		await qb.rerunUntil(
+			() =>
+				qb
+					.sent()
+					.at(-1)
+					?.compositeQuery.queries.map((q) => q.spec.name),
+			['A', 'B'],
+		);
+	});
+});

tests/e2e/tests/query-builder/panel-editor.spec.ts

@@ -0,0 +1,203 @@
+import {
+	logsCountQuery,
+	metricsQuery,
+	PanelKind,
+	SINGLE_PANEL_ID,
+	singlePanelDashboard,
+	test as editorTest,
+} from '../../drivers/panel-editor';
+import {
+	expect,
+	reduceToLabel,
+	SUM_METRIC,
+	withMetricTypes,
+	withQueryBuilder,
+} from '../../drivers/query-builder';
+
+const test = withMetricTypes(withQueryBuilder(editorTest));
+
+const LOGS_FILTER = "severity_text = 'ERROR'";
+const TRACES_FILTER = "http.method = 'GET'";
+const PROMQL = 'sum(rate(signoz_calls_total[5m]))';
+
+const QUERIES = {
+	logs: () => logsCountQuery(),
+	traces: () => logsCountQuery({ signal: 'traces' }),
+	metrics: () => metricsQuery(),
+};
+
+const ALL = ['group_by', 'having', 'order_by', 'limit', 'legend_format'];
+const NO_HAVING = ['group_by', 'order_by', 'limit', 'legend_format'];
+const METRICS = ['having', 'order_by', 'limit', 'legend_format'];
+
+/**
+ * Add-on toggles each panel kind offers per signal. Metrics group by lives in
+ * the aggregation row, so it is never a toggle there.
+ */
+const ADD_ONS: Record<
+	keyof typeof QUERIES,
+	Partial<Record<string, string[]>>
+> = {
+	logs: {
+		[PanelKind.TimeSeries]: ALL,
+		[PanelKind.BarChart]: ALL,
+		[PanelKind.Table]: ALL,
+		[PanelKind.PieChart]: ALL,
+		[PanelKind.Number]: ['legend_format'],
+		[PanelKind.Heatmap]: NO_HAVING,
+	},
+	traces: {
+		[PanelKind.TimeSeries]: ALL,
+		[PanelKind.BarChart]: ALL,
+		[PanelKind.Table]: ALL,
+		[PanelKind.PieChart]: ALL,
+		[PanelKind.Number]: ['legend_format'],
+		[PanelKind.Heatmap]: NO_HAVING,
+	},
+	metrics: {
+		[PanelKind.TimeSeries]: METRICS,
+		[PanelKind.BarChart]: METRICS,
+		[PanelKind.Table]: [...METRICS, 'reduce_to'],
+		[PanelKind.PieChart]: [...METRICS, 'reduce_to'],
+		[PanelKind.Number]: ['legend_format', 'reduce_to'],
+		[PanelKind.Heatmap]: ['order_by', 'limit', 'legend_format', 'bucket_options'],
+	},
+};
+
+test.describe('Query builder — panel editor', () => {
+	for (const [signal, kinds] of Object.entries(ADD_ONS)) {
+		for (const [kind, expected] of Object.entries(kinds)) {
+			test(`TC-27 ${signal} on ${kind.replace('signoz/', '')} offers its add-ons`, async ({
+				dashboards,
+				qb,
+			}) => {
+				await dashboards.seedAndEdit(
+					singlePanelDashboard({
+						kind: kind as PanelKind,
+						query: QUERIES[signal as keyof typeof QUERIES](),
+					}),
+					SINGLE_PANEL_ID,
+				);
+
+				await expect(qb.query('A').addOns.toggles()).toHaveCount(
+					expected?.length ?? 0,
+				);
+				const toggles = await qb
+					.query('A')
+					.addOns.toggles()
+					.evaluateAll((nodes) =>
+						nodes.map((node) =>
+							(node.getAttribute('data-testid') ?? '').replace('query-add-on-', ''),
+						),
+					);
+				expect(toggles).toEqual(expected);
+			});
+		}
+	}
+
+	test('TC-27 a limit hidden by a kind switch reopens with its value', async ({
+		dashboards,
+		editor,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: logsCountQuery() }),
+			SINGLE_PANEL_ID,
+		);
+		const addOns = qb.query('A').addOns;
+		await addOns.open('limit');
+		await addOns.limit().fill('7');
+
+		await editor.switchType(PanelKind.Number);
+		await expect(addOns.content('limit')).toHaveCount(0);
+		await editor.switchType(PanelKind.TimeSeries);
+
+		await expect(addOns.limit()).toHaveValue('7');
+		// The kind switch already fetched: Run can be a cache hit.
+		await qb.runButton().click();
+		await expect.poll(() => qb.latest('A')?.limit).toBe(7);
+	});
+
+	test('TC-26 reduce-to follows the metric type and keeps a choice within it', async ({
+		dashboards,
+		metricTypes,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ kind: PanelKind.Table, query: metricsQuery() }),
+			SINGLE_PANEL_ID,
+		);
+		const query = qb.query('A');
+		await expect(query.addOns.reduceTo.value()).toHaveText(reduceToLabel('Sum'));
+
+		await query.addOns.reduceTo.set('Max');
+		await query.metric.select('signoz_latency_count');
+		await expect(query.addOns.reduceTo.value()).toHaveText(reduceToLabel('Max'));
+
+		await query.metric.select(metricTypes.gauge);
+		await expect(query.addOns.reduceTo.value()).toHaveText(
+			reduceToLabel('Average'),
+		);
+
+		await query.metric.select(SUM_METRIC);
+		await expect(query.addOns.reduceTo.value()).toHaveText(reduceToLabel('Sum'));
+		expect(qb.spec(await qb.run(), 'A').aggregations?.[0]).toMatchObject({
+			metricName: SUM_METRIC,
+			reduceTo: 'sum',
+		});
+	});
+
+	test('TC-31 switching signal restores the query left on each signal', async ({
+		dashboards,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: logsCountQuery({ groupBy: [] }) }),
+			SINGLE_PANEL_ID,
+		);
+		const query = qb.query('A');
+		await query.filter.type(LOGS_FILTER);
+		await query.filter.press('Escape');
+
+		await query.setSignal('Traces');
+		await expect.poll(() => query.filter.expression()).toBe('');
+		await query.filter.type(TRACES_FILTER);
+		await query.filter.press('Escape');
+
+		await query.setSignal('Logs');
+		await expect.poll(() => query.filter.expression()).toBe(LOGS_FILTER);
+		await query.setSignal('Traces');
+		await expect.poll(() => query.filter.expression()).toBe(TRACES_FILTER);
+		await qb.runButton().click();
+		await expect
+			.poll(() => qb.latest('A'))
+			.toMatchObject({
+				signal: 'traces',
+				filter: { expression: TRACES_FILTER },
+			});
+	});
+
+	test('TC-33 a PromQL query is sent as promql and kept across tab switches', async ({
+		dashboards,
+		qb,
+	}) => {
+		await dashboards.seedAndEdit(
+			singlePanelDashboard({ query: metricsQuery() }),
+			SINGLE_PANEL_ID,
+		);
+
+		await qb.tab('promql').click();
+		await qb.promql().fill(PROMQL);
+		const fired = await qb.run();
+		expect(fired.at(-1)?.compositeQuery.queries[0]).toMatchObject({
+			type: 'promql',
+			spec: { name: 'A', query: PROMQL },
+		});
+
+		await qb.tab('clickhouse_sql').click();
+		await qb.tab('builder').click();
+		await expect(qb.query('A').metric.spaceAggregation()).toHaveText('Sum');
+		await qb.tab('promql').click();
+		await expect(qb.promql()).toHaveValue(PROMQL);
+	});
+});

tests/e2e/tests/query-builder/run.spec.ts

@@ -0,0 +1,80 @@
+import { expect, EXPLORER, test } from '../../drivers/query-builder';
+import {
+	holdQueryRange,
+	mockQueryRange,
+	mockQueryRangeError,
+	QueryRange,
+	unmockQueryRange,
+} from '../../drivers/query-range-mock';
+
+test.describe('Query builder — run and cancel', () => {
+	test('TC-34 a held run can be cancelled and the next run goes through', async ({
+		authedPage: page,
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		const held = await holdQueryRange(page, QueryRange.empty());
+		await qb.query('A').filter.type("severity_text = 'WARN'");
+		await qb.query('A').filter.press('Escape');
+
+		await qb.runButton().click();
+		await expect(qb.runButton()).toHaveText('Cancel');
+		await qb.runButton().click();
+		await expect(qb.runButton()).toHaveText(/Run Query/);
+		await expect(qb.logsResults()).toContainText('Query cancelled');
+
+		held.release();
+		await unmockQueryRange(page);
+		await qb.query('A').filter.type("severity_text = 'ERROR'");
+		await qb.query('A').filter.press('Escape');
+		// The cancelled query is re-sent alongside; the newest request wins.
+		await qb.run();
+		expect(qb.latest('A')?.filter?.expression).toBe("severity_text = 'ERROR'");
+		await expect(qb.logsResults()).not.toContainText('Query cancelled');
+	});
+
+	test('TC-35 a failed run keeps the query editable and the next run recovers', async ({
+		authedPage: page,
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		await mockQueryRangeError(page, 'mocked query failure');
+		await qb.query('A').filter.type("severity_text = 'INFO'");
+		await qb.query('A').filter.press('Escape');
+
+		await qb.runButton().click();
+		// The failed request is retried before the error settles.
+		await expect(qb.runButton()).toHaveText(/Run Query/, { timeout: 20_000 });
+		await expect(qb.logsResults()).toContainText('mocked query failure');
+		await expect
+			.poll(() => qb.query('A').filter.expression())
+			.toBe("severity_text = 'INFO'");
+
+		await unmockQueryRange(page);
+		await qb.query('A').filter.type("severity_text = 'WARN'");
+		await qb.query('A').filter.press('Escape');
+		const fired = await qb.run();
+		expect(qb.spec(fired, 'A').filter?.expression).toBe("severity_text = 'WARN'");
+		await expect(qb.logsResults()).not.toContainText('mocked query failure');
+	});
+
+	test('TC-35 an empty result leaves the query unchanged', async ({
+		authedPage: page,
+		qb,
+	}) => {
+		await qb.openExplorer(EXPLORER.logs);
+		await mockQueryRange(page, QueryRange.empty());
+		await qb.query('A').filter.type("service.name = 'nothing-here'");
+		await qb.query('A').filter.press('Escape');
+
+		const fired = await qb.run();
+
+		expect(qb.spec(fired, 'A').filter?.expression).toBe(
+			"service.name = 'nothing-here'",
+		);
+		await expect
+			.poll(() => qb.query('A').filter.expression())
+			.toBe("service.name = 'nothing-here'");
+		expect(qb.console.errors).toEqual([]);
+	});
+});

tests/e2e/tests/query-builder/url.spec.ts

@@ -0,0 +1,194 @@
+import { expect, EXPLORER, test } from '../../drivers/query-builder';
+
+// A shared or hand-edited explorer link must never take the page down: the
+// param is parsed, repaired and rewritten before the builder mounts.
+
+const MALFORMED: Record<string, string> = {
+	'not JSON': 'not-json',
+	'truncated JSON': '%7B',
+	'a JSON string': encodeURIComponent('"a string"'),
+	'a JSON array': encodeURIComponent('[]'),
+	'JSON null': 'null',
+	'an empty JSON string': '%22%22',
+	'double encoded': encodeURIComponent(
+		encodeURIComponent(JSON.stringify({ queryType: 'builder' })),
+	),
+};
+
+const PARTIAL: Record<string, unknown> = {
+	'an empty object': {},
+	'builder with no builder block': { queryType: 'builder' },
+	'builder with no queryData': { queryType: 'builder', builder: {} },
+	'empty queryData': {
+		queryType: 'builder',
+		builder: { queryData: [], queryFormulas: [] },
+	},
+	'a query with no dataSource': {
+		queryType: 'builder',
+		builder: { queryData: [{ queryName: 'A' }] },
+	},
+	'an unknown queryType': { queryType: 'zzz' },
+	'non-array promql and clickhouse blocks': {
+		queryType: 'builder',
+		promql: {},
+		clickhouse_sql: 'x',
+		builder: { queryData: [{ queryName: 'A', dataSource: 'logs' }] },
+	},
+};
+
+/**
+ * Saved before the v5 builder: structured filters, a having array and an
+ * aggregate operator. The old having filter wrote `columnName` upper-cased
+ * (`COUNT()`).
+ */
+const legacyLogsQuery = (having: unknown[]): unknown => ({
+	queryType: 'builder',
+	promql: [],
+	clickhouse_sql: [],
+	builder: {
+		queryFormulas: [],
+		queryData: [
+			{
+				queryName: 'A',
+				dataSource: 'logs',
+				expression: 'A',
+				disabled: false,
+				aggregateOperator: 'count',
+				aggregateAttribute: { key: '', dataType: '', type: '', isColumn: false },
+				filters: {
+					op: 'AND',
+					items: [
+						{
+							id: 'f1',
+							key: {
+								key: 'severity_text',
+								dataType: 'string',
+								type: '',
+								isColumn: true,
+							},
+							op: '=',
+							value: 'ERROR',
+						},
+					],
+				},
+				having,
+				groupBy: [],
+				orderBy: [],
+				functions: [],
+				legend: '',
+				limit: null,
+				stepInterval: 60,
+				reduceTo: 'avg',
+			},
+		],
+	},
+});
+
+const FIRST = "service.name = 'frontend'";
+const SECOND = "service.name = 'cartservice'";
+
+interface UrlQuery {
+	builder?: { queryData?: { filter?: { expression?: string } }[] };
+}
+
+test.describe('Query builder — URL handling', () => {
+	for (const [label, raw] of Object.entries(MALFORMED)) {
+		test(`TC-01 logs explorer survives ${label} and still runs`, async ({
+			qb,
+		}) => {
+			await qb.openExplorer(EXPLORER.logs, { raw });
+
+			await expect(qb.query('A').filter.content()).toBeVisible();
+			await qb.query('A').filter.type("severity_text = 'ERROR'");
+			const fired = await qb.run();
+
+			expect(qb.spec(fired, 'A').filter?.expression).toBe(
+				"severity_text = 'ERROR'",
+			);
+			expect(qb.urlQuery()).toMatchObject({ queryType: 'builder' });
+			expect(qb.console.errors).toEqual([]);
+		});
+	}
+
+	for (const [label, query] of Object.entries(PARTIAL)) {
+		test(`TC-02 logs explorer repairs ${label}`, async ({ qb }) => {
+			const loaded = await qb.openExplorer(EXPLORER.logs, { query });
+
+			expect(qb.spec(loaded, 'A').signal).toBe('logs');
+			await expect
+				.poll(() => qb.urlQuery())
+				.toMatchObject({
+					queryType: 'builder',
+					builder: { queryData: [{ queryName: 'A', dataSource: 'logs' }] },
+				});
+			expect(qb.console.errors).toEqual([]);
+		});
+	}
+
+	test('TC-03 legacy filters and aggregate operator convert to v5 expressions', async ({
+		qb,
+	}) => {
+		const loaded = await qb.openExplorer(EXPLORER.logs, {
+			view: 'graph',
+			query: legacyLogsQuery([]),
+		});
+
+		const spec = qb.spec(loaded, 'A');
+		expect(spec.filter?.expression).toMatch(/^severity_text\s*=\s*'ERROR'$/);
+		expect(spec.aggregations?.[0]?.expression).toBe('count()');
+		expect(spec).not.toHaveProperty('filters');
+		await expect
+			.poll(() => qb.query('A').filter.expression())
+			.toMatch(/^severity_text\s*=\s*'ERROR'$/);
+		expect(qb.console.errors).toEqual([]);
+	});
+
+	test('TC-03 a legacy having as the old builder stored it still runs', async ({
+		qb,
+	}) => {
+		const loaded = await qb.openExplorer(EXPLORER.logs, {
+			view: 'graph',
+			query: legacyLogsQuery([{ columnName: 'COUNT()', op: '>', value: 5 }]),
+		});
+
+		expect(qb.spec(loaded, 'A').having?.expression).toBe('count() > 5');
+		expect(qb.console.failedResponses).toEqual([]);
+	});
+
+	for (const explorer of ['logs', 'traces'] as const) {
+		test(`TC-04 ${explorer} explorer query follows back, forward and reload`, async ({
+			authedPage: page,
+			qb,
+		}) => {
+			await qb.openExplorer(EXPLORER[explorer]);
+			const filter = qb.query('A').filter;
+			const urlFilter = (): unknown =>
+				(qb.urlQuery() as UrlQuery | null)?.builder?.queryData?.[0]?.filter
+					?.expression;
+
+			await filter.type(FIRST);
+			await qb.run();
+			await filter.type(SECOND);
+			await qb.run();
+
+			await page.goBack();
+			await expect.poll(urlFilter).toBe(FIRST);
+			await expect.poll(() => filter.expression()).toBe(FIRST);
+
+			await page.goForward();
+			await expect.poll(urlFilter).toBe(SECOND);
+			await expect.poll(() => filter.expression()).toBe(SECOND);
+
+			await filter.type("service.name = 'unsaved'");
+			const sentBefore = qb.sent().length;
+			await page.reload();
+			await expect.poll(() => filter.expression()).toBe(SECOND);
+			await expect
+				.poll(() => qb.sent().slice(sentBefore).length)
+				.toBeGreaterThan(0);
+			expect(qb.spec(qb.sent().slice(sentBefore), 'A').filter?.expression).toBe(
+				SECOND,
+			);
+		});
+	}
+});