Merge branch 'main' into issue-5535

* refactor(authz): drop create guarded route component

* refactor(authz): drop guarded authz component

* refactor(authz): support list of permissions on denied callout

* refactor(authz): support list of permissions on denied page

* feat(authz): add guard authz button

* feat(authz): add guard authz with page/content variants

* feat(authz): add withAuthZ HOC component to guard pages/components

* feat(authz): add docs for authz + agents update

.github/workflows/integrationci.yaml

@@ -56,6 +56,8 @@ jobs:
           - querier_json_body
           - querier_skip_resource_fingerprint
           - ttl
+          - clickhousecluster
+          - metricreduction
         sqlstore-provider:
           - postgres
           - sqlite

frontend/AGENTS.md

@@ -25,6 +25,7 @@ You are operating within a constrained context window and strict system prompts.
 - Never create barrel files.
 - When writing new css, prefer CSS Modules
   - Use ./docs/css-modules-guide.md as reference on how to write good CSS Modules.
+- When writing code that could need authorization checks, read ./src/lib/authz/README.md
 
 3. FORCED VERIFICATION: Your internal tools mark file writes as successful even if the code does not compile. You are FORBIDDEN from reporting a task as complete until you have:
 - Run `pnpm tsgo --noEmit`

frontend/src/components/RouteTab/types.ts

@@ -1,10 +1,11 @@
+import { ComponentType } from 'react';
 import { TabsProps } from 'antd';
 import { History } from 'history';
 
 export type TabRoutes = {
 	name: React.ReactNode;
 	route: string;
-	Component: () => JSX.Element;
+	Component: ComponentType;
 	key: string;
 };
 

frontend/src/lib/authz/README.md

@@ -0,0 +1,21 @@
+# AuthZ
+
+Permission-based authorization system for SigNoz frontend.
+
+## Supported Resources
+
+See [hooks/useAuthZ/permissions.type.ts](./hooks/useAuthZ/permissions.type.ts) for available resources and verbs.
+
+If your page/content represents a resource not listed there, skip authz implementation — the backend doesn't enforce it yet.
+
+## UI Gating
+
+Need to gate UI based on permissions? See [components/README.md](./components/README.md).
+
+Covers: AuthZButton, AuthZTooltip, withAuthZ*, AuthZGuard*, when to use each.
+
+## Testing
+
+Need to test authz behavior? See [utils/README.md](./utils/README.md).
+
+Covers: MSW handlers, mock hooks, test patterns.

frontend/src/lib/authz/components/AuthZButton/AuthZButton.authz.test.tsx

@@ -0,0 +1,81 @@
+import { ReactElement } from 'react';
+import { render, screen } from 'tests/test-utils';
+import AuthZTooltip from 'lib/authz/components/AuthZTooltip/AuthZTooltip';
+import type { AuthZObject } from 'lib/authz/hooks/useAuthZ/types';
+import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';
+
+import AuthZButton from './AuthZButton';
+
+// AuthZButton is a thin composition over AuthZTooltip + Button. The denial
+// tooltip / disabled-on-deny UX is owned and tested by AuthZTooltip; here we
+// assert AuthZButton forwards the right props and renders a Button child.
+jest.mock('lib/authz/components/AuthZTooltip/AuthZTooltip');
+const mockTooltip = AuthZTooltip as unknown as jest.Mock;
+
+const createPerm = buildPermission(
+	'create',
+	'serviceaccount:*' as AuthZObject<'create'>,
+);
+
+describe('AuthZButton', () => {
+	beforeEach(() => {
+		mockTooltip.mockImplementation(
+			({ children }: { children: ReactElement }) => children,
+		);
+	});
+
+	afterEach(() => {
+		mockTooltip.mockReset();
+	});
+
+	it('renders a Button child with forwarded props', () => {
+		render(
+			<AuthZButton checks={[createPerm]} testId="create-btn">
+				Create
+			</AuthZButton>,
+		);
+
+		expect(screen.getByTestId('create-btn')).toBeInTheDocument();
+		expect(screen.getByTestId('create-btn').tagName).toBe('BUTTON');
+	});
+
+	it('forwards checks and enables the check by default', () => {
+		render(
+			<AuthZButton checks={[createPerm]} testId="create-btn">
+				Create
+			</AuthZButton>,
+		);
+
+		expect(mockTooltip).toHaveBeenCalledTimes(1);
+		expect(mockTooltip.mock.calls[0][0]).toMatchObject({
+			checks: [createPerm],
+			enabled: true,
+		});
+	});
+
+	it('forwards a custom tooltipMessage', () => {
+		render(
+			<AuthZButton
+				checks={[createPerm]}
+				tooltipMessage="Ask an admin"
+				testId="create-btn"
+			>
+				Create
+			</AuthZButton>,
+		);
+
+		expect(mockTooltip.mock.calls[0][0]).toMatchObject({
+			tooltipMessage: 'Ask an admin',
+		});
+	});
+
+	it('passes authZEnabled through as the tooltip enabled flag', () => {
+		render(
+			<AuthZButton checks={[createPerm]} authZEnabled={false} testId="create-btn">
+				Create
+			</AuthZButton>,
+		);
+
+		expect(mockTooltip.mock.calls[0][0]).toMatchObject({ enabled: false });
+	});
+});

frontend/src/lib/authz/components/AuthZButton/AuthZButton.tsx

@@ -0,0 +1,37 @@
+import { Button, ButtonProps } from '@signozhq/ui/button';
+import AuthZTooltip from 'lib/authz/components/AuthZTooltip/AuthZTooltip';
+import type { BrandedPermission } from 'lib/authz/hooks/useAuthZ/types';
+
+export type AuthZButtonProps = ButtonProps & {
+	/**
+	 * Permissions required to enable the button (AND semantics).
+	 */
+	checks: BrandedPermission[];
+	/**
+	 * Override the default denial tooltip message.
+	 */
+	tooltipMessage?: string;
+	/**
+	 * Gate the permission check itself. When false, renders a plain button.
+	 */
+	authZEnabled?: boolean;
+};
+
+function AuthZButton({
+	checks,
+	tooltipMessage,
+	authZEnabled = true,
+	...buttonProps
+}: AuthZButtonProps): JSX.Element {
+	return (
+		<AuthZTooltip
+			checks={checks}
+			enabled={authZEnabled}
+			tooltipMessage={tooltipMessage}
+		>
+			<Button {...buttonProps} />
+		</AuthZTooltip>
+	);
+}
+
+export default AuthZButton;

frontend/src/lib/authz/components/AuthZGuard/AuthZGuard.authz.test.tsx

@@ -0,0 +1,202 @@
+import { render, screen, waitFor } from 'tests/test-utils';
+import { server } from 'mocks-server/server';
+import { rest } from 'msw';
+import {
+	AUTHZ_CHECK_URL,
+	setupAuthzAllow,
+	setupAuthzDeny,
+} from 'lib/authz/utils/authz-test-utils';
+import type { AuthZObject } from 'lib/authz/hooks/useAuthZ/types';
+import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';
+
+import { AuthZGuard } from './AuthZGuard';
+import { AuthZGuardContent } from './AuthZGuardContent';
+import { AuthZGuardPage } from './AuthZGuardPage';
+
+const readPerm = buildPermission('read', 'role:*' as AuthZObject<'read'>);
+
+const Protected = (): JSX.Element => <div>Protected content</div>;
+
+describe('AuthZGuard', () => {
+	it('renders children when allowed', async () => {
+		server.use(setupAuthzAllow(readPerm));
+
+		render(
+			<AuthZGuard checks={[readPerm]}>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('Protected content')).toBeInTheDocument();
+		});
+	});
+
+	it('renders the fallback when denied', async () => {
+		server.use(setupAuthzDeny(readPerm));
+
+		render(
+			<AuthZGuard checks={[readPerm]} fallback={<div>No access</div>}>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('No access')).toBeInTheDocument();
+		});
+		expect(screen.queryByText('Protected content')).not.toBeInTheDocument();
+	});
+
+	it('passes denied permissions to a function fallback', async () => {
+		server.use(setupAuthzDeny(readPerm));
+
+		render(
+			<AuthZGuard
+				checks={[readPerm]}
+				fallback={({ deniedPermissions }): JSX.Element => (
+					<div>denied: {deniedPermissions.length}</div>
+				)}
+			>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('denied: 1')).toBeInTheDocument();
+		});
+	});
+
+	it('renders nothing for a denied check with no fallback', async () => {
+		server.use(setupAuthzDeny(readPerm));
+
+		const { container } = render(
+			<AuthZGuard checks={[readPerm]}>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		await waitFor(() => {
+			expect(screen.queryByText('Protected content')).not.toBeInTheDocument();
+		});
+		expect(container).toBeEmptyDOMElement();
+	});
+
+	it('renders the loading fallback while checking', () => {
+		server.use(setupAuthzAllow(readPerm));
+
+		render(
+			<AuthZGuard checks={[readPerm]} fallbackOnLoading={<div>Loading…</div>}>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		expect(screen.getByText('Loading…')).toBeInTheDocument();
+	});
+
+	it('fails open on error by default (renders children)', async () => {
+		server.use(
+			rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) =>
+				res(ctx.status(500), ctx.json({ error: 'boom' })),
+			),
+		);
+
+		render(
+			<AuthZGuard checks={[readPerm]} fallback={<div>No access</div>}>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('Protected content')).toBeInTheDocument();
+		});
+	});
+
+	it('renders the fallback on error when failOpenOnError is false', async () => {
+		server.use(
+			rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) =>
+				res(ctx.status(500), ctx.json({ error: 'boom' })),
+			),
+		);
+
+		render(
+			<AuthZGuard
+				checks={[readPerm]}
+				onFailRenderContent={false}
+				fallback={<div>No access</div>}
+			>
+				<Protected />
+			</AuthZGuard>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('No access')).toBeInTheDocument();
+		});
+		expect(screen.queryByText('Protected content')).not.toBeInTheDocument();
+	});
+});
+
+describe('AuthZGuardPage', () => {
+	it('renders the full-page denied screen when denied', async () => {
+		server.use(setupAuthzDeny(readPerm));
+
+		render(
+			<AuthZGuardPage checks={[readPerm]}>
+				<Protected />
+			</AuthZGuardPage>,
+		);
+
+		await waitFor(() => {
+			expect(
+				screen.getByText('Uh-oh! You are not authorized'),
+			).toBeInTheDocument();
+		});
+		expect(screen.getByText('read:role:*')).toBeInTheDocument();
+	});
+
+	it('renders the app loader while checking', () => {
+		server.use(setupAuthzDeny(readPerm));
+
+		render(
+			<AuthZGuardPage checks={[readPerm]}>
+				<Protected />
+			</AuthZGuardPage>,
+		);
+
+		expect(
+			screen.getByText(
+				'OpenTelemetry-Native Logs, Metrics and Traces in a single pane',
+			),
+		).toBeInTheDocument();
+	});
+});
+
+describe('AuthZGuardContent', () => {
+	it('renders the denied callout when denied', async () => {
+		server.use(setupAuthzDeny(readPerm));
+
+		render(
+			<AuthZGuardContent checks={[readPerm]}>
+				<Protected />
+			</AuthZGuardContent>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('read:role:*')).toBeInTheDocument();
+		});
+		expect(screen.queryByText('Protected content')).not.toBeInTheDocument();
+	});
+
+	it('renders children when allowed', async () => {
+		server.use(setupAuthzAllow(readPerm));
+
+		render(
+			<AuthZGuardContent checks={[readPerm]}>
+				<Protected />
+			</AuthZGuardContent>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByText('Protected content')).toBeInTheDocument();
+		});
+	});
+});

frontend/src/lib/authz/components/AuthZGuard/AuthZGuard.tsx

@@ -0,0 +1,82 @@
+import { ReactElement, ReactNode, useMemo } from 'react';
+import type { BrandedPermission } from 'lib/authz/hooks/useAuthZ/types';
+import { useAuthZ } from 'lib/authz/hooks/useAuthZ/useAuthZ';
+
+export type AuthZGuardFallback =
+	| ReactNode
+	| ((info: { deniedPermissions: BrandedPermission[] }) => ReactNode);
+
+export type AuthZGuardProps = {
+	/**
+	 * Permissions required to render `children` (AND semantics).
+	 */
+	checks: BrandedPermission[];
+	children: ReactElement;
+	/**
+	 * Rendered when denied. A function receives the denied permissions.
+	 */
+	fallback?: AuthZGuardFallback;
+	fallbackOnLoading?: ReactNode;
+	/**
+	 * By default, we don't expect the check API request to fail, in those cases, we prefer to show the content and then let the API fail (during list/create).
+	 *
+	 * In case you want to have a different behavior when request fail, set to false.
+	 *
+	 * @default true
+	 */
+	onFailRenderContent?: boolean;
+};
+
+function resolveFallback(
+	fallback: AuthZGuardFallback | undefined,
+	deniedPermissions: BrandedPermission[],
+): ReactNode {
+	if (typeof fallback === 'function') {
+		return fallback({ deniedPermissions });
+	}
+	return fallback ?? null;
+}
+
+export function AuthZGuard({
+	checks,
+	children,
+	fallback,
+	fallbackOnLoading,
+	onFailRenderContent = true,
+}: AuthZGuardProps): JSX.Element | null {
+	const { isLoading, error, permissions } = useAuthZ(checks);
+
+	// TODO(authz): Use allowed/deniedPermissions from useAuthZ after devtools PR merges
+	const { allowed, deniedPermissions } = useMemo(() => {
+		if (!permissions) {
+			return { allowed: false, deniedPermissions: [] as BrandedPermission[] };
+		}
+
+		const denied = Object.entries(permissions)
+			.filter(([, { isGranted }]) => !isGranted)
+			.map(([perm]) => perm as BrandedPermission);
+
+		return {
+			allowed: denied.length === 0,
+			deniedPermissions: denied,
+		};
+	}, [permissions]);
+
+	if (isLoading) {
+		return <>{fallbackOnLoading ?? null}</>;
+	}
+
+	if (error) {
+		return onFailRenderContent ? (
+			children
+		) : (
+			<>{resolveFallback(fallback, deniedPermissions)}</>
+		);
+	}
+
+	if (!allowed) {
+		return <>{resolveFallback(fallback, deniedPermissions)}</>;
+	}
+
+	return children;
+}

frontend/src/lib/authz/components/AuthZGuard/AuthZGuardContent.tsx

@@ -0,0 +1,21 @@
+import { ReactElement } from 'react';
+import PermissionDeniedCallout from 'lib/authz/components/PermissionDeniedCallout/PermissionDeniedCallout';
+
+import { AuthZGuard, AuthZGuardProps } from './AuthZGuard';
+
+export function AuthZGuardContent({
+	fallback,
+	...rest
+}: AuthZGuardProps): JSX.Element | null {
+	return (
+		<AuthZGuard
+			{...rest}
+			fallback={
+				fallback ??
+				(({ deniedPermissions }): ReactElement => (
+					<PermissionDeniedCallout deniedPermissions={deniedPermissions} />
+				))
+			}
+		/>
+	);
+}

frontend/src/lib/authz/components/AuthZGuard/AuthZGuardPage.tsx

@@ -0,0 +1,24 @@
+import { ReactElement } from 'react';
+import AppLoading from 'components/AppLoading/AppLoading';
+import PermissionDeniedFullPage from 'lib/authz/components/PermissionDeniedFullPage/PermissionDeniedFullPage';
+
+import { AuthZGuard, AuthZGuardProps } from './AuthZGuard';
+
+export function AuthZGuardPage({
+	fallback,
+	fallbackOnLoading,
+	...rest
+}: AuthZGuardProps): JSX.Element | null {
+	return (
+		<AuthZGuard
+			{...rest}
+			fallbackOnLoading={fallbackOnLoading ?? <AppLoading />}
+			fallback={
+				fallback ??
+				(({ deniedPermissions }): ReactElement => (
+					<PermissionDeniedFullPage deniedPermissions={deniedPermissions} />
+				))
+			}
+		/>
+	);
+}

frontend/src/lib/authz/components/AuthZTooltip/AuthZTooltip.authz.test.tsx

@@ -16,6 +16,8 @@ const noPermissions = {
 	isFetching: false,
 	error: null,
 	permissions: null,
+	allowed: false,
+	deniedPermissions: [] as BrandedPermission[],
 	refetchPermissions: jest.fn(),
 };
 
@@ -160,11 +162,11 @@ describe('AuthZTooltip — multi-check (checks array)', () => {
 			</AuthZTooltip>,
 		);
 
-		expect(screen.getByRole('button', { name: 'Action' })).toBeDisabled();
+		const button = screen.getByRole('button', { name: 'Action' });
+		expect(button).toBeDisabled();
 
-		const wrapper = screen.getByRole('button', { name: 'Action' }).parentElement;
-		expect(wrapper?.getAttribute('data-denied-permissions')).toContain(sa);
-		expect(wrapper?.getAttribute('data-denied-permissions')).toContain(
+		expect(button.getAttribute('data-denied-permissions')).toContain(sa);
+		expect(button.getAttribute('data-denied-permissions')).toContain(
 			attachRolePerm,
 		);
 	});

frontend/src/lib/authz/components/AuthZTooltip/AuthZTooltip.module.scss

@@ -1,7 +1,3 @@
-.wrapper {
-	cursor: not-allowed;
-}
-
 .errorContent {
 	background: var(--callout-error-background) !important;
 	border-color: var(--callout-error-border) !important;

frontend/src/lib/authz/components/AuthZTooltip/AuthZTooltip.tsx

@@ -1,4 +1,4 @@
-import { ReactElement, cloneElement, useMemo } from 'react';
+import { CSSProperties, ReactElement, cloneElement, useMemo } from 'react';
 import {
 	TooltipRoot,
 	TooltipContent,
@@ -11,6 +11,13 @@ import { formatPermission } from 'lib/authz/hooks/useAuthZ/utils';
 import { useAppContext } from 'providers/App/App';
 import styles from './AuthZTooltip.module.scss';
 
+const DISABLED_STYLE: CSSProperties = {
+	pointerEvents: 'all',
+	cursor: 'not-allowed',
+};
+
+const noOp = (): void => {};
+
 interface AuthZTooltipProps {
 	checks: BrandedPermission[];
 	children: ReactElement;
@@ -49,11 +56,13 @@ function AuthZTooltip({
 	}, [checks, permissions]);
 
 	if (shouldCheck && isLoading) {
-		return (
-			<span className={styles.wrapper}>
-				{cloneElement(children, { disabled: true })}
-			</span>
-		);
+		return cloneElement(children, {
+			disabled: true,
+			style: DISABLED_STYLE,
+			onClick: noOp,
+			onMouseDown: noOp,
+			onPointerDown: noOp,
+		});
 	}
 
 	if (!shouldCheck || deniedPermissions.length === 0) {
@@ -64,12 +73,14 @@ function AuthZTooltip({
 		<TooltipProvider>
 			<TooltipRoot>
 				<TooltipTrigger asChild>
-					<span
-						className={styles.wrapper}
-						data-denied-permissions={deniedPermissions.join(',')}
-					>
-						{cloneElement(children, { disabled: true })}
-					</span>
+					{cloneElement(children, {
+						disabled: true,
+						style: DISABLED_STYLE,
+						onClick: noOp,
+						onMouseDown: noOp,
+						onPointerDown: noOp,
+						'data-denied-permissions': deniedPermissions.join(','),
+					})}
 				</TooltipTrigger>
 				<TooltipContent className={styles.errorContent}>
 					{formatDeniedMessage(deniedPermissions, user.id, tooltipMessage)}

frontend/src/lib/authz/components/GuardAuthZ/GuardAuthZ.authz.test.tsx

@@ -1,263 +0,0 @@
-import { ReactElement } from 'react';
-import { BrandedPermission } from 'lib/authz/hooks/useAuthZ/types';
-import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';
-import { server } from 'mocks-server/server';
-import { rest } from 'msw';
-import { render, screen, waitFor } from 'tests/test-utils';
-import {
-	AUTHZ_CHECK_URL,
-	authzMockResponse,
-} from 'lib/authz/utils/authz-test-utils';
-
-import { GuardAuthZ } from './GuardAuthZ';
-
-describe('GuardAuthZ', () => {
-	const TestChild = (): ReactElement => <div>Protected Content</div>;
-	const LoadingFallback = (): ReactElement => <div>Loading...</div>;
-	const NoPermissionFallback = (_response: {
-		requiredPermissionName: BrandedPermission;
-	}): ReactElement => <div>Access denied</div>;
-	const NoPermissionFallbackWithSuggestions = (response: {
-		requiredPermissionName: BrandedPermission;
-	}): ReactElement => (
-		<div>
-			Access denied. Required permission: {response.requiredPermissionName}
-		</div>
-	);
-
-	it('should render children when permission is granted', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		render(
-			<GuardAuthZ relation="read" object="role:*">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(screen.getByText('Protected Content')).toBeInTheDocument();
-		});
-	});
-
-	it('should render fallbackOnLoading when loading', () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (_req, res, ctx) => {
-				return res(
-					ctx.delay('infinite'),
-					ctx.status(200),
-					ctx.json({ data: [], status: 'success' }),
-				);
-			}),
-		);
-
-		render(
-			<GuardAuthZ
-				relation="read"
-				object="role:*"
-				fallbackOnLoading={<LoadingFallback />}
-			>
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		expect(screen.getByText('Loading...')).toBeInTheDocument();
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should render null when loading and no fallbackOnLoading provided', () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (_req, res, ctx) => {
-				return res(
-					ctx.delay('infinite'),
-					ctx.status(200),
-					ctx.json({ data: [], status: 'success' }),
-				);
-			}),
-		);
-
-		const { container } = render(
-			<GuardAuthZ relation="read" object="role:*">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		expect(container.firstChild).toBeNull();
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should render children when API error occurs and no fallbackOnError provided (fail open)', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) => {
-				return res(ctx.status(500), ctx.json({ error: 'Internal Server Error' }));
-			}),
-		);
-
-		render(
-			<GuardAuthZ relation="read" object="role:*">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(screen.getByText('Protected Content')).toBeInTheDocument();
-		});
-	});
-
-	it('should render fallbackOnError when API error occurs and fallbackOnError is provided', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) => {
-				return res(ctx.status(500), ctx.json({ error: 'Internal Server Error' }));
-			}),
-		);
-
-		render(
-			<GuardAuthZ
-				relation="read"
-				object="role:*"
-				fallbackOnError={<div>Custom error fallback</div>}
-			>
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(screen.getByText('Custom error fallback')).toBeInTheDocument();
-		});
-
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should render fallbackOnNoPermissions when permission is denied', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [false])));
-			}),
-		);
-
-		render(
-			<GuardAuthZ
-				relation="update"
-				object="role:123"
-				fallbackOnNoPermissions={NoPermissionFallback}
-			>
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(screen.getByText('Access denied')).toBeInTheDocument();
-		});
-
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should render null when permission is denied and no fallbackOnNoPermissions provided', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [false])));
-			}),
-		);
-
-		const { container } = render(
-			<GuardAuthZ relation="update" object="role:123">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(container.firstChild).toBeNull();
-		});
-
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should render null when permissions object is null', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) => {
-				return res(ctx.status(200), ctx.json({ data: [], status: 'success' }));
-			}),
-		);
-
-		const { container } = render(
-			<GuardAuthZ relation="read" object="role:*">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(container.firstChild).toBeNull();
-		});
-
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should pass requiredPermissionName to fallbackOnNoPermissions', async () => {
-		const permission = buildPermission('update', 'role:123');
-
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [false])));
-			}),
-		);
-
-		render(
-			<GuardAuthZ
-				relation="update"
-				object="role:123"
-				fallbackOnNoPermissions={NoPermissionFallbackWithSuggestions}
-			>
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(
-				screen.getByText(/Access denied. Required permission:/),
-			).toBeInTheDocument();
-		});
-
-		expect(
-			screen.getAllByText(
-				new RegExp(permission.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')),
-			).length,
-		).toBeGreaterThan(0);
-		expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
-	});
-
-	it('should handle different relation and object combinations', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const { rerender } = render(
-			<GuardAuthZ relation="read" object="role:*">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(screen.getByText('Protected Content')).toBeInTheDocument();
-		});
-
-		rerender(
-			<GuardAuthZ relation="delete" object="role:456">
-				<TestChild />
-			</GuardAuthZ>,
-		);
-
-		await waitFor(() => {
-			expect(screen.getByText('Protected Content')).toBeInTheDocument();
-		});
-	});
-});

frontend/src/lib/authz/components/GuardAuthZ/GuardAuthZ.tsx

@@ -1,50 +0,0 @@
-import { ReactElement } from 'react';
-import {
-	AuthZObject,
-	AuthZRelation,
-	BrandedPermission,
-} from 'lib/authz/hooks/useAuthZ/types';
-import { useAuthZ } from 'lib/authz/hooks/useAuthZ/useAuthZ';
-import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';
-
-export type GuardAuthZProps<R extends AuthZRelation> = {
-	children: ReactElement;
-	relation: R;
-	object: AuthZObject<R>;
-	fallbackOnLoading?: JSX.Element;
-	fallbackOnError?: JSX.Element;
-	fallbackOnNoPermissions?: (response: {
-		requiredPermissionName: BrandedPermission;
-	}) => JSX.Element;
-};
-
-export function GuardAuthZ<R extends AuthZRelation>({
-	children,
-	relation,
-	object,
-	fallbackOnLoading,
-	fallbackOnError,
-	fallbackOnNoPermissions,
-}: GuardAuthZProps<R>): JSX.Element | null {
-	const permission = buildPermission<R>(relation, object);
-
-	const { permissions, isLoading, error } = useAuthZ([permission]);
-
-	if (isLoading) {
-		return fallbackOnLoading ?? null;
-	}
-
-	if (error) {
-		return fallbackOnError ?? children;
-	}
-
-	if (!permissions?.[permission]?.isGranted) {
-		return (
-			fallbackOnNoPermissions?.({
-				requiredPermissionName: permission,
-			}) ?? null
-		);
-	}
-
-	return children;
-}

frontend/src/lib/authz/components/PermissionDeniedCallout/PermissionDeniedCallout.test.tsx

@@ -1,18 +1,39 @@
 import { render, screen } from 'tests/test-utils';
 import PermissionDeniedCallout from './PermissionDeniedCallout';
+import {
+	buildPermission,
+	buildObjectString,
+} from 'lib/authz/hooks/useAuthZ/utils';
 
 describe('PermissionDeniedCallout', () => {
 	it('renders the permission name in the callout message', () => {
-		render(<PermissionDeniedCallout permissionName="serviceaccount:attach" />);
+		const deniedPermissions = [
+			buildPermission('read', buildObjectString('serviceaccount', '*')),
+		];
+		render(<PermissionDeniedCallout deniedPermissions={deniedPermissions} />);
 
 		expect(screen.getByText(/is not authorized/)).toBeInTheDocument();
-		expect(screen.getByText(/serviceaccount:attach/)).toBeInTheDocument();
+		expect(screen.getByText(/read:serviceaccount:\*/)).toBeInTheDocument();
+	});
+
+	it('renders multiple denied permissions', () => {
+		const deniedPermissions = [
+			buildPermission('read', buildObjectString('serviceaccount', '*')),
+			buildPermission('update', buildObjectString('role', 'admin')),
+		];
+		render(<PermissionDeniedCallout deniedPermissions={deniedPermissions} />);
+
+		expect(screen.getByText(/read:serviceaccount:\*/)).toBeInTheDocument();
+		expect(screen.getByText(/update:role:admin/)).toBeInTheDocument();
 	});
 
 	it('accepts an optional className', () => {
+		const deniedPermissions = [
+			buildPermission('read', buildObjectString('serviceaccount', '*')),
+		];
 		const { container } = render(
 			<PermissionDeniedCallout
-				permissionName="serviceaccount:read"
+				deniedPermissions={deniedPermissions}
 				className="custom-class"
 			/>,
 		);

frontend/src/lib/authz/components/PermissionDeniedCallout/PermissionDeniedCallout.tsx

@@ -3,18 +3,32 @@ import cx from 'classnames';
 import styles from './PermissionDeniedCallout.module.scss';
 import { useAppContext } from 'providers/App/App';
 import { Typography } from '@signozhq/ui/typography';
+import { BrandedPermission } from 'lib/authz/hooks/useAuthZ/types';
+import { formatPermission } from 'lib/authz/hooks/useAuthZ/utils';
 
-interface PermissionDeniedCalloutProps {
-	permissionName: string;
+export interface PermissionDeniedCalloutProps {
+	/**
+	 * @deprecated Use `deniedPermissions` instead. Will be removed after authz devtools PR merges.
+	 */
+	permissionName?: string;
+	deniedPermissions?: BrandedPermission[];
 	className?: string;
 }
 
 function PermissionDeniedCallout({
 	permissionName,
+	deniedPermissions,
 	className,
 }: PermissionDeniedCalloutProps): JSX.Element {
 	const { user } = useAppContext();
 
+	// TODO(authz): Remove permissionName support after devtools PR merges
+	const formattedPermissions = deniedPermissions
+		? deniedPermissions.map(formatPermission)
+		: permissionName
+			? [permissionName]
+			: [];
+
 	return (
 		<Callout
 			type="error"
@@ -25,7 +39,12 @@ function PermissionDeniedCallout({
 			<Typography.Text className={styles.permission}>
 				<code className={styles.permissionCode}>user/{user.id}</code> is not
 				authorized to perform{' '}
-				<code className={styles.permissionCode}>{permissionName}</code>
+				{formattedPermissions.map((perm, idx) => (
+					<span key={perm}>
+						<code className={styles.permissionCode}>{perm}</code>
+						{idx < formattedPermissions.length - 1 && ', '}
+					</span>
+				))}
 			</Typography.Text>
 		</Callout>
 	);

frontend/src/lib/authz/components/PermissionDeniedFullPage/PermissionDeniedFullPage.test.tsx

@@ -1,17 +1,29 @@
 import { render, screen } from 'tests/test-utils';
 import PermissionDeniedFullPage from './PermissionDeniedFullPage';
+import {
+	buildPermission,
+	buildObjectString,
+} from 'lib/authz/hooks/useAuthZ/utils';
 
 describe('PermissionDeniedFullPage', () => {
 	it('renders the title and subtitle with the permissionName interpolated', () => {
-		render(<PermissionDeniedFullPage permissionName="serviceaccount:list" />);
+		const deniedPermissions = [
+			buildPermission('read', buildObjectString('serviceaccount', '*')),
+		];
+		render(<PermissionDeniedFullPage deniedPermissions={deniedPermissions} />);
 
 		expect(screen.getByText('Uh-oh! You are not authorized')).toBeInTheDocument();
-		expect(screen.getByText(/serviceaccount:list/)).toBeInTheDocument();
+		expect(screen.getByText(/read:serviceaccount:\*/)).toBeInTheDocument();
 		expect(screen.getByText(/is not authorized to perform/)).toBeInTheDocument();
 	});
 
-	it('renders with a different permissionName', () => {
-		render(<PermissionDeniedFullPage permissionName="role:read" />);
-		expect(screen.getByText(/role:read/)).toBeInTheDocument();
+	it('renders with multiple denied permissions', () => {
+		const deniedPermissions = [
+			buildPermission('read', buildObjectString('role', 'admin')),
+			buildPermission('update', buildObjectString('role', 'admin')),
+		];
+		render(<PermissionDeniedFullPage deniedPermissions={deniedPermissions} />);
+		expect(screen.getByText(/read:role:admin/)).toBeInTheDocument();
+		expect(screen.getByText(/update:role:admin/)).toBeInTheDocument();
 	});
 });

frontend/src/lib/authz/components/PermissionDeniedFullPage/PermissionDeniedFullPage.tsx

@@ -3,16 +3,30 @@ import { CircleSlash2 } from '@signozhq/icons';
 import styles from './PermissionDeniedFullPage.module.scss';
 import { Style } from '@signozhq/design-tokens';
 import { useAppContext } from 'providers/App/App';
+import { BrandedPermission } from 'lib/authz/hooks/useAuthZ/types';
+import { formatPermission } from 'lib/authz/hooks/useAuthZ/utils';
 
-interface PermissionDeniedFullPageProps {
-	permissionName: string;
+export interface PermissionDeniedFullPageProps {
+	/**
+	 * @deprecated Use `deniedPermissions` instead. Will be removed after authz devtools PR merges.
+	 */
+	permissionName?: string;
+	deniedPermissions?: BrandedPermission[];
 }
 
 function PermissionDeniedFullPage({
 	permissionName,
+	deniedPermissions,
 }: PermissionDeniedFullPageProps): JSX.Element {
 	const { user } = useAppContext();
 
+	// TODO(authz): Remove permissionName support after devtools PR merges
+	const formattedPermissions = deniedPermissions
+		? deniedPermissions.map(formatPermission)
+		: permissionName
+			? [permissionName]
+			: [];
+
 	return (
 		<div className={styles.container}>
 			<div className={styles.content}>
@@ -22,7 +36,13 @@ function PermissionDeniedFullPage({
 				<p className={styles.title}>Uh-oh! You are not authorized</p>
 				<p className={styles.subtitle}>
 					<code className={styles.permission}>user/{user.id}</code> is not authorized
-					to perform <code className={styles.permission}>{permissionName}</code>
+					to perform{' '}
+					{formattedPermissions.map((perm, idx) => (
+						<span key={perm}>
+							<code className={styles.permission}>{perm}</code>
+							{idx < formattedPermissions.length - 1 && ', '}
+						</span>
+					))}
 				</p>
 			</div>
 		</div>

frontend/src/lib/authz/components/README.md

@@ -0,0 +1,185 @@
+# AuthZ Components
+
+Quick reference for permission-gating UI. All components use AND semantics: user needs ALL permissions in `checks` array.
+
+## Decision Tree
+
+```
+Need to gate...
+├── A button? → AuthZButton
+├── Any element with tooltip on deny? → AuthZTooltip
+├── A section inside a page? → withAuthZContent (preferred)
+│   └── Need JSX wrapper? → AuthZGuardContent
+├── An entire page/route? → withAuthZPage (preferred)
+│   └── Need JSX wrapper? → AuthZGuardPage
+├── Need full control over fallback? → withAuthZ / AuthZGuard
+└── None of above fit?
+    ├── Can create wrapper component? → Create it (like AuthZButton)
+    └── Last resort → useAuthZ hook directly
+```
+
+## Building Permissions
+
+Use `buildPermission`, `buildObjectString` or pre-built constants. Never cast with `as BrandedPermission`.
+
+```tsx
+import { buildPermission, buildObjectString } from 'lib/authz/hooks/useAuthZ/utils';
+import { 
+  RoleCreatePermission,
+  buildRoleReadPermission 
+} from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';
+
+// Static permission (pre-built)
+const checks = [RoleCreatePermission];
+
+// Dynamic permission (builder fn)
+const checks = [buildRoleReadPermission(roleId)];
+
+// Custom permission (buildPermission + buildObjectString)
+const checks = [buildPermission('read', buildObjectString('dashboard', dashboardId))];
+```
+
+## Creating Permission Helpers
+
+When adding authz to a new resource, create a permissions file under `lib/authz/hooks/useAuthZ/permissions/`.
+
+```tsx
+// lib/authz/hooks/useAuthZ/permissions/dashboard.permissions.ts
+import { buildPermission } from '../utils';
+import type { BrandedPermission } from '../types';
+
+// Collection-level — wildcard, no specific id needed
+export const DashboardCreatePermission = buildPermission('create', 'dashboard:*');
+export const DashboardListPermission = buildPermission('list', 'dashboard:*');
+
+// Resource-level — require specific id
+export const buildDashboardReadPermission = (id: string): BrandedPermission =>
+  buildPermission('read', `dashboard:${id}`);
+export const buildDashboardUpdatePermission = (id: string): BrandedPermission =>
+  buildPermission('update', `dashboard:${id}`);
+export const buildDashboardDeletePermission = (id: string): BrandedPermission =>
+  buildPermission('delete', `dashboard:${id}`);
+```
+
+Pattern:
+- `<Resource><Action>Permission` → collection-level const (wildcard `*`)
+- `build<Resource><Action>Permission(id)` → resource-level fn (specific id)
+
+## Components
+
+### AuthZButton
+
+Button that disables + shows tooltip when denied.
+
+```tsx
+import { SACreatePermission } from 'lib/authz/hooks/useAuthZ/permissions/service-account.permissions';
+
+<AuthZButton checks={[SACreatePermission]} onClick={handleCreate}>
+  Create
+</AuthZButton>
+```
+
+### AuthZTooltip
+
+Wraps any element. Disables child + shows denial tooltip.
+
+```tsx
+import { buildSADeletePermission } from 'lib/authz/hooks/useAuthZ/permissions/service-account.permissions';
+
+<AuthZTooltip checks={[buildSADeletePermission(accountId)]}>
+  <IconButton icon={<Trash />} onClick={handleDelete} />
+</AuthZTooltip>
+```
+
+### withAuthZPage (preferred for pages)
+
+HOC for route-level gating. Wrap at export. Shows `PermissionDeniedFullPage` + `AppLoading`.
+
+```tsx
+import { RoleListPermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';
+
+function RolesPage(): JSX.Element {
+  return <div>...</div>;
+}
+
+export default withAuthZPage(RolesPage, {
+  checks: [RoleListPermission],
+});
+```
+
+### withAuthZContent (preferred for sections)
+
+HOC for inline sections. Shows `PermissionDeniedCallout` on deny.
+
+```tsx
+import { buildRoleReadPermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';
+
+function RoleEditor(): JSX.Element {
+  return <div>...</div>;
+}
+
+// Dynamic checks from route params
+export default withAuthZContent(RoleEditor, {
+  checks: (_props, ctx) => [buildRoleReadPermission(ctx.params.roleId)],
+});
+```
+
+### withAuthZ
+
+HOC base. No default fallback. Use when you need custom fallback.
+
+```tsx
+import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';
+
+export default withAuthZ(SecretPanel, {
+  checks: [buildPermission('write', 'settings:org')],
+  fallback: <p>No access</p>,
+});
+```
+
+### AuthZGuardPage
+
+JSX variant of `withAuthZPage`. Use when HOC not possible (conditional rendering).
+
+```tsx
+import { RoleListPermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';
+
+<AuthZGuardPage checks={[RoleListPermission]}>
+  <RolesPage />
+</AuthZGuardPage>
+```
+
+### AuthZGuardContent
+
+JSX variant of `withAuthZContent`. Use when HOC not possible.
+
+```tsx
+import { RoleCreatePermission } from 'lib/authz/hooks/useAuthZ/permissions/role.permissions';
+
+<AuthZGuardContent checks={[RoleCreatePermission]}>
+  <RoleEditor />
+</AuthZGuardContent>
+```
+
+### AuthZGuard
+
+JSX base guard. No default fallback. Use when you need custom fallback in JSX.
+
+```tsx
+import { buildPermission } from 'lib/authz/hooks/useAuthZ/utils';
+
+<AuthZGuard
+  checks={[buildPermission('write', 'settings:org')]}
+  fallback={<p>No access</p>}
+  fallbackOnLoading={<Spinner />}
+>
+  <SecretContent />
+</AuthZGuard>
+```
+
+## Fallback Components
+
+Don't use these components directly, always prefer using via `withAuthZ` and their variants.
+
+- PermissionDeniedCallout: inline error callout. Shows `user/{id} is not authorized to perform {permissions}`.
+- PermissionDeniedFullPage: full-page centered error. Same message, bigger presentation.

frontend/src/lib/authz/components/createGuardedRoute/createGuardedRoute.authz.test.tsx

@@ -1,440 +0,0 @@
-import { ReactElement } from 'react';
-import type { RouteComponentProps } from 'react-router-dom';
-import type {
-	AuthtypesGettableTransactionDTO,
-	AuthtypesTransactionDTO,
-} from 'api/generated/services/sigNoz.schemas';
-import { server } from 'mocks-server/server';
-import { rest } from 'msw';
-import { render, screen, waitFor } from 'tests/test-utils';
-import {
-	AUTHZ_CHECK_URL,
-	authzMockResponse,
-} from 'lib/authz/utils/authz-test-utils';
-
-import { createGuardedRoute } from './createGuardedRoute';
-
-describe('createGuardedRoute', () => {
-	const TestComponent = ({ testProp }: { testProp: string }): ReactElement => (
-		<div>Test Component: {testProp}</div>
-	);
-
-	it('should render component when permission is granted', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(TestComponent, 'read', 'role:*');
-
-		const mockMatch = {
-			params: {},
-			isExact: true,
-			path: '/dashboard',
-			url: '/dashboard',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value')).toBeInTheDocument();
-		});
-	});
-
-	it('should substitute route parameters in object string', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			TestComponent,
-			'read',
-			'role:{id}',
-		);
-
-		const mockMatch = {
-			params: { id: '123' },
-			isExact: true,
-			path: '/dashboard/:id',
-			url: '/dashboard/123',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value')).toBeInTheDocument();
-		});
-	});
-
-	it('should handle multiple route parameters', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = (await req.json()) as AuthtypesTransactionDTO[];
-				const txn = payload[0];
-				const responseData: AuthtypesGettableTransactionDTO[] = [
-					{
-						relation: txn.relation,
-						object: {
-							resource: {
-								kind: txn.object.resource.kind,
-								type: txn.object.resource.type,
-							},
-							selector: '123:456',
-						},
-						authorized: true,
-					},
-				];
-				return res(
-					ctx.status(200),
-					ctx.json({ data: responseData, status: 'success' }),
-				);
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			TestComponent,
-			'update',
-			'role:{id}:{version}',
-		);
-
-		const mockMatch = {
-			params: { id: '123', version: '456' },
-			isExact: true,
-			path: '/dashboard/:id/:version',
-			url: '/dashboard/123/456',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value')).toBeInTheDocument();
-		});
-	});
-
-	it('should keep placeholder when route parameter is missing', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			TestComponent,
-			'read',
-			'role:{id}',
-		);
-
-		const mockMatch = {
-			params: {},
-			isExact: true,
-			path: '/dashboard',
-			url: '/dashboard',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value')).toBeInTheDocument();
-		});
-	});
-
-	it('should render loading fallback when loading', () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (_req, res, ctx) => {
-				return res(
-					ctx.delay('infinite'),
-					ctx.status(200),
-					ctx.json({ data: [], status: 'success' }),
-				);
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(TestComponent, 'read', 'role:*');
-
-		const mockMatch = {
-			params: {},
-			isExact: true,
-			path: '/dashboard',
-			url: '/dashboard',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		expect(screen.getByText('SigNoz')).toBeInTheDocument();
-		expect(
-			screen.queryByText('Test Component: test-value'),
-		).not.toBeInTheDocument();
-	});
-
-	it('should render the component when API error occurs (fail open)', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) => {
-				return res(ctx.status(500), ctx.json({ error: 'Internal Server Error' }));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(TestComponent, 'read', 'role:*');
-
-		const mockMatch = {
-			params: {},
-			isExact: true,
-			path: '/dashboard',
-			url: '/dashboard',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value')).toBeInTheDocument();
-		});
-	});
-
-	it('should render no permissions fallback when permission is denied', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [false])));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			TestComponent,
-			'update',
-			'role:{id}',
-		);
-
-		const mockMatch = {
-			params: { id: '123' },
-			isExact: true,
-			path: '/dashboard/:id',
-			url: '/dashboard/123',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			const heading = document.querySelector('h3');
-			expect(heading).toBeInTheDocument();
-			expect(heading?.textContent).toMatch(/not authorized/i);
-		});
-
-		expect(screen.getByText(/update:role:123/)).toBeInTheDocument();
-		expect(
-			screen.queryByText('Test Component: test-value'),
-		).not.toBeInTheDocument();
-	});
-
-	it('should pass all props to wrapped component', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const ComponentWithMultipleProps = ({
-			prop1,
-			prop2,
-			prop3,
-		}: {
-			prop1: string;
-			prop2: number;
-			prop3: boolean;
-		}): ReactElement => (
-			<div>
-				{prop1} - {prop2} - {prop3.toString()}
-			</div>
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			ComponentWithMultipleProps,
-			'read',
-			'role:*',
-		);
-
-		const mockMatch = {
-			params: {},
-			isExact: true,
-			path: '/dashboard',
-			url: '/dashboard',
-		};
-
-		const props = {
-			prop1: 'value1',
-			prop2: 42,
-			prop3: true,
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('value1 - 42 - true')).toBeInTheDocument();
-		});
-	});
-
-	it('should memoize resolved object based on route params', async () => {
-		let requestCount = 0;
-		const requestedObjects: string[] = [];
-
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				requestCount++;
-				const payload = (await req.json()) as AuthtypesTransactionDTO[];
-				const obj = payload[0]?.object;
-				const kind = obj?.resource?.kind;
-				const selector = obj?.selector ?? '*';
-				const objectStr = `${kind}:${selector}`;
-				requestedObjects.push(objectStr ?? '');
-
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			TestComponent,
-			'read',
-			'role:{id}',
-		);
-
-		const mockMatch1 = {
-			params: { id: '123' },
-			isExact: true,
-			path: '/dashboard/:id',
-			url: '/dashboard/123',
-		};
-
-		const props1 = {
-			testProp: 'test-value-1',
-			match: mockMatch1,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		const { unmount } = render(<GuardedComponent {...props1} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value-1')).toBeInTheDocument();
-		});
-
-		expect(requestCount).toBe(1);
-		expect(requestedObjects).toContain('role:123');
-
-		unmount();
-
-		const mockMatch2 = {
-			params: { id: '456' },
-			isExact: true,
-			path: '/dashboard/:id',
-			url: '/dashboard/456',
-		};
-
-		const props2 = {
-			testProp: 'test-value-2',
-			match: mockMatch2,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props2} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value-2')).toBeInTheDocument();
-		});
-
-		expect(requestCount).toBe(2);
-		expect(requestedObjects).toContain('role:456');
-	});
-
-	it('should handle different relation types', async () => {
-		server.use(
-			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
-				const payload = await req.json();
-				return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true])));
-			}),
-		);
-
-		const GuardedComponent = createGuardedRoute(
-			TestComponent,
-			'delete',
-			'role:{id}',
-		);
-
-		const mockMatch = {
-			params: { id: '789' },
-			isExact: true,
-			path: '/dashboard/:id',
-			url: '/dashboard/789',
-		};
-
-		const props = {
-			testProp: 'test-value',
-			match: mockMatch,
-			location: {} as unknown as RouteComponentProps['location'],
-			history: {} as unknown as RouteComponentProps['history'],
-		};
-
-		render(<GuardedComponent {...props} />);
-
-		await waitFor(() => {
-			expect(screen.getByText('Test Component: test-value')).toBeInTheDocument();
-		});
-	});
-});

frontend/src/lib/authz/components/createGuardedRoute/createGuardedRoute.styles.scss

@@ -1,41 +0,0 @@
-.guard-authz-error-no-authz {
-	display: flex;
-	align-items: center;
-	justify-content: center;
-
-	width: 100%;
-	height: 100%;
-
-	padding: 24px;
-
-	.guard-authz-error-no-authz-content {
-		display: flex;
-		flex-direction: column;
-		justify-content: flex-start;
-		gap: 8px;
-		max-width: 500px;
-	}
-
-	img {
-		width: 32px;
-		height: 32px;
-	}
-
-	h3 {
-		font-size: 18px;
-		color: var(--l1-foreground);
-		line-height: 18px;
-	}
-
-	p {
-		font-size: 14px;
-		color: var(--l3-foreground);
-		line-height: 18px;
-
-		span {
-			background-color: var(--l3-background);
-			white-space: nowrap;
-			padding: 0 2px;
-		}
-	}
-}

frontend/src/lib/authz/components/createGuardedRoute/createGuardedRoute.tsx

@@ -1,67 +0,0 @@
-import { ComponentType, ReactElement, useMemo } from 'react';
-import { RouteComponentProps } from 'react-router-dom';
-import {
-	AuthZObject,
-	AuthZRelation,
-	BrandedPermission,
-} from 'lib/authz/hooks/useAuthZ/types';
-import { formatPermission } from 'lib/authz/hooks/useAuthZ/utils';
-import { useAppContext } from 'providers/App/App';
-
-import noDataUrl from 'assets/Icons/no-data.svg';
-
-import AppLoading from '../../../../components/AppLoading/AppLoading';
-import { GuardAuthZ } from '../GuardAuthZ/GuardAuthZ';
-
-import './createGuardedRoute.styles.scss';
-
-function OnNoPermissionsFallback(response: {
-	requiredPermissionName: BrandedPermission;
-}): ReactElement {
-	const { user } = useAppContext();
-
-	return (
-		<div className="guard-authz-error-no-authz">
-			<div className="guard-authz-error-no-authz-content">
-				<img src={noDataUrl} alt="No permission" />
-				<h3>Uh-oh! You are not authorized</h3>
-				<p>
-					<code>user/{user.id}</code> is not authorized to perform{' '}
-					<code>{formatPermission(response.requiredPermissionName)}</code>
-				</p>
-			</div>
-		</div>
-	);
-}
-
-// eslint-disable-next-line @typescript-eslint/ban-types
-export function createGuardedRoute<P extends object, R extends AuthZRelation>(
-	Component: ComponentType<P>,
-	relation: R,
-	object: AuthZObject<R>,
-): ComponentType<P & RouteComponentProps<Record<string, string>>> {
-	return function GuardedRouteComponent(
-		props: P & RouteComponentProps<Record<string, string>>,
-	): ReactElement {
-		const resolvedObject = useMemo(() => {
-			const paramPattern = /\{([^}]+)\}/g;
-			return object.replace(paramPattern, (match, paramName) => {
-				const paramValue = props.match?.params?.[paramName];
-				return paramValue !== undefined ? paramValue : match;
-			}) as AuthZObject<R>;
-		}, [props.match?.params]);
-
-		return (
-			<GuardAuthZ
-				relation={relation}
-				object={resolvedObject}
-				fallbackOnLoading={<AppLoading />}
-				fallbackOnNoPermissions={(response): ReactElement => (
-					<OnNoPermissionsFallback {...response} />
-				)}
-			>
-				<Component {...props} />
-			</GuardAuthZ>
-		);
-	};
-}

frontend/src/lib/authz/components/withAuthZ/withAuthZ.authz.test.tsx

@@ -0,0 +1,578 @@
+import React from 'react';
+import { render, screen, waitFor, act } from 'tests/test-utils';
+import { useQueryClient } from 'react-query';
+import { server } from 'mocks-server/server';
+import { rest } from 'msw';
+import {
+	AUTHZ_CHECK_URL,
+	authzMockResponse,
+	setupAuthzAllow,
+	setupAuthzDeny,
+	setupAuthzGrantByPrefix,
+} from 'lib/authz/utils/authz-test-utils';
+import type { AuthZObject } from 'lib/authz/hooks/useAuthZ/types';
+import {
+	buildObjectString,
+	buildPermission,
+} from 'lib/authz/hooks/useAuthZ/utils';
+
+import { withAuthZ, RouterContext } from './withAuthZ';
+import { withAuthZContent } from './withAuthZContent';
+import { withAuthZPage } from './withAuthZPage';
+
+const mockUseParams = jest.fn();
+const mockUseLocation = jest.fn();
+
+jest.mock('react-router-dom', () => ({
+	...jest.requireActual('react-router-dom'),
+	useParams: (): Record<string, string> => mockUseParams(),
+	useLocation: (): { pathname: string; search: string } => mockUseLocation(),
+}));
+
+const readPerm = buildPermission('read', 'role:*' as AuthZObject<'read'>);
+
+function Base(): JSX.Element {
+	return <div>Base component</div>;
+}
+
+beforeEach(() => {
+	mockUseParams.mockReturnValue({});
+	mockUseLocation.mockReturnValue({ pathname: '/', search: '' });
+});
+
+describe('withAuthZ', () => {
+	it('renders the wrapped component when allowed', async () => {
+		server.use(setupAuthzAllow(readPerm));
+		const Guarded = withAuthZ(Base, { checks: [readPerm] });
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('Base component')).toBeInTheDocument();
+		});
+	});
+
+	it('renders nothing when denied without a fallback', async () => {
+		server.use(setupAuthzDeny(readPerm));
+		const Guarded = withAuthZ(Base, { checks: [readPerm] });
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.queryByText('Base component')).not.toBeInTheDocument();
+		});
+	});
+
+	it('renders the provided fallback when denied', async () => {
+		server.use(setupAuthzDeny(readPerm));
+		const Guarded = withAuthZ(Base, {
+			checks: [readPerm],
+			fallback: <div>No access</div>,
+		});
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('No access')).toBeInTheDocument();
+		});
+	});
+
+	it('resolves checks from props via the selector form', async () => {
+		type Props = { roleId: string };
+		const RoleView = ({ roleId }: Props): JSX.Element => <div>role {roleId}</div>;
+		const deniedPerm = buildPermission(
+			'read',
+			buildObjectString<'read'>('role', 'r-1'),
+		);
+		server.use(setupAuthzDeny(deniedPerm));
+
+		const Guarded = withAuthZ<Props>(RoleView, {
+			checks: ({ roleId }) => [
+				buildPermission('read', buildObjectString<'read'>('role', roleId)),
+			],
+			fallback: <div>denied selector</div>,
+		});
+
+		render(<Guarded roleId="r-1" />);
+
+		await waitFor(() => {
+			expect(screen.getByText('denied selector')).toBeInTheDocument();
+		});
+		expect(screen.queryByText('role r-1')).not.toBeInTheDocument();
+	});
+
+	it('sets a descriptive displayName', () => {
+		const Guarded = withAuthZ(Base, { checks: [readPerm] });
+		expect(Guarded.displayName).toBe('withAuthZ(Base)');
+	});
+});
+
+describe('withAuthZPage', () => {
+	it('renders the full-page denied screen when denied', async () => {
+		server.use(setupAuthzDeny(readPerm));
+		const Guarded = withAuthZPage(Base, { checks: [readPerm] });
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(
+				screen.getByText('Uh-oh! You are not authorized'),
+			).toBeInTheDocument();
+		});
+	});
+});
+
+describe('withAuthZContent', () => {
+	it('renders the denied callout when denied', async () => {
+		server.use(setupAuthzDeny(readPerm));
+		const Guarded = withAuthZContent(Base, { checks: [readPerm] });
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('read:role:*')).toBeInTheDocument();
+		});
+		expect(screen.queryByText('Base component')).not.toBeInTheDocument();
+	});
+});
+
+describe('withAuthZ router context', () => {
+	it('extracts checks from route params via router.params', async () => {
+		mockUseParams.mockReturnValue({ roleId: 'r-123' });
+
+		const rolePerm = buildPermission(
+			'read',
+			buildObjectString<'read'>('role', 'r-123'),
+		);
+		server.use(setupAuthzAllow(rolePerm));
+
+		const RoleView = (): JSX.Element => <div>role view</div>;
+		const Guarded = withAuthZ(RoleView, {
+			checks: (_props, router: RouterContext) => [
+				buildPermission(
+					'read',
+					buildObjectString<'read'>('role', router.params.roleId ?? ''),
+				),
+			],
+		});
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('role view')).toBeInTheDocument();
+		});
+	});
+
+	it('extracts checks from query params via router.searchParams', async () => {
+		mockUseLocation.mockReturnValue({
+			pathname: '/roles',
+			search: '?roleId=r-456',
+		});
+
+		const rolePerm = buildPermission(
+			'read',
+			buildObjectString<'read'>('role', 'r-456'),
+		);
+		server.use(setupAuthzAllow(rolePerm));
+
+		const RoleListView = (): JSX.Element => <div>role list view</div>;
+		const Guarded = withAuthZ(RoleListView, {
+			checks: (_props, router: RouterContext) => [
+				buildPermission(
+					'read',
+					buildObjectString<'read'>('role', router.searchParams.get('roleId') ?? ''),
+				),
+			],
+		});
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('role list view')).toBeInTheDocument();
+		});
+	});
+
+	it('extracts checks from pathname via router.matchPath', async () => {
+		mockUseLocation.mockReturnValue({
+			pathname: '/settings/roles/r-789/edit',
+			search: '',
+		});
+
+		const rolePerm = buildPermission(
+			'update',
+			buildObjectString<'update'>('role', 'r-789'),
+		);
+		server.use(setupAuthzAllow(rolePerm));
+
+		const EditRoleView = (): JSX.Element => <div>edit role</div>;
+		const Guarded = withAuthZ(EditRoleView, {
+			checks: (_props, router: RouterContext) => {
+				const match = router.matchPath<{ roleId: string }>(
+					'/settings/roles/:roleId/edit',
+				);
+				return match
+					? [
+							buildPermission(
+								'update',
+								buildObjectString<'update'>('role', match.roleId),
+							),
+						]
+					: [];
+			},
+		});
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('edit role')).toBeInTheDocument();
+		});
+	});
+
+	it('denies when router-derived permission is not allowed', async () => {
+		mockUseParams.mockReturnValue({ roleId: 'r-denied' });
+
+		const deniedPerm = buildPermission(
+			'read',
+			buildObjectString<'read'>('role', 'r-denied'),
+		);
+		server.use(setupAuthzDeny(deniedPerm));
+
+		const RoleView = (): JSX.Element => <div>role view</div>;
+		const Guarded = withAuthZ(RoleView, {
+			checks: (_props, router: RouterContext) => [
+				buildPermission(
+					'read',
+					buildObjectString<'read'>('role', router.params.roleId ?? ''),
+				),
+			],
+			fallback: <div>access denied</div>,
+		});
+
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByText('access denied')).toBeInTheDocument();
+		});
+		expect(screen.queryByText('role view')).not.toBeInTheDocument();
+	});
+});
+
+describe('withAuthZ router context stability', () => {
+	let renderCount = 0;
+
+	function RenderCounter(): JSX.Element {
+		renderCount += 1;
+		return <div data-testid="render-count">{renderCount}</div>;
+	}
+
+	beforeEach(() => {
+		renderCount = 0;
+		server.use(setupAuthzGrantByPrefix('read||__||role'));
+	});
+
+	it('does not re-render when useParams returns new object with same values', async () => {
+		mockUseParams.mockReturnValue({ roleId: 'r-1' });
+		mockUseLocation.mockReturnValue({ pathname: '/', search: '' });
+
+		const Guarded = withAuthZ(RenderCounter, {
+			checks: (_props, router: RouterContext) => [
+				buildPermission(
+					'read',
+					buildObjectString<'read'>('role', router.params.roleId ?? '*'),
+				),
+			],
+		});
+
+		const { rerender } = render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('render-count')).toBeInTheDocument();
+		});
+
+		const initialCount = renderCount;
+
+		// Return NEW object with SAME values — should not cause re-render
+		mockUseParams.mockReturnValue({ roleId: 'r-1' });
+		rerender(<Guarded />);
+
+		// Allow any pending effects to flush
+		await waitFor(() => {
+			expect(renderCount).toBe(initialCount);
+		});
+	});
+
+	it('does not re-render when useLocation returns new object with same pathname', async () => {
+		mockUseParams.mockReturnValue({});
+		mockUseLocation.mockReturnValue({ pathname: '/roles', search: '' });
+
+		const Guarded = withAuthZ(RenderCounter, {
+			checks: (_props, router: RouterContext) => {
+				const match = router.matchPath<{ id: string }>('/roles/:id');
+				return match
+					? [buildPermission('read', buildObjectString<'read'>('role', match.id))]
+					: [readPerm];
+			},
+		});
+
+		const { rerender } = render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('render-count')).toBeInTheDocument();
+		});
+
+		const initialCount = renderCount;
+
+		// Return NEW object with SAME pathname — should not cause re-render
+		mockUseLocation.mockReturnValue({ pathname: '/roles', search: '' });
+		rerender(<Guarded />);
+
+		await waitFor(() => {
+			expect(renderCount).toBe(initialCount);
+		});
+	});
+
+	it('does not re-render when useLocation returns new object with same search params', async () => {
+		mockUseParams.mockReturnValue({});
+		mockUseLocation.mockReturnValue({ pathname: '/', search: '?tab=keys' });
+
+		const Guarded = withAuthZ(RenderCounter, {
+			checks: (_props, router: RouterContext) => {
+				// Access searchParams to ensure it's part of the dependency chain
+				void router.searchParams.get('tab');
+				return [readPerm];
+			},
+		});
+
+		const { rerender } = render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('render-count')).toBeInTheDocument();
+		});
+
+		const initialCount = renderCount;
+
+		// Return NEW object with SAME search — should not cause re-render
+		mockUseLocation.mockReturnValue({ pathname: '/', search: '?tab=keys' });
+		rerender(<Guarded />);
+
+		await waitFor(() => {
+			expect(renderCount).toBe(initialCount);
+		});
+	});
+
+	it('re-renders when params values actually change', async () => {
+		mockUseParams.mockReturnValue({ roleId: 'r-1' });
+		mockUseLocation.mockReturnValue({ pathname: '/', search: '' });
+
+		const Guarded = withAuthZ(RenderCounter, {
+			checks: (_props, router: RouterContext) => [
+				buildPermission(
+					'read',
+					buildObjectString<'read'>('role', router.params.roleId ?? '*'),
+				),
+			],
+		});
+
+		const { unmount } = render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('render-count')).toBeInTheDocument();
+		});
+
+		const initialCount = renderCount;
+		unmount();
+
+		// Return DIFFERENT values — re-mount with new mock values
+		mockUseParams.mockReturnValue({ roleId: 'r-2' });
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(renderCount).toBeGreaterThan(initialCount);
+		});
+	});
+
+	it('re-renders when pathname actually changes', async () => {
+		mockUseParams.mockReturnValue({});
+		mockUseLocation.mockReturnValue({ pathname: '/roles', search: '' });
+
+		const Guarded = withAuthZ(RenderCounter, {
+			checks: [readPerm],
+		});
+
+		const { unmount } = render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('render-count')).toBeInTheDocument();
+		});
+
+		const initialCount = renderCount;
+		unmount();
+
+		// DIFFERENT pathname — re-mount with new mock values
+		mockUseLocation.mockReturnValue({ pathname: '/users', search: '' });
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(renderCount).toBeGreaterThan(initialCount);
+		});
+	});
+
+	it('re-renders when search params actually change', async () => {
+		mockUseParams.mockReturnValue({});
+		mockUseLocation.mockReturnValue({ pathname: '/', search: '?tab=keys' });
+
+		const Guarded = withAuthZ(RenderCounter, {
+			checks: [readPerm],
+		});
+
+		const { unmount } = render(<Guarded />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('render-count')).toBeInTheDocument();
+		});
+
+		const initialCount = renderCount;
+		unmount();
+
+		// DIFFERENT search — re-mount with new mock values
+		mockUseLocation.mockReturnValue({ pathname: '/', search: '?tab=details' });
+		render(<Guarded />);
+
+		await waitFor(() => {
+			expect(renderCount).toBeGreaterThan(initialCount);
+		});
+	});
+});
+
+describe('withAuthZContent cache invalidation', () => {
+	const testPerm = buildPermission(
+		'read',
+		'role:test-invalidation' as AuthZObject<'read'>,
+	);
+	// Callout displays permission as "relation:object" format
+	const displayedPerm = 'read:role:test-invalidation';
+
+	function ContentComponent(): JSX.Element {
+		return <div data-testid="protected-content">Protected Content</div>;
+	}
+
+	function InvalidationTrigger({
+		permission,
+		onReady,
+	}: {
+		permission: string;
+		onReady: (invalidate: () => Promise<void>) => void;
+	}): null {
+		const queryClient = useQueryClient();
+
+		React.useEffect(() => {
+			onReady(async () => {
+				// Reset query to initial state and trigger refetch (matches devtools behavior)
+				await queryClient.resetQueries(['authz', permission]);
+			});
+		}, [queryClient, permission, onReady]);
+
+		return null;
+	}
+
+	it('re-renders from allowed to denied when cache is invalidated', async () => {
+		let shouldGrant = true;
+		let invalidateFn: (() => Promise<void>) | null = null;
+
+		server.use(
+			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
+				const payload = await req.json();
+				return res(
+					ctx.status(200),
+					ctx.json(authzMockResponse(payload, [shouldGrant])),
+				);
+			}),
+		);
+
+		const Guarded = withAuthZContent(ContentComponent, { checks: [testPerm] });
+
+		render(
+			<>
+				<Guarded />
+				<InvalidationTrigger
+					permission={testPerm}
+					onReady={(fn): void => {
+						invalidateFn = fn;
+					}}
+				/>
+			</>,
+		);
+
+		// Initially allowed - should show content
+		await waitFor(() => {
+			expect(screen.getByTestId('protected-content')).toBeInTheDocument();
+		});
+
+		// Change server response to deny
+		shouldGrant = false;
+
+		// Invalidate cache
+		await act(async () => {
+			await invalidateFn?.();
+		});
+
+		// Should now show denied callout
+		await waitFor(() => {
+			expect(screen.queryByTestId('protected-content')).not.toBeInTheDocument();
+		});
+
+		// Callout should show the denied permission
+		expect(screen.getByRole('alert')).toBeInTheDocument();
+		expect(screen.getByText(displayedPerm)).toBeInTheDocument();
+	});
+
+	it('re-renders from denied to allowed when cache is invalidated', async () => {
+		let shouldGrant = false;
+		let invalidateFn: (() => Promise<void>) | null = null;
+
+		server.use(
+			rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
+				const payload = await req.json();
+				return res(
+					ctx.status(200),
+					ctx.json(authzMockResponse(payload, [shouldGrant])),
+				);
+			}),
+		);
+
+		const Guarded = withAuthZContent(ContentComponent, { checks: [testPerm] });
+
+		render(
+			<>
+				<Guarded />
+				<InvalidationTrigger
+					permission={testPerm}
+					onReady={(fn): void => {
+						invalidateFn = fn;
+					}}
+				/>
+			</>,
+		);
+
+		// Initially denied - should show callout
+		await waitFor(() => {
+			expect(screen.getByRole('alert')).toBeInTheDocument();
+		});
+		expect(screen.queryByTestId('protected-content')).not.toBeInTheDocument();
+
+		// Change server response to allow
+		shouldGrant = true;
+
+		// Invalidate cache
+		await act(async () => {
+			await invalidateFn?.();
+		});
+
+		// Should now show protected content
+		await waitFor(() => {
+			expect(screen.getByTestId('protected-content')).toBeInTheDocument();
+		});
+
+		expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+	});
+});

frontend/src/lib/authz/components/withAuthZ/withAuthZ.tsx

@@ -0,0 +1,13 @@
+import { ComponentType } from 'react';
+import { AuthZGuard } from 'lib/authz/components/AuthZGuard/AuthZGuard';
+
+import { createAuthZHOC, WithAuthZOptions } from './withAuthZ.utils';
+
+export type { RouterContext, WithAuthZOptions } from './withAuthZ.utils';
+
+export function withAuthZ<P extends object>(
+	Component: ComponentType<P>,
+	opts: WithAuthZOptions<P>,
+): ComponentType<P> {
+	return createAuthZHOC(AuthZGuard, 'withAuthZ', Component, opts);
+}

frontend/src/lib/authz/components/withAuthZ/withAuthZ.utils.tsx

@@ -0,0 +1,108 @@
+import { ComponentType, ReactElement, createElement, useMemo } from 'react';
+import {
+	matchPath as reactRouterMatchPath,
+	useLocation,
+	useParams,
+} from 'react-router-dom';
+import type { AuthZGuardProps } from 'lib/authz/components/AuthZGuard/AuthZGuard';
+import type { BrandedPermission } from 'lib/authz/hooks/useAuthZ/types';
+
+export type RouterContext = {
+	/**
+	 * Route params from useParams (e.g. `/roles/:roleId` → `{ roleId: "r-1" }`)
+	 */
+	params: Record<string, string | undefined>;
+	pathname: string;
+	/**
+	 * Query params as URLSearchParams (use `.get('key')` to read)
+	 */
+	searchParams: URLSearchParams;
+	/**
+	 * Extract params from pathname using a route pattern.
+	 * Returns null if pattern doesn't match.
+	 * @example router.matchPath<{ id: string }>('/edit/:id')?.id
+	 */
+	matchPath: <Params extends Record<string, string>>(
+		pattern: string,
+	) => Params | null;
+};
+
+export type WithAuthZOptions<P> = {
+	/**
+	 * Static checks, or a selector deriving them from props and router context.
+	 * Use router context to extract dynamic values from route params, pathname, or query params.
+	 * @example
+	 * // From route params
+	 * checks: (props, router) => [buildPermission('read', `role:${router.params.roleId}`)]
+	 * // From query params
+	 * checks: (props, router) => [buildPermission('read', `dashboard:${router.searchParams.get('id')}`)]
+	 * // From pathname matching
+	 * checks: (props, router) => {
+	 *   const match = router.matchPath<{ id: string }>('/edit/:id');
+	 *   return match ? [buildPermission('update', `role:${match.id}`)] : [];
+	 * }
+	 */
+	checks:
+		| BrandedPermission[]
+		| ((props: P, router: RouterContext) => BrandedPermission[]);
+	fallback?: AuthZGuardProps['fallback'];
+	fallbackOnLoading?: AuthZGuardProps['fallbackOnLoading'];
+	failOpenOnError?: AuthZGuardProps['onFailRenderContent'];
+};
+
+function useStableParams(): Record<string, string | undefined> {
+	const params = useParams();
+	const paramsJson = JSON.stringify(params);
+	return useMemo(() => JSON.parse(paramsJson), [paramsJson]);
+}
+
+function useRouterContext(): RouterContext {
+	const params = useStableParams();
+	const { pathname, search } = useLocation();
+	const searchParams = useMemo(() => new URLSearchParams(search), [search]);
+
+	return useMemo(
+		(): RouterContext => ({
+			params,
+			pathname,
+			searchParams,
+			matchPath: <Params extends Record<string, string>>(
+				pattern: string,
+			): Params | null => {
+				const match = reactRouterMatchPath<Params>(pathname, {
+					path: pattern,
+					exact: false,
+				});
+				return match?.params ?? null;
+			},
+		}),
+		[params, pathname, searchParams],
+	);
+}
+
+export function createAuthZHOC<P extends object>(
+	Guard: ComponentType<AuthZGuardProps>,
+	hocName: string,
+	Component: ComponentType<P>,
+	opts: WithAuthZOptions<P>,
+): ComponentType<P> {
+	const { checks, ...guardProps } = opts;
+
+	function Wrapped(props: P): ReactElement | null {
+		const router = useRouterContext();
+		const resolvedChecks =
+			typeof checks === 'function' ? checks(props, router) : checks;
+
+		return (
+			<Guard checks={resolvedChecks} {...guardProps}>
+				{createElement(Component, props)}
+			</Guard>
+		);
+	}
+
+	Wrapped.displayName = `${hocName}(${
+		Component.displayName || Component.name || 'Component'
+	})`;
+
+	return Wrapped;
+}

frontend/src/lib/authz/components/withAuthZ/withAuthZContent.tsx

@@ -0,0 +1,11 @@
+import { ComponentType } from 'react';
+import { AuthZGuardContent } from 'lib/authz/components/AuthZGuard/AuthZGuardContent';
+
+import { createAuthZHOC, WithAuthZOptions } from './withAuthZ.utils';
+
+export function withAuthZContent<P extends object>(
+	Component: ComponentType<P>,
+	opts: WithAuthZOptions<P>,
+): ComponentType<P> {
+	return createAuthZHOC(AuthZGuardContent, 'withAuthZContent', Component, opts);
+}

frontend/src/lib/authz/components/withAuthZ/withAuthZPage.tsx

@@ -0,0 +1,11 @@
+import { ComponentType } from 'react';
+import { AuthZGuardPage } from 'lib/authz/components/AuthZGuard/AuthZGuardPage';
+
+import { createAuthZHOC, WithAuthZOptions } from './withAuthZ.utils';
+
+export function withAuthZPage<P extends object>(
+	Component: ComponentType<P>,
+	opts: WithAuthZOptions<P>,
+): ComponentType<P> {
+	return createAuthZHOC(AuthZGuardPage, 'withAuthZPage', Component, opts);
+}

frontend/src/lib/authz/utils/README.md

@@ -0,0 +1,125 @@
+# AuthZ Test Utilities
+
+Helpers for testing permission-gated components.
+
+## File Naming
+
+AuthZ tests live in `*.authz.test.tsx` files alongside other test files:
+
+```
+ComponentName/
+├── ComponentName.tsx
+├── __tests__/
+│   ├── ComponentName.test.tsx        # functional tests
+│   └── ComponentName.authz.test.tsx  # permission tests
+```
+
+## Test Structure
+
+```tsx
+import { server } from 'mocks-server/server';
+import { setupAuthzAdmin, setupAuthzDenyAll } from 'lib/authz/utils/authz-test-utils';
+import { render, screen, waitFor } from 'tests/test-utils';
+
+describe('ComponentName - AuthZ', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+    server.resetHandlers();  // reset MSW handlers after each test
+  });
+
+  describe('permission denied', () => {
+    it('shows permission denied when read denied', async () => {
+      server.use(setupAuthzDenyAll());
+
+      render(<ComponentName />);
+
+      await expect(
+        screen.findByText(/not authorized/i),
+      ).resolves.toBeInTheDocument();
+    });
+  });
+
+  describe('permission granted', () => {
+    it('renders content when permitted', async () => {
+      server.use(setupAuthzAdmin());
+
+      render(<ComponentName />);
+
+      await waitFor(() => {
+        expect(screen.getByTestId('protected-content')).toBeInTheDocument();
+      });
+    });
+  });
+});
+```
+
+Key points:
+- Use `server.use()` at start of each test (not `beforeEach`) for explicit setup
+- Call `server.resetHandlers()` in `afterEach` to avoid test pollution
+- Use `waitFor` or `findBy*` queries since authz checks are async
+- Group tests by permission scenario: denied, granted, partial, loading
+
+## MSW Handlers
+
+Mock `/api/v1/authz/check` endpoint responses.
+
+```tsx
+import { server } from 'mocks-server/server';
+import {
+  setupAuthzAdmin,
+  setupAuthzDenyAll,
+  setupAuthzDeny,
+  setupAuthzAllow,
+  setupAuthzGrantByPrefix,
+} from 'lib/authz/utils/authz-test-utils';
+
+// Grant all permissions
+server.use(setupAuthzAdmin());
+
+// Deny all permissions
+server.use(setupAuthzDenyAll());
+
+// Grant all except specific permissions
+server.use(setupAuthzDeny(RoleCreatePermission, RoleDeletePermission));
+
+// Deny all except specific permissions
+server.use(setupAuthzAllow(RoleListPermission));
+
+// Grant by relation prefix (e.g., grant read/delete, deny update)
+server.use(setupAuthzGrantByPrefix('read', 'delete'));
+```
+
+## Custom Mock Response
+
+For fine-grained control over responses.
+
+```tsx
+import { rest } from 'msw';
+import { AUTHZ_CHECK_URL, authzMockResponse } from 'lib/authz/utils/authz-test-utils';
+
+server.use(
+  rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
+    const payload = await req.json();
+    // [true, false] = first permission granted, second denied
+    return res(ctx.status(200), ctx.json(authzMockResponse(payload, [true, false])));
+  }),
+);
+```
+
+## Testing Loading State
+
+Use `ctx.delay('infinite')` to hold response indefinitely:
+
+```tsx
+it('shows skeleton while checking permissions', () => {
+  server.use(
+    rest.post(AUTHZ_CHECK_URL, (_req, res, ctx) =>
+      res(ctx.delay('infinite')),
+    ),
+  );
+
+  render(<ComponentName />);
+
+  expect(document.querySelector('.ant-skeleton')).toBeInTheDocument();
+});
+```

frontend/src/lib/authz/utils/authz-test-utils.ts

@@ -104,6 +104,25 @@ export function setupAuthzAllow(
 	});
 }
 
+/** Grants permissions that start with any of the given prefixes. */
+export function setupAuthzGrantByPrefix(...prefixes: string[]): RestHandler {
+	return rest.post(AUTHZ_CHECK_URL, async (req, res, ctx) => {
+		const payload = (await req.json()) as AuthtypesTransactionDTO[];
+		return res(
+			ctx.status(200),
+			ctx.json(
+				authzMockResponse(
+					payload,
+					payload.map((txn) => {
+						const perm = gettableTransactionToPermission(txn);
+						return prefixes.some((prefix) => perm.startsWith(prefix));
+					}),
+				),
+			),
+		);
+	});
+}
+
 export function buildLicense(
 	overrides?: Partial<LicenseResModel>,
 ): LicenseResModel {

frontend/src/pages/DashboardPageV2/DashboardContainer/DashboardPageToolbar/index.tsx

@@ -63,13 +63,8 @@ function DashboardPageToolbar(props: DashboardPageToolbarProps): JSX.Element {
 	const { user } = useAppContext();
 	const { showErrorModal } = useErrorModal();
 	const { patchAsync } = useOptimisticPatch();
-	const {
-		isPickerOpen,
-		openPicker,
-		closePicker,
-		createPanel,
-		targetLayoutIndex,
-	} = useCreatePanel();
+	const { isPickerOpen, openPicker, closePicker, createPanel } =
+		useCreatePanel();
 
 	const isAuthor =
 		!!user?.email && !!dashboard.createdBy && dashboard.createdBy === user.email;
@@ -188,7 +183,6 @@ function DashboardPageToolbar(props: DashboardPageToolbarProps): JSX.Element {
 				open={isPickerOpen}
 				onClose={closePicker}
 				onSelect={createPanel}
-				defaultLayoutIndex={targetLayoutIndex}
 			/>
 		</section>
 	);

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelTypeSelectionModal/PanelTypeSelectionModal.module.scss

@@ -1,69 +1,22 @@
-.panelTypeSection {
-	display: flex;
-	flex-direction: column;
-	gap: 12px;
-	align-items: center;
-}
-
 .grid {
-	align-self: stretch;
 	display: grid;
 	grid-template-columns: repeat(2, 1fr);
 	gap: 8px;
 }
 
-.panelTypeCard {
+.typeButton {
 	display: flex;
-	flex-direction: column;
 	align-items: center;
-	border: 1px solid var(--l2-border);
-	background: var(--l2-background);
+	gap: 8px;
 	padding: 12px;
-	gap: 12px;
-	cursor: pointer;
-	font: inherit;
+	background: var(--bg-ink-400, #0b0c0e);
+	border: 1px solid var(--l1-border);
 	border-radius: 4px;
 	color: var(--l1-foreground);
-	transition:
-		transform 180ms ease,
-		border-color 180ms ease;
+	cursor: pointer;
+	text-align: left;
 
 	&:hover {
-		background-color: var(--l2-background-hover);
-		border-color: var(--bg-robin-400);
-	}
-	&:active {
-		transform: translateY(2px);
+		border-color: var(--bg-robin-500);
 	}
 }
-
-.panelTypeCardSelected {
-	border-color: var(--bg-robin-400);
-	background-color: var(--l2-background-hover);
-	box-shadow: inset 0 0 0 1px var(--bg-robin-400);
-}
-
-.footerActions {
-	display: flex;
-	align-items: flex-end;
-	justify-content: flex-end;
-	gap: 8px;
-	width: 100%;
-}
-
-.footerPicker {
-	// Take all the width left over by the (natural-width) confirm button.
-	display: flex;
-	flex: 1;
-	flex-direction: column;
-	gap: 6px;
-	min-width: 0;
-}
-
-.pickerLabel {
-	color: var(--l3-foreground);
-	font-size: 11px;
-	font-weight: 500;
-	letter-spacing: 0.06em;
-	text-transform: uppercase;
-}

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelTypeSelectionModal/PanelTypeSelectionModal.tsx

@@ -1,135 +1,45 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { Color } from '@signozhq/design-tokens';
+import { Modal } from 'antd';
 import { Button } from '@signozhq/ui/button';
-import { DialogWrapper } from '@signozhq/ui/dialog';
-import cx from 'classnames';
 
-import { useDashboardSections } from '../../../hooks/useDashboardSections';
 import type { PanelKind } from '../../../Panels/types/panelKind';
 import { PANEL_TYPES } from './constants';
-import SectionPicker from './SectionPicker';
-import { buildSectionOptions, resolveDefaultSectionValue } from './utils';
 import styles from './PanelTypeSelectionModal.module.scss';
-import { Plus } from '@signozhq/icons';
 
 interface PanelTypeSelectionModalProps {
 	open: boolean;
 	onClose: () => void;
-	onSelect: (panelKind: PanelKind, layoutIndex?: number) => void;
-	/** Section the picker opens on; omit → the untitled root / first section. */
-	defaultLayoutIndex?: number;
+	onSelect: (panelKind: PanelKind) => void;
 }
 
-/** Fake loader shown on the confirm button before navigating to the editor. */
-const CONFIRM_LOADER_MS = 500;
-
 function PanelTypeSelectionModal({
 	open,
 	onClose,
 	onSelect,
-	defaultLayoutIndex,
 }: PanelTypeSelectionModalProps): JSX.Element {
-	const sections = useDashboardSections();
-	const options = useMemo(() => buildSectionOptions(sections), [sections]);
-	const hasSectionPicker = options.length > 1;
-
-	const [selectedValue, setSelectedValue] = useState('');
-	const [selectedPanelKind, setSelectedPanelKind] = useState<PanelKind | null>(
-		null,
-	);
-	const [isSubmitting, setIsSubmitting] = useState(false);
-	const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-	const clearTimer = useCallback((): void => {
-		if (timerRef.current !== null) {
-			clearTimeout(timerRef.current);
-			timerRef.current = null;
-		}
-	}, []);
-
-	// Seed the target section on open; cancel a pending navigation on close.
-	useEffect(() => {
-		if (open) {
-			setSelectedValue(resolveDefaultSectionValue(options, defaultLayoutIndex));
-			setSelectedPanelKind(null);
-			setIsSubmitting(false);
-		} else {
-			clearTimer();
-		}
-	}, [open, options, defaultLayoutIndex, clearTimer]);
-
-	useEffect(() => clearTimer, [clearTimer]);
-
-	const handleConfirm = (): void => {
-		if (selectedPanelKind === null || isSubmitting) {
-			return;
-		}
-		setIsSubmitting(true);
-		const layoutIndex = selectedValue === '' ? undefined : Number(selectedValue);
-		timerRef.current = setTimeout(() => {
-			onSelect(selectedPanelKind, layoutIndex);
-		}, CONFIRM_LOADER_MS);
-	};
-
-	// Footer is always shown; the confirm button is disabled until a panel type is picked.
-	const footer = (
-		<div className={styles.footerActions}>
-			{hasSectionPicker && (
-				<div className={styles.footerPicker}>
-					<span className={styles.pickerLabel}>Add panel to</span>
-					<SectionPicker
-						options={options}
-						value={selectedValue}
-						onChange={setSelectedValue}
-					/>
-				</div>
-			)}
-			<Button
-				color="primary"
-				size="md"
-				disabled={selectedPanelKind === null}
-				loading={isSubmitting}
-				prefix={<Plus size={16} />}
-				onClick={handleConfirm}
-				testId="panel-type-confirm"
-			>
-				Add Panel
-			</Button>
-		</div>
-	);
-
 	return (
-		<DialogWrapper
+		<Modal
 			open={open}
-			onOpenChange={(isOpen): void => {
-				if (!isOpen) {
-					onClose();
-				}
-			}}
-			title="New Panel"
-			footer={footer}
+			title="Select a panel type"
+			onCancel={onClose}
+			footer={null}
+			destroyOnClose
 		>
-			<div className={styles.panelTypeSection}>
-				<span className={styles.pickerLabel}>Select panel type</span>
-				<div className={styles.grid}>
-					{PANEL_TYPES.map(({ panelKind, label, Icon }) => (
-						<button
-							key={panelKind}
-							type="button"
-							className={cx(styles.panelTypeCard, {
-								[styles.panelTypeCardSelected]: panelKind === selectedPanelKind,
-							})}
-							data-testid={`panel-type-${panelKind}`}
-							aria-pressed={panelKind === selectedPanelKind}
-							onClick={(): void => setSelectedPanelKind(panelKind)}
-						>
-							<Icon size={24} color={Color.BG_ROBIN_400} />
-							{label}
-						</button>
-					))}
-				</div>
+			<div className={styles.grid}>
+				{PANEL_TYPES.map(({ panelKind, label, Icon }) => (
+					<Button
+						key={panelKind}
+						type="button"
+						variant="ghost"
+						className={styles.typeButton}
+						data-testid={`panel-type-${panelKind}`}
+						onClick={(): void => onSelect(panelKind)}
+					>
+						<Icon size={14} />
+						{label}
+					</Button>
+				))}
 			</div>
-		</DialogWrapper>
+		</Modal>
 	);
 }
 

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelTypeSelectionModal/SectionPicker.module.scss

@@ -1,55 +0,0 @@
-.select {
-	width: 100%;
-}
-
-.dropdown {
-	min-width: 260px;
-}
-
-.rootIcon {
-	color: var(--bg-robin-400);
-	flex-shrink: 0;
-}
-
-.sectionIcon {
-	color: var(--l3-foreground);
-	flex-shrink: 0;
-}
-
-.triggerValue {
-	display: flex;
-	align-items: center;
-	gap: 8px;
-	overflow: hidden;
-}
-
-.triggerLabel {
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-}
-
-.optionRow {
-	display: flex;
-	align-items: center;
-	gap: 12px;
-	padding: 4px 0;
-}
-
-.optionText {
-	display: flex;
-	flex-direction: column;
-	gap: 2px;
-	overflow: hidden;
-}
-
-.optionLabel {
-	color: var(--l1-foreground);
-	line-height: 1.2;
-}
-
-.optionDescription {
-	color: var(--l3-foreground);
-	font-size: 12px;
-	line-height: 1.2;
-}

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelTypeSelectionModal/SectionPicker.tsx

@@ -1,65 +0,0 @@
-import { useMemo } from 'react';
-// eslint-disable-next-line signoz/no-antd-components
-import { Select } from 'antd';
-
-import type { SectionOption } from './types';
-import styles from './SectionPicker.module.scss';
-
-interface SectionPickerProps {
-	options: SectionOption[];
-	value: string;
-	onChange: (value: string) => void;
-}
-
-function SectionPicker({
-	options,
-	value,
-	onChange,
-}: SectionPickerProps): JSX.Element {
-	// `selectedLabel` (one line) shows in the trigger; `label` (two lines) in the list.
-	const selectOptions = useMemo(
-		() =>
-			options.map((option) => {
-				const iconClass = option.isRoot ? styles.rootIcon : styles.sectionIcon;
-				return {
-					value: option.value,
-					selectedLabel: (
-						<span className={styles.triggerValue}>
-							<option.Icon size={16} className={iconClass} />
-							<span className={styles.triggerLabel}>{option.label}</span>
-						</span>
-					),
-					label: (
-						<span
-							className={styles.optionRow}
-							data-testid={`panel-section-option-${option.layoutIndex}`}
-						>
-							<option.Icon size={16} className={iconClass} />
-							<span className={styles.optionText}>
-								<span className={styles.optionLabel}>{option.label}</span>
-								<span className={styles.optionDescription}>{option.description}</span>
-							</span>
-						</span>
-					),
-				};
-			}),
-		[options],
-	);
-
-	return (
-		<Select<string>
-			className={styles.select}
-			popupClassName={styles.dropdown}
-			value={value}
-			onChange={onChange}
-			data-testid="panel-section-select"
-			optionLabelProp="selectedLabel"
-			getPopupContainer={(trigger): HTMLElement =>
-				trigger.parentElement ?? document.body
-			}
-			options={selectOptions}
-		/>
-	);
-}
-
-export default SectionPicker;

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelTypeSelectionModal/types.ts

@@ -14,16 +14,3 @@ export interface PanelType {
 	/** Icon component — the consumer renders it and controls size/color/etc. */
 	Icon: ComponentType<IconProps>;
 }
-
-export interface SectionOption {
-	/** The section's `layoutIndex`, stringified for the Select value. */
-	value: string;
-	layoutIndex: number;
-	/** Section title, or "Dashboard (root)" for the untitled top-level layout. */
-	label: string;
-	/** Caption under the label. */
-	description: string;
-	/** Untitled top-level layout (has no section header). */
-	isRoot: boolean;
-	Icon: ComponentType<IconProps>;
-}

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelTypeSelectionModal/utils.ts

@@ -1,41 +0,0 @@
-import { LayoutDashboard, Rows2 } from '@signozhq/icons';
-
-import type { DashboardSection } from '../../../utils';
-import type { SectionOption } from './types';
-
-const ROOT_LABEL = 'Dashboard (root)';
-const ROOT_DESCRIPTION = 'Top level — no section';
-const SECTION_DESCRIPTION = 'Section';
-
-/** Maps dashboard sections to section-picker options (untitled → "root"). */
-export function buildSectionOptions(
-	sections: DashboardSection[],
-): SectionOption[] {
-	return sections.map((section) => {
-		const isRoot = !section.title;
-		return {
-			value: String(section.layoutIndex),
-			layoutIndex: section.layoutIndex,
-			label: isRoot ? ROOT_LABEL : (section.title as string),
-			description: isRoot ? ROOT_DESCRIPTION : SECTION_DESCRIPTION,
-			isRoot,
-			Icon: isRoot ? LayoutDashboard : Rows2,
-		};
-	});
-}
-
-/**
- * Picks the option the picker should open on: the section the "Add panel" was
- * triggered from when present and still valid, otherwise the first option.
- */
-export function resolveDefaultSectionValue(
-	options: SectionOption[],
-	defaultLayoutIndex: number | undefined,
-): string {
-	const fallback = options[0]?.value ?? '';
-	if (defaultLayoutIndex === undefined) {
-		return fallback;
-	}
-	const target = String(defaultLayoutIndex);
-	return options.some((option) => option.value === target) ? target : fallback;
-}

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Section/Section/Section.tsx

@@ -29,13 +29,8 @@ interface SectionProps {
 
 function Section({ section, sections, dragHandle }: SectionProps): JSX.Element {
 	const isEditable = useDashboardStore((s) => s.isEditable);
-	const {
-		isPickerOpen,
-		openPicker,
-		closePicker,
-		createPanel,
-		targetLayoutIndex,
-	} = useCreatePanel();
+	const { isPickerOpen, openPicker, closePicker, createPanel } =
+		useCreatePanel();
 	const [isDeleteOpen, setIsDeleteOpen] = useState(false);
 	const containerRef = useRef<HTMLDivElement>(null);
 	// Placeholder signal for lazy panel query-loading (consumed in a later PR):
@@ -146,7 +141,6 @@ function Section({ section, sections, dragHandle }: SectionProps): JSX.Element {
 				open={isPickerOpen}
 				onClose={closePicker}
 				onSelect={createPanel}
-				defaultLayoutIndex={targetLayoutIndex}
 			/>
 			<ConfirmDeleteDialog
 				open={isDeleteOpen}

frontend/src/pages/DashboardPageV2/DashboardContainer/hooks/useCreatePanel.ts

@@ -12,10 +12,7 @@ interface UseCreatePanelResult {
 	/** Pass the target section's layout index; omit → last/new section. */
 	openPicker: (layoutIndex?: number) => void;
 	closePicker: () => void;
-	/** The section the picker was opened against — seeds its section dropdown. */
-	targetLayoutIndex: number | undefined;
-	/** `layoutIndex` overrides the opened-against target (the dropdown's choice). */
-	createPanel: (panelKind: PanelKind, layoutIndex?: number) => void;
+	createPanel: (panelKind: PanelKind) => void;
 }
 
 /**
@@ -41,23 +38,16 @@ export function useCreatePanel(): UseCreatePanelResult {
 	}, []);
 
 	const createPanel = useCallback(
-		(panelKind: PanelKind, targetIndex?: number): void => {
+		(panelKind: PanelKind): void => {
 			setIsPickerOpen(false);
 			const path = generatePath(ROUTES.DASHBOARD_PANEL_EDITOR, {
 				dashboardId,
 				panelId: NEW_PANEL_ID,
 			});
-			const target = targetIndex ?? layoutIndex;
-			safeNavigate(`${path}${newPanelSearch(panelKind, target)}`);
+			safeNavigate(`${path}${newPanelSearch(panelKind, layoutIndex)}`);
 		},
 		[safeNavigate, dashboardId, layoutIndex],
 	);
 
-	return {
-		isPickerOpen,
-		openPicker,
-		closePicker,
-		targetLayoutIndex: layoutIndex,
-		createPanel,
-	};
+	return { isPickerOpen, openPicker, closePicker, createPanel };
 }

frontend/src/pages/DashboardPageV2/DashboardContainer/hooks/useDashboardSections.ts

@@ -1,21 +0,0 @@
-import { useMemo } from 'react';
-import { useGetDashboardV2 } from 'api/generated/services/dashboard';
-
-import { useDashboardStore } from '../store/useDashboardStore';
-import { type DashboardSection, layoutsToSections } from '../utils';
-
-/**
- * The current dashboard's sections, read from the already-loaded dashboard
- * query. The page fetches via useGetDashboardV2 keyed by id, so this reuses that
- * cache (no extra request) instead of prop-drilling the section list.
- */
-export function useDashboardSections(): DashboardSection[] {
-	const dashboardId = useDashboardStore((s) => s.dashboardId);
-	const { data } = useGetDashboardV2({ id: dashboardId });
-	const spec = data?.data?.spec;
-
-	return useMemo(
-		() => layoutsToSections(spec?.layouts, spec?.panels),
-		[spec?.layouts, spec?.panels],
-	);
-}

pkg/telemetrymetrics/reduced_test.go

@@ -39,48 +39,48 @@ func TestReducedStatementBuilder(t *testing.T) {
 			name:  "gauge_sum_latest",
 			query: reducedQuery("test.metric", metrictypes.GaugeType, metrictypes.Unspecified, metrictypes.TimeAggregationLatest, metrictypes.SpaceAggregationSum),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, anyLast(last) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, argMax(value, unix_milli) AS per_series_value FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`sum_last`, computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_last_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), "test.metric", uint64(1746999900000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, anyLast(last) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, argMax(value, unix_milli) AS per_series_value FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`sum_last`, points.computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_last_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), false, "test.metric", uint64(1746999900000), uint64(1747172760000)},
 			},
 		},
 		{
 			name:  "gauge_avg_avg",
 			query: reducedQuery("test.metric", metrictypes.GaugeType, metrictypes.Unspecified, metrictypes.TimeAggregationAvg, metrictypes.SpaceAggregationAvg),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(sum) / sum(count) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, avg(value) AS per_series_value, avg(weight) AS per_series_weight FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`sum_last`, computed_at) AS value, argMax(`count_series`, computed_at) AS weight FROM signoz_metrics.distributed_samples_v4_reduced_last_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) / sum(per_series_weight) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), "test.metric", uint64(1746999900000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(sum) / sum(count) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, avg(value) AS per_series_value, avg(weight) AS per_series_weight FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`sum_last`, points.computed_at) AS value, argMax(`count_series`, points.computed_at) AS weight FROM signoz_metrics.distributed_samples_v4_reduced_last_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) / sum(per_series_weight) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), false, "test.metric", uint64(1746999900000), uint64(1747172760000)},
 			},
 		},
 		{
 			name:  "gauge_min_min",
 			query: reducedQuery("test.metric", metrictypes.GaugeType, metrictypes.Unspecified, metrictypes.TimeAggregationMin, metrictypes.SpaceAggregationMin),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, min(min) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, min(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, min(value) AS per_series_value FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`min`, computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_last_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, min(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), "test.metric", uint64(1746999900000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, min(min) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, min(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, min(value) AS per_series_value FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`min`, points.computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_last_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, min(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), false, "test.metric", uint64(1746999900000), uint64(1747172760000)},
 			},
 		},
 		{
 			name:  "gauge_max_max",
 			query: reducedQuery("test.metric", metrictypes.GaugeType, metrictypes.Unspecified, metrictypes.TimeAggregationMax, metrictypes.SpaceAggregationMax),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, max(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(value) AS per_series_value FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`max`, computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_last_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, max(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), "test.metric", uint64(1746999900000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, max(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(value) AS per_series_value FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`max`, points.computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_last_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, max(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), false, "test.metric", uint64(1746999900000), uint64(1747172760000)},
 			},
 		},
 		{
 			name:  "counter_sum_rate",
 			query: reducedQuery("test.metric.sum", metrictypes.SumType, metrictypes.Cumulative, metrictypes.TimeAggregationRate, metrictypes.SpaceAggregationSum),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT ts, multiIf(row_number() OVER rate_window = 1, nan, (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) < 0, per_series_value / (ts - lagInFrame(ts, 1) OVER rate_window), (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) / (ts - lagInFrame(ts, 1) OVER rate_window)) AS per_series_value FROM (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts) WINDOW rate_window AS (PARTITION BY fingerprint ORDER BY fingerprint, ts)), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(value) / 300 AS per_series_value FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`sum`, computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_sum_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric.sum", uint64(1746921600000), uint64(1747172760000), "cumulative", false, "test.metric.sum", uint64(1746999600000), uint64(1747172760000), 0, "test.metric.sum", uint64(1746999600000), uint64(1747172760000), "test.metric.sum", uint64(1746999600000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT ts, multiIf(row_number() OVER rate_window = 1, nan, (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) < 0, per_series_value / (ts - lagInFrame(ts, 1) OVER rate_window), (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) / (ts - lagInFrame(ts, 1) OVER rate_window)) AS per_series_value FROM (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts) WINDOW rate_window AS (PARTITION BY fingerprint ORDER BY fingerprint, ts)), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(value) / 300 AS per_series_value FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`sum`, points.computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_sum_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric.sum", uint64(1746921600000), uint64(1747172760000), "cumulative", false, "test.metric.sum", uint64(1746999600000), uint64(1747172760000), 0, "test.metric.sum", uint64(1746999600000), uint64(1747172760000), false, "test.metric.sum", uint64(1746999600000), uint64(1747172760000)},
 			},
 		},
 		{
 			name:  "counter_avg_increase",
 			query: reducedQuery("test.metric", metrictypes.SumType, metrictypes.Cumulative, metrictypes.TimeAggregationIncrease, metrictypes.SpaceAggregationAvg),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT ts, multiIf(row_number() OVER rate_window = 1, nan, (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) < 0, per_series_value, per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) AS per_series_value FROM (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts) WINDOW rate_window AS (PARTITION BY fingerprint ORDER BY fingerprint, ts)), __spatial_aggregation_cte AS (SELECT ts, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(value) AS per_series_value, avg(weight) AS per_series_weight FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`sum`, computed_at) AS value, argMax(`count_series`, computed_at) AS weight FROM signoz_metrics.distributed_samples_v4_reduced_sum_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) / sum(per_series_weight) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "cumulative", false, "test.metric", uint64(1746999600000), uint64(1747172760000), 0, "test.metric", uint64(1746999600000), uint64(1747172760000), "test.metric", uint64(1746999600000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT ts, multiIf(row_number() OVER rate_window = 1, nan, (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) < 0, per_series_value, per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) AS per_series_value FROM (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts) WINDOW rate_window AS (PARTITION BY fingerprint ORDER BY fingerprint, ts)), __spatial_aggregation_cte AS (SELECT ts, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(value) AS per_series_value, avg(weight) AS per_series_weight FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`sum`, points.computed_at) AS value, argMax(`count_series`, points.computed_at) AS weight FROM signoz_metrics.distributed_samples_v4_reduced_sum_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) / sum(per_series_weight) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "cumulative", false, "test.metric", uint64(1746999600000), uint64(1747172760000), 0, "test.metric", uint64(1746999600000), uint64(1747172760000), false, "test.metric", uint64(1746999600000), uint64(1747172760000)},
 			},
 		},
 		{
@@ -103,16 +103,16 @@ func TestReducedStatementBuilder(t *testing.T) {
 			name:  "histogram_p99",
 			query: reducedQuery("test.metric.bucket", metrictypes.HistogramType, metrictypes.Cumulative, metrictypes.TimeAggregationUnspecified, metrictypes.SpaceAggregationPercentile99),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT ts, `le`, multiIf(row_number() OVER rate_window = 1, nan, (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) < 0, per_series_value / (ts - lagInFrame(ts, 1) OVER rate_window), (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) / (ts - lagInFrame(ts, 1) OVER rate_window)) AS per_series_value FROM (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, `le`, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint, JSONExtractString(labels, 'le') AS `le` FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint, `le`) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts, `le` ORDER BY fingerprint, ts) WINDOW rate_window AS (PARTITION BY fingerprint ORDER BY fingerprint, ts)), __spatial_aggregation_cte AS (SELECT ts, `le`, sum(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts, `le`) SELECT ts, histogramQuantile(arrayMap(x -> toFloat64(x), groupArray(le)), groupArray(value), 0.990) AS value FROM __spatial_aggregation_cte GROUP BY ts ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, `le`, sum(value) / 300 AS per_series_value FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`sum`, computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_sum_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint, JSONExtractString(labels, 'le') AS `le` FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint, `le`) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts, `le`), __spatial_aggregation_cte AS (SELECT ts, `le`, sum(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts, `le`) SELECT ts, histogramQuantile(arrayMap(x -> toFloat64(x), groupArray(le)), groupArray(value), 0.990) AS value FROM __spatial_aggregation_cte GROUP BY ts ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric.bucket", uint64(1746921600000), uint64(1747172760000), "cumulative", false, "test.metric.bucket", uint64(1746999900000), uint64(1747172760000), 0, "test.metric.bucket", uint64(1746999900000), uint64(1747172760000), "test.metric.bucket", uint64(1746999900000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT ts, `le`, multiIf(row_number() OVER rate_window = 1, nan, (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) < 0, per_series_value / (ts - lagInFrame(ts, 1) OVER rate_window), (per_series_value - lagInFrame(per_series_value, 1) OVER rate_window) / (ts - lagInFrame(ts, 1) OVER rate_window)) AS per_series_value FROM (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, `le`, max(max) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint, JSONExtractString(labels, 'le') AS `le` FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint, `le`) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts, `le` ORDER BY fingerprint, ts) WINDOW rate_window AS (PARTITION BY fingerprint ORDER BY fingerprint, ts)), __spatial_aggregation_cte AS (SELECT ts, `le`, sum(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts, `le`) SELECT ts, histogramQuantile(arrayMap(x -> toFloat64(x), groupArray(le)), groupArray(value), 0.990) AS value FROM __spatial_aggregation_cte GROUP BY ts ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, `le`, sum(value) / 300 AS per_series_value FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, `le`, argMax(`sum`, points.computed_at) AS value FROM signoz_metrics.distributed_samples_v4_reduced_sum_60s AS points INNER JOIN (SELECT fingerprint, JSONExtractString(labels, 'le') AS `le` FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint, `le`) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli, `le`) GROUP BY fingerprint, ts, `le`), __spatial_aggregation_cte AS (SELECT ts, `le`, sum(per_series_value) AS value FROM __temporal_aggregation_cte GROUP BY ts, `le`) SELECT ts, histogramQuantile(arrayMap(x -> toFloat64(x), groupArray(le)), groupArray(value), 0.990) AS value FROM __spatial_aggregation_cte GROUP BY ts ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric.bucket", uint64(1746921600000), uint64(1747172760000), "cumulative", false, "test.metric.bucket", uint64(1746999900000), uint64(1747172760000), 0, "test.metric.bucket", uint64(1746999900000), uint64(1747172760000), false, "test.metric.bucket", uint64(1746999900000), uint64(1747172760000)},
 			},
 		},
 		{
 			name:  "summary_avg",
 			query: reducedQuery("test.metric", metrictypes.SummaryType, metrictypes.Unspecified, metrictypes.TimeAggregationAvg, metrictypes.SpaceAggregationAvg),
 			expected: qbtypes.Statement{
-				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(sum) / sum(count) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, avg(value) AS per_series_value, avg(weight) AS per_series_weight FROM (SELECT reduced_fingerprint AS fingerprint, unix_milli, argMax(`sum_last`, computed_at) AS value, argMax(`count_series`, computed_at) AS weight FROM signoz_metrics.distributed_samples_v4_reduced_last_60s WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY reduced_fingerprint, unix_milli) AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) / sum(per_series_weight) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
-				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), "test.metric", uint64(1746999900000), uint64(1747172760000), false},
+				Query: "SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, sum(sum) / sum(count) AS per_series_value FROM signoz_metrics.distributed_samples_v4_agg_5m AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_1day WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) UNION ALL SELECT * FROM (WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(300)) AS ts, avg(value) AS per_series_value, avg(weight) AS per_series_weight FROM (SELECT points.reduced_fingerprint AS fingerprint, points.unix_milli AS unix_milli, argMax(`sum_last`, points.computed_at) AS value, argMax(`count_series`, points.computed_at) AS weight FROM signoz_metrics.distributed_samples_v4_reduced_last_60s AS points INNER JOIN (SELECT fingerprint FROM signoz_metrics.time_series_v4_reduced WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND __normalized = ? GROUP BY fingerprint) AS filtered_time_series ON points.reduced_fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, unix_milli) GROUP BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, sum(per_series_value) / sum(per_series_weight) AS value FROM __temporal_aggregation_cte GROUP BY ts) SELECT * FROM __spatial_aggregation_cte ORDER BY ts) ORDER BY ts",
+				Args:  []any{"test.metric", uint64(1746921600000), uint64(1747172760000), "unspecified", false, "test.metric", uint64(1746999900000), uint64(1747172760000), 0, "test.metric", uint64(1746999900000), uint64(1747172760000), false, "test.metric", uint64(1746999900000), uint64(1747172760000)},
 			},
 		},
 	}

pkg/telemetrymetrics/statement_builder.go

@@ -338,19 +338,24 @@ func (b *MetricQueryStatementBuilder) buildReducedTemporalAggregationCTE(
 
 	// dedup recomputed buckets: latest computed_at wins per (series, 60s bucket)
 	dedup := sqlbuilder.NewSelectBuilder()
-	dedup.Select("reduced_fingerprint AS fingerprint", "unix_milli")
-	dedup.SelectMore(fmt.Sprintf("argMax(%s, computed_at) AS value", value))
-	if weight != "" {
-		dedup.SelectMore(fmt.Sprintf("argMax(%s, computed_at) AS weight", weight))
+	dedup.Select("points.reduced_fingerprint AS fingerprint", "points.unix_milli AS unix_milli")
+	for _, g := range query.GroupBy {
+		dedup.SelectMore(fmt.Sprintf("`%s`", g.Name))
 	}
-	dedup.From(fmt.Sprintf("%s.%s", DBName, WhichReducedSamplesTableToUse(agg.Type)))
+	dedup.SelectMore(fmt.Sprintf("argMax(%s, points.computed_at) AS value", value))
+	if weight != "" {
+		dedup.SelectMore(fmt.Sprintf("argMax(%s, points.computed_at) AS weight", weight))
+	}
+	dedup.From(fmt.Sprintf("%s.%s AS points", DBName, WhichReducedSamplesTableToUse(agg.Type)))
+	dedup.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.reduced_fingerprint = filtered_time_series.fingerprint")
 	dedup.Where(
 		dedup.In("metric_name", agg.MetricName),
 		dedup.GTE("unix_milli", start),
 		dedup.LT("unix_milli", end),
 	)
-	dedup.GroupBy("reduced_fingerprint", "unix_milli")
-	dedupQuery, dedupArgs := dedup.BuildWithFlavor(sqlbuilder.ClickHouse)
+	dedup.GroupBy("fingerprint", "unix_milli")
+	dedup.GroupBy(querybuilder.GroupByKeys(query.GroupBy)...)
+	dedupQuery, dedupArgs := dedup.BuildWithFlavor(sqlbuilder.ClickHouse, timeSeriesCTEArgs...)
 
 	sb := sqlbuilder.NewSelectBuilder()
 	sb.Select("fingerprint")
@@ -364,13 +369,11 @@ func (b *MetricQueryStatementBuilder) buildReducedTemporalAggregationCTE(
 		// denominator is reduced with avg
 		sb.SelectMore("avg(weight) AS per_series_weight")
 	}
-	sb.From(fmt.Sprintf("(%s) AS points", dedupQuery))
-	sb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.fingerprint = filtered_time_series.fingerprint")
+	sb.From(fmt.Sprintf("(%s)", dedupQuery))
 	sb.GroupBy("fingerprint", "ts")
 	sb.GroupBy(querybuilder.GroupByKeys(query.GroupBy)...)
 
-	initArgs := append(append([]any{}, dedupArgs...), timeSeriesCTEArgs...)
-	q, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse, initArgs...)
+	q, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse, dedupArgs...)
 	return fmt.Sprintf("__temporal_aggregation_cte AS (%s)", q), args, true
 }
 

tests/fixtures/clickhouse.py

@@ -2,6 +2,7 @@ import os
 from collections.abc import Callable, Generator
 from datetime import datetime
 from typing import Any
+from uuid import uuid4
 
 import clickhouse_connect
 import clickhouse_connect.driver
@@ -10,37 +11,93 @@ import docker
 import docker.errors
 import pytest
 from testcontainers.clickhouse import ClickHouseContainer
-from testcontainers.core.container import Network
+from testcontainers.core.container import DockerContainer, Network
 
 from fixtures import reuse, types
 from fixtures.logger import setup_logger
 
 logger = setup_logger(__name__)
 
+CLICKHOUSE_USERNAME = "signoz"
+CLICKHOUSE_PASSWORD = "password"
 
-@pytest.fixture(name="clickhouse", scope="package")
-def clickhouse(
-    tmpfs: Generator[types.LegacyPath, Any],
-    network: Network,
-    zookeeper: types.TestContainerDocker,
-    request: pytest.FixtureRequest,
-    pytestconfig: pytest.Config,
-) -> types.TestContainerClickhouse:
-    """
-    Package-scoped fixture for Clickhouse TestContainer.
+CUSTOM_FUNCTION_CONFIG = """
+<functions>
+    <function>
+        <type>executable</type>
+        <name>histogramQuantile</name>
+        <return_type>Float64</return_type>
+        <argument>
+            <type>Array(Float64)</type>
+            <name>buckets</name>
+        </argument>
+        <argument>
+            <type>Array(Float64)</type>
+            <name>counts</name>
+        </argument>
+        <argument>
+            <type>Float64</type>
+            <name>quantile</name>
+        </argument>
+        <format>CSV</format>
+        <command>./histogramQuantile</command>
+    </function>
+</functions>
+"""
+
+# Distributed inserts to a remote shard are async by default. We force
+# sycn at the profile level for deterministic tests.
+CLUSTER_USERS_CONFIG = """
+<clickhouse>
+    <profiles>
+        <default>
+            <insert_distributed_sync>1</insert_distributed_sync>
+        </default>
+    </profiles>
+</clickhouse>
+"""
+
+
+def render_remote_servers(shard_hosts: list[tuple[str, int]], secret: str | None = None) -> str:
+    """Render the <remote_servers> block for a cluster named `cluster` with one
+    single-replica shard per (host, port).
     """
+    shards = "".join(
+        f"""
+                <shard>
+                    <replica>
+                        <host>{host}</host>
+                        <port>{port}</port>
+                    </replica>
+                </shard>"""
+        for host, port in shard_hosts
+    )
 
-    def create() -> types.TestContainerClickhouse:
-        version = request.config.getoption("--clickhouse-version")
+    # Multi-node clusters need `secret` because distributed queries otherwise
+    # authenticate as the `default` user, which the docker entrypoint restricts
+    # to localhost when a custom user is configured.
+    secret_block = (
+        f"""
+                    <secret>{secret}</secret>"""
+        if secret
+        else ""
+    )
 
-        container = ClickHouseContainer(
-            image=f"clickhouse/clickhouse-server:{version}",
-            port=9000,
-            username="signoz",
-            password="password",
-        )
+    return f"""
+            <remote_servers>
+                <cluster>{secret_block}{shards}
+                </cluster>
+            </remote_servers>"""
 
-        cluster_config = f"""
+
+def render_node_config(
+    zookeeper_address: str,
+    zookeeper_port: int,
+    shard: str,
+    remote_servers: str,
+    distributed_ddl_path: str = "/clickhouse/task_queue/ddl",
+) -> str:
+    return f"""
         <clickhouse>
             <logger>
                 <level>information</level>
@@ -55,33 +112,23 @@ def clickhouse(
             </logger>
 
             <macros>
-                <shard>01</shard>
+                <shard>{shard}</shard>
                 <replica>01</replica>
             </macros>
 
             <zookeeper>
                 <node>
-                    <host>{zookeeper.container_configs["2181"].address}</host>
-                    <port>{zookeeper.container_configs["2181"].port}</port>
+                    <host>{zookeeper_address}</host>
+                    <port>{zookeeper_port}</port>
                 </node>
             </zookeeper>
-
-            <remote_servers>
-                <cluster>
-                    <shard>
-                        <replica>
-                            <host>127.0.0.1</host>
-                            <port>9000</port>
-                        </replica>
-                    </shard>
-                </cluster>
-            </remote_servers>
+{remote_servers}
 
             <user_defined_executable_functions_config>*function.xml</user_defined_executable_functions_config>
             <user_scripts_path>/var/lib/clickhouse/user_scripts/</user_scripts_path>
 
             <distributed_ddl>
-                <path>/clickhouse/task_queue/ddl</path>
+                <path>{distributed_ddl_path}</path>
                 <profile>default</profile>
             </distributed_ddl>
 
@@ -122,38 +169,66 @@ def clickhouse(
         </clickhouse>
         """
 
-        custom_function_config = """
-        <functions>
-            <function>
-                <type>executable</type>
-                <name>histogramQuantile</name>
-                <return_type>Float64</return_type>
-                <argument>
-                    <type>Array(Float64)</type>
-                    <name>buckets</name>
-                </argument>
-                <argument>
-                    <type>Array(Float64)</type>
-                    <name>counts</name>
-                </argument>
-                <argument>
-                    <type>Float64</type>
-                    <name>quantile</name>
-                </argument>
-                <format>CSV</format>
-                <command>./histogramQuantile</command>
-            </function>
-        </functions>
-        """
 
-        tmp_dir = tmpfs("clickhouse")
+def install_histogram_quantile(container: ClickHouseContainer) -> None:
+    wrapped = container.get_wrapped_container()
+    exit_code, output = wrapped.exec_run(
+        [
+            "bash",
+            "-c",
+            (
+                'version="v0.0.1" && '
+                'node_os=$(uname -s | tr "[:upper:]" "[:lower:]") && '
+                "node_arch=$(uname -m | sed s/aarch64/arm64/ | sed s/x86_64/amd64/) && "
+                "cd /tmp && "
+                'wget -O histogram-quantile.tar.gz "https://github.com/SigNoz/signoz/releases/download/histogram-quantile%2F${version}/histogram-quantile_${node_os}_${node_arch}.tar.gz" && '
+                "tar -xzf histogram-quantile.tar.gz && "
+                "mkdir -p /var/lib/clickhouse/user_scripts && "
+                "mv histogram-quantile /var/lib/clickhouse/user_scripts/histogramQuantile && "
+                "chmod +x /var/lib/clickhouse/user_scripts/histogramQuantile"
+            ),
+        ],
+    )
+    if exit_code != 0:
+        raise RuntimeError(f"Failed to install histogramQuantile binary: {output.decode()}")
+
+
+def create_clickhouse(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    keeper: types.TestContainerDocker,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+    cache_key: str = "clickhouse",
+    version: str | None = None,
+) -> types.TestContainerClickhouse:
+    coordinator = next(iter(keeper.container_configs.values()))
+
+    def create() -> types.TestContainerClickhouse:
+        clickhouse_version = version or request.config.getoption("--clickhouse-version")
+
+        container = ClickHouseContainer(
+            image=f"clickhouse/clickhouse-server:{clickhouse_version}",
+            port=9000,
+            username=CLICKHOUSE_USERNAME,
+            password=CLICKHOUSE_PASSWORD,
+        )
+
+        cluster_config = render_node_config(
+            zookeeper_address=coordinator.address,
+            zookeeper_port=coordinator.port,
+            shard="01",
+            remote_servers=render_remote_servers([("127.0.0.1", 9000)]),
+        )
+
+        tmp_dir = tmpfs(cache_key)
         cluster_config_file_path = os.path.join(tmp_dir, "cluster.xml")
         with open(cluster_config_file_path, "w", encoding="utf-8") as f:
             f.write(cluster_config)
 
         custom_function_file_path = os.path.join(tmp_dir, "custom-function.xml")
         with open(custom_function_file_path, "w", encoding="utf-8") as f:
-            f.write(custom_function_config)
+            f.write(CUSTOM_FUNCTION_CONFIG)
 
         container.with_volume_mapping(cluster_config_file_path, "/etc/clickhouse-server/config.d/cluster.xml")
         container.with_volume_mapping(
@@ -163,27 +238,7 @@ def clickhouse(
         container.with_network(network)
         container.start()
 
-        # Download and install the histogramQuantile binary
-        wrapped = container.get_wrapped_container()
-        exit_code, output = wrapped.exec_run(
-            [
-                "bash",
-                "-c",
-                (
-                    'version="v0.0.1" && '
-                    'node_os=$(uname -s | tr "[:upper:]" "[:lower:]") && '
-                    "node_arch=$(uname -m | sed s/aarch64/arm64/ | sed s/x86_64/amd64/) && "
-                    "cd /tmp && "
-                    'wget -O histogram-quantile.tar.gz "https://github.com/SigNoz/signoz/releases/download/histogram-quantile%2F${version}/histogram-quantile_${node_os}_${node_arch}.tar.gz" && '
-                    "tar -xzf histogram-quantile.tar.gz && "
-                    "mkdir -p /var/lib/clickhouse/user_scripts && "
-                    "mv histogram-quantile /var/lib/clickhouse/user_scripts/histogramQuantile && "
-                    "chmod +x /var/lib/clickhouse/user_scripts/histogramQuantile"
-                ),
-            ],
-        )
-        if exit_code != 0:
-            raise RuntimeError(f"Failed to install histogramQuantile binary: {output.decode()}")
+        install_histogram_quantile(container)
 
         connection = clickhouse_connect.get_client(
             user=container.username,
@@ -253,7 +308,7 @@ def clickhouse(
     return reuse.wrap(
         request,
         pytestconfig,
-        "clickhouse",
+        cache_key,
         empty=lambda: types.TestContainerSQL(
             container=types.TestContainerDocker(id="", host_configs={}, container_configs={}),
             conn=None,
@@ -265,6 +320,334 @@ def clickhouse(
     )
 
 
+@pytest.fixture(name="clickhouse", scope="package")
+def clickhouse(
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    zookeeper: types.TestContainerDocker,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerClickhouse:
+    """
+    Package-scoped fixture for Clickhouse TestContainer.
+    """
+    return create_clickhouse(
+        tmpfs=tmpfs,
+        network=network,
+        keeper=zookeeper,
+        request=request,
+        pytestconfig=pytestconfig,
+    )
+
+
+def local_series_counts(
+    node_conns: list[clickhouse_connect.driver.client.Client],
+    table: str,
+    metric_name: str,
+) -> list[int]:
+    """Distinct series per node via the LOCAL (non-distributed) table."""
+    return [
+        int(
+            conn.query(
+                f"SELECT count(DISTINCT fingerprint) FROM signoz_metrics.{table} WHERE metric_name = %(metric_name)s",
+                parameters={"metric_name": metric_name},
+            ).result_rows[0][0]
+        )
+        for conn in node_conns
+    ]
+
+
+def assert_spans_shards(
+    node_conns: list[clickhouse_connect.driver.client.Client],
+    table: str,
+    metric_name: str,
+    total: int,
+) -> None:
+    """Guard for distributed tests: a green run on a cluster proves nothing
+    unless the seeded series actually landed on more than one shard."""
+    counts = local_series_counts(node_conns, table, metric_name)
+    assert sum(counts) == total, f"expected {total} series in {table} across shards, got {counts}"
+    assert min(counts) > 0, f"seeded series in {table} all landed on one shard: {counts}"
+
+
+@pytest.fixture(name="clickhouse_node_conns", scope="function")
+def clickhouse_node_conns(
+    clickhouse: types.TestContainerClickhouse,
+) -> Generator[list[clickhouse_connect.driver.client.Client], Any]:
+    """Per-node clients (index 0 = the initiator) for asserting shard-local
+    state via the local, non-distributed tables. Empty for single-node
+    fixtures, which don't populate `nodes`."""
+    conns = [
+        clickhouse_connect.get_client(
+            user=clickhouse.env["SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_USERNAME"],
+            password=clickhouse.env["SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_PASSWORD"],
+            host=node.host_configs["8123"].address,
+            port=node.host_configs["8123"].port,
+        )
+        for node in clickhouse.nodes
+    ]
+    yield conns
+    for conn in conns:
+        conn.close()
+
+
+KEEPER_CONFIG = """
+<clickhouse>
+    <listen_host>0.0.0.0</listen_host>
+    <keeper_server>
+        <tcp_port>9181</tcp_port>
+        <server_id>1</server_id>
+        <log_storage_path>/var/lib/clickhouse-keeper/coordination/log</log_storage_path>
+        <snapshot_storage_path>/var/lib/clickhouse-keeper/coordination/snapshots</snapshot_storage_path>
+        <coordination_settings>
+            <operation_timeout_ms>10000</operation_timeout_ms>
+            <session_timeout_ms>30000</session_timeout_ms>
+            <raft_logs_level>warning</raft_logs_level>
+        </coordination_settings>
+        <raft_configuration>
+            <server>
+                <id>1</id>
+                <hostname>localhost</hostname>
+                <port>9234</port>
+            </server>
+        </raft_configuration>
+    </keeper_server>
+</clickhouse>
+"""
+
+
+def create_clickhouse_keeper(
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+    cache_key: str = "clickhousekeeper",
+    version: str | None = None,
+) -> types.TestContainerDocker:
+
+    def create() -> types.TestContainerDocker:
+        keeper_version = version or request.config.getoption("--clickhouse-version")
+
+        tmp_dir = tmpfs(cache_key)
+        keeper_config_file_path = os.path.join(tmp_dir, "keeper_config.xml")
+        with open(keeper_config_file_path, "w", encoding="utf-8") as f:
+            f.write(KEEPER_CONFIG)
+
+        container = DockerContainer(image=f"clickhouse/clickhouse-keeper:{keeper_version}")
+        container.with_volume_mapping(keeper_config_file_path, "/etc/clickhouse-keeper/keeper_config.xml")
+        container.with_exposed_ports(9181)
+        container.with_network(network=network)
+
+        container.start()
+        return types.TestContainerDocker(
+            id=container.get_wrapped_container().id,
+            host_configs={
+                "9181": types.TestContainerUrlConfig(
+                    scheme="tcp",
+                    address=container.get_container_host_ip(),
+                    port=container.get_exposed_port(9181),
+                )
+            },
+            container_configs={
+                "9181": types.TestContainerUrlConfig(
+                    scheme="tcp",
+                    address=container.get_wrapped_container().name,
+                    port=9181,
+                )
+            },
+        )
+
+    def delete(container: types.TestContainerDocker):
+        client = docker.from_env()
+        try:
+            client.containers.get(container_id=container.id).stop()
+            client.containers.get(container_id=container.id).remove(v=True)
+        except docker.errors.NotFound:
+            logger.info(
+                "Skipping removal of ClickHouse Keeper, Keeper(%s) not found. Maybe it was manually removed?",
+                {"id": container.id},
+            )
+
+    def restore(cache: dict) -> types.TestContainerDocker:
+        return types.TestContainerDocker.from_cache(cache)
+
+    return reuse.wrap(
+        request,
+        pytestconfig,
+        cache_key,
+        lambda: types.TestContainerDocker(id="", host_configs={}, container_configs={}),
+        create,
+        delete,
+        restore,
+    )
+
+
+def create_clickhouse_cluster(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    keeper: types.TestContainerDocker,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+    cache_key: str = "clickhouse_cluster",
+    shards: int = 2,
+    version: str | None = None,
+) -> types.TestContainerClickhouse:
+    """
+    To some extent, taken inspiration from how ClickHouse's own integration
+    harness composes real clusters: deterministic hostnames
+    (network aliases), per-node shard macros, and a shared cluster definition
+    named `cluster`.
+
+    `conn`/`env` point at node 1 i.e the initiator every query-service query and
+    migration goes through. Per-node containers are exposed via `nodes` so
+    tests can assert shard-local state. `keeper` is any coordination service
+    (ZooKeeper or ClickHouse Keeper).
+    """
+    coordinator = next(iter(keeper.container_configs.values()))
+
+    def create() -> types.TestContainerClickhouse:
+        clickhouse_version = version or request.config.getoption("--clickhouse-version")
+
+        # Unique aliases per creation: docker allows duplicate network aliases
+        # (DNS round-robin), so a stale cluster must never share names with a
+        # fresh one.
+        suffix = uuid4().hex[:6]
+        aliases = [f"signoz-ch-{suffix}-{i:02d}" for i in range(1, shards + 1)]
+        remote_servers = render_remote_servers([(alias, 9000) for alias in aliases], secret=cache_key)
+        # Own DDL queue path: the keeper instance may be shared with other
+        # environments under --reuse; its DDL queue stays separate.
+        distributed_ddl_path = f"/clickhouse/{cache_key}-{suffix}/task_queue/ddl"
+
+        nodes: list[types.TestContainerDocker] = []
+        started: list[ClickHouseContainer] = []
+        try:
+            for i, alias in enumerate(aliases, start=1):
+                node_config = render_node_config(
+                    zookeeper_address=coordinator.address,
+                    zookeeper_port=coordinator.port,
+                    shard=f"{i:02d}",
+                    remote_servers=remote_servers,
+                    distributed_ddl_path=distributed_ddl_path,
+                )
+
+                tmp_dir = tmpfs(f"clickhouse-{suffix}-{i:02d}")
+                cluster_config_file_path = os.path.join(tmp_dir, "cluster.xml")
+                with open(cluster_config_file_path, "w", encoding="utf-8") as f:
+                    f.write(node_config)
+                custom_function_file_path = os.path.join(tmp_dir, "custom-function.xml")
+                with open(custom_function_file_path, "w", encoding="utf-8") as f:
+                    f.write(CUSTOM_FUNCTION_CONFIG)
+                users_config_file_path = os.path.join(tmp_dir, "users.xml")
+                with open(users_config_file_path, "w", encoding="utf-8") as f:
+                    f.write(CLUSTER_USERS_CONFIG)
+
+                container = ClickHouseContainer(
+                    image=f"clickhouse/clickhouse-server:{clickhouse_version}",
+                    port=9000,
+                    username=CLICKHOUSE_USERNAME,
+                    password=CLICKHOUSE_PASSWORD,
+                )
+                container.with_volume_mapping(cluster_config_file_path, "/etc/clickhouse-server/config.d/cluster.xml")
+                container.with_volume_mapping(custom_function_file_path, "/etc/clickhouse-server/custom-function.xml")
+                container.with_volume_mapping(users_config_file_path, "/etc/clickhouse-server/users.d/integration-cluster.xml")
+                container.with_network(network)
+                container.with_network_aliases(alias)
+                container.start()
+                started.append(container)
+
+                install_histogram_quantile(container)
+
+                nodes.append(
+                    types.TestContainerDocker(
+                        id=container.get_wrapped_container().id,
+                        host_configs={
+                            "9000": types.TestContainerUrlConfig(
+                                "tcp",
+                                container.get_container_host_ip(),
+                                container.get_exposed_port(9000),
+                            ),
+                            "8123": types.TestContainerUrlConfig(
+                                "tcp",
+                                container.get_container_host_ip(),
+                                container.get_exposed_port(8123),
+                            ),
+                        },
+                        container_configs={
+                            "9000": types.TestContainerUrlConfig("tcp", alias, 9000),
+                            "8123": types.TestContainerUrlConfig("tcp", alias, 8123),
+                        },
+                    )
+                )
+        except Exception:
+            for container in started:
+                container.stop()
+            raise
+
+        connection = clickhouse_connect.get_client(
+            user=CLICKHOUSE_USERNAME,
+            password=CLICKHOUSE_PASSWORD,
+            host=nodes[0].host_configs["8123"].address,
+            port=nodes[0].host_configs["8123"].port,
+        )
+
+        return types.TestContainerClickhouse(
+            container=nodes[0],
+            conn=connection,
+            env={
+                "SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN": f"tcp://{CLICKHOUSE_USERNAME}:{CLICKHOUSE_PASSWORD}@{aliases[0]}:{9000}",
+                "SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_USERNAME": CLICKHOUSE_USERNAME,
+                "SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_PASSWORD": CLICKHOUSE_PASSWORD,
+                "SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_CLUSTER": "cluster",
+            },
+            nodes=nodes,
+        )
+
+    def delete(resource: types.TestContainerClickhouse) -> None:
+        client = docker.from_env()
+        for node in resource.nodes or [resource.container]:
+            try:
+                client.containers.get(container_id=node.id).stop()
+                client.containers.get(container_id=node.id).remove(v=True)
+            except docker.errors.NotFound:
+                logger.info(
+                    "Skipping removal of Clickhouse cluster node, node(%s) not found. Maybe it was manually removed?",
+                    {"id": node.id},
+                )
+
+    def restore(cache: dict) -> types.TestContainerClickhouse:
+        nodes = [types.TestContainerDocker.from_cache(node) for node in cache["nodes"]]
+        env = cache["env"]
+        host_config = nodes[0].host_configs["8123"]
+
+        conn = clickhouse_connect.get_client(
+            user=env["SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_USERNAME"],
+            password=env["SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_PASSWORD"],
+            host=host_config.address,
+            port=host_config.port,
+        )
+
+        return types.TestContainerClickhouse(
+            container=nodes[0],
+            conn=conn,
+            env=env,
+            nodes=nodes,
+        )
+
+    return reuse.wrap(
+        request,
+        pytestconfig,
+        cache_key,
+        empty=lambda: types.TestContainerClickhouse(
+            container=types.TestContainerDocker(id="", host_configs={}, container_configs={}),
+            conn=None,
+            env={},
+        ),
+        create=create,
+        delete=delete,
+        restore=restore,
+    )
+
+
 @pytest.fixture(name="check_query_log")
 def check_query_log(
     signoz: types.SigNoz,

tests/fixtures/http.py

@@ -18,19 +18,22 @@ from fixtures.logger import setup_logger
 logger = setup_logger(__name__)
 
 
-@pytest.fixture(name="zeus", scope="package")
-def zeus(
+ZEUS_NETWORK_ALIAS = "signoz-zeus-it"
+
+
+def create_zeus(
     network: Network,
     request: pytest.FixtureRequest,
     pytestconfig: pytest.Config,
+    cache_key: str = "zeus",
+    alias: str | None = None,
 ) -> types.TestContainerDocker:
-    """
-    Package-scoped fixture for running zeus
-    """
 
     def create() -> types.TestContainerDocker:
         container = WireMockContainer(image="wiremock/wiremock:2.35.1-1", secure=False)
         container.with_network(network)
+        if alias:
+            container.with_network_aliases(alias)
         container.start()
 
         return types.TestContainerDocker(
@@ -42,7 +45,7 @@ def zeus(
                     container.get_exposed_port(8080),
                 )
             },
-            container_configs={"8080": types.TestContainerUrlConfig("http", container.get_wrapped_container().name, 8080)},
+            container_configs={"8080": types.TestContainerUrlConfig("http", alias or container.get_wrapped_container().name, 8080)},
         )
 
     def delete(container: types.TestContainerDocker):
@@ -62,7 +65,7 @@ def zeus(
     return reuse.wrap(
         request,
         pytestconfig,
-        "zeus",
+        cache_key,
         lambda: types.TestContainerDocker(id="", host_configs={}, container_configs={}),
         create,
         delete,
@@ -70,6 +73,18 @@ def zeus(
     )
 
 
+@pytest.fixture(name="zeus", scope="package")
+def zeus(
+    network: Network,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerDocker:
+    """
+    Package-scoped fixture for running zeus
+    """
+    return create_zeus(network=network, request=request, pytestconfig=pytestconfig)
+
+
 @pytest.fixture(name="gateway", scope="package")
 def gateway(
     network: Network,

tests/fixtures/metricreduction.py

@@ -0,0 +1,51 @@
+import datetime
+from collections.abc import Sequence
+
+from fixtures.metrics import MetricsBufferSample, MetricsBufferTimeSeries
+
+
+def build_ruled_gauge_buffer(
+    metric_name: str,
+    base_epoch: int,
+    services: Sequence[str],
+    pods_per_service: int,
+    minutes: int,
+    value: float = 1.0,
+) -> tuple[list[MetricsBufferTimeSeries], list[MetricsBufferSample]]:
+    """Collector-shaped buffer rows for a gauge under a reduction rule that
+    keeps `service`: per raw series a raw series row (is_reduced=false, full
+    labels, reduced_fingerprint -> group) plus the group's reduced series row
+    (is_reduced=true, kept labels), and one raw sample per series per minute
+    carrying both fingerprints. Returns (time_series, samples) for
+    insert_buffer_metrics."""
+    reduced_series = {
+        service: MetricsBufferTimeSeries(
+            metric_name=metric_name,
+            labels={"service": service},
+            timestamp=datetime.datetime.fromtimestamp(base_epoch, tz=datetime.UTC),
+            is_reduced=True,
+        )
+        for service in services
+    }
+    raw_series = [
+        MetricsBufferTimeSeries(
+            metric_name=metric_name,
+            labels={"service": service, "pod": f"pod-{service}-{i}"},
+            timestamp=datetime.datetime.fromtimestamp(base_epoch, tz=datetime.UTC),
+            reduced_fingerprint=reduced_series[service].fingerprint,
+        )
+        for service in services
+        for i in range(pods_per_service)
+    ]
+    samples = [
+        MetricsBufferSample(
+            metric_name=metric_name,
+            fingerprint=ts.fingerprint,
+            timestamp=datetime.datetime.fromtimestamp(base_epoch + minute * 60, tz=datetime.UTC),
+            value=value,
+            reduced_fingerprint=ts.reduced_fingerprint,
+        )
+        for ts in raw_series
+        for minute in range(minutes)
+    ]
+    return raw_series + list(reduced_series.values()), samples

tests/fixtures/metrics.py

@@ -11,6 +11,14 @@ import pytest
 from fixtures import types
 from fixtures.time import parse_timestamp
 
+_REDUCED_METRICS_TABLES_TO_TRUNCATE = [
+    "time_series_v4_reduced",
+    "samples_v4_reduced_last_60s",
+    "samples_v4_reduced_sum_60s",
+    "time_series_v4_buffer",
+    "samples_v4_buffer",
+]
+
 
 class MetricsTimeSeries(ABC):
     """Represents a row in the time_series_v4 table."""
@@ -414,6 +422,267 @@ class Metrics(ABC):
         return metrics
 
 
+class MetricsReducedTimeSeries(ABC):
+    """Represents a row in the time_series_v4_reduced table i.e what
+    the time_series_v4_reduced_mv materializes for a metric under a
+    reduction rule. One row per kept-label group. `fingerprint` holds the
+    reduced fingerprint and `labels` contains only the kept labels.
+
+    The fingerprint recipe (md5, like MetricsTimeSeries) does not match the
+    collector's real hash; it only needs to be consistent with the
+    reduced_fingerprint used in the reduced samples rows.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        metric_name: str,
+        kept_labels: dict[str, str],
+        timestamp: datetime.datetime,
+        temporality: str = "Unspecified",
+        description: str = "",
+        unit: str = "",
+        type_: str = "Gauge",
+        is_monotonic: bool = False,
+        env: str = "default",
+    ) -> None:
+        kept_labels = dict(kept_labels)
+        kept_labels["__name__"] = metric_name
+        self.env = env
+        # mirror time_series_v4_reduced_mv: monotonic cumulative counters are
+        # reduced as deltas
+        if temporality == "Cumulative" and is_monotonic:
+            temporality = "Delta"
+        self.temporality = temporality
+        self.metric_name = metric_name
+        self.description = description
+        self.unit = unit
+        self.type = type_
+        self.is_monotonic = is_monotonic
+        self.labels = json.dumps(kept_labels, separators=(",", ":"))
+        self.attrs = kept_labels
+        self.unix_milli = np.int64(int(timestamp.timestamp() * 1e3))
+        self.normalized = False
+
+        fingerprint_str = metric_name + self.labels
+        self.fingerprint = np.uint64(int(hashlib.md5(fingerprint_str.encode()).hexdigest()[:16], 16))
+
+    def to_row(self) -> list:
+        return [
+            self.env,
+            self.temporality,
+            self.metric_name,
+            self.description,
+            self.unit,
+            self.type,
+            self.is_monotonic,
+            self.fingerprint,
+            self.unix_milli,
+            self.labels,
+            self.attrs,
+            {},
+            {},
+            self.normalized,
+        ]
+
+
+class MetricsReducedSampleLast60s(ABC):
+    """Represents a row in the samples_v4_reduced_last_60s table. One 60s
+    bucket per reduced group, as the samples_v4_reduced_last_60s_mv refresh
+    would emit it (gauges and non-monotonic cumulative sums)."""
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        metric_name: str,
+        reduced_fingerprint: np.uint64,
+        timestamp: datetime.datetime,
+        sum_last: float,
+        min_value: float,
+        max_value: float,
+        sum_values: float,
+        count_series: int,
+        count_samples: int,
+        temporality: str = "Unspecified",
+        env: str = "default",
+        computed_at: datetime.datetime | None = None,
+    ) -> None:
+        self.env = env
+        self.temporality = temporality
+        self.metric_name = metric_name
+        self.reduced_fingerprint = reduced_fingerprint
+        # buckets are 60s-aligned: intDiv(unix_milli, 60000) * 60000
+        self.unix_milli = np.int64((int(timestamp.timestamp() * 1e3) // 60000) * 60000)
+        self.sum_last = np.float64(sum_last)
+        self.min = np.float64(min_value)
+        self.max = np.float64(max_value)
+        self.sum_values = np.float64(sum_values)
+        self.count_series = np.uint64(count_series)
+        self.count_samples = np.uint64(count_samples)
+        # the refresh stamps now(); default to shortly after the bucket closes
+        if computed_at is None:
+            computed_at = datetime.datetime.fromtimestamp(int(self.unix_milli) / 1e3, tz=datetime.UTC) + datetime.timedelta(seconds=180)
+        self.computed_at = computed_at
+
+    def to_row(self) -> list:
+        return [
+            self.env,
+            self.temporality,
+            self.metric_name,
+            self.reduced_fingerprint,
+            self.unix_milli,
+            self.sum_last,
+            self.min,
+            self.max,
+            self.sum_values,
+            self.count_series,
+            self.count_samples,
+            self.computed_at,
+        ]
+
+
+class MetricsReducedSampleSum60s(ABC):
+    """Represents a row in the samples_v4_reduced_sum_60s table. One 60s
+    bucket per reduced group for delta counters and histograms."""
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        metric_name: str,
+        reduced_fingerprint: np.uint64,
+        timestamp: datetime.datetime,
+        sum_value: float,
+        count_series: int,
+        count_samples: int,
+        temporality: str = "Delta",
+        env: str = "default",
+        computed_at: datetime.datetime | None = None,
+    ) -> None:
+        self.env = env
+        self.temporality = temporality
+        self.metric_name = metric_name
+        self.reduced_fingerprint = reduced_fingerprint
+        self.unix_milli = np.int64((int(timestamp.timestamp() * 1e3) // 60000) * 60000)
+        self.sum = np.float64(sum_value)
+        self.count_series = np.uint64(count_series)
+        self.count_samples = np.uint64(count_samples)
+        if computed_at is None:
+            computed_at = datetime.datetime.fromtimestamp(int(self.unix_milli) / 1e3, tz=datetime.UTC) + datetime.timedelta(seconds=180)
+        self.computed_at = computed_at
+
+    def to_row(self) -> list:
+        return [
+            self.env,
+            self.temporality,
+            self.metric_name,
+            self.reduced_fingerprint,
+            self.unix_milli,
+            self.sum,
+            self.count_series,
+            self.count_samples,
+            self.computed_at,
+        ]
+
+
+class MetricsBufferTimeSeries(ABC):
+    """Represents a row in the time_series_v4_buffer table. This is the collector's
+    universal landing target under cardinality control. For a ruled metric the
+    collector writes two rows per series: the raw one (is_reduced=false, full
+    labels, reduced_fingerprint pointing at its group) and the group's reduced
+    one (is_reduced=true, kept labels, fingerprint = reduced fingerprint)."""
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        metric_name: str,
+        labels: dict[str, str],
+        timestamp: datetime.datetime,
+        reduced_fingerprint: np.uint64 | int = 0,
+        is_reduced: bool = False,
+        temporality: str = "Unspecified",
+        description: str = "",
+        unit: str = "",
+        type_: str = "Gauge",
+        is_monotonic: bool = False,
+        env: str = "default",
+    ) -> None:
+        labels = dict(labels)
+        labels["__name__"] = metric_name
+        self.env = env
+        self.temporality = temporality
+        self.metric_name = metric_name
+        self.description = description
+        self.unit = unit
+        self.type = type_
+        self.is_monotonic = is_monotonic
+        self.reduced_fingerprint = np.uint64(reduced_fingerprint)
+        self.is_reduced = is_reduced
+        self.labels = json.dumps(labels, separators=(",", ":"))
+        self.attrs = labels
+        self.unix_milli = np.int64(int(timestamp.timestamp() * 1e3))
+        self.normalized = False
+
+        fingerprint_str = metric_name + self.labels
+        self.fingerprint = np.uint64(int(hashlib.md5(fingerprint_str.encode()).hexdigest()[:16], 16))
+
+    def to_row(self) -> list:
+        return [
+            self.env,
+            self.temporality,
+            self.metric_name,
+            self.description,
+            self.unit,
+            self.type,
+            self.is_monotonic,
+            self.fingerprint,
+            self.reduced_fingerprint,
+            self.is_reduced,
+            self.unix_milli,
+            self.labels,
+            self.attrs,
+            {},
+            {},
+            self.normalized,
+        ]
+
+
+class MetricsBufferSample(ABC):
+    """Represents a row in the samples_v4_buffer table. Ruled samples carry
+    the raw fingerprint plus the group's reduced_fingerprint; unruled samples
+    have reduced_fingerprint = 0."""
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        metric_name: str,
+        fingerprint: np.uint64,
+        timestamp: datetime.datetime,
+        value: float,
+        reduced_fingerprint: np.uint64 | int = 0,
+        is_monotonic: bool = False,
+        temporality: str = "Unspecified",
+        env: str = "default",
+        flags: int = 0,
+    ) -> None:
+        self.env = env
+        self.temporality = temporality
+        self.metric_name = metric_name
+        self.fingerprint = fingerprint
+        self.reduced_fingerprint = np.uint64(reduced_fingerprint)
+        self.is_monotonic = is_monotonic
+        self.unix_milli = np.int64(int(timestamp.timestamp() * 1e3))
+        self.value = np.float64(value)
+        self.flags = np.uint32(flags)
+
+    def to_row(self) -> list:
+        return [
+            self.env,
+            self.temporality,
+            self.metric_name,
+            self.fingerprint,
+            self.reduced_fingerprint,
+            self.is_monotonic,
+            self.unix_milli,
+            self.value,
+            self.flags,
+        ]
+
+
 def insert_metrics_to_clickhouse(conn, metrics: list[Metrics]) -> None:
     """
     Insert metrics into ClickHouse tables.
@@ -576,6 +845,163 @@ def insert_metrics(
     )
 
 
+def insert_reduced_metrics_to_clickhouse(
+    conn,
+    time_series: list[MetricsReducedTimeSeries],
+    last_samples: list[MetricsReducedSampleLast60s] | None = None,
+    sum_samples: list[MetricsReducedSampleSum60s] | None = None,
+) -> None:
+    """Insert reduced series into distributed_time_series_v4_reduced and 60s
+    buckets into the reduced samples tables. These tables exist only when
+    the schema migrator version includes the metrics cardinality-control
+    migration."""
+    if time_series:
+        conn.insert(
+            database="signoz_metrics",
+            table="distributed_time_series_v4_reduced",
+            column_names=[
+                "env",
+                "temporality",
+                "metric_name",
+                "description",
+                "unit",
+                "type",
+                "is_monotonic",
+                "fingerprint",
+                "unix_milli",
+                "labels",
+                "attrs",
+                "scope_attrs",
+                "resource_attrs",
+                "__normalized",
+            ],
+            data=[ts.to_row() for ts in time_series],
+        )
+
+    if last_samples:
+        conn.insert(
+            database="signoz_metrics",
+            table="distributed_samples_v4_reduced_last_60s",
+            column_names=[
+                "env",
+                "temporality",
+                "metric_name",
+                "reduced_fingerprint",
+                "unix_milli",
+                "sum_last",
+                "min",
+                "max",
+                "sum_values",
+                "count_series",
+                "count_samples",
+                "computed_at",
+            ],
+            data=[sample.to_row() for sample in last_samples],
+        )
+
+    if sum_samples:
+        conn.insert(
+            database="signoz_metrics",
+            table="distributed_samples_v4_reduced_sum_60s",
+            column_names=[
+                "env",
+                "temporality",
+                "metric_name",
+                "reduced_fingerprint",
+                "unix_milli",
+                "sum",
+                "count_series",
+                "count_samples",
+                "computed_at",
+            ],
+            data=[sample.to_row() for sample in sum_samples],
+        )
+
+
+def insert_buffer_metrics_to_clickhouse(
+    conn,
+    time_series: list[MetricsBufferTimeSeries],
+    samples: list[MetricsBufferSample],
+) -> None:
+    if time_series:
+        conn.insert(
+            database="signoz_metrics",
+            table="distributed_time_series_v4_buffer",
+            column_names=[
+                "env",
+                "temporality",
+                "metric_name",
+                "description",
+                "unit",
+                "type",
+                "is_monotonic",
+                "fingerprint",
+                "reduced_fingerprint",
+                "is_reduced",
+                "unix_milli",
+                "labels",
+                "attrs",
+                "scope_attrs",
+                "resource_attrs",
+                "__normalized",
+            ],
+            data=[ts.to_row() for ts in time_series],
+        )
+
+    if samples:
+        conn.insert(
+            database="signoz_metrics",
+            table="distributed_samples_v4_buffer",
+            column_names=[
+                "env",
+                "temporality",
+                "metric_name",
+                "fingerprint",
+                "reduced_fingerprint",
+                "is_monotonic",
+                "unix_milli",
+                "value",
+                "flags",
+            ],
+            data=[sample.to_row() for sample in samples],
+        )
+
+
+@pytest.fixture(name="insert_reduced_metrics", scope="function")
+def insert_reduced_metrics(
+    clickhouse: types.TestContainerClickhouse,
+) -> Generator[Callable[..., None], Any]:
+    def _insert_reduced_metrics(
+        time_series: list[MetricsReducedTimeSeries],
+        last_samples: list[MetricsReducedSampleLast60s] | None = None,
+        sum_samples: list[MetricsReducedSampleSum60s] | None = None,
+    ) -> None:
+        insert_reduced_metrics_to_clickhouse(clickhouse.conn, time_series, last_samples, sum_samples)
+
+    yield _insert_reduced_metrics
+
+    cluster = clickhouse.env["SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_CLUSTER"]
+    for table in _REDUCED_METRICS_TABLES_TO_TRUNCATE:
+        clickhouse.conn.query(f"TRUNCATE TABLE signoz_metrics.{table} ON CLUSTER '{cluster}' SYNC")
+
+
+@pytest.fixture(name="insert_buffer_metrics", scope="function")
+def insert_buffer_metrics(
+    clickhouse: types.TestContainerClickhouse,
+) -> Generator[Callable[..., None], Any]:
+    def _insert_buffer_metrics(
+        time_series: list[MetricsBufferTimeSeries],
+        samples: list[MetricsBufferSample],
+    ) -> None:
+        insert_buffer_metrics_to_clickhouse(clickhouse.conn, time_series, samples)
+
+    yield _insert_buffer_metrics
+
+    cluster = clickhouse.env["SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_CLUSTER"]
+    for table in _REDUCED_METRICS_TABLES_TO_TRUNCATE:
+        clickhouse.conn.query(f"TRUNCATE TABLE signoz_metrics.{table} ON CLUSTER '{cluster}' SYNC")
+
+
 @pytest.fixture(name="remove_metrics_ttl_and_storage_settings", scope="function")
 def remove_metrics_ttl_and_storage_settings(signoz: types.SigNoz):
     """

tests/fixtures/migrator.py

@@ -8,27 +8,30 @@ from fixtures.logger import setup_logger
 logger = setup_logger(__name__)
 
 
-def create_migrator(
+def create_migrator(  # pylint: disable=too-many-arguments,too-many-positional-arguments
     network: Network,
     clickhouse: types.TestContainerClickhouse,
     request: pytest.FixtureRequest,
     pytestconfig: pytest.Config,
     cache_key: str = "migrator",
     env_overrides: dict | None = None,
+    version: str | None = None,
 ) -> types.Operation:
     """
     Factory function for running schema migrations.
-    Accepts optional env_overrides to customize the migrator environment.
+    Accepts optional env_overrides to customize the migrator environment, and
+    an optional version to pin a schema-migrator release different from the
+    --schema-migrator-version option.
     """
 
     def create() -> None:
-        version = request.config.getoption("--schema-migrator-version")
+        migrator_version = version or request.config.getoption("--schema-migrator-version")
         client = docker.from_env()
 
         environment = dict(env_overrides) if env_overrides else {}
 
         container = client.containers.run(
-            image=f"signoz/signoz-schema-migrator:{version}",
+            image=f"signoz/signoz-schema-migrator:{migrator_version}",
             command=f"sync --replication=true --cluster-name=cluster --up= --dsn={clickhouse.env['SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN']}",
             detach=True,
             auto_remove=False,
@@ -47,7 +50,7 @@ def create_migrator(
         container.remove()
 
         container = client.containers.run(
-            image=f"signoz/signoz-schema-migrator:{version}",
+            image=f"signoz/signoz-schema-migrator:{migrator_version}",
             command=f"async --replication=true --cluster-name=cluster --up= --dsn={clickhouse.env['SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN']}",
             detach=True,
             auto_remove=False,

tests/fixtures/querier.py

@@ -189,6 +189,35 @@ def make_query_request(
     )
 
 
+def aligned_epoch(ago: timedelta, step_seconds: int = DEFAULT_STEP_INTERVAL) -> int:
+    """Epoch seconds for `now - ago`, floored to a step boundary so seeded
+    points land exactly on the query's toStartOfInterval buckets."""
+    return (int((datetime.now(tz=UTC) - ago).timestamp()) // step_seconds) * step_seconds
+
+
+def query_metric_values(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    signoz: types.SigNoz,
+    token: str,
+    metric_name: str,
+    start_epoch: int,
+    end_epoch: int,
+    time_agg: str,
+    space_agg: str,
+    step_interval: int = DEFAULT_STEP_INTERVAL,
+) -> list[dict]:
+    """Run a single metrics builder query over [start_epoch, end_epoch) in
+    epoch seconds and return its series values sorted by timestamp."""
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms=start_epoch * 1000,
+        end_ms=end_epoch * 1000,
+        queries=[build_builder_query("A", metric_name, time_agg, space_agg, step_interval=step_interval)],
+    )
+    assert response.status_code == HTTPStatus.OK, response.text
+    return sorted(get_series_values(response.json(), "A"), key=lambda v: v["timestamp"])
+
+
 def build_builder_query(
     name: str,
     metric_name: str,

tests/fixtures/types.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Literal
 from urllib.parse import urljoin
 
@@ -84,11 +84,16 @@ class TestContainerClickhouse:
     container: TestContainerDocker
     conn: clickhouse_connect.driver.client.Client
     env: dict[str, str]
+    # Per-node containers when running a multi-node cluster. Empty for the
+    # default single-node setup; nodes[0] is the node `conn`/`env` point at
+    # (the initiator every query goes through).
+    nodes: list[TestContainerDocker] = field(default_factory=list)
 
     def __cache__(self) -> dict:
         return {
             "container": self.container.__cache__(),
             "env": self.env,
+            "nodes": [node.__cache__() for node in self.nodes],
         }
 
     def __log__(self) -> str:

tests/integration/tests/clickhousecluster/01_basic_cluster.py

@@ -0,0 +1,52 @@
+import clickhouse_connect.driver.client
+
+from fixtures import types
+
+TOTAL_ROWS = 64
+
+
+def test_topology(
+    clickhouse: types.TestContainerClickhouse,
+    clickhouse_node_conns: list[clickhouse_connect.driver.client.Client],
+) -> None:
+    aliases = {node.container_configs["9000"].address for node in clickhouse.nodes}
+
+    # Every node sees the same 2-shard cluster definition and identifies
+    # exactly itself as the local replica
+
+    for i, conn in enumerate(clickhouse_node_conns, start=1):
+        rows = conn.query("SELECT shard_num, host_name, is_local FROM system.clusters WHERE cluster = 'cluster' ORDER BY shard_num").result_rows
+        assert [row[0] for row in rows] == [1, 2], f"node {i}: expected 2 shards, got {rows}"
+        assert {row[1] for row in rows} == aliases, f"node {i}: cluster hosts {rows} != node aliases {aliases}"
+        local = [row[0] for row in rows if row[2]]
+        assert local == [i], f"node {i}: expected to be local for shard {i} only, got {local}"
+
+
+def test_replicated_distributed_round_trip(
+    clickhouse: types.TestContainerClickhouse,
+    clickhouse_node_conns: list[clickhouse_connect.driver.client.Client],
+) -> None:
+    # ON CLUSTER DDL reaches both nodes, Replicated engines register with the
+    # keeper via per-node macros, and a sharded Distributed insert scatters rows
+    # across shards while the distributed read returns the union.
+    conn = clickhouse.conn
+    try:
+        conn.query("CREATE DATABASE IF NOT EXISTS it_cluster ON CLUSTER 'cluster'")
+        conn.query("CREATE TABLE it_cluster.events ON CLUSTER 'cluster' (id UInt64, payload String) ENGINE = ReplicatedMergeTree ORDER BY id")
+        conn.query("CREATE TABLE it_cluster.distributed_events ON CLUSTER 'cluster' AS it_cluster.events ENGINE = Distributed('cluster', 'it_cluster', 'events', cityHash64(id))")
+
+        conn.insert(
+            database="it_cluster",
+            table="distributed_events",
+            column_names=["id", "payload"],
+            data=[[i, f"payload-{i:03d}"] for i in range(TOTAL_ROWS)],
+        )
+
+        distributed_count = int(conn.query("SELECT count() FROM it_cluster.distributed_events").result_rows[0][0])
+        assert distributed_count == TOTAL_ROWS
+
+        local_counts = [int(node_conn.query("SELECT count() FROM it_cluster.events").result_rows[0][0]) for node_conn in clickhouse_node_conns]
+        assert sum(local_counts) == TOTAL_ROWS, f"local counts {local_counts} do not add up to {TOTAL_ROWS}"
+        assert min(local_counts) > 0, f"all rows landed on one shard: {local_counts}"
+    finally:
+        conn.query("DROP DATABASE IF EXISTS it_cluster ON CLUSTER 'cluster' SYNC")

tests/integration/tests/clickhousecluster/conftest.py

@@ -0,0 +1,47 @@
+from collections.abc import Generator
+from typing import Any
+
+import pytest
+from testcontainers.core.container import Network
+
+from fixtures import types
+from fixtures.clickhouse import create_clickhouse_cluster, create_clickhouse_keeper
+
+CLICKHOUSE_VERSION = "25.12.5"
+
+
+@pytest.fixture(name="keeper", scope="package")
+def keeper_cluster(
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerDocker:
+    return create_clickhouse_keeper(
+        tmpfs=tmpfs,
+        network=network,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="keeper_cluster",
+        version=CLICKHOUSE_VERSION,
+    )
+
+
+@pytest.fixture(name="clickhouse", scope="package")
+def clickhouse_cluster(
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    keeper: types.TestContainerDocker,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerClickhouse:
+    return create_clickhouse_cluster(
+        tmpfs=tmpfs,
+        network=network,
+        keeper=keeper,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="clickhouse_cluster",
+        shards=2,
+        version=CLICKHOUSE_VERSION,
+    )

tests/integration/tests/metricreduction/01_reduced_gauge.py

@@ -0,0 +1,203 @@
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+
+import clickhouse_connect.driver.client
+import pytest
+
+from fixtures import types
+from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.clickhouse import assert_spans_shards
+from fixtures.metrics import (
+    Metrics,
+    MetricsReducedSampleLast60s,
+    MetricsReducedTimeSeries,
+)
+from fixtures.querier import aligned_epoch, query_metric_values
+
+
+def test_stitch_across_epoch(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_metrics: Callable[[list[Metrics]], None],
+    insert_reduced_metrics: Callable[..., None],
+    clickhouse_node_conns: list[clickhouse_connect.driver.client.Client],
+) -> None:
+    """Before the rule activates, samples live in the raw tables; after, only
+    the reduced 60s tables have data. One query spanning the boundary must
+    stitch the two branches into a continuous series with no gap and no double
+    counting: 32 raw series at 2.0 collapse into 16 groups whose sum_last is
+    4.0, so the summed value stays 320 per step across the epoch. Enough
+    series to guarantee both shards hold data (guarded below), so the totals
+    also prove the raw and reduced joins execute shard-local."""
+    metric_name = "test_reduction_stitch"
+    base_epoch = aligned_epoch(timedelta(hours=30), step_seconds=300)
+    services = [f"svc-{i:02d}" for i in range(16)]
+
+    # first 30 minutes: raw samples (2 pods per service, one sample per minute)
+    insert_metrics(
+        [
+            Metrics(
+                metric_name=metric_name,
+                labels={"service": service, "pod": f"{service}-pod-{pod}"},
+                timestamp=datetime.fromtimestamp(base_epoch + minute * 60, tz=UTC),
+                value=2.0,
+                type_="Gauge",
+                is_monotonic=False,
+            )
+            for service in services
+            for pod in range(2)
+            for minute in range(30)
+        ]
+    )
+
+    # next 30 minutes: reduced 60s buckets (one group per service)
+    time_series = [
+        MetricsReducedTimeSeries(
+            metric_name=metric_name,
+            kept_labels={"service": service},
+            timestamp=datetime.fromtimestamp(base_epoch + 30 * 60, tz=UTC),
+        )
+        for service in services
+    ]
+    insert_reduced_metrics(
+        time_series,
+        [
+            MetricsReducedSampleLast60s(
+                metric_name=metric_name,
+                reduced_fingerprint=ts.fingerprint,
+                timestamp=datetime.fromtimestamp(base_epoch + (30 + minute) * 60, tz=UTC),
+                sum_last=4.0,
+                min_value=2.0,
+                max_value=2.0,
+                sum_values=4.0,
+                count_series=2,
+                count_samples=2,
+            )
+            for ts in time_series
+            for minute in range(30)
+        ],
+    )
+
+    assert_spans_shards(clickhouse_node_conns, "time_series_v4", metric_name, total=len(services) * 2)
+    assert_spans_shards(clickhouse_node_conns, "time_series_v4_reduced", metric_name, total=len(services))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    values = query_metric_values(signoz, token, metric_name, base_epoch, base_epoch + 3600, "sum", "sum", step_interval=300)
+
+    assert [v["timestamp"] for v in values] == [(base_epoch + step * 300) * 1000 for step in range(12)]
+    assert [v["value"] for v in values] == [320.0] * 12
+
+
+@pytest.mark.parametrize(
+    "space_agg, expected",
+    [
+        ("sum", 12.0),  # sum_last: 4 + 8
+        ("avg", 3.0),  # sum(sum_last) / sum(count_series): 12 / 4
+        ("min", 1.0),  # min(min)
+        ("max", 6.0),  # max(max)
+    ],
+)
+def test_space_aggregations(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_reduced_metrics: Callable[..., None],
+    space_agg: str,
+    expected: float,
+) -> None:
+    """Space aggregations read the reduced pre-aggregated columns: sum/avg
+    from sum_last with the count_series weight, min/max from the min/max
+    columns."""
+    metric_name = f"test_reduction_space_{space_agg}"
+    base_epoch = aligned_epoch(timedelta(hours=30), step_seconds=300)
+
+    groups = [
+        # (service, sum_last, min, max, count_series)
+        ("a", 4.0, 1.0, 3.0, 2),
+        ("b", 8.0, 2.0, 6.0, 2),
+    ]
+    time_series = {
+        service: MetricsReducedTimeSeries(
+            metric_name=metric_name,
+            kept_labels={"service": service},
+            timestamp=datetime.fromtimestamp(base_epoch, tz=UTC),
+        )
+        for service, _, _, _, _ in groups
+    }
+    insert_reduced_metrics(
+        list(time_series.values()),
+        [
+            MetricsReducedSampleLast60s(
+                metric_name=metric_name,
+                reduced_fingerprint=time_series[service].fingerprint,
+                timestamp=datetime.fromtimestamp(base_epoch + minute * 60, tz=UTC),
+                sum_last=sum_last,
+                min_value=min_value,
+                max_value=max_value,
+                sum_values=sum_last,
+                count_series=count_series,
+                count_samples=count_series,
+            )
+            for service, sum_last, min_value, max_value, count_series in groups
+            for minute in range(20)
+        ],
+    )
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    values = query_metric_values(signoz, token, metric_name, base_epoch, base_epoch + 20 * 60, "avg", space_agg, step_interval=300)
+
+    assert [v["timestamp"] for v in values] == [(base_epoch + step * 300) * 1000 for step in range(4)]
+    assert [v["value"] for v in values] == [expected] * 4
+
+
+def test_dedup_latest_computed_at_wins(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_reduced_metrics: Callable[..., None],
+) -> None:
+    """The refreshable MVs re-emit every bucket on each refresh with a newer
+    computed_at (APPEND mode); reads must dedup to the latest version per
+    (series, bucket). Recompute the same buckets with a newer computed_at and
+    a different value: only the newer value may be counted."""
+    metric_name = "test_reduction_dedup"
+    base_epoch = aligned_epoch(timedelta(hours=30), step_seconds=300)
+
+    time_series = [
+        MetricsReducedTimeSeries(
+            metric_name=metric_name,
+            kept_labels={"service": service},
+            timestamp=datetime.fromtimestamp(base_epoch, tz=UTC),
+        )
+        for service in ("a", "b")
+    ]
+
+    def buckets(sum_last: float, computed_at_offset_seconds: int) -> list[MetricsReducedSampleLast60s]:
+        return [
+            MetricsReducedSampleLast60s(
+                metric_name=metric_name,
+                reduced_fingerprint=ts.fingerprint,
+                timestamp=datetime.fromtimestamp(base_epoch + minute * 60, tz=UTC),
+                sum_last=sum_last,
+                min_value=sum_last,
+                max_value=sum_last,
+                sum_values=sum_last,
+                count_series=1,
+                count_samples=1,
+                computed_at=datetime.fromtimestamp(base_epoch + minute * 60 + computed_at_offset_seconds, tz=UTC),
+            )
+            for ts in time_series
+            for minute in range(10)
+        ]
+
+    # first refresh emits 1.0; a later refresh recomputes the same buckets to 5.0
+    insert_reduced_metrics(time_series, buckets(sum_last=1.0, computed_at_offset_seconds=120))
+    insert_reduced_metrics(time_series, buckets(sum_last=5.0, computed_at_offset_seconds=180))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    values = query_metric_values(signoz, token, metric_name, base_epoch, base_epoch + 10 * 60, "sum", "sum", step_interval=300)
+
+    # 2 groups x 5 buckets x 5.0 per step; 1.0 rows must not contribute
+    assert [v["timestamp"] for v in values] == [(base_epoch + step * 300) * 1000 for step in range(2)]
+    assert [v["value"] for v in values] == [50.0] * 2

tests/integration/tests/metricreduction/02_reduced_counter.py

@@ -0,0 +1,70 @@
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from fixtures import types
+from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.metrics import (
+    MetricsReducedSampleSum60s,
+    MetricsReducedTimeSeries,
+)
+from fixtures.querier import aligned_epoch, query_metric_values
+
+
+@pytest.mark.parametrize(
+    "time_agg, expected",
+    [
+        # 2 groups x 5 buckets x 30.0 per 300s step
+        ("rate", 1.0),  # 300 / 300s
+        ("increase", 300.0),
+    ],
+)
+def test_counter_rate_and_increase(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_reduced_metrics: Callable[..., None],
+    time_agg: str,
+    expected: float,
+) -> None:
+    metric_name = f"test_reduction_counter_{time_agg}"
+    base_epoch = aligned_epoch(timedelta(hours=30), step_seconds=300)
+
+    # monotonic cumulative counter: MetricsReducedTimeSeries mirrors the
+    # collector's temporality rewrite to Delta
+    time_series = [
+        MetricsReducedTimeSeries(
+            metric_name=metric_name,
+            kept_labels={"service": service},
+            timestamp=datetime.fromtimestamp(base_epoch, tz=UTC),
+            temporality="Cumulative",
+            type_="Sum",
+            is_monotonic=True,
+        )
+        for service in ("a", "b")
+    ]
+    assert all(ts.temporality == "Delta" for ts in time_series)
+
+    insert_reduced_metrics(
+        time_series,
+        sum_samples=[
+            MetricsReducedSampleSum60s(
+                metric_name=metric_name,
+                reduced_fingerprint=ts.fingerprint,
+                timestamp=datetime.fromtimestamp(base_epoch + minute * 60, tz=UTC),
+                sum_value=30.0,
+                count_series=2,
+                count_samples=2,
+                temporality="Delta",
+            )
+            for ts in time_series
+            for minute in range(20)
+        ],
+    )
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    values = query_metric_values(signoz, token, metric_name, base_epoch, base_epoch + 20 * 60, time_agg, "sum", step_interval=300)
+
+    assert [v["timestamp"] for v in values] == [(base_epoch + step * 300) * 1000 for step in range(4)]
+    assert [v["value"] for v in values] == [expected] * 4

tests/integration/tests/metricreduction/03_reduced_buffer_window.py

@@ -0,0 +1,70 @@
+from collections.abc import Callable
+from datetime import timedelta
+from http import HTTPStatus
+
+from fixtures import types
+from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.metricreduction import build_ruled_gauge_buffer
+from fixtures.querier import (
+    aligned_epoch,
+    build_builder_query,
+    get_all_series,
+    index_series_by_label,
+    make_query_request,
+    query_metric_values,
+)
+
+SERVICES = ("a", "b")
+PODS_PER_SERVICE = 2
+MINUTES = 20
+
+
+def test_recent_window_reads_buffer_totals(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_buffer_metrics: Callable[..., None],
+) -> None:
+    metric_name = "test_reduction_buffer_totals"
+    # samples span [now-25m, now-5m); the query window sits inside the last 24h
+    base_epoch = aligned_epoch(timedelta(minutes=25), step_seconds=300)
+    insert_buffer_metrics(*build_ruled_gauge_buffer(metric_name, base_epoch, SERVICES, PODS_PER_SERVICE, MINUTES))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    values = query_metric_values(signoz, token, metric_name, base_epoch, base_epoch + MINUTES * 60, "sum", "sum", step_interval=300)
+
+    # 4 raw series x 5 samples x 1.0 per step: full raw resolution, and the
+    # is_reduced=true series rows must not join in (their fingerprints match
+    # no samples, and the ts CTE filters them out)
+    assert [v["timestamp"] for v in values] == [(base_epoch + step * 300) * 1000 for step in range(4)]
+    assert [v["value"] for v in values] == [float(len(SERVICES) * PODS_PER_SERVICE * 5)] * 4
+
+
+def test_recent_window_group_by_raw_label(
+    signoz: types.SigNoz,
+    create_user_admin: None,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_buffer_metrics: Callable[..., None],
+) -> None:
+    """Group-by resolves against the raw buffer series rows (full labels), so
+    grouping by the kept label still sees every raw series underneath."""
+    metric_name = "test_reduction_buffer_groupby"
+    base_epoch = aligned_epoch(timedelta(minutes=25), step_seconds=300)
+    insert_buffer_metrics(*build_ruled_gauge_buffer(metric_name, base_epoch, SERVICES, PODS_PER_SERVICE, MINUTES))
+
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    response = make_query_request(
+        signoz,
+        token,
+        start_ms=base_epoch * 1000,
+        end_ms=(base_epoch + MINUTES * 60) * 1000,
+        queries=[build_builder_query("A", metric_name, "sum", "sum", step_interval=300, group_by=["service"])],
+    )
+    assert response.status_code == HTTPStatus.OK, response.text
+
+    series_by_service = index_series_by_label(get_all_series(response.json(), "A"), "service")
+    assert set(series_by_service.keys()) == set(SERVICES)
+    for service in SERVICES:
+        values = sorted(series_by_service[service]["values"], key=lambda v: v["timestamp"])
+        # 2 pods x 5 samples x 1.0 per step
+        assert [v["value"] for v in values] == [float(PODS_PER_SERVICE * 5)] * 4

tests/integration/tests/metricreduction/conftest.py

@@ -0,0 +1,114 @@
+from collections.abc import Generator
+from typing import Any
+
+import pytest
+from testcontainers.core.container import Network
+
+from fixtures import types
+from fixtures.auth import register_admin
+from fixtures.clickhouse import create_clickhouse_cluster, create_clickhouse_keeper
+from fixtures.http import ZEUS_NETWORK_ALIAS, create_zeus
+from fixtures.migrator import create_migrator
+from fixtures.signoz import create_signoz
+
+SCHEMA_MIGRATOR_VERSION = "v0.144.6-rc.2"
+CLICKHOUSE_VERSION = "25.12.5"
+
+
+@pytest.fixture(name="keeper", scope="package")
+def keeper_metricreduction(
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerDocker:
+    return create_clickhouse_keeper(
+        tmpfs=tmpfs,
+        network=network,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="keeper_metricreduction",
+        version=CLICKHOUSE_VERSION,
+    )
+
+
+@pytest.fixture(name="zeus", scope="package")
+def zeus_metricreduction(
+    network: Network,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerDocker:
+    return create_zeus(
+        network=network,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="zeus_metricreduction",
+        alias=ZEUS_NETWORK_ALIAS,
+    )
+
+
+@pytest.fixture(name="clickhouse", scope="package")
+def clickhouse_metricreduction(
+    tmpfs: Generator[types.LegacyPath, Any],
+    network: Network,
+    keeper: types.TestContainerDocker,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.TestContainerClickhouse:
+    return create_clickhouse_cluster(
+        tmpfs=tmpfs,
+        network=network,
+        keeper=keeper,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="clickhouse_metricreduction",
+        shards=2,
+        version=CLICKHOUSE_VERSION,
+    )
+
+
+@pytest.fixture(name="migrator", scope="package")
+def migrator_metricreduction(
+    network: Network,
+    clickhouse: types.TestContainerClickhouse,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.Operation:
+    return create_migrator(
+        network=network,
+        clickhouse=clickhouse,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="migrator_metricreduction",
+        version=SCHEMA_MIGRATOR_VERSION,
+    )
+
+
+@pytest.fixture(name="signoz", scope="package")
+def signoz_metricreduction(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    network: Network,
+    zeus: types.TestContainerDocker,
+    gateway: types.TestContainerDocker,
+    sqlstore: types.TestContainerSQL,
+    clickhouse: types.TestContainerClickhouse,
+    request: pytest.FixtureRequest,
+    pytestconfig: pytest.Config,
+) -> types.SigNoz:
+    return create_signoz(
+        network=network,
+        zeus=zeus,
+        gateway=gateway,
+        sqlstore=sqlstore,
+        clickhouse=clickhouse,
+        request=request,
+        pytestconfig=pytestconfig,
+        cache_key="signoz_metricreduction",
+        env_overrides={
+            "SIGNOZ_FLAGGER_CONFIG_BOOLEAN_ENABLE__METRICS__REDUCTION": True,
+        },
+    )
+
+
+@pytest.fixture(name="create_user_admin", scope="package")
+def create_user_admin_metricreduction(signoz: types.SigNoz, request: pytest.FixtureRequest, pytestconfig: pytest.Config) -> types.Operation:
+    return register_admin(signoz, request, pytestconfig, cache_key="create_user_admin_metricreduction")