fix: refactor integration tests

* feat(authz): expose telemetry resources in generated frontend permissions

* feat(authz): add support for telemetry resources on roles page (#12296)

* feat(create-edit-role): add support for telemetry resource

* test(create-edit-role): add tests for telemetry resource

* fix(pr): address comments

* fix(authz): app routing and sidebar fixes when no built-in role (#12307)

* fix(sidebar): render fallback when user preferences fails on sidenav

Otherwise, it fails and don't show any menu that can be pinned

* feat(app-routing): bypass unauthorized when authz is enabled

Those pages should render to allow us to handle authz
directly in each page/component

* fix(private): drop feature flag gate

* fix(authz): backfill managed role transaction groups for meter metrics

* feat(authz): resolve conflicts

* refactor(telemetry-selector): couple fixes after feedback on ux/ui (#12316)

* fix(pr): address more ux feedback

---------

Co-authored-by: Vinicius Lourenço <12551007+H4ad@users.noreply.github.com>
Co-authored-by: Vinícius Lourenço <vinicius@signoz.io>

.github/workflows/integrationci.yaml

@@ -53,6 +53,7 @@ jobs:
           - queriermetrics
           - querierscalar
           - queriercommon
+          - querierai
           - rawexportdata
           - promqlconformance
           - querierauthz

cmd/authz.go

@@ -93,9 +93,13 @@ func runGenerateAuthz(_ context.Context) error {
 	registry := coretypes.NewRegistry()
 
 	allowedResources := map[string]bool{
-		coretypes.NewResourceRef(coretypes.ResourceServiceAccount).String():           true,
-		coretypes.NewResourceRef(coretypes.ResourceRole).String():                     true,
-		coretypes.NewResourceRef(coretypes.ResourceMetaResourceFactorAPIKey).String(): true,
+		coretypes.NewResourceRef(coretypes.ResourceServiceAccount).String():                true,
+		coretypes.NewResourceRef(coretypes.ResourceRole).String():                          true,
+		coretypes.NewResourceRef(coretypes.ResourceMetaResourceFactorAPIKey).String():      true,
+		coretypes.NewResourceRef(coretypes.ResourceTelemetryResourceLogs).String():         true,
+		coretypes.NewResourceRef(coretypes.ResourceTelemetryResourceTraces).String():       true,
+		coretypes.NewResourceRef(coretypes.ResourceTelemetryResourceMetrics).String():      true,
+		coretypes.NewResourceRef(coretypes.ResourceTelemetryResourceMeterMetrics).String(): true,
 	}
 
 	allowedTypes := map[string]bool{}

docs/api/openapi.yml

@@ -6900,6 +6900,7 @@ components:
     Querybuildertypesv5QueryEnvelope:
       discriminator:
         mapping:
+          builder_ai_query: '#/components/schemas/Querybuildertypesv5QueryEnvelopeBuilderAI'
           builder_formula: '#/components/schemas/Querybuildertypesv5QueryEnvelopeFormula'
           builder_query: '#/components/schemas/Querybuildertypesv5QueryEnvelopeBuilder'
           builder_trace_operator: '#/components/schemas/Querybuildertypesv5QueryEnvelopeTraceOperator'
@@ -6908,6 +6909,7 @@ components:
         propertyName: type
       oneOf:
       - $ref: '#/components/schemas/Querybuildertypesv5QueryEnvelopeBuilder'
+      - $ref: '#/components/schemas/Querybuildertypesv5QueryEnvelopeBuilderAI'
       - $ref: '#/components/schemas/Querybuildertypesv5QueryEnvelopeFormula'
       - $ref: '#/components/schemas/Querybuildertypesv5QueryEnvelopeTraceOperator'
       - $ref: '#/components/schemas/Querybuildertypesv5QueryEnvelopePromQL'
@@ -6922,6 +6924,15 @@ components:
       required:
       - type
       type: object
+    Querybuildertypesv5QueryEnvelopeBuilderAI:
+      properties:
+        spec:
+          $ref: '#/components/schemas/Querybuildertypesv5QueryBuilderQueryGithubComSigNozSignozPkgTypesQuerybuildertypesQuerybuildertypesv5TraceAggregation'
+        type:
+          $ref: '#/components/schemas/Querybuildertypesv5QueryType'
+      required:
+      - type
+      type: object
     Querybuildertypesv5QueryEnvelopeClickHouseSQL:
       properties:
         spec:
@@ -7035,6 +7046,7 @@ components:
     Querybuildertypesv5QueryType:
       enum:
       - builder_query
+      - builder_ai_query
       - builder_formula
       - builder_trace_operator
       - clickhouse_sql

frontend/docs/authz-guide.md

@@ -0,0 +1,136 @@
+# AuthZ Guide
+
+How to structure a page so it works with the permission system.
+
+We are migrating from the `ADMIN | EDITOR | VIEWER` roles to per-action checks. Instead of granting `VIEWER` and
+exposing everything, a user can now be granted access to a single resource, eg: `Logs` only.
+
+- [Prerequisites](#prerequisites)
+- [Core rules](#core-rules)
+- [Page patterns](#page-patterns)
+- [What "blocked" means](#what-blocked-means)
+- [Migration checklist](#migration-checklist)
+- [Testing](#testing)
+
+## Prerequisites
+
+Check whether the resource your page represents is supported: see
+[permissions.type.ts](../src/lib/authz/hooks/useAuthZ/permissions.type.ts) for the current resources and their allowed
+verbs.
+
+**If the resource is not listed there, skip authz for now**. The backend does not enforce it yet, so any frontend
+check would be decorative. Revisit once the resource is generated into that file (it is auto-generated from the
+backend).
+
+## Core rules
+
+These hold for every page. The per-pattern sections below only add to them.
+
+1. **A page is always reachable, regardless of permission.** The intended action must be known before permission can
+   be checked, so the route renders first and individual pieces are gated.
+2. **`update` requires both `read` and `update`.** A user who can write but cannot read the current value must not get
+   an edit affordance.
+3. **`delete` is independent of `read`.** Delete controls stay visible for a user who holds `delete` but not `read`.
+4. **Never gate per row.** If a user can `list`, render every row. Check `read` only when the row is opened (drawer or
+   detail route).
+5. **Gate the narrowest thing that works**, a button over a section, a section over a page.
+6. **A resource may be gated while a sub-resource is not.** A user without `read` on Service Accounts can still hold
+   `create` on API Keys, so blocking the outer container would hide work they are allowed to do.
+7. **Verbs not covered here** (`attach`, `detach`, `assignee`) behave like `delete`: gate the control that triggers
+   them, not the surrounding content.
+
+## Page patterns
+
+### List page
+
+![Visual rules for structuring a list page](./assets/list-example.svg)
+
+Without `list`, but with any of `read` / `create` / `update`, only the table is blocked:
+
+- Title, description, search filters and action buttons stay visible.
+- Filters and any control that drives the table are non-interactive.
+- The create button stays enabled if the user holds `create`.
+
+### Edit page
+
+![Visual rules for structuring an edit page](./assets/edit-example.svg)
+
+Without `read`:
+
+- Block the content with `withAuthZContent`, not the whole route.
+- Keep delete visible (rule 3).
+- Keep update blocked (rule 2).
+
+### Drawer
+
+![Visual rules for structuring a drawer](./assets/drawer-example.svg)
+
+Without `read`:
+
+- Block the drawer body, not the drawer itself.
+- Prefer routing that carries the resource ID in the URL, so delete stays reachable without `read`.
+- Keep update blocked (rule 2).
+- Watch for sub-resources the user may still be allowed to act on (rule 6).
+
+### Create
+
+Without `create`:
+
+| Entry point           | Gate with                                                     |
+| --------------------- | ------------------------------------------------------------- |
+| Button                | `AuthZButton`                                                 |
+| Dedicated create page | `withAuthZPage`                                               |
+| Create drawer opened directly (deep link) | `withAuthZContent` on the body + `AuthZButton` on footer actions |
+
+### Delete
+
+Gate the control with `AuthZButton`, or `AuthZTooltip` for a non-button trigger such as an icon or menu item.
+
+### Quick filters
+
+![Visual rules for structuring a page with quick filters](./assets/quick-filters-example.svg)
+
+## What "blocked" means
+
+Blocking is always a visible denial, never a silent removal. Use the components in
+[`lib/authz/components`](../src/lib/authz/components/README.md) rather than hand-rolling a check, they carry the
+denial message and the loading state.
+
+| Scope           | Component                                 | Denied state                                |
+| --------------- | ----------------------------------------- | ------------------------------------------- |
+| Button          | `AuthZButton`                             | Disabled + tooltip                          |
+| Any element      | `AuthZTooltip`                            | Disabled child + tooltip                    |
+| Section         | `withAuthZContent` / `AuthZGuardContent`  | Inline `PermissionDeniedCallout`            |
+| Page / route    | `withAuthZPage` / `AuthZGuardPage`        | `PermissionDeniedFullPage`                  |
+| Custom fallback | `withAuthZ` / `AuthZGuard`                | Whatever you pass as `fallback`             |
+
+Prefer the HOC (`withAuthZ*`); reach for the JSX guard (`AuthZGuard*`) when the gate depends on conditional rendering
+and an HOC cannot express it. The components README has the full decision tree and how to build the `checks` array.
+
+## Migration checklist
+
+Use the existing components. Create a new one only if none fit.
+
+- [ ] Can I apply a `withAuthZ*` variant directly, or must I extract the content into a component first?
+  - If extraction is needed, declare the new content component in the same file to keep the diff small, then move it
+    to its own file in a follow-up commit or PR.
+- [ ] Is the layout structured to respect the [core rules](#core-rules)?
+  - If not, raise it in the frontend Slack channel before reshaping the page.
+- [ ] Am I gating a shared component rather than a page or section?
+  - If so, it must stay functional with no permission. Example: the Query Builder works without field suggestions when
+    the user cannot read them.
+
+## Testing
+
+### Devtool
+
+Press `Cmd + K` (`Ctrl + K` on Windows/Linux) to open the shortcuts, search for `AuthZ`, and pick the first
+result. The devtool simulates granted and denied permissions across the UI.
+
+Available only in local development, it is stripped from production builds.
+
+### Unit tests
+
+[`lib/authz/utils/README.md`](../src/lib/authz/utils/README.md) covers the `*.authz.test.tsx` naming convention, the
+MSW handlers (`setupAuthzAdmin`, `setupAuthzDenyAll`, `setupAuthzDeny`, `setupAuthzAllow`,
+`setupAuthzGrantByPrefix`), and how to test the loading state.

frontend/src/AppRoutes/Private.tsx

@@ -14,7 +14,10 @@ import { useAppContext } from 'providers/App/App';
 import { LicensePlatform, LicenseState } from 'types/api/licensesV3/getActive';
 import { OrgPreference } from 'types/api/preferences/preference';
 import { USER_ROLES } from 'types/roles';
-import { routePermission } from 'utils/permission';
+import {
+	routePermission,
+	routeWithInitialAuthZSupport,
+} from 'utils/permission';
 
 import routes, {
 	LIST_LICENSES,
@@ -42,7 +45,6 @@ function PrivateRoute({ children }: PrivateRouteProps): JSX.Element {
 	const isAdmin = user.role === USER_ROLES.ADMIN;
 	const isAIAssistantEnabled = useIsAIAssistantEnabled();
 	const isAIObservabilityEnabled = useIsAIObservabilityEnabled();
-
 	const mapRoutes = useMemo(
 		() =>
 			new Map(
@@ -226,7 +228,16 @@ function PrivateRoute({ children }: PrivateRouteProps): JSX.Element {
 		if (isPrivate) {
 			if (isLoggedInState) {
 				const route = routePermission[key];
-				if (route && route.find((e) => e === user.role) === undefined) {
+				const hasInitialAuthZSupport = Object.hasOwn(
+					routeWithInitialAuthZSupport,
+					key,
+				);
+
+				if (
+					route &&
+					route.find((e) => e === user.role) === undefined &&
+					hasInitialAuthZSupport === false
+				) {
 					return <Redirect to={ROUTES.UN_AUTHORIZED} />;
 				}
 			} else {

frontend/src/AppRoutes/__tests__/Private.test.tsx

@@ -17,6 +17,7 @@ import {
 } from 'types/api/licensesV3/getActive';
 import { OrgPreference } from 'types/api/preferences/preference';
 import { ROLES, USER_ROLES } from 'types/roles';
+import { routeWithInitialAuthZSupport } from 'utils/permission';
 
 import PrivateRoute from '../Private';
 
@@ -178,6 +179,7 @@ function createMockAppContext(
 		isFetchingHosts: false,
 		isFetchingFeatureFlags: false,
 		isFetchingOrgPreferences: false,
+		isFetchingUserPreferences: false,
 		userFetchError: null,
 		activeLicenseFetchError: null,
 		hostsFetchError: null,
@@ -198,24 +200,39 @@ function createMockAppContext(
 	};
 }
 
+// Roles that no authz-aware route grants through the legacy routePermission table
+const DENIED_ROLES: ROLES[] = [
+	USER_ROLES.ANONYMOUS as ROLES,
+	USER_ROLES.AUTHOR as ROLES,
+];
+
+const PERMITTED_ROLES: ROLES[] = [
+	USER_ROLES.ADMIN as ROLES,
+	USER_ROLES.EDITOR as ROLES,
+	USER_ROLES.VIEWER as ROLES,
+];
+
+interface AuthzRouteCase {
+	path: string;
+	deniedRoles: ROLES[];
+}
+
 interface RenderPrivateRouteOptions {
 	initialRoute?: string;
 	appContext?: Partial<IAppContext>;
 	isCloudUser?: boolean;
 }
 
-function renderPrivateRoute(options: RenderPrivateRouteOptions = {}): void {
-	const {
-		initialRoute = ROUTES.HOME,
-		appContext = {},
-		isCloudUser = true,
-	} = options;
+function buildPrivateRouteTree(
+	options: RenderPrivateRouteOptions,
+): ReactElement {
+	const { initialRoute = ROUTES.HOME, appContext = {} } = options;
 
-	mockIsCloudUser = isCloudUser;
+	const contextValue = createMockAppContext({
+		...appContext,
+	});
 
-	const contextValue = createMockAppContext(appContext);
-
-	render(
+	return (
 		<QueryClientProvider client={queryClient}>
 			<MemoryRouter initialEntries={[initialRoute]}>
 				<AppContext.Provider value={contextValue}>
@@ -229,10 +246,15 @@ function renderPrivateRoute(options: RenderPrivateRouteOptions = {}): void {
 					</PrivateRoute>
 				</AppContext.Provider>
 			</MemoryRouter>
-		</QueryClientProvider>,
+		</QueryClientProvider>
 	);
 }
 
+function renderPrivateRoute(options: RenderPrivateRouteOptions = {}): void {
+	mockIsCloudUser = options.isCloudUser ?? true;
+	render(buildPrivateRouteTree(options));
+}
+
 // Generic assertion helpers for navigation behavior
 // Using location-based assertions since Private.tsx now uses Redirect component
 
@@ -1432,6 +1454,25 @@ describe('PrivateRoute', () => {
 
 			assertStaysOnRoute(ROUTES.GET_STARTED_WITH_CLOUD);
 		});
+
+		it.each([...PERMITTED_ROLES, ...DENIED_ROLES])(
+			'should render the unauthorized page for a %s instead of bouncing off it',
+			(role) => {
+				// routePermission.UN_AUTHORIZED must grant every role: a role denied here
+				// is redirected to /un-authorized and then redirected away from it again,
+				// which loops until React bails out with a blank screen.
+				renderPrivateRoute({
+					initialRoute: ROUTES.UN_AUTHORIZED,
+					appContext: {
+						isLoggedIn: true,
+						user: createMockUser({ role }),
+					},
+				});
+
+				assertStaysOnRoute(ROUTES.UN_AUTHORIZED);
+				assertRendersChildren();
+			},
+		);
 	});
 
 	describe('Edge Cases', () => {
@@ -1477,6 +1518,174 @@ describe('PrivateRoute', () => {
 		});
 	});
 
+	describe('AuthZ Support (routeWithInitialAuthZSupport)', () => {
+		// Routes in routeWithInitialAuthZSupport always bypass legacy role check
+		const AUTHZ_ROUTE_CASES: Record<
+			keyof typeof routeWithInitialAuthZSupport,
+			AuthzRouteCase
+		> = {
+			// Everything under /settings resolves to the non-exact SETTINGS route
+			SETTINGS: { path: ROUTES.SETTINGS, deniedRoles: DENIED_ROLES },
+			MY_SETTINGS: { path: ROUTES.MY_SETTINGS, deniedRoles: DENIED_ROLES },
+			ROLES_SETTINGS: { path: ROUTES.ROLES_SETTINGS, deniedRoles: DENIED_ROLES },
+			ROLE_CREATE: { path: ROUTES.ROLE_CREATE, deniedRoles: DENIED_ROLES },
+			ROLE_DETAILS: {
+				path: ROUTES.ROLE_DETAILS.replace(':roleId', 'role-id-1'),
+				deniedRoles: DENIED_ROLES,
+			},
+			ROLE_EDIT: {
+				path: ROUTES.ROLE_EDIT.replace(':roleId', 'role-id-1'),
+				deniedRoles: DENIED_ROLES,
+			},
+			SERVICE_ACCOUNTS_SETTINGS: {
+				path: ROUTES.SERVICE_ACCOUNTS_SETTINGS,
+				deniedRoles: DENIED_ROLES,
+			},
+			TRACES_EXPLORER: { path: ROUTES.TRACES_EXPLORER, deniedRoles: DENIED_ROLES },
+			TRACE: { path: ROUTES.TRACE, deniedRoles: DENIED_ROLES },
+			TRACE_DETAIL: {
+				path: ROUTES.TRACE_DETAIL.replace(':id', 'trace-id-1'),
+				deniedRoles: DENIED_ROLES,
+			},
+			TRACE_DETAIL_OLD: {
+				path: ROUTES.TRACE_DETAIL_OLD.replace(':id', 'trace-id-1'),
+				deniedRoles: DENIED_ROLES,
+			},
+			// LOGS and LOGS_EXPLORER share a path - matchPath resolves it to whichever
+			// route definition comes last, and both keys are authz-aware either way.
+			LOGS: { path: ROUTES.LOGS, deniedRoles: DENIED_ROLES },
+			LOGS_EXPLORER: { path: ROUTES.LOGS_EXPLORER, deniedRoles: DENIED_ROLES },
+			LIVE_LOGS: { path: ROUTES.LIVE_LOGS, deniedRoles: DENIED_ROLES },
+			OLD_LOGS_EXPLORER: {
+				path: ROUTES.OLD_LOGS_EXPLORER,
+				deniedRoles: DENIED_ROLES,
+			},
+			METRICS_EXPLORER: {
+				path: ROUTES.METRICS_EXPLORER,
+				deniedRoles: DENIED_ROLES,
+			},
+			METRICS_EXPLORER_EXPLORER: {
+				path: ROUTES.METRICS_EXPLORER_EXPLORER,
+				deniedRoles: DENIED_ROLES,
+			},
+			METRICS_EXPLORER_VOLUME_CONTROL: {
+				path: ROUTES.METRICS_EXPLORER_VOLUME_CONTROL,
+				deniedRoles: DENIED_ROLES,
+			},
+			METER: { path: ROUTES.METER, deniedRoles: DENIED_ROLES },
+			METER_EXPLORER: { path: ROUTES.METER_EXPLORER, deniedRoles: DENIED_ROLES },
+			// SUPPORT already grants ANONYMOUS in routePermission, so only AUTHOR
+			// exercises the redirect branch here.
+			SUPPORT: {
+				path: ROUTES.SUPPORT,
+				deniedRoles: [USER_ROLES.AUTHOR as ROLES],
+			},
+		};
+
+		const authzRouteRolePairs: [string, string, ROLES][] = Object.entries(
+			AUTHZ_ROUTE_CASES,
+		).flatMap(([name, { path, deniedRoles }]) =>
+			deniedRoles.map((role): [string, string, ROLES] => [name, path, role]),
+		);
+
+		// Routes with no authz check - legacy role check still applies
+		const NON_AUTHZ_ROUTE_CASES: [string, string, ROLES][] = [
+			['ALERTS_NEW', ROUTES.ALERTS_NEW, USER_ROLES.VIEWER as ROLES],
+			['LIST_LICENSES', ROUTES.LIST_LICENSES, USER_ROLES.EDITOR as ROLES],
+			['ONBOARDING', ROUTES.ONBOARDING, USER_ROLES.VIEWER as ROLES],
+			['APPLICATION', ROUTES.APPLICATION, USER_ROLES.ANONYMOUS as ROLES],
+			[
+				'METRICS_EXPLORER_VIEWS',
+				ROUTES.METRICS_EXPLORER_VIEWS,
+				USER_ROLES.ANONYMOUS as ROLES,
+			],
+		];
+
+		it.each(authzRouteRolePairs)(
+			'should not redirect %s (%s) for role %s - authz routes bypass legacy role check',
+			(_name, path, role) => {
+				// Routes in routeWithInitialAuthZSupport always bypass the legacy role check.
+				// Authorization is handled by downstream components via fine-grained authz.
+				renderPrivateRoute({
+					initialRoute: path,
+					appContext: {
+						isLoggedIn: true,
+						user: createMockUser({ role }),
+					},
+				});
+
+				assertStaysOnRoute(path);
+				assertRendersChildren();
+			},
+		);
+
+		it.each([...PERMITTED_ROLES, ...DENIED_ROLES])(
+			'should not redirect a %s from an authz-aware route',
+			(role) => {
+				// All roles pass through - authorization handled downstream
+				renderPrivateRoute({
+					initialRoute: ROUTES.LOGS_EXPLORER,
+					appContext: {
+						isLoggedIn: true,
+						user: createMockUser({ role }),
+					},
+				});
+
+				assertStaysOnRoute(ROUTES.LOGS_EXPLORER);
+				assertRendersChildren();
+			},
+		);
+
+		it.each(NON_AUTHZ_ROUTE_CASES)(
+			'should redirect %s (%s) for role %s - non-authz routes use legacy role check',
+			async (_name, path, role) => {
+				// Routes NOT in routeWithInitialAuthZSupport still use legacy role check
+				renderPrivateRoute({
+					initialRoute: path,
+					appContext: {
+						isLoggedIn: true,
+						user: createMockUser({ role }),
+					},
+				});
+
+				await assertRedirectsTo(ROUTES.UN_AUTHORIZED);
+			},
+		);
+
+		it.each(authzRouteRolePairs)(
+			'should still redirect unauthenticated users away from %s (%s) with role %s',
+			async (_name, path, role) => {
+				// The authz bypass only relaxes the role check, never the login check.
+				renderPrivateRoute({
+					initialRoute: path,
+					appContext: {
+						isLoggedIn: false,
+						user: createMockUser({ role }),
+					},
+				});
+
+				await assertRedirectsTo(ROUTES.LOGIN);
+			},
+		);
+
+		it('should still redirect to workspace locked from an authz-aware route', async () => {
+			// Workspace guards run before the role check and must not be bypassed.
+			renderPrivateRoute({
+				initialRoute: ROUTES.LOGS_EXPLORER,
+				appContext: {
+					isLoggedIn: true,
+					isFetchingActiveLicense: false,
+					activeLicense: createMockLicense({ platform: LicensePlatform.CLOUD }),
+					trialInfo: createMockTrialInfo({ workSpaceBlock: true }),
+					user: createMockUser({ role: USER_ROLES.VIEWER as ROLES }),
+				},
+				isCloudUser: true,
+			});
+
+			await assertRedirectsTo(ROUTES.WORKSPACE_LOCKED);
+		});
+	});
+
 	describe('Old channel route redirects', () => {
 		it.each([
 			['/settings/channels', '/alerts', 'tab=Channels'],

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -4299,6 +4299,18 @@ export interface Querybuildertypesv5QueryEnvelopeBuilderDTO {
 	type: Querybuildertypesv5QueryEnvelopeBuilderDTOType;
 }
 
+export enum Querybuildertypesv5QueryEnvelopeBuilderAIDTOType {
+	builder_ai_query = 'builder_ai_query',
+}
+export interface Querybuildertypesv5QueryEnvelopeBuilderAIDTO {
+	spec?: Querybuildertypesv5QueryBuilderQueryGithubComSigNozSignozPkgTypesQuerybuildertypesQuerybuildertypesv5TraceAggregationDTO;
+	/**
+	 * @type string
+	 * @enum builder_ai_query
+	 */
+	type: Querybuildertypesv5QueryEnvelopeBuilderAIDTOType;
+}
+
 export interface Querybuildertypesv5QueryBuilderFormulaDTO {
 	/**
 	 * @type boolean
@@ -4482,6 +4494,7 @@ export interface Querybuildertypesv5QueryEnvelopeClickHouseSQLDTO {
 
 export type Querybuildertypesv5QueryEnvelopeDTO =
 	| Querybuildertypesv5QueryEnvelopeBuilderDTO
+	| Querybuildertypesv5QueryEnvelopeBuilderAIDTO
 	| Querybuildertypesv5QueryEnvelopeFormulaDTO
 	| Querybuildertypesv5QueryEnvelopeTraceOperatorDTO
 	| Querybuildertypesv5QueryEnvelopePromQLDTO
@@ -8285,6 +8298,7 @@ export interface Querybuildertypesv5QueryRangeResponseDTO {
 
 export enum Querybuildertypesv5QueryTypeDTO {
 	builder_query = 'builder_query',
+	builder_ai_query = 'builder_ai_query',
 	builder_formula = 'builder_formula',
 	builder_trace_operator = 'builder_trace_operator',
 	clickhouse_sql = 'clickhouse_sql',

frontend/src/components/LogDetail/index.tsx

@@ -438,7 +438,11 @@ function LogDetailInner({
 			destroyOnClose
 			closeIcon={<X size={16} style={{ marginTop: Spacing.MARGIN_1 }} />}
 		>
-			<div className="log-detail-drawer__content" data-log-detail-ignore="true">
+			<div
+				className="log-detail-drawer__content"
+				data-log-detail-ignore="true"
+				data-testid="log-detail-drawer"
+			>
 				<div className="log-detail-drawer__log">
 					<Divider type="vertical" className={cx('log-type-indicator', logType)} />
 					<Tooltip

frontend/src/components/QueryBuilderV2/QueryV2/QuerySearch/QuerySearch.tsx

@@ -49,7 +49,11 @@ import { unquote } from 'utils/stringUtils';
 import { getRecentQueries } from 'lib/recentQueries/getRecentQueries';
 import type { SignalType } from 'types/api/v5/queryRange';
 
-import { queryExamples, SUGGESTIONS_SECTION } from './constants';
+import {
+	queryExamples,
+	SUGGESTION_FETCH_DEBOUNCE_MS,
+	SUGGESTIONS_SECTION,
+} from './constants';
 import {
 	combineInitialAndUserExpression,
 	dedupeOptionsByLabel,
@@ -353,7 +357,7 @@ function QuerySearch({
 	);
 
 	const debouncedFetchKeySuggestions = useMemo(
-		() => debounce(fetchKeySuggestions, 300),
+		() => debounce(fetchKeySuggestions, SUGGESTION_FETCH_DEBOUNCE_MS),
 		[fetchKeySuggestions],
 	);
 
@@ -584,7 +588,7 @@ function QuerySearch({
 	);
 
 	const debouncedFetchValueSuggestions = useMemo(
-		() => debounce(fetchValueSuggestions, 300),
+		() => debounce(fetchValueSuggestions, SUGGESTION_FETCH_DEBOUNCE_MS),
 		[fetchValueSuggestions],
 	);
 

frontend/src/components/QueryBuilderV2/QueryV2/QuerySearch/constants.ts

@@ -1,6 +1,8 @@
 export const RECENTS_SECTION = { name: 'Recent searches', rank: 1 } as const;
 export const SUGGESTIONS_SECTION = { name: 'Suggestions', rank: 2 } as const;
 
+export const SUGGESTION_FETCH_DEBOUNCE_MS = 300;
+
 // TODO: move to using TelemetrytypesFieldContextDTO when we migrate getKeySuggestions API (Part of https://github.com/SigNoz/engineering-pod/issues/5289)
 export const FIELD_CONTEXTS = [
 	'attribute',

frontend/src/components/QueryBuilderV2/QueryV2/__tests__/QuerySearch.contextSuggestions.test.tsx

@@ -23,6 +23,13 @@ jest.mock('providers/Dashboard/store/useDashboardStore', () => ({
 	}),
 }));
 
+// Shrink the suggestion-fetch debounce (300ms in prod) so these integration
+// tests aren't paced by it; coalescing semantics stay intact.
+jest.mock('../QuerySearch/constants', () => ({
+	...jest.requireActual('../QuerySearch/constants'),
+	SUGGESTION_FETCH_DEBOUNCE_MS: 30,
+}));
+
 jest.mock('hooks/queryBuilder/useQueryBuilder', () => {
 	const handleRunQuery = jest.fn();
 	return {

frontend/src/components/TanStackTableView/TanStackCustomTableRow.tsx

@@ -88,6 +88,7 @@ function TanStackCustomTableRow<TData, TItemKey = string>({
 			{...props}
 			className={rowClassName}
 			style={rowStyle}
+			data-testid={context?.getRowTestId?.(rowData)}
 			onMouseEnter={handleMouseEnter}
 			onMouseLeave={clearHovered}
 		>
@@ -154,6 +155,12 @@ function areTableRowPropsEqual<TData, TItemKey = string>(
 			return false;
 		}
 
+		const prevTestId = prev.context?.getRowTestId?.(prevData) ?? '';
+		const nextTestId = next.context?.getRowTestId?.(nextData) ?? '';
+		if (prevTestId !== nextTestId) {
+			return false;
+		}
+
 		const prevStyle = prev.context?.getRowStyle?.(prevData);
 		const nextStyle = next.context?.getRowStyle?.(nextData);
 		if (prevStyle !== nextStyle) {

frontend/src/components/TanStackTableView/TanStackRow.tsx

@@ -33,7 +33,6 @@ function TanStackRowCellsInner<TData, TItemKey = string>({
 	// Stable references via destructuring, keep them as is
 	const onRowClick = context?.onRowClick;
 	const onRowClickNewTab = context?.onRowClickNewTab;
-	const onRowDeactivate = context?.onRowDeactivate;
 	const isRowActive = context?.isRowActive;
 	const getRowKeyData = context?.getRowKeyData;
 	const rowIndex = row.index;
@@ -52,21 +51,9 @@ function TanStackRowCellsInner<TData, TItemKey = string>({
 			}
 
 			const isActive = isRowActive?.(rowData) ?? false;
-			if (isActive && onRowDeactivate) {
-				onRowDeactivate();
-			} else {
-				onRowClick?.(rowData, itemKey);
-			}
+			onRowClick?.(rowData, itemKey, { isActive });
 		},
-		[
-			isRowActive,
-			onRowDeactivate,
-			onRowClick,
-			onRowClickNewTab,
-			rowData,
-			getRowKeyData,
-			rowIndex,
-		],
+		[isRowActive, onRowClick, onRowClickNewTab, rowData, getRowKeyData, rowIndex],
 	);
 
 	if (itemKind === 'expansion') {
@@ -120,7 +107,6 @@ function areRowCellsPropsEqual<TData>(
 		prev.columnVisibilityKey === next.columnVisibilityKey &&
 		prev.context?.onRowClick === next.context?.onRowClick &&
 		prev.context?.onRowClickNewTab === next.context?.onRowClickNewTab &&
-		prev.context?.onRowDeactivate === next.context?.onRowDeactivate &&
 		prev.context?.isRowActive === next.context?.isRowActive &&
 		prev.context?.getRowKeyData === next.context?.getRowKeyData &&
 		prev.context?.renderRowActions === next.context?.renderRowActions &&

frontend/src/components/TanStackTableView/TanStackTable.tsx

@@ -92,11 +92,11 @@ function TanStackTableInner<TData, TItemKey = string>(
 		getGroupKey,
 		getRowStyle,
 		getRowClassName,
+		getRowTestId,
 		isRowActive,
 		renderRowActions,
 		onRowClick,
 		onRowClickNewTab,
-		onRowDeactivate,
 		onSort,
 		activeRowIndex,
 		renderExpandedRow,
@@ -378,11 +378,11 @@ function TanStackTableInner<TData, TItemKey = string>(
 		() => ({
 			getRowStyle,
 			getRowClassName,
+			getRowTestId,
 			isRowActive,
 			renderRowActions,
 			onRowClick,
 			onRowClickNewTab,
-			onRowDeactivate,
 			renderExpandedRow,
 			getRowKeyData,
 			colCount: visibleColumnsCount,
@@ -396,11 +396,11 @@ function TanStackTableInner<TData, TItemKey = string>(
 		[
 			getRowStyle,
 			getRowClassName,
+			getRowTestId,
 			isRowActive,
 			renderRowActions,
 			onRowClick,
 			onRowClickNewTab,
-			onRowDeactivate,
 			renderExpandedRow,
 			getRowKeyData,
 			visibleColumnsCount,

frontend/src/components/TanStackTableView/__tests__/TanStackRow.test.tsx

@@ -85,7 +85,9 @@ describe('TanStackRowCells', () => {
 			</table>,
 		);
 		await user.click(screen.getAllByRole('cell')[0]);
-		expect(onRowClick).toHaveBeenCalledWith({ id: 'r1' }, 'r1');
+		expect(onRowClick).toHaveBeenCalledWith({ id: 'r1' }, 'r1', {
+			isActive: false,
+		});
 	});
 
 	it('fires onRowClick with empty itemKey when getRowKeyData is not provided', async () => {
@@ -117,17 +119,19 @@ describe('TanStackRowCells', () => {
 			</table>,
 		);
 		await user.click(screen.getAllByRole('cell')[0]);
-		expect(onRowClick).toHaveBeenCalledWith({ id: 'r1' }, '');
+		expect(onRowClick).toHaveBeenCalledWith({ id: 'r1' }, '', {
+			isActive: false,
+		});
 	});
 
-	it('calls onRowDeactivate instead of onRowClick when row is active', async () => {
+	it('calls onRowClick with isActive: true when the row is active', async () => {
+		// The table no longer owns open/close — it reports the active state and the
+		// consumer routes the click. An active row must still fire onRowClick.
 		const user = userEvent.setup();
 		const onRowClick = jest.fn();
-		const onRowDeactivate = jest.fn();
 		const ctx: TableRowContext<Row> = {
 			colCount: 1,
 			onRowClick,
-			onRowDeactivate,
 			isRowActive: () => true,
 			getRowKeyData: () => ({ finalKey: 'r1', itemKey: 'r1' }),
 			hasSingleColumn: false,
@@ -152,8 +156,44 @@ describe('TanStackRowCells', () => {
 			</table>,
 		);
 		await user.click(screen.getAllByRole('cell')[0]);
-		expect(onRowDeactivate).toHaveBeenCalled();
-		expect(onRowClick).not.toHaveBeenCalled();
+		expect(onRowClick).toHaveBeenCalledWith({ id: 'r1' }, 'r1', {
+			isActive: true,
+		});
+	});
+
+	it('calls onRowClick with isActive: false when the row is not active', async () => {
+		const user = userEvent.setup();
+		const onRowClick = jest.fn();
+		const ctx: TableRowContext<Row> = {
+			colCount: 1,
+			onRowClick,
+			isRowActive: () => false,
+			getRowKeyData: () => ({ finalKey: 'r1', itemKey: 'r1' }),
+			hasSingleColumn: false,
+			columnOrderKey: '',
+			columnVisibilityKey: '',
+		};
+		const row = buildMockRow([{ id: 'body' }]);
+		render(
+			<table>
+				<tbody>
+					<tr>
+						<TanStackRowCells<Row>
+							row={row as never}
+							context={ctx}
+							itemKind="row"
+							hasSingleColumn={false}
+							columnOrderKey=""
+							columnVisibilityKey=""
+						/>
+					</tr>
+				</tbody>
+			</table>,
+		);
+		await user.click(screen.getAllByRole('cell')[0]);
+		expect(onRowClick).toHaveBeenCalledWith({ id: 'r1' }, 'r1', {
+			isActive: false,
+		});
 	});
 
 	it('does not render renderRowActions before hover', () => {

frontend/src/components/TanStackTableView/__tests__/TanStackTableView.test.tsx

@@ -611,6 +611,7 @@ describe('TanStackTableView Integration', () => {
 			expect(onRowClick).toHaveBeenCalledWith(
 				expect.objectContaining({ id: '1', name: 'Item 1' }),
 				'1',
+				{ isActive: false },
 			);
 		});
 
@@ -639,6 +640,7 @@ describe('TanStackTableView Integration', () => {
 			expect(onRowClick).toHaveBeenCalledWith(
 				expect.objectContaining({ id: '1', name: 'Item 1' }),
 				{ id: '1', name: 'Item 1' },
+				{ isActive: false },
 			);
 		});
 
@@ -659,15 +661,15 @@ describe('TanStackTableView Integration', () => {
 			expect(row).toHaveClass('tableRowActive');
 		});
 
-		it('calls onRowDeactivate when clicking active row', async () => {
+		it('calls onRowClick with isActive: true when clicking the active row', async () => {
+			// The consumer owns open/close routing — the table just reports the
+			// active state via the click context.
 			const user = userEvent.setup();
 			const onRowClick = jest.fn();
-			const onRowDeactivate = jest.fn();
 
 			renderTanStackTable({
 				props: {
 					onRowClick,
-					onRowDeactivate,
 					isRowActive: (row) => row.id === '1',
 				},
 			});
@@ -678,8 +680,11 @@ describe('TanStackTableView Integration', () => {
 
 			await user.click(screen.getByText('Item 1'));
 
-			expect(onRowDeactivate).toHaveBeenCalled();
-			expect(onRowClick).not.toHaveBeenCalled();
+			expect(onRowClick).toHaveBeenCalledWith(
+				expect.objectContaining({ id: '1' }),
+				expect.anything(),
+				{ isActive: true },
+			);
 		});
 
 		it('opens in new tab on ctrl+click', async () => {

frontend/src/components/TanStackTableView/index.tsx

@@ -116,9 +116,11 @@ export * from './useTableParams';
  *   getItemKey={(row) => row.id}
  *   isRowActive={(row) => row.id === selectedId}
  *   activeRowIndex={selectedIndex}
- *   onRowClick={(row, itemKey) => setSelectedId(itemKey)}
+ *   // The table reports the click + the row's active state; the consumer owns open/close.
+ *   onRowClick={(row, itemKey, { isActive }) =>
+ *     setSelectedId(isActive ? undefined : itemKey)
+ *   }
  *   onRowClickNewTab={(row, itemKey) => openInNewTab(itemKey)}
- *   onRowDeactivate={() => setSelectedId(undefined)}
  *   getRowClassName={(row) => (row.severity === 'error' ? 'row-error' : '')}
  *   getRowStyle={(row) => (row.dimmed ? { opacity: 0.5 } : {})}
  *   renderRowActions={(row) => <Button size="small">Open</Button>}

frontend/src/components/TanStackTableView/types.ts

@@ -81,15 +81,19 @@ export type FlatItem<TData> =
 	| { kind: 'row'; row: TanStackRowType<TData> }
 	| { kind: 'expansion'; row: TanStackRowType<TData> };
 
+export type RowClickContext = {
+	isActive: boolean;
+};
+
 export type TableRowContext<TData, TItemKey = string> = {
 	getRowStyle?: (row: TData) => CSSProperties;
 	getRowClassName?: (row: TData) => string;
+	getRowTestId?: (row: TData) => string;
 	isRowActive?: (row: TData) => boolean;
 	renderRowActions?: (row: TData) => ReactNode;
-	onRowClick?: (row: TData, itemKey: TItemKey) => void;
+	onRowClick?: (row: TData, itemKey: TItemKey, context: RowClickContext) => void;
 	/** Called when ctrl+click or cmd+click on a row */
 	onRowClickNewTab?: (row: TData, itemKey: TItemKey) => void;
-	onRowDeactivate?: () => void;
 	renderExpandedRow?: (
 		row: TData,
 		rowKey: string,
@@ -178,12 +182,12 @@ export type TanStackTableProps<TData, TItemKey = string> = {
 	getGroupKey?: (row: TData) => Record<string, string>;
 	getRowStyle?: (row: TData) => CSSProperties;
 	getRowClassName?: (row: TData) => string;
+	getRowTestId?: (row: TData) => string;
 	isRowActive?: (row: TData) => boolean;
 	renderRowActions?: (row: TData) => ReactNode;
-	onRowClick?: (row: TData, itemKey: TItemKey) => void;
+	onRowClick?: (row: TData, itemKey: TItemKey, context: RowClickContext) => void;
 	/** Called when ctrl+click or cmd+click on a row */
 	onRowClickNewTab?: (row: TData, itemKey: TItemKey) => void;
-	onRowDeactivate?: () => void;
 	activeRowIndex?: number;
 	renderExpandedRow?: (
 		row: TData,

frontend/src/container/AppLayout/index.tsx

@@ -104,6 +104,7 @@ function AppLayout(props: AppLayoutProps): JSX.Element {
 		isFetchingFeatureFlags,
 		featureFlagsFetchError,
 		userPreferences,
+		isFetchingUserPreferences,
 		updateChangelog,
 		toggleChangelogModal,
 		showChangelogModal,
@@ -724,12 +725,12 @@ function AppLayout(props: AppLayoutProps): JSX.Element {
 		}
 	}, []);
 
-	// Set sidebar as loaded after user preferences are fetched
+	// Set sidebar as loaded after user preferences fetch completes (success or error)
 	useEffect(() => {
-		if (userPreferences !== null) {
+		if (!isFetchingUserPreferences) {
 			setIsSidebarLoaded(true);
 		}
-	}, [userPreferences]);
+	}, [isFetchingUserPreferences]);
 
 	// Use localStorage value as fallback until preferences are loaded
 	const isSideNavPinned = isSidebarLoaded

frontend/src/container/LiveLogs/LiveLogsList/LiveLogsList.styles.scss

@@ -60,3 +60,7 @@
 		}
 	}
 }
+
+.logs-linked-row td {
+	background-color: var(--row-active-bg) !important;
+}

frontend/src/container/LiveLogs/LiveLogsList/index.tsx

@@ -204,6 +204,9 @@ function LiveLogsList({
 							data={formattedLogs}
 							isLoading={false}
 							isRowActive={(log): boolean => log.id === activeLog?.id}
+							getRowClassName={(log): string =>
+								log.id === activeLogId ? 'logs-linked-row' : ''
+							}
 							getRowStyle={(log): CSSProperties =>
 								({
 									'--row-active-bg': getRowBackgroundColor(
@@ -216,10 +219,13 @@ function LiveLogsList({
 									),
 								}) as CSSProperties
 							}
-							onRowClick={(log): void => {
-								handleSetActiveLog(log);
+							onRowClick={(log, _itemKey, { isActive }): void => {
+								if (isActive) {
+									handleCloseLogDetail();
+								} else {
+									handleSetActiveLog(log);
+								}
 							}}
-							onRowDeactivate={handleCloseLogDetail}
 							activeRowIndex={activeLogIndex}
 							renderRowActions={(log): ReactNode => (
 								<LogLinesActionButtons

frontend/src/container/LogsExplorerList/LogsExplorerList.style.scss

@@ -323,3 +323,7 @@
 		}
 	}
 }
+
+.logs-linked-row td {
+	background-color: var(--row-active-bg) !important;
+}

frontend/src/container/LogsExplorerList/index.tsx

@@ -211,9 +211,11 @@ function LogsExplorerList({
 					data={logs}
 					isLoading={isLoading || isFetching}
 					onEndReached={onEndReached}
-					isRowActive={(log): boolean =>
-						log.id === activeLog?.id || log.id === activeLogId
+					isRowActive={(log): boolean => log.id === activeLog?.id}
+					getRowClassName={(log): string =>
+						log.id === activeLogId ? 'logs-linked-row' : ''
 					}
+					getRowTestId={(log): string => `logs-table-row-${log.id}`}
 					getRowStyle={(log): CSSProperties =>
 						({
 							'--row-active-bg': getRowBackgroundColor(
@@ -226,10 +228,13 @@ function LogsExplorerList({
 							),
 						}) as CSSProperties
 					}
-					onRowClick={(log): void => {
-						handleSetActiveLog(log);
+					onRowClick={(log, _itemKey, { isActive }): void => {
+						if (isActive) {
+							handleCloseLogDetail();
+						} else {
+							handleSetActiveLog(log);
+						}
 					}}
-					onRowDeactivate={handleCloseLogDetail}
 					activeRowIndex={activeLogIndex}
 					renderRowActions={(log): ReactNode => (
 						<LogLinesActionButtons
@@ -282,6 +287,7 @@ function LogsExplorerList({
 		options.maxLines,
 		options.fontSize,
 		activeLogIndex,
+		activeLogId,
 		logs,
 		onEndReached,
 		getItemContent,

frontend/src/container/RolesSettings/CreateEditRolePage/__tests__/JsonEditor.test.tsx

@@ -151,7 +151,9 @@ describe('JsonEditor', () => {
 			);
 			await user.click(await within(readToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'test-key-123{enter}');
 
 			await switchToJsonMode();

frontend/src/container/RolesSettings/CreateEditRolePage/__tests__/PermissionEditor.test.tsx

@@ -1,17 +1,8 @@
-import { Route, Switch } from 'react-router-dom';
-import ROUTES from 'constants/routes';
 import { server } from 'mocks-server/server';
-import { render, screen, userEvent, waitFor, within } from 'tests/test-utils';
+import { screen, userEvent, waitFor, within } from 'tests/test-utils';
 import { setupAuthzAdmin } from 'lib/authz/utils/authz-test-utils';
-import { TooltipProvider } from '@signozhq/ui/tooltip';
 
-import CreateEditRolePage from '../CreateEditRolePage';
-
-async function expandAllCards(): Promise<void> {
-	const user = userEvent.setup();
-	const expandButton = await screen.findByTestId('expand-all-button');
-	await user.click(expandButton);
-}
+import { expandAllCards, renderCreateRolePage } from './testUtils';
 
 beforeEach(() => {
 	server.use(setupAuthzAdmin());
@@ -21,35 +12,16 @@ afterEach(() => {
 	server.resetHandlers();
 });
 
-async function renderPage(): Promise<ReturnType<typeof render>> {
-	const result = render(
-		<TooltipProvider>
-			<Switch>
-				<Route path={ROUTES.ROLES_SETTINGS} exact>
-					<div data-testid="roles-list-redirect" />
-				</Route>
-				<Route path={ROUTES.ROLE_CREATE}>
-					<CreateEditRolePage />
-				</Route>
-			</Switch>
-		</TooltipProvider>,
-		undefined,
-		{ initialRoute: '/settings/roles/new' },
-	);
-	await screen.findByTestId('permission-editor');
-	return result;
-}
-
 describe('PermissionEditor', () => {
 	describe('mode toggle', () => {
 		it('renders permission editor with testId', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 
 			expect(screen.getByTestId('permission-editor')).toBeInTheDocument();
 		});
 
 		it('defaults to interactive mode', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 
 			const interactiveRadio = screen.getByTestId(
 				'permission-editor-mode-interactive',
@@ -59,7 +31,7 @@ describe('PermissionEditor', () => {
 
 		it('switches to JSON mode when clicked', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const jsonRadio = screen.getByTestId('permission-editor-mode-json');
 			await user.click(jsonRadio);
@@ -70,7 +42,7 @@ describe('PermissionEditor', () => {
 
 		it('switches back to interactive mode', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const jsonRadio = screen.getByTestId('permission-editor-mode-json');
 			await user.click(jsonRadio);
@@ -87,7 +59,7 @@ describe('PermissionEditor', () => {
 
 	describe('resource cards', () => {
 		it('renders all resource cards', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 
 			expect(
 				screen.getByTestId('resource-card-factor-api-key'),
@@ -99,7 +71,7 @@ describe('PermissionEditor', () => {
 		});
 
 		it('resource cards are collapsed by default', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
 			const header = within(apiKeyCard).getByTestId(
@@ -111,7 +83,7 @@ describe('PermissionEditor', () => {
 
 		it('expands resource card when header clicked', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
 			const header = within(apiKeyCard).getByTestId(
@@ -125,7 +97,7 @@ describe('PermissionEditor', () => {
 
 		it('collapses expanded resource card when header clicked again', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
 			const header = within(apiKeyCard).getByTestId(
@@ -139,7 +111,7 @@ describe('PermissionEditor', () => {
 		});
 
 		it('shows granted count in resource card header', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
 			await expect(
@@ -150,7 +122,7 @@ describe('PermissionEditor', () => {
 
 	describe('action toggles', () => {
 		it('renders action toggles for each available action', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -169,7 +141,7 @@ describe('PermissionEditor', () => {
 		});
 
 		it('defaults all actions to None scope', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -187,7 +159,7 @@ describe('PermissionEditor', () => {
 
 		it('changes scope to All when clicked', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -208,7 +180,7 @@ describe('PermissionEditor', () => {
 
 		it('updates granted count when scope changed', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -227,7 +199,7 @@ describe('PermissionEditor', () => {
 	describe('Only Selected scope', () => {
 		it('shows item input selector when Only Selected is chosen', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -239,12 +211,14 @@ describe('PermissionEditor', () => {
 				await within(createToggle).findByText('Only selected');
 			await user.click(onlySelectedBtn);
 
-			expect(screen.getByTestId('item-input-selector')).toBeInTheDocument();
+			expect(
+				screen.getByTestId('item-input-selector-factor-api-key-read'),
+			).toBeInTheDocument();
 		});
 
 		it('adds item when typed and Enter pressed', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -254,7 +228,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'api-key-001{enter}');
 
 			await expect(screen.findByText('api-key-001')).resolves.toBeInTheDocument();
@@ -262,7 +238,7 @@ describe('PermissionEditor', () => {
 
 		it('adds item when Add button clicked', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -272,10 +248,14 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'api-key-002');
 
-			const addBtn = screen.getByTestId('item-input-selector-add-btn');
+			const addBtn = screen.getByTestId(
+				'item-input-selector-add-btn-factor-api-key-read',
+			);
 			await user.click(addBtn);
 
 			await expect(screen.findByText('api-key-002')).resolves.toBeInTheDocument();
@@ -283,7 +263,7 @@ describe('PermissionEditor', () => {
 
 		it('adds multiple items separated by comma', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -293,7 +273,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'key-a, key-b, key-c{enter}');
 
 			await expect(screen.findByText('key-a')).resolves.toBeInTheDocument();
@@ -303,7 +285,7 @@ describe('PermissionEditor', () => {
 
 		it('adds multiple items separated by space', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -313,7 +295,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'key-x key-y key-z{enter}');
 
 			await expect(screen.findByText('key-x')).resolves.toBeInTheDocument();
@@ -323,7 +307,7 @@ describe('PermissionEditor', () => {
 
 		it('does not add duplicate items', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -333,7 +317,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'same-key{enter}');
 			await user.type(input, 'same-key{enter}');
 
@@ -343,7 +329,7 @@ describe('PermissionEditor', () => {
 
 		it('removes item when X clicked', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -353,20 +339,138 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'removable-key{enter}');
 
-			const removeBtn = screen.getByRole('button', {
-				name: /remove removable-key/i,
+			const badge = await screen.findByTestId('item-badge-factor-api-key-read-0');
+			const removeBtn = within(badge).getByRole('button', {
+				name: 'Remove removable-key',
 			});
 			await user.click(removeBtn);
 
 			expect(screen.queryByText('removable-key')).not.toBeInTheDocument();
 		});
 
+		it('names each badge close button after the item it removes', async () => {
+			const user = userEvent.setup();
+			await renderCreateRolePage();
+			await expandAllCards();
+
+			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
+			const readToggle = within(apiKeyCard).getByTestId(
+				'action-toggle-factor-api-key-read',
+			);
+			await user.click(await within(readToggle).findByText('Only selected'));
+
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
+			await user.type(input, 'key-one key-two{enter}');
+
+			const firstBadge = await screen.findByTestId(
+				'item-badge-factor-api-key-read-0',
+			);
+			const secondBadge = screen.getByTestId('item-badge-factor-api-key-read-1');
+
+			expect(
+				within(firstBadge).getByRole('button', { name: 'Remove key-one' }),
+			).toBeInTheDocument();
+			expect(
+				within(secondBadge).getByRole('button', { name: 'Remove key-two' }),
+			).toBeInTheDocument();
+		});
+
+		it('exposes the full item value as a title so truncated badges stay readable', async () => {
+			const user = userEvent.setup();
+			await renderCreateRolePage();
+			await expandAllCards();
+
+			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
+			const readToggle = within(apiKeyCard).getByTestId(
+				'action-toggle-factor-api-key-read',
+			);
+			await user.click(await within(readToggle).findByText('Only selected'));
+
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
+			await user.type(input, 'a-very-long-api-key-identifier-000001{enter}');
+
+			const badge = await screen.findByTestId('item-badge-factor-api-key-read-0');
+			expect(
+				within(badge).getByTitle('a-very-long-api-key-identifier-000001'),
+			).toBeInTheDocument();
+		});
+
+		it('moves focus to the previous badge when closed with the keyboard', async () => {
+			const user = userEvent.setup();
+			await renderCreateRolePage();
+			await expandAllCards();
+
+			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
+			const readToggle = within(apiKeyCard).getByTestId(
+				'action-toggle-factor-api-key-read',
+			);
+			await user.click(await within(readToggle).findByText('Only selected'));
+
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
+			await user.type(input, 'key-one key-two{enter}');
+
+			const secondBadge = await screen.findByTestId(
+				'item-badge-factor-api-key-read-1',
+			);
+			within(secondBadge).getByRole('button', { name: 'Remove key-two' }).focus();
+
+			await user.keyboard('{Enter}');
+
+			await waitFor(() => {
+				const firstBadge = screen.getByTestId('item-badge-factor-api-key-read-0');
+				expect(
+					within(firstBadge).getByRole('button', { name: 'Remove key-one' }),
+				).toHaveFocus();
+			});
+		});
+
+		it('does not steal focus when a badge is closed with the mouse', async () => {
+			const user = userEvent.setup();
+			await renderCreateRolePage();
+			await expandAllCards();
+
+			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
+			const readToggle = within(apiKeyCard).getByTestId(
+				'action-toggle-factor-api-key-read',
+			);
+			await user.click(await within(readToggle).findByText('Only selected'));
+
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
+			await user.type(input, 'key-one key-two{enter}');
+
+			const secondBadge = await screen.findByTestId(
+				'item-badge-factor-api-key-read-1',
+			);
+			await user.click(
+				within(secondBadge).getByRole('button', { name: 'Remove key-two' }),
+			);
+
+			await waitFor(() => {
+				expect(screen.queryByText('key-two')).not.toBeInTheDocument();
+			});
+
+			const firstBadge = screen.getByTestId('item-badge-factor-api-key-read-0');
+			expect(
+				within(firstBadge).getByRole('button', { name: 'Remove key-one' }),
+			).not.toHaveFocus();
+		});
+
 		it('shows Add button disabled when input is empty', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -376,7 +480,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const addBtn = screen.getByTestId('item-input-selector-add-btn');
+			const addBtn = screen.getByTestId(
+				'item-input-selector-add-btn-factor-api-key-read',
+			);
 			expect(addBtn).toBeDisabled();
 		});
 	});
@@ -384,7 +490,7 @@ describe('PermissionEditor', () => {
 	describe('scope change confirmation dialog', () => {
 		it('shows confirm dialog when leaving Only Selected with items', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -394,7 +500,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'will-be-cleared{enter}');
 
 			await user.click(await within(createToggle).findByText('All'));
@@ -406,7 +514,7 @@ describe('PermissionEditor', () => {
 
 		it('clears items when confirmed', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -416,7 +524,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'to-be-cleared{enter}');
 
 			await user.click(await within(createToggle).findByText('All'));
@@ -433,7 +543,7 @@ describe('PermissionEditor', () => {
 
 		it('keeps items when cancelled', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -443,7 +553,9 @@ describe('PermissionEditor', () => {
 
 			await user.click(await within(createToggle).findByText('Only selected'));
 
-			const input = screen.getByTestId('item-input-selector-input');
+			const input = screen.getByTestId(
+				'item-input-selector-input-factor-api-key-read',
+			);
 			await user.type(input, 'preserved-key{enter}');
 
 			await user.click(await within(createToggle).findByText('None'));
@@ -455,12 +567,14 @@ describe('PermissionEditor', () => {
 				screen.findByText('preserved-key'),
 			).resolves.toBeInTheDocument();
 
-			expect(screen.getByTestId('item-input-selector')).toBeInTheDocument();
+			expect(
+				screen.getByTestId('item-input-selector-factor-api-key-read'),
+			).toBeInTheDocument();
 		});
 
 		it('does not show dialog when leaving Only Selected with no items', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -479,7 +593,7 @@ describe('PermissionEditor', () => {
 
 	describe('verbs without Only Selected option', () => {
 		it('does not show Only Selected for list verb', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -501,7 +615,7 @@ describe('PermissionEditor', () => {
 
 	describe('collapse/expand all resources', () => {
 		it('shows expand/collapse toggle group', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 
 			expect(screen.getByTestId('toggle-all-group')).toBeInTheDocument();
 			expect(screen.getByTestId('expand-all-button')).toBeInTheDocument();
@@ -509,7 +623,7 @@ describe('PermissionEditor', () => {
 		});
 
 		it('expands all cards when expand button clicked', async () => {
-			await renderPage();
+			await renderCreateRolePage();
 			await expandAllCards();
 
 			const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
@@ -523,7 +637,7 @@ describe('PermissionEditor', () => {
 	describe('resource card error states', () => {
 		it('shows error border on collapsed card with validation error', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const nameInput = screen.getByTestId('role-name-input');
 			await user.type(nameInput, 'valid-role');
@@ -553,7 +667,7 @@ describe('PermissionEditor', () => {
 
 		it('hides error border when card is expanded', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const nameInput = screen.getByTestId('role-name-input');
 			await user.type(nameInput, 'valid-role');
@@ -590,7 +704,7 @@ describe('PermissionEditor', () => {
 
 		it('clears validation error when permission is changed', async () => {
 			const user = userEvent.setup();
-			await renderPage();
+			await renderCreateRolePage();
 
 			const nameInput = screen.getByTestId('role-name-input');
 			await user.type(nameInput, 'valid-role');

frontend/src/container/RolesSettings/CreateEditRolePage/__tests__/PermissionEditor.wizard.test.tsx

@@ -0,0 +1,462 @@
+import { server } from 'mocks-server/server';
+import { screen, userEvent, waitFor, within } from 'tests/test-utils';
+import { setupAuthzAdmin } from 'lib/authz/utils/authz-test-utils';
+
+import { expandAllCards, renderCreateRolePage } from './testUtils';
+
+beforeEach(() => {
+	server.use(setupAuthzAdmin());
+});
+
+afterEach(() => {
+	server.resetHandlers();
+});
+
+async function selectOnlySelected(
+	user: ReturnType<typeof userEvent.setup>,
+	resource = 'logs',
+): Promise<void> {
+	await renderCreateRolePage();
+	await expandAllCards();
+
+	const card = screen.getByTestId(`resource-card-${resource}`);
+	const readToggle = within(card).getByTestId(`action-toggle-${resource}-read`);
+	await user.click(await within(readToggle).findByText('Only selected'));
+}
+
+async function selectLogsOnlySelected(
+	user: ReturnType<typeof userEvent.setup>,
+): Promise<void> {
+	await selectOnlySelected(user, 'logs');
+}
+
+async function openWizard(
+	user: ReturnType<typeof userEvent.setup>,
+	resource = 'logs',
+): Promise<void> {
+	await selectOnlySelected(user, resource);
+
+	await user.click(
+		screen.getByTestId(`telemetry-wizard-trigger-${resource}-read`),
+	);
+	await screen.findByTestId(`telemetry-wizard-dialog-${resource}-read`);
+}
+
+async function openLogsWizard(
+	user: ReturnType<typeof userEvent.setup>,
+): Promise<void> {
+	await openWizard(user, 'logs');
+}
+
+describe('PermissionEditor - TelemetrySelectorWizard', () => {
+	it('shows wizard button for telemetry resources', async () => {
+		const user = userEvent.setup();
+		await selectLogsOnlySelected(user);
+
+		expect(
+			screen.getByTestId('telemetry-wizard-trigger-logs-read'),
+		).toBeInTheDocument();
+	});
+
+	it('does not show wizard button for non-telemetry resources', async () => {
+		await renderCreateRolePage();
+		await expandAllCards();
+
+		const apiKeyCard = screen.getByTestId('resource-card-factor-api-key');
+		const readToggle = within(apiKeyCard).getByTestId(
+			'action-toggle-factor-api-key-read',
+		);
+
+		const user = userEvent.setup();
+		await user.click(await within(readToggle).findByText('Only selected'));
+
+		expect(
+			screen.queryByTestId('telemetry-wizard-trigger-logs-read'),
+		).not.toBeInTheDocument();
+	});
+
+	it('opens wizard dialog when trigger clicked', async () => {
+		const user = userEvent.setup();
+		await selectLogsOnlySelected(user);
+
+		await user.click(screen.getByTestId('telemetry-wizard-trigger-logs-read'));
+
+		await expect(
+			screen.findByTestId('telemetry-wizard-dialog-logs-read'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('adds a query-type wildcard when the value is left empty', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await expect(
+			screen.findByText('builder_query/*'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('does not offer builder sub query', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+
+		expect(screen.queryByText('Builder Sub Query')).not.toBeInTheDocument();
+	});
+
+	it('does not show PromQL for logs', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+
+		expect(
+			screen.queryByTestId('wizard-query-type-option-promql-logs-read'),
+		).not.toBeInTheDocument();
+	});
+
+	it('does not show PromQL for traces', async () => {
+		const user = userEvent.setup();
+		await openWizard(user, 'traces');
+
+		await user.click(screen.getByTestId('wizard-query-type-select-traces-read'));
+
+		expect(
+			screen.queryByTestId('wizard-query-type-option-promql-traces-read'),
+		).not.toBeInTheDocument();
+	});
+
+	it('allows PromQL for metrics', async () => {
+		const user = userEvent.setup();
+		await openWizard(user, 'metrics');
+
+		await user.click(screen.getByTestId('wizard-query-type-select-metrics-read'));
+		await user.click(
+			await screen.findByTestId('wizard-query-type-option-promql-metrics-read'),
+		);
+
+		await user.click(screen.getByTestId('wizard-add-btn-metrics-read'));
+
+		await expect(screen.findByText('promql/*')).resolves.toBeInTheDocument();
+	});
+
+	it('hardcodes the key and does not let it be edited', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const keyInput = screen.getByTestId('wizard-key-input-logs-read');
+		expect(keyInput).toHaveValue('signoz.workspace.key.id');
+		expect(keyInput).toBeDisabled();
+	});
+
+	it('hides Key field for query types that do not support key scoping', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+		await user.click(await screen.findByText('ClickHouse SQL'));
+
+		expect(
+			screen.queryByTestId('wizard-key-input-logs-read'),
+		).not.toBeInTheDocument();
+	});
+
+	it('adds a key-scoped selector when the value is filled', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.type(screen.getByTestId('wizard-value-input-logs-read'), '123');
+
+		expect(screen.getByTestId('wizard-selector-input-logs-read')).toHaveValue(
+			'builder_query/signoz.workspace.key.id/123',
+		);
+
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await expect(
+			screen.findByText('builder_query/signoz.workspace.key.id/123'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('replaces the value with a wildcard when any resource is checked', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByLabelText('Any value'));
+
+		expect(screen.getByTestId('wizard-value-input-logs-read')).toHaveValue('*');
+
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await expect(
+			screen.findByText('builder_query/signoz.workspace.key.id/*'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('clears the value when any resource is unchecked', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const anyResource = screen.getByLabelText('Any value');
+		await user.click(anyResource);
+		expect(anyResource).toBeChecked();
+
+		await user.click(anyResource);
+
+		expect(anyResource).not.toBeChecked();
+		expect(screen.getByTestId('wizard-value-input-logs-read')).toHaveValue('');
+	});
+
+	it('checks any resource when the value is typed as a wildcard', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.type(screen.getByTestId('wizard-value-input-logs-read'), '*');
+
+		expect(screen.getByLabelText('Any value')).toBeChecked();
+	});
+
+	it('disables value scoping for query types that do not support it', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+		await user.click(await screen.findByText('ClickHouse SQL'));
+
+		expect(screen.getByTestId('wizard-value-input-logs-read')).toBeDisabled();
+		expect(screen.getByLabelText('Any value')).toBeDisabled();
+	});
+
+	it('clears the value when switching to a query type without key scoping', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.type(screen.getByTestId('wizard-value-input-logs-read'), '123');
+
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+		await user.click(await screen.findByText('ClickHouse SQL'));
+
+		expect(screen.getByTestId('wizard-value-input-logs-read')).toHaveValue('');
+		expect(screen.getByTestId('wizard-selector-input-logs-read')).toHaveValue(
+			'clickhouse_sql/*',
+		);
+
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await expect(
+			screen.findByText('clickhouse_sql/*'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('follows a hand-edited selector on the query type and value inputs', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const selectorInput = screen.getByTestId('wizard-selector-input-logs-read');
+		await user.clear(selectorInput);
+		await user.type(
+			selectorInput,
+			'clickhouse_sql/signoz.workspace.key.id/checkout',
+		);
+
+		const selectTrigger = screen.getByTestId(
+			'wizard-query-type-select-logs-read',
+		);
+		expect(within(selectTrigger).getByText('ClickHouse SQL')).toBeInTheDocument();
+		expect(screen.getByTestId('wizard-value-input-logs-read')).toHaveValue(
+			'checkout',
+		);
+	});
+
+	it('checks any resource when the selector is edited to a wildcard value', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const selectorInput = screen.getByTestId('wizard-selector-input-logs-read');
+		await user.clear(selectorInput);
+		await user.type(selectorInput, 'builder_query/signoz.workspace.key.id/*');
+
+		expect(screen.getByLabelText('Any value')).toBeChecked();
+	});
+
+	it('keeps the key input hardcoded when the selector uses another key', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const selectorInput = screen.getByTestId('wizard-selector-input-logs-read');
+		await user.clear(selectorInput);
+		await user.type(selectorInput, 'builder_query/service.name/frontend');
+
+		expect(screen.getByTestId('wizard-key-input-logs-read')).toHaveValue(
+			'signoz.workspace.key.id',
+		);
+		expect(
+			screen.getByTestId('wizard-selector-hint-logs-read'),
+		).toHaveTextContent('Allow service.name=frontend for Builder Query queries.');
+		expect(screen.getByTestId('wizard-add-btn-logs-read')).not.toBeDisabled();
+	});
+
+	it('restores the hardcoded key in the selector once the value changes', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const selectorInput = screen.getByTestId('wizard-selector-input-logs-read');
+		await user.clear(selectorInput);
+		await user.type(selectorInput, 'builder_query/service.name/frontend');
+
+		await user.type(screen.getByTestId('wizard-value-input-logs-read'), '2');
+
+		expect(selectorInput).toHaveValue(
+			'builder_query/signoz.workspace.key.id/frontend2',
+		);
+		expect(screen.getByTestId('wizard-add-btn-logs-read')).not.toBeDisabled();
+	});
+
+	it('blocks adding when the selector has an unknown query type', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const selectorInput = screen.getByTestId('wizard-selector-input-logs-read');
+		await user.clear(selectorInput);
+		await user.type(selectorInput, 'sql_query/*');
+
+		expect(
+			screen.getByTestId('wizard-selector-hint-logs-read'),
+		).toHaveTextContent('"sql_query" is not a supported query type.');
+		expect(screen.getByTestId('wizard-add-btn-logs-read')).toBeDisabled();
+	});
+
+	it('blocks adding when the selector is emptied', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.clear(screen.getByTestId('wizard-selector-input-logs-read'));
+
+		expect(
+			screen.getByTestId('wizard-selector-hint-logs-read'),
+		).toHaveTextContent('Enter a selector.');
+		expect(screen.getByTestId('wizard-add-btn-logs-read')).toBeDisabled();
+	});
+
+	it('adds the hand-edited selector verbatim', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		const selectorInput = screen.getByTestId('wizard-selector-input-logs-read');
+		await user.clear(selectorInput);
+		await user.type(selectorInput, 'builder_query/signoz.workspace.key.id/a/b');
+
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await expect(
+			screen.findByText('builder_query/signoz.workspace.key.id/a/b'),
+		).resolves.toBeInTheDocument();
+	});
+
+	it('closes dialog after adding selector', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await waitFor(() => {
+			expect(
+				screen.queryByTestId('telemetry-wizard-dialog-logs-read'),
+			).not.toBeInTheDocument();
+		});
+	});
+
+	it('does not add duplicate selectors', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		await user.click(screen.getByTestId('telemetry-wizard-trigger-logs-read'));
+		await screen.findByTestId('telemetry-wizard-dialog-logs-read');
+		await user.click(screen.getByTestId('wizard-add-btn-logs-read'));
+
+		const badges = screen.getAllByText('builder_query/*');
+		expect(badges).toHaveLength(1);
+	});
+
+	it('resets wizard state when dialog is closed and reopened', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.type(screen.getByTestId('wizard-value-input-logs-read'), '123');
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+		await user.click(await screen.findByText('ClickHouse SQL'));
+
+		await user.click(screen.getByRole('button', { name: /cancel/i }));
+
+		await waitFor(() => {
+			expect(
+				screen.queryByTestId('telemetry-wizard-dialog-logs-read'),
+			).not.toBeInTheDocument();
+		});
+
+		await user.click(screen.getByTestId('telemetry-wizard-trigger-logs-read'));
+		const selectTrigger = await screen.findByTestId(
+			'wizard-query-type-select-logs-read',
+		);
+
+		expect(within(selectTrigger).getByText('Builder Query')).toBeInTheDocument();
+		expect(screen.getByTestId('wizard-value-input-logs-read')).toHaveValue('');
+		expect(screen.getByTestId('wizard-selector-input-logs-read')).toHaveValue(
+			'builder_query/*',
+		);
+	});
+
+	it('previews the query-type wildcard while the value is empty', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		expect(screen.getByTestId('wizard-selector-input-logs-read')).toHaveValue(
+			'builder_query/*',
+		);
+		expect(
+			screen.getByTestId('wizard-selector-hint-logs-read'),
+		).toHaveTextContent('Allow every "Builder Query" query.');
+	});
+
+	it('describes a key-scoped selector', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.type(screen.getByTestId('wizard-value-input-logs-read'), '123');
+
+		expect(
+			screen.getByTestId('wizard-selector-hint-logs-read'),
+		).toHaveTextContent(
+			'Allow signoz.workspace.key.id=123 for Builder Query queries.',
+		);
+	});
+
+	it('describes an any-resource selector', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByLabelText('Any value'));
+
+		expect(
+			screen.getByTestId('wizard-selector-hint-logs-read'),
+		).toHaveTextContent(
+			'Allow every signoz.workspace.key.id for Builder Query queries.',
+		);
+	});
+
+	it('does not show query type descriptions', async () => {
+		const user = userEvent.setup();
+		await openLogsWizard(user);
+
+		await user.click(screen.getByTestId('wizard-query-type-select-logs-read'));
+
+		expect(
+			screen.queryByText(
+				'Visual query builder for selecting data sources, filters, and aggregations',
+			),
+		).not.toBeInTheDocument();
+	});
+});

frontend/src/container/RolesSettings/CreateEditRolePage/__tests__/testUtils.tsx

@@ -0,0 +1,33 @@
+import { Route, Switch } from 'react-router-dom';
+import ROUTES from 'constants/routes';
+import { render, screen, userEvent } from 'tests/test-utils';
+import { TooltipProvider } from '@signozhq/ui/tooltip';
+
+import CreateEditRolePage from '../CreateEditRolePage';
+
+export async function renderCreateRolePage(): Promise<
+	ReturnType<typeof render>
+> {
+	const result = render(
+		<TooltipProvider>
+			<Switch>
+				<Route path={ROUTES.ROLES_SETTINGS} exact>
+					<div data-testid="roles-list-redirect" />
+				</Route>
+				<Route path={ROUTES.ROLE_CREATE}>
+					<CreateEditRolePage />
+				</Route>
+			</Switch>
+		</TooltipProvider>,
+		undefined,
+		{ initialRoute: '/settings/roles/new' },
+	);
+	await screen.findByTestId('permission-editor');
+	return result;
+}
+
+export async function expandAllCards(): Promise<void> {
+	const user = userEvent.setup();
+	const expandButton = await screen.findByTestId('expand-all-button');
+	await user.click(expandButton);
+}

frontend/src/container/RolesSettings/CreateEditRolePage/components/ActionToggle.tsx

@@ -7,6 +7,7 @@ import { Typography } from '@signozhq/ui/typography';
 import { PermissionScope } from '../../types';
 import { getResourcePanel } from '../../permissions.config';
 import ItemInputSelector from './ItemInputSelector';
+import TelemetrySelectorWizard from './TelemetrySelectorWizard';
 
 import styles from './ActionToggle.module.scss';
 import { AuthZResource, AuthZVerb } from 'lib/authz/hooks/useAuthZ/types';
@@ -39,10 +40,13 @@ function ActionToggle({
 	onSelectedIdsChange,
 	hasError = false,
 }: ActionToggleProps): JSX.Element {
+	const panel = getResourcePanel(resource);
+
 	const [confirmDialogOpen, setConfirmDialogOpen] = useState(false);
 	const [pendingScope, setPendingScope] = useState<PermissionScope | null>(null);
 
 	const displayLabel = getActionLabel(action);
+	const selectorTestId = `${resource}-${action}`;
 
 	const scopeItems: Array<{ value: PermissionScope; label: string }> =
 		useMemo(() => {
@@ -121,11 +125,25 @@ function ActionToggle({
 						<Divider />
 
 						<ItemInputSelector
-							placeholder={getResourcePanel(resource).selectorPlaceholder}
+							placeholder={panel.selectorPlaceholder}
 							selectedIds={selectedIds}
 							onChange={onSelectedIdsChange}
-							docsAnchor={getResourcePanel(resource).docsAnchor}
+							testId={selectorTestId}
+							docsAnchor={panel.docsAnchor}
 							hasError={hasError}
+							prefixElement={
+								panel.selectorType === 'telemetryBuilder' ? (
+									<TelemetrySelectorWizard
+										resource={resource}
+										testId={selectorTestId}
+										onAdd={(selector): void => {
+											if (!selectedIds.includes(selector)) {
+												onSelectedIdsChange([...selectedIds, selector]);
+											}
+										}}
+									/>
+								) : null
+							}
 						/>
 					</div>
 				)}

frontend/src/container/RolesSettings/CreateEditRolePage/components/ItemInputSelector.module.scss

@@ -4,9 +4,10 @@
 	gap: var(--spacing-4);
 	background: var(--l1-background);
 	border: 1px solid var(--l1-border);
-	border-radius: 4px;
+	border-radius: var(--radius-2);
 	padding: var(--spacing-4);
 
+	--input-prefix-padding: var(--spacing-2);
 	--input-suffix-padding: var(--spacing-2);
 }
 
@@ -41,6 +42,11 @@
 	overflow-y: auto;
 }
 
+.itemInputSelectorBadge {
+	--badge-border-radius: 4px;
+	--badge-hover-background: var(--l2-background) !important;
+}
+
 .itemInputSelectorInfoIcon {
 	flex-shrink: 0;
 	color: var(--l2-foreground);
@@ -51,55 +57,7 @@
 	}
 }
 
-.itemInputSelectorBadge {
-	display: inline-flex;
-	align-items: center;
-	gap: 4px;
-	max-width: 140px;
-	padding: 2px 4px 2px 6px;
-	background: var(--l2-background);
-	border: 1px solid var(--l2-border);
-	border-radius: 4px;
-}
-
-.itemInputSelectorBadgeLabel {
-	flex: 1;
-	min-width: 0;
-}
-
-.itemInputSelectorBadgeRemove {
-	flex-shrink: 0;
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	width: 14px;
-	height: 14px;
-	padding: 0;
-	background: transparent;
-	border: none;
-	border-radius: 2px;
-	color: var(--l2-foreground);
-	cursor: pointer;
-	transition:
-		background 0.15s ease,
-		color 0.15s ease;
-
-	&:hover {
-		background: var(--l1-background);
-		color: var(--l1-foreground);
-	}
-}
-
 .itemInputSelectorHint {
 	margin: 0;
 	color: var(--l2-foreground);
-
-	a {
-		color: var(--primary);
-		text-decoration: none;
-
-		&:hover {
-			text-decoration: underline;
-		}
-	}
 }

frontend/src/container/RolesSettings/CreateEditRolePage/components/ItemInputSelector.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useRef, useState } from 'react';
-import { Info, Plus, X } from '@signozhq/icons';
+import { Info, Plus } from '@signozhq/icons';
+import { Badge } from '@signozhq/ui/badge';
 import { Button } from '@signozhq/ui/button';
 import { Input } from '@signozhq/ui/input';
 import { Typography } from '@signozhq/ui/typography';
@@ -15,8 +16,10 @@ export interface ItemInputSelectorProps {
 	placeholder: string;
 	selectedIds: string[];
 	onChange: (ids: string[]) => void;
+	testId: string;
 	docsAnchor?: string;
 	hasError?: boolean;
+	prefixElement?: React.ReactNode;
 }
 
 function parseInputValues(input: string): string[] {
@@ -30,11 +33,13 @@ function ItemInputSelector({
 	placeholder,
 	selectedIds,
 	onChange,
+	testId,
 	docsAnchor = 'role',
 	hasError = false,
+	prefixElement,
 }: ItemInputSelectorProps): JSX.Element {
 	const [inputValue, setInputValue] = useState('');
-	const footerRef = useRef<HTMLDivElement>(null);
+	const badgesRef = useRef<HTMLDivElement>(null);
 
 	const addValues = useCallback(
 		(input: string): void => {
@@ -87,26 +92,24 @@ function ItemInputSelector({
 		[selectedIds, onChange],
 	);
 
-	const handleBadgeKeyDown = useCallback(
-		(
-			e: React.KeyboardEvent<HTMLButtonElement>,
-			itemId: string,
-			index: number,
-		): void => {
-			if (e.key !== 'Enter' && e.key !== ' ') {
-				return;
-			}
-
+	const handleBadgeClose = useCallback(
+		(e: React.MouseEvent, itemId: string, index: number): void => {
 			e.preventDefault();
 			handleRemove(itemId);
 
+			// Activating a button via Enter/Space reports detail 0;
+			// a real click reports 1 or more
+			// Only trigger focus when using keyboard
+			const isKeyboardActivation = e.detail === 0;
+
+			if (!isKeyboardActivation) {
+				return;
+			}
+
 			const targetIndex = index > 0 ? index - 1 : 0;
 			requestAnimationFrame(() => {
-				const buttons = footerRef.current?.querySelectorAll('button');
-				const targetButton = buttons?.[targetIndex] as
-					| HTMLButtonElement
-					| undefined;
-				targetButton?.focus();
+				const buttons = badgesRef.current?.querySelectorAll('button');
+				buttons?.[targetIndex]?.focus();
 			});
 		},
 		[handleRemove],
@@ -120,7 +123,7 @@ function ItemInputSelector({
 				styles.itemInputSelector,
 				showError ? styles.itemInputSelectorError : '',
 			)}
-			data-testid="item-input-selector"
+			data-testid={`item-input-selector-${testId}`}
 		>
 			<Input
 				placeholder={placeholder}
@@ -128,14 +131,15 @@ function ItemInputSelector({
 				onChange={handleInputChange}
 				onKeyDown={handleInputKeyDown}
 				onBlur={handleInputBlur}
-				data-testid="item-input-selector-input"
+				data-testid={`item-input-selector-input-${testId}`}
+				prefix={prefixElement}
 				suffix={
 					<Button
 						variant="solid"
 						size="sm"
 						onClick={handleAddClick}
 						disabled={!inputValue.trim()}
-						data-testid="item-input-selector-add-btn"
+						data-testid={`item-input-selector-add-btn-${testId}`}
 					>
 						<Plus size={14} />
 						Add
@@ -144,28 +148,22 @@ function ItemInputSelector({
 			/>
 
 			{selectedIds.length > 0 ? (
-				<div ref={footerRef} className={styles.itemInputSelectorFooter}>
-					<div className={styles.itemInputSelectorBadges}>
+				<div className={styles.itemInputSelectorFooter}>
+					<div ref={badgesRef} className={styles.itemInputSelectorBadges}>
 						{selectedIds.map((id, index) => (
-							<span key={id} className={styles.itemInputSelectorBadge} title={id}>
-								<Typography
-									as="span"
-									size="small"
-									truncate={1}
-									className={styles.itemInputSelectorBadgeLabel}
-								>
+							<Badge
+								key={id}
+								color="secondary"
+								className={styles.itemInputSelectorBadge}
+								testId={`item-badge-${testId}-${index}`}
+								closable
+								closeAriaLabel={`Remove ${id}`}
+								onClose={(e): void => handleBadgeClose(e, id, index)}
+							>
+								<Typography as="span" size="small" truncate={1} title={id}>
 									{id}
 								</Typography>
-								<button
-									type="button"
-									className={styles.itemInputSelectorBadgeRemove}
-									onClick={(): void => handleRemove(id)}
-									onKeyDown={(e): void => handleBadgeKeyDown(e, id, index)}
-									aria-label={`Remove ${id}`}
-								>
-									<X size={10} />
-								</button>
-							</span>
+							</Badge>
 						))}
 					</div>
 					<TooltipSimple

frontend/src/container/RolesSettings/CreateEditRolePage/components/TelemetrySelectorWizard.constants.ts

@@ -0,0 +1,50 @@
+// intentionally omitting few query types
+// from pkg/types/querybuildertypes/querybuildertypesv5/query_type.go
+export type QueryTypeId = 'builder_query' | 'promql' | 'clickhouse_sql';
+
+export interface QueryTypeOption {
+	id: QueryTypeId;
+	label: string;
+	supportsKeyScoping: boolean;
+	metricsOnly?: boolean;
+}
+
+export const QUERY_TYPES: readonly QueryTypeOption[] = [
+	{
+		id: 'builder_query',
+		label: 'Builder Query',
+		supportsKeyScoping: true,
+	},
+	{
+		id: 'promql',
+		label: 'PromQL',
+		supportsKeyScoping: false,
+		metricsOnly: true,
+	},
+	{
+		id: 'clickhouse_sql',
+		label: 'ClickHouse SQL',
+		supportsKeyScoping: false,
+	},
+] as const;
+
+export const DEFAULT_QUERY_TYPE: QueryTypeId = 'builder_query';
+
+export const SUPPORTED_GRANT_KEY = 'signoz.workspace.key.id';
+
+export const ANY_RESOURCE_VALUE = '*';
+
+export interface SelectorDraft {
+	queryType: QueryTypeId;
+	value: string;
+}
+
+export interface ParsedSelector {
+	queryType?: QueryTypeId;
+	value: string;
+}
+
+export interface SelectorValidation {
+	message: string;
+	isError: boolean;
+}

frontend/src/container/RolesSettings/CreateEditRolePage/components/TelemetrySelectorWizard.module.scss

@@ -0,0 +1,52 @@
+.wizardDialog {
+	border-color: var(--l1-border);
+
+	--select-trigger-background-color: var(--l3-background);
+	--select-trigger-border-color: var(--l3-background);
+	--select-content-background: var(--l3-background);
+	--select-item-highlight-background: var(--l3-background-hover);
+	--select-trigger-outline-width: 1px;
+	--select-trigger-outline-offset: 0px;
+
+	--input-background: var(--l3-background);
+	--input-hover-background: var(--l3-background);
+	--input-focus-background: var(--l3-background);
+	--input-disabled-background: var(--l3-background);
+	--input-border-color: var(--l3-border);
+	--input-hover-border-color: var(--l3-border);
+	--input-focus-border-color: var(--l3-border);
+
+	outline: none;
+
+	& > div {
+		background-color: var(--l2-background);
+	}
+}
+
+.wizardBody {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-6);
+}
+
+.wizardField {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-2);
+}
+
+.wizardValueRow {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-3);
+}
+
+.wizardValueInput {
+	flex: 1;
+	min-width: 0;
+}
+
+.selectContent {
+	z-index: 10;
+	background-color: var(--l3-background);
+}

frontend/src/container/RolesSettings/CreateEditRolePage/components/TelemetrySelectorWizard.tsx

@@ -0,0 +1,190 @@
+import { Wand } from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { Checkbox } from '@signozhq/ui/checkbox';
+import { DialogWrapper } from '@signozhq/ui/dialog';
+import { Input } from '@signozhq/ui/input';
+import {
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+} from '@signozhq/ui/select';
+import { Typography } from '@signozhq/ui/typography';
+
+import {
+	ANY_RESOURCE_VALUE,
+	QUERY_TYPES,
+	SUPPORTED_GRANT_KEY,
+} from './TelemetrySelectorWizard.constants';
+import { isQueryTypeAvailable } from './TelemetrySelectorWizard.utils';
+import useTelemetrySelectorWizard from './useTelemetrySelectorWizard';
+
+import styles from './TelemetrySelectorWizard.module.scss';
+import { AuthZResource } from 'lib/authz/hooks/useAuthZ/types';
+
+interface TelemetrySelectorWizardProps {
+	onAdd: (selector: string) => void;
+	resource: AuthZResource;
+	testId: string;
+}
+
+function TelemetrySelectorWizard({
+	onAdd,
+	resource,
+	testId,
+}: TelemetrySelectorWizardProps): JSX.Element {
+	const {
+		open,
+		queryType,
+		selectedQueryType,
+		value,
+		selector,
+		isAnyResource,
+		supportsKeyScoping,
+		validation,
+		canAdd,
+		handleOpenChange,
+		handleQueryTypeChange,
+		handleValueChange,
+		handleAnyResourceChange,
+		handleSelectorChange,
+		handleAdd,
+		handleInputKeyDown,
+	} = useTelemetrySelectorWizard({ onAdd });
+
+	const trigger = (
+		<Button
+			variant="solid"
+			size="sm"
+			data-testid={`telemetry-wizard-trigger-${testId}`}
+		>
+			<Wand size={14} />
+			Wizard
+		</Button>
+	);
+
+	const footer = (
+		<>
+			<Button
+				variant="ghost"
+				color="secondary"
+				onClick={(): void => handleOpenChange(false)}
+			>
+				Cancel
+			</Button>
+			<Button
+				variant="solid"
+				onClick={handleAdd}
+				disabled={!canAdd}
+				data-testid={`wizard-add-btn-${testId}`}
+			>
+				Add Selector
+			</Button>
+		</>
+	);
+
+	return (
+		<DialogWrapper
+			open={open}
+			onOpenChange={handleOpenChange}
+			title="Selector Wizard"
+			width="wide"
+			testId={`telemetry-wizard-dialog-${testId}`}
+			trigger={trigger}
+			footer={footer}
+			className={styles.wizardDialog}
+		>
+			<div className={styles.wizardBody}>
+				<div className={styles.wizardField}>
+					<Typography as="label" weight="medium">
+						Query Type
+					</Typography>
+					<Select value={queryType} onChange={handleQueryTypeChange}>
+						<SelectTrigger data-testid={`wizard-query-type-select-${testId}`}>
+							<SelectValue>{selectedQueryType?.label}</SelectValue>
+						</SelectTrigger>
+						<SelectContent withPortal={false} className={styles.selectContent}>
+							{QUERY_TYPES.filter((queryTypeOption) =>
+								isQueryTypeAvailable(queryTypeOption, resource),
+							).map((queryTypeOption) => (
+								<SelectItem
+									key={queryTypeOption.id}
+									value={queryTypeOption.id}
+									testId={`wizard-query-type-option-${queryTypeOption.id}-${testId}`}
+								>
+									{queryTypeOption.label}
+								</SelectItem>
+							))}
+						</SelectContent>
+					</Select>
+				</div>
+
+				{supportsKeyScoping && (
+					<div className={styles.wizardField}>
+						<Typography as="label" weight="medium">
+							Key
+						</Typography>
+						<Input
+							value={SUPPORTED_GRANT_KEY}
+							readOnly
+							disabled
+							testId={`wizard-key-input-${testId}`}
+						/>
+					</div>
+				)}
+
+				<div className={styles.wizardField}>
+					<Typography as="label" weight="medium">
+						Value
+					</Typography>
+					<div className={styles.wizardValueRow}>
+						<Input
+							className={styles.wizardValueInput}
+							placeholder={
+								supportsKeyScoping
+									? 'Value or leave empty to allow every query'
+									: ANY_RESOURCE_VALUE
+							}
+							value={value}
+							disabled={!supportsKeyScoping}
+							onChange={handleValueChange}
+							onKeyDown={handleInputKeyDown}
+							testId={`wizard-value-input-${testId}`}
+						/>
+						<Checkbox
+							id={`wizard-any-resource-${testId}`}
+							value={isAnyResource}
+							disabled={!supportsKeyScoping}
+							onChange={(checked): void => handleAnyResourceChange(checked === true)}
+							testId={`wizard-any-resource-checkbox-${testId}`}
+						>
+							Any value
+						</Checkbox>
+					</div>
+				</div>
+
+				<div className={styles.wizardField}>
+					<Typography as="label" weight="medium">
+						Selector
+					</Typography>
+					<Input
+						value={selector}
+						onChange={handleSelectorChange}
+						onKeyDown={handleInputKeyDown}
+						testId={`wizard-selector-input-${testId}`}
+					/>
+					<Typography.Text
+						size="small"
+						color={validation.isError ? 'danger' : 'muted'}
+						testId={`wizard-selector-hint-${testId}`}
+					>
+						{validation.message}
+					</Typography.Text>
+				</div>
+			</div>
+		</DialogWrapper>
+	);
+}
+
+export default TelemetrySelectorWizard;

frontend/src/container/RolesSettings/CreateEditRolePage/components/TelemetrySelectorWizard.utils.ts

@@ -0,0 +1,139 @@
+import { AuthZResource } from 'lib/authz/hooks/useAuthZ/types';
+
+import {
+	ANY_RESOURCE_VALUE,
+	ParsedSelector,
+	QUERY_TYPES,
+	QueryTypeId,
+	QueryTypeOption,
+	SelectorDraft,
+	SelectorValidation,
+	SUPPORTED_GRANT_KEY,
+} from './TelemetrySelectorWizard.constants';
+
+const METRIC_RESOURCES: ReadonlySet<AuthZResource> = new Set<AuthZResource>([
+	'metrics',
+	'meter-metrics',
+]);
+
+export function getQueryTypeOption(
+	queryType: string,
+): QueryTypeOption | undefined {
+	return QUERY_TYPES.find((option) => option.id === queryType);
+}
+
+export function isQueryTypeAvailable(
+	option: QueryTypeOption,
+	resource: AuthZResource,
+): boolean {
+	return !option.metricsOnly || METRIC_RESOURCES.has(resource);
+}
+
+export function supportsKeyScoping(queryType: string): boolean {
+	return getQueryTypeOption(queryType)?.supportsKeyScoping ?? false;
+}
+
+export function isAnyResourceValue(value: string): boolean {
+	return value.trim() === ANY_RESOURCE_VALUE;
+}
+
+function splitSelector(selector: string): string[] {
+	const parts = selector.split('/');
+
+	if (parts.length <= 3) {
+		return parts;
+	}
+
+	return [parts[0], parts[1], parts.slice(2).join('/')];
+}
+
+export function buildSelector({ queryType, value }: SelectorDraft): string {
+	const trimmedValue = value.trim();
+
+	if (!supportsKeyScoping(queryType) || !trimmedValue) {
+		return `${queryType}/${ANY_RESOURCE_VALUE}`;
+	}
+
+	return `${queryType}/${SUPPORTED_GRANT_KEY}/${trimmedValue}`;
+}
+
+export function parseSelector(selector: string): ParsedSelector {
+	const parts = splitSelector(selector.trim());
+
+	return {
+		queryType: getQueryTypeOption(parts[0])?.id,
+		value: parts.length >= 3 ? parts[2] : '',
+	};
+}
+
+/**
+ * This does a basic validation, intentionally omitting deep validations since this is to be made at backend,
+ * so this will allow to produce invalid selectors, and the validation will be done after the user try to save
+ */
+export function validateSelector(selector: string): SelectorValidation {
+	const trimmed = selector.trim();
+
+	if (!trimmed) {
+		return { message: 'Enter a selector.', isError: true };
+	}
+
+	if (trimmed === ANY_RESOURCE_VALUE) {
+		return { message: 'Allow every query of every type.', isError: false };
+	}
+
+	const parts = splitSelector(trimmed);
+	const option = getQueryTypeOption(parts[0]);
+
+	if (!option) {
+		return {
+			message: `"${parts[0]}" is not a supported query type.`,
+			isError: true,
+		};
+	}
+
+	if (parts.length < 3) {
+		if (parts.length === 2 && parts[1] !== ANY_RESOURCE_VALUE) {
+			if (!option.supportsKeyScoping) {
+				return {
+					message: `This query type does not support key scoping. Use ${option.id}/*`,
+					isError: false, // intentionally not an error
+				};
+			}
+
+			return {
+				message: `Use <query-type>/${ANY_RESOURCE_VALUE} or <query-type>/${SUPPORTED_GRANT_KEY}/<value>.`,
+				isError: false, // intentionally not an error
+			};
+		}
+
+		return {
+			message: `Allow every "${option.label}" query.`,
+			isError: false,
+		};
+	}
+
+	const [, key, value] = parts;
+
+	if (value === ANY_RESOURCE_VALUE) {
+		return {
+			message: `Allow every ${key} for ${option.label} queries.`,
+			isError: false,
+		};
+	}
+
+	if (!option.supportsKeyScoping) {
+		return {
+			message: `This query type does not support key scoping. Use ${option.id}/*`,
+			isError: false, // intentionally not an error
+		};
+	}
+
+	return {
+		message: `Allow ${key}=${value} for ${option.label} queries.`,
+		isError: false,
+	};
+}
+
+export function getDefaultSelector(queryType: QueryTypeId): string {
+	return buildSelector({ queryType, value: '' });
+}

frontend/src/container/RolesSettings/CreateEditRolePage/components/jsonSchema.config.ts

@@ -76,9 +76,10 @@ function createGrantPermissionAsReadonly(
 	return {
 		label: 'readonly',
 		insertText: resources
-			.filter(
-				(r) => r.allowedVerbs.includes('read') || r.allowedVerbs.includes('list'),
-			)
+			.filter((r) => {
+				const verbs: readonly string[] = r.allowedVerbs;
+				return verbs.includes('read') || verbs.includes('list');
+			})
 			.flatMap((r) => {
 				const verbs = r.allowedVerbs.filter((v) => v === 'read' || v === 'list');
 				return verbs.map(
@@ -103,7 +104,12 @@ function buildResourceSnippets(): SnippetDef[] {
 	for (const resource of resources) {
 		const { kind, type, allowedVerbs } = resource;
 
-		snippets.push(createGrantAllPermissionSnippet(kind, allowedVerbs, type));
+		// If only one verb is supported, no point on add grant all
+		// that will only add one permission at time, just leave the verb snippet
+		// and it will look cleaner
+		if (allowedVerbs.length > 1) {
+			snippets.push(createGrantAllPermissionSnippet(kind, allowedVerbs, type));
+		}
 
 		for (const verb of allowedVerbs) {
 			snippets.push(createGrantPermissionToVerbAndKind(kind, verb, type));

frontend/src/container/RolesSettings/CreateEditRolePage/components/useTelemetrySelectorWizard.ts

@@ -0,0 +1,157 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import {
+	ANY_RESOURCE_VALUE,
+	DEFAULT_QUERY_TYPE,
+	QueryTypeId,
+	QueryTypeOption,
+	SelectorValidation,
+} from './TelemetrySelectorWizard.constants';
+import {
+	buildSelector,
+	getDefaultSelector,
+	getQueryTypeOption,
+	isAnyResourceValue,
+	parseSelector,
+	validateSelector,
+} from './TelemetrySelectorWizard.utils';
+
+interface UseTelemetrySelectorWizardParams {
+	onAdd: (selector: string) => void;
+}
+
+interface UseTelemetrySelectorWizardResult {
+	open: boolean;
+	queryType: QueryTypeId;
+	selectedQueryType: QueryTypeOption | undefined;
+	value: string;
+	selector: string;
+	isAnyResource: boolean;
+	supportsKeyScoping: boolean;
+	validation: SelectorValidation;
+	canAdd: boolean;
+	handleOpenChange: (nextOpen: boolean) => void;
+	handleQueryTypeChange: (value: string | string[]) => void;
+	handleValueChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+	handleAnyResourceChange: (checked: boolean) => void;
+	handleSelectorChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+	handleAdd: () => void;
+	handleInputKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+}
+
+function useTelemetrySelectorWizard({
+	onAdd,
+}: UseTelemetrySelectorWizardParams): UseTelemetrySelectorWizardResult {
+	const [open, setOpen] = useState(false);
+	const [queryType, setQueryType] = useState<QueryTypeId>(DEFAULT_QUERY_TYPE);
+	const [value, setValue] = useState('');
+	const [selector, setSelector] = useState(() =>
+		getDefaultSelector(DEFAULT_QUERY_TYPE),
+	);
+
+	const selectedQueryType = useMemo(
+		() => getQueryTypeOption(queryType),
+		[queryType],
+	);
+	const supportsKeyScoping = selectedQueryType?.supportsKeyScoping ?? false;
+
+	const validation = useMemo(() => validateSelector(selector), [selector]);
+
+	const applyDraft = useCallback(
+		(nextQueryType: QueryTypeId, nextValue: string): void => {
+			setQueryType(nextQueryType);
+			setValue(nextValue);
+			setSelector(buildSelector({ queryType: nextQueryType, value: nextValue }));
+		},
+		[],
+	);
+
+	const handleQueryTypeChange = useCallback(
+		(next: string | string[]): void => {
+			const selected = (Array.isArray(next) ? next[0] : next) as QueryTypeId;
+			const keepsValue = getQueryTypeOption(selected)?.supportsKeyScoping ?? false;
+
+			applyDraft(selected, keepsValue ? value : '');
+		},
+		[applyDraft, value],
+	);
+
+	const handleValueChange = useCallback(
+		(event: React.ChangeEvent<HTMLInputElement>): void => {
+			applyDraft(queryType, event.target.value);
+		},
+		[applyDraft, queryType],
+	);
+
+	const handleAnyResourceChange = useCallback(
+		(checked: boolean): void => {
+			applyDraft(queryType, checked ? ANY_RESOURCE_VALUE : '');
+		},
+		[applyDraft, queryType],
+	);
+
+	const handleSelectorChange = useCallback(
+		(event: React.ChangeEvent<HTMLInputElement>): void => {
+			const nextSelector = event.target.value;
+			setSelector(nextSelector);
+
+			const parsed = parseSelector(nextSelector);
+			if (parsed.queryType) {
+				setQueryType(parsed.queryType);
+			}
+			setValue(parsed.value);
+		},
+		[],
+	);
+
+	const handleOpenChange = useCallback((nextOpen: boolean): void => {
+		setOpen(nextOpen);
+
+		if (!nextOpen) {
+			setQueryType(DEFAULT_QUERY_TYPE);
+			setValue('');
+			setSelector(getDefaultSelector(DEFAULT_QUERY_TYPE));
+		}
+	}, []);
+
+	const handleAdd = useCallback((): void => {
+		const trimmed = selector.trim();
+
+		if (validateSelector(trimmed).isError) {
+			return;
+		}
+
+		onAdd(trimmed);
+		handleOpenChange(false);
+	}, [selector, onAdd, handleOpenChange]);
+
+	const handleInputKeyDown = useCallback(
+		(event: React.KeyboardEvent<HTMLInputElement>): void => {
+			if (event.key === 'Enter') {
+				handleAdd();
+			}
+		},
+		[handleAdd],
+	);
+
+	return {
+		open,
+		queryType,
+		selectedQueryType,
+		value,
+		selector,
+		isAnyResource: isAnyResourceValue(value),
+		supportsKeyScoping,
+		validation,
+		canAdd: !validation.isError,
+		handleOpenChange,
+		handleQueryTypeChange,
+		handleValueChange,
+		handleAnyResourceChange,
+		handleSelectorChange,
+		handleAdd,
+		handleInputKeyDown,
+	};
+}
+
+export default useTelemetrySelectorWizard;

frontend/src/container/RolesSettings/hooks/__tests__/useRolePermissions.test.ts

@@ -329,11 +329,15 @@ describe('transformTransactionGroupsToResourcePermissions', () => {
 	it('returns all resources from RESOURCE_ORDER even with empty transaction groups', () => {
 		const result = transformTransactionGroupsToResourcePermissions([]);
 
-		expect(result).toHaveLength(3);
+		expect(result).toHaveLength(7);
 		expect(result.map((r) => r.resourceKind)).toStrictEqual([
 			'factor-api-key',
 			'role',
 			'serviceaccount',
+			'logs',
+			'traces',
+			'metrics',
+			'meter-metrics',
 		]);
 	});
 
@@ -414,11 +418,15 @@ describe('createEmptyRolePermissions', () => {
 	it('creates permissions for all resources in RESOURCE_ORDER', () => {
 		const result = createEmptyRolePermissions();
 
-		expect(result).toHaveLength(3);
+		expect(result).toHaveLength(7);
 		expect(result.map((r) => r.resourceKind)).toStrictEqual([
 			'factor-api-key',
 			'role',
 			'serviceaccount',
+			'logs',
+			'traces',
+			'metrics',
+			'meter-metrics',
 		]);
 	});
 

frontend/src/container/RolesSettings/permissions.config.ts

@@ -1,4 +1,12 @@
-import { Bot, Key, Shield } from '@signozhq/icons';
+import {
+	Bot,
+	ChartLine,
+	DraftingCompass,
+	Gauge,
+	Key,
+	Logs,
+	Shield,
+} from '@signozhq/icons';
 
 import permissionsType from 'lib/authz/hooks/useAuthZ/permissions.type';
 import {
@@ -14,12 +22,15 @@ type IconComponent = typeof Shield;
 
 const OBJECT_SCOPED_VERB_SET = new Set<string>(OBJECT_SCOPED_VERBS);
 
+export type SelectorType = 'input' | 'telemetryBuilder';
+
 export interface ResourcePanelConfig {
 	label: string;
 	description: string;
 	icon: IconComponent;
 	selectorPlaceholder: string;
 	docsAnchor: string;
+	selectorType?: SelectorType;
 }
 
 /**
@@ -50,6 +61,42 @@ export const RESOURCE_PANELS: Record<AuthZResource, ResourcePanelConfig> = {
 			'Type service account ID, separate multiple with comma or space',
 		docsAnchor: 'service-account',
 	},
+	logs: {
+		label: 'Logs',
+		description: 'Log data collected across the workspace.',
+		icon: Logs,
+		selectorPlaceholder:
+			'Enter selector as <query-type>/<key>/<value> or <query-type>/* or use wizard...',
+		docsAnchor: 'logs',
+		selectorType: 'telemetryBuilder',
+	},
+	traces: {
+		label: 'Traces',
+		description: 'Distributed tracing data collected across the workspace.',
+		icon: DraftingCompass,
+		selectorPlaceholder:
+			'Enter selector as <query-type>/<key>/<value> or <query-type>/* or use wizard...',
+		docsAnchor: 'traces',
+		selectorType: 'telemetryBuilder',
+	},
+	metrics: {
+		label: 'Metrics',
+		description: 'Metric data collected across the workspace.',
+		icon: ChartLine,
+		selectorPlaceholder:
+			'Enter selector as <query-type>/<key>/<value> or <query-type>/* or use wizard...',
+		docsAnchor: 'metrics',
+		selectorType: 'telemetryBuilder',
+	},
+	'meter-metrics': {
+		label: 'Meter Metrics',
+		description: 'Usage metering data for the workspace.',
+		icon: Gauge,
+		selectorPlaceholder:
+			'Enter selector as <query-type>/<key>/<value> or <query-type>/* or use wizard...',
+		docsAnchor: 'meter-metrics',
+		selectorType: 'telemetryBuilder',
+	},
 };
 
 export const RESOURCE_ORDER = Object.keys(RESOURCE_PANELS) as AuthZResource[];

frontend/src/container/RoutingPolicies/__tests__/testUtils.ts

@@ -108,6 +108,7 @@ export function getAppContextMockState(
 		isFetchingHosts: false,
 		isFetchingFeatureFlags: false,
 		isFetchingOrgPreferences: false,
+		isFetchingUserPreferences: false,
 		userFetchError: undefined,
 		activeLicenseFetchError: null,
 		hostsFetchError: undefined,

frontend/src/container/SideNav/SideNav.tsx

@@ -144,6 +144,7 @@ function SideNav({ isPinned }: { isPinned: boolean }): JSX.Element {
 		trialInfo,
 		isLoggedIn,
 		userPreferences,
+		isFetchingUserPreferences,
 		changelog,
 		toggleChangelogModal,
 		updateUserPreferenceInContext,
@@ -261,6 +262,11 @@ function SideNav({ isPinned }: { isPinned: boolean }): JSX.Element {
 
 	// Compute initial pinned items and secondary menu items synchronously to avoid flash
 	const computedPinnedMenuItems = useMemo(() => {
+		// While loading, return empty to avoid flash
+		if (isFetchingUserPreferences) {
+			return [];
+		}
+
 		const navShortcutsPreference = userPreferences?.find(
 			(preference) => preference.name === USER_PREFERENCES.NAV_SHORTCUTS,
 		);
@@ -268,11 +274,6 @@ function SideNav({ isPinned }: { isPinned: boolean }): JSX.Element {
 			| string[]
 			| undefined;
 
-		// If userPreferences not loaded yet, return empty to avoid showing defaults before preferences load
-		if (userPreferences === null) {
-			return [];
-		}
-
 		// If preference exists with non-empty array, use stored shortcuts
 		if (isArray(navShortcuts) && navShortcuts.length > 0) {
 			return navShortcuts
@@ -282,9 +283,9 @@ function SideNav({ isPinned }: { isPinned: boolean }): JSX.Element {
 				.filter((item): item is SidebarItem => item !== undefined);
 		}
 
-		// No preference, or empty array → use defaults
+		// No preference, or empty array, or error loading → use defaults
 		return defaultMoreMenuItems.filter((item) => item.isPinned);
-	}, [userPreferences]);
+	}, [isFetchingUserPreferences, userPreferences]);
 
 	const computedSecondaryMenuItems = useMemo(() => {
 		const shouldShowIntegrationsValue =
@@ -322,12 +323,16 @@ function SideNav({ isPinned }: { isPinned: boolean }): JSX.Element {
 	// Sync state only on initial load when userPreferences first becomes available
 	useEffect(() => {
 		// Only sync once: when userPreferences loads for the first time
-		if (!hasInitializedRef.current && userPreferences !== null) {
+		if (!hasInitializedRef.current && isFetchingUserPreferences === false) {
 			setPinnedMenuItems(computedPinnedMenuItems);
 			setSecondaryMenuItems(computedSecondaryMenuItems);
 			hasInitializedRef.current = true;
 		}
-	}, [computedPinnedMenuItems, computedSecondaryMenuItems, userPreferences]);
+	}, [
+		computedPinnedMenuItems,
+		computedSecondaryMenuItems,
+		isFetchingUserPreferences,
+	]);
 
 	const isChatSupportEnabled = featureFlags?.find(
 		(flag) => flag.name === FeatureKeys.CHAT_SUPPORT,

frontend/src/hooks/useCopyToClipboard.ts

@@ -1,62 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-const DEFAULT_COPIED_RESET_MS = 2000;
-
-export interface UseCopyToClipboardOptions {
-	/** How long (ms) to keep "copied" state before resetting. Default 2000. */
-	copiedResetMs?: number;
-}
-
-export type ID = number | string | null;
-
-export interface UseCopyToClipboardReturn {
-	/** Copy text to clipboard. Pass an optional id to track which item was copied (e.g. seriesIndex). */
-	copyToClipboard: (text: string, id?: ID) => void;
-	/** True when something was just copied and still within the reset threshold. */
-	isCopied: boolean;
-	/** The id passed to the last successful copy, or null after reset. Use to show "copied" state for a specific item (e.g. copiedId === item.seriesIndex). */
-	id: ID;
-}
-
-export function useCopyToClipboard(
-	options: UseCopyToClipboardOptions = {},
-): UseCopyToClipboardReturn {
-	const { copiedResetMs = DEFAULT_COPIED_RESET_MS } = options;
-	const [state, setState] = useState<{ isCopied: boolean; id: ID }>({
-		isCopied: false,
-		id: null,
-	});
-	const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-	useEffect(() => {
-		return (): void => {
-			if (timeoutRef.current) {
-				clearTimeout(timeoutRef.current);
-				timeoutRef.current = null;
-			}
-		};
-	}, []);
-
-	const copyToClipboard = useCallback(
-		(text: string, id?: ID): void => {
-			// oxlint-disable-next-line signoz/no-navigator-clipboard
-			navigator.clipboard.writeText(text).then(() => {
-				if (timeoutRef.current) {
-					clearTimeout(timeoutRef.current);
-				}
-				setState({ isCopied: true, id: id ?? null });
-				timeoutRef.current = setTimeout(() => {
-					setState({ isCopied: false, id: null });
-					timeoutRef.current = null;
-				}, copiedResetMs);
-			});
-		},
-		[copiedResetMs],
-	);
-
-	return {
-		copyToClipboard,
-		isCopied: state.isCopied,
-		id: state.id,
-	};
-}

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

@@ -19,7 +19,7 @@ describe('PermissionDeniedCallout', () => {
 	it('renders multiple denied permissions', () => {
 		const deniedPermissions = [
 			buildPermission('read', buildObjectString('serviceaccount', '*')),
-			buildPermission('update', buildObjectString('role', 'admin')),
+			buildPermission('update', buildObjectString<'update'>('role', 'admin')),
 		];
 		render(<PermissionDeniedCallout deniedPermissions={deniedPermissions} />);
 

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

@@ -20,7 +20,7 @@ describe('PermissionDeniedFullPage', () => {
 	it('renders with multiple denied permissions', () => {
 		const deniedPermissions = [
 			buildPermission('read', buildObjectString('role', 'admin')),
-			buildPermission('update', buildObjectString('role', 'admin')),
+			buildPermission('update', buildObjectString<'update'>('role', 'admin')),
 		];
 		render(<PermissionDeniedFullPage deniedPermissions={deniedPermissions} />);
 		expect(screen.getByText(/read:role:admin/)).toBeInTheDocument();

frontend/src/lib/authz/hooks/useAuthZ/permissions.type.ts

@@ -35,6 +35,26 @@ export default {
 					'update',
 				],
 			},
+			{
+				kind: 'logs',
+				type: 'telemetryresource',
+				allowedVerbs: ['read'],
+			},
+			{
+				kind: 'meter-metrics',
+				type: 'telemetryresource',
+				allowedVerbs: ['read'],
+			},
+			{
+				kind: 'metrics',
+				type: 'telemetryresource',
+				allowedVerbs: ['read'],
+			},
+			{
+				kind: 'traces',
+				type: 'telemetryresource',
+				allowedVerbs: ['read'],
+			},
 		],
 		relations: {
 			assignee: ['role'],
@@ -43,7 +63,7 @@ export default {
 			delete: ['metaresource', 'role', 'serviceaccount'],
 			detach: ['metaresource', 'role', 'serviceaccount'],
 			list: ['metaresource', 'role', 'serviceaccount'],
-			read: ['metaresource', 'role', 'serviceaccount'],
+			read: ['metaresource', 'role', 'serviceaccount', 'telemetryresource'],
 			update: ['metaresource', 'role', 'serviceaccount'],
 		},
 	},

frontend/src/lib/authz/hooks/useAuthZ/utils.ts

@@ -23,6 +23,40 @@ export function buildPermission<R extends AuthZRelation>(
 	return `${relation}${PermissionSeparator}${object}` as BrandedPermission;
 }
 
+/**
+ * Builds an object string for use with `buildPermission`.
+ *
+ * ## Type Inference Behavior
+ *
+ * TypeScript infers `R` from `resource`. If a resource belongs to multiple relations,
+ * the return type becomes a union of all matching `AuthZObject` types.
+ *
+ * Example: 'role' is valid for 'read', 'update', 'delete', 'assignee'.
+ * Without explicit generic, return type = `AuthZObject<'read' | 'update' | 'delete' | 'assignee'>`.
+ *
+ * ## When to specify explicit generic
+ *
+ * **Needed** when resource belongs to multiple relations AND you pass result to `buildPermission`
+ * with a relation that has FEWER valid resources than others:
+ *
+ * ```ts
+ * // ERROR: 'read' includes telemetry resources, 'update' does not
+ * buildPermission('update', buildObjectString('role', 'admin'))
+ *
+ * // OK: explicit generic narrows return type
+ * buildPermission('update', buildObjectString<'update'>('role', 'admin'))
+ * ```
+ *
+ * **Not needed** when:
+ * - Resource only belongs to one relation in the constraint
+ * - Using with 'read' relation (widest type, accepts all)
+ * - Storing in a variable typed as `BrandedPermission` (already opaque)
+ *
+ * ```ts
+ * // OK: 'read' is widest, accepts union return type
+ * buildPermission('read', buildObjectString('role', 'admin'))
+ * ```
+ */
 export function buildObjectString<
 	R extends 'delete' | 'read' | 'update' | 'assignee',
 >(resource: ResourcesForRelation<R>, objectId: string): AuthZObject<R> {

frontend/src/lib/uPlotV2/components/Legend/Legend.tsx

@@ -1,13 +1,11 @@
 import { useCallback, useMemo, useRef, useState } from 'react';
 import { VirtuosoGrid } from 'react-virtuoso';
 import { Input } from 'antd';
-import { Button } from '@signozhq/ui/button';
 import { TooltipSimple } from '@signozhq/ui/tooltip';
 import cx from 'classnames';
-import { useCopyToClipboard } from 'hooks/useCopyToClipboard';
 import { useResizeObserver } from 'hooks/useDimensions';
 import { LegendItem } from 'lib/uPlotV2/config/types';
-import { Check, Copy } from '@signozhq/icons';
+import CopyButton from 'periscope/components/CopyButton/CopyButton';
 
 import { LegendPosition, LegendProps } from '../types';
 
@@ -33,7 +31,6 @@ export default function Legend({
 }: LegendProps): JSX.Element {
 	const legendContainerRef = useRef<HTMLDivElement | null>(null);
 	const [legendSearchQuery, setLegendSearchQuery] = useState('');
-	const { copyToClipboard, id: copiedId } = useCopyToClipboard();
 
 	// Search is intrinsic to the right-positioned legend.
 	const searchEnabled = position === LegendPosition.RIGHT;
@@ -57,17 +54,8 @@ export default function Legend({
 		return items.filter((item) => item.label?.toLowerCase().includes(query));
 	}, [searchEnabled, legendSearchQuery, items]);
 
-	const handleCopyLegendItem = useCallback(
-		(e: React.MouseEvent, seriesIndex: number, label: string): void => {
-			e.stopPropagation();
-			copyToClipboard(label, seriesIndex);
-		},
-		[copyToClipboard],
-	);
-
 	const renderLegendItem = useCallback(
 		(item: LegendItem): JSX.Element => {
-			const isCopied = copiedId === item.seriesIndex;
 			// `color` is uPlot's stroke union (string | fn | gradient); only a string
 			// is a usable CSS colour for the marker.
 			const markerColor = typeof item.color === 'string' ? item.color : undefined;
@@ -91,36 +79,18 @@ export default function Legend({
 						</div>
 					</TooltipSimple>
 					{showCopy && (
-						<TooltipSimple
-							title={isCopied ? 'Copied' : 'Copy'}
-							arrow
-							side="top"
-							disableHoverableContent
-						>
-							<Button
-								type="button"
-								size="icon"
-								variant="ghost"
-								color="secondary"
-								className="legend-copy-button"
-								onClick={(e): void =>
-									handleCopyLegendItem(e, item.seriesIndex, item.label ?? '')
-								}
-								aria-label={`Copy ${item.label}`}
-								// data-testid (not testId): TooltipSimple's trigger injects
-								// data-testid:undefined via Radix Slot, and Button spreads
-								// incoming props after its own testId — so set it as a prop
-								// that wins the Slot merge and survives the spread.
-								data-testid="legend-copy"
-							>
-								{isCopied ? <Check size={12} /> : <Copy size={12} />}
-							</Button>
-						</TooltipSimple>
+						<CopyButton
+							value={item.label ?? ''}
+							size={12}
+							className="legend-copy-button"
+							ariaLabel={`Copy ${item.label}`}
+							testId="legend-copy"
+						/>
 					)}
 				</div>
 			);
 		},
-		[copiedId, focusedSeriesIndex, handleCopyLegendItem, position, showCopy],
+		[focusedSeriesIndex, position, showCopy],
 	);
 
 	const isEmptyState = useMemo(() => {

frontend/src/lib/uPlotV2/components/__tests__/UPlotLegend.test.tsx

@@ -1,11 +1,5 @@
 import React from 'react';
-import {
-	fireEvent,
-	render,
-	RenderResult,
-	screen,
-	within,
-} from '@testing-library/react';
+import { render, RenderResult, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { TooltipProvider } from '@signozhq/ui/tooltip';
 import { LegendItem } from 'lib/uPlotV2/config/types';
@@ -15,9 +9,6 @@ import { useLegendActions } from '../../hooks/useLegendActions';
 import UPlotLegend from '../Legend/UPlotLegend';
 import { LegendPosition } from '../types';
 
-const mockWriteText = jest.fn().mockResolvedValue(undefined);
-let clipboardSpy: jest.SpyInstance | undefined;
-
 jest.mock('react-virtuoso', () => ({
 	VirtuosoGrid: ({
 		data,
@@ -49,15 +40,6 @@ const mockUseLegendActions = useLegendActions as jest.MockedFunction<
 >;
 
 describe('UPlotLegend', () => {
-	beforeAll(() => {
-		// JSDOM does not define navigator.clipboard; add it so we can spy on writeText
-		Object.defineProperty(navigator, 'clipboard', {
-			value: { writeText: () => Promise.resolve() },
-			writable: true,
-			configurable: true,
-		});
-	});
-
 	const baseLegendItemsMap = {
 		0: {
 			seriesIndex: 0,
@@ -89,11 +71,6 @@ describe('UPlotLegend', () => {
 		onLegendMouseMove = jest.fn();
 		onLegendMouseLeave = jest.fn();
 		onFocusSeries = jest.fn();
-		mockWriteText.mockClear();
-
-		clipboardSpy = jest
-			.spyOn(navigator.clipboard, 'writeText')
-			.mockImplementation(mockWriteText);
 
 		mockUseLegendsSync.mockReturnValue({
 			legendItemsMap: baseLegendItemsMap,
@@ -110,7 +87,6 @@ describe('UPlotLegend', () => {
 	});
 
 	afterEach(() => {
-		clipboardSpy?.mockRestore();
 		jest.clearAllMocks();
 	});
 
@@ -237,47 +213,4 @@ describe('UPlotLegend', () => {
 			expect(onLegendMouseLeave).toHaveBeenCalledTimes(1);
 		});
 	});
-
-	describe('copy action', () => {
-		it('copies the legend label to clipboard when copy button is clicked', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			const firstLegendItem = document.querySelector(
-				'[data-legend-item-id="0"]',
-			) as HTMLElement;
-			const copyButton = within(firstLegendItem).getByTestId('legend-copy');
-
-			fireEvent.click(copyButton);
-
-			expect(mockWriteText).toHaveBeenCalledTimes(1);
-			expect(mockWriteText).toHaveBeenCalledWith('A');
-		});
-
-		it('copies the correct label when copy is clicked on a different legend item', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			const thirdLegendItem = document.querySelector(
-				'[data-legend-item-id="2"]',
-			) as HTMLElement;
-			const copyButton = within(thirdLegendItem).getByTestId('legend-copy');
-
-			fireEvent.click(copyButton);
-
-			expect(mockWriteText).toHaveBeenCalledTimes(1);
-			expect(mockWriteText).toHaveBeenCalledWith('C');
-		});
-
-		it('does not call onLegendClick when copy button is clicked', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			const firstLegendItem = document.querySelector(
-				'[data-legend-item-id="0"]',
-			) as HTMLElement;
-			const copyButton = within(firstLegendItem).getByTestId('legend-copy');
-
-			fireEvent.click(copyButton);
-
-			expect(onLegendClick).not.toHaveBeenCalled();
-		});
-	});
 });

frontend/src/periscope/components/CopyButton/CopyButton.tsx

@@ -1,10 +1,10 @@
-import { CSSProperties, useCallback } from 'react';
+import { CSSProperties, type MouseEvent, useCallback } from 'react';
 import { Check, Copy } from '@signozhq/icons';
 import { Button } from '@signozhq/ui/button';
 import cx from 'classnames';
-import { useCopyToClipboard } from 'hooks/useCopyToClipboard';
 
 import styles from './CopyButton.module.scss';
+import { useCopyButton } from './useCopyButton';
 
 export interface CopyButtonProps {
 	/** Text written to the clipboard on click. */
@@ -30,11 +30,15 @@ function CopyButton({
 	className,
 	testId,
 }: CopyButtonProps): JSX.Element {
-	const { copyToClipboard, isCopied } = useCopyToClipboard();
+	const { copyToClipboard, isCopied } = useCopyButton();
 
-	const handleClick = useCallback((): void => {
-		copyToClipboard(value);
-	}, [copyToClipboard, value]);
+	const handleClick = useCallback(
+		(e: MouseEvent<HTMLButtonElement>): void => {
+			e.stopPropagation();
+			copyToClipboard(value);
+		},
+		[copyToClipboard, value],
+	);
 
 	const stackStyle: CSSProperties = { width: size, height: size };
 

frontend/src/periscope/components/CopyButton/__test__/CopyButton.test.tsx

@@ -0,0 +1,65 @@
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import CopyButton from '../CopyButton';
+
+const mockCopy = jest.fn();
+
+// Exercise the real useCopyButton — stub only react-use's underlying copy so the
+// click doesn't hit copy-to-clipboard's jsdom fallback (window.prompt).
+jest.mock('react-use', () => ({
+	...jest.requireActual('react-use'),
+	useCopyToClipboard: (): [unknown, jest.Mock] => [null, mockCopy],
+}));
+
+describe('CopyButton', () => {
+	let user: ReturnType<typeof userEvent.setup>;
+
+	beforeEach(() => {
+		jest.useFakeTimers();
+		user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
+		mockCopy.mockClear();
+	});
+
+	afterEach(() => {
+		jest.runOnlyPendingTimers();
+		jest.useRealTimers();
+	});
+
+	it('copies its value on click', async () => {
+		render(<CopyButton value="hello" testId="copy" />);
+
+		await user.click(screen.getByTestId('copy'));
+
+		expect(mockCopy).toHaveBeenCalledWith('hello');
+	});
+
+	it('does not trigger parent click handlers (stops propagation)', async () => {
+		const onParentClick = jest.fn();
+		render(
+			// oxlint-disable-next-line jsx-a11y/no-static-element-interactions, jsx-a11y/click-events-have-key-events
+			<div onClick={onParentClick}>
+				<CopyButton value="x" testId="copy" />
+			</div>,
+		);
+
+		await user.click(screen.getByTestId('copy'));
+
+		expect(onParentClick).not.toHaveBeenCalled();
+	});
+
+	it('shows the copied state after clicking and reverts after the reset window', async () => {
+		const { container } = render(<CopyButton value="hello" testId="copy" />);
+		const iconStack = container.querySelector('[data-copied]') as HTMLElement;
+
+		expect(iconStack).toHaveAttribute('data-copied', 'false');
+
+		await user.click(screen.getByTestId('copy'));
+		expect(iconStack).toHaveAttribute('data-copied', 'true');
+
+		act(() => {
+			jest.runOnlyPendingTimers();
+		});
+		expect(iconStack).toHaveAttribute('data-copied', 'false');
+	});
+});

frontend/src/periscope/components/CopyButton/constants.ts

@@ -0,0 +1,2 @@
+/** How long (ms) CopyButton stays in the "copied" state before reverting. */
+export const COPIED_RESET_MS = 1000;

frontend/src/periscope/components/CopyButton/useCopyButton.ts

@@ -0,0 +1,44 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCopyToClipboard } from 'react-use';
+
+import { COPIED_RESET_MS } from './constants';
+
+export interface UseCopyButtonReturn {
+	copyToClipboard: (text: string) => void;
+	isCopied: boolean;
+}
+
+export function useCopyButton(): UseCopyButtonReturn {
+	const [, copy] = useCopyToClipboard();
+	const [isCopied, setIsCopied] = useState(false);
+	const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	useEffect(() => {
+		return (): void => {
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+		};
+	}, []);
+
+	const copyToClipboard = useCallback(
+		(text: string): void => {
+			copy(text);
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+			}
+			setIsCopied(true);
+			timeoutRef.current = setTimeout(() => {
+				setIsCopied(false);
+				timeoutRef.current = null;
+			}, COPIED_RESET_MS);
+		},
+		[copy],
+	);
+
+	return {
+		copyToClipboard,
+		isCopied,
+	};
+}

frontend/src/providers/App/App.tsx

@@ -434,6 +434,7 @@ export function AppProvider({ children }: PropsWithChildren): JSX.Element {
 			isFetchingHosts,
 			isFetchingFeatureFlags,
 			isFetchingOrgPreferences,
+			isFetchingUserPreferences,
 			userFetchError,
 			activeLicenseFetchError,
 			hostsFetchError,
@@ -464,6 +465,7 @@ export function AppProvider({ children }: PropsWithChildren): JSX.Element {
 			isFetchingHosts,
 			isFetchingFeatureFlags,
 			isFetchingOrgPreferences,
+			isFetchingUserPreferences,
 			isFetchingUser,
 			isLoggedIn,
 			hostsData,

frontend/src/providers/App/types.ts

@@ -27,6 +27,7 @@ export interface IAppContext {
 	isFetchingHosts: boolean;
 	isFetchingFeatureFlags: boolean;
 	isFetchingOrgPreferences: boolean;
+	isFetchingUserPreferences: boolean;
 	userFetchError: unknown;
 	activeLicenseFetchError: APIError | null;
 	hostsFetchError: unknown;

frontend/src/tests/test-utils.tsx

@@ -242,6 +242,7 @@ export function getAppContextMock(
 		userPreferences: [],
 		updateUserPreferenceInContext: jest.fn(),
 		isFetchingOrgPreferences: false,
+		isFetchingUserPreferences: false,
 		orgPreferencesFetchError: null,
 		isLoggedIn: true,
 		isPreflightLoading: false,

frontend/src/utils/permission/index.ts

@@ -23,6 +23,11 @@ export type ComponentTypes =
 	| 'add_panel_locked_dashboard'
 	| 'manage_llm_pricing';
 
+/**
+ * @deprecated Before adding a new value here, check if what you want to add permission is supported by authz.
+ * If so, read AuthZ Guidelines on how to add permission check via AuthZ.
+ * If not, you can keep adding to this record.
+ */
 export const componentPermission: Record<ComponentTypes, ROLES[]> = {
 	current_org_settings: ['ADMIN'],
 	invite_members: ['ADMIN'],
@@ -46,11 +51,16 @@ export const componentPermission: Record<ComponentTypes, ROLES[]> = {
 	manage_llm_pricing: ['ADMIN'],
 };
 
+/**
+ * @deprecated You can still add new permissions/routes here but be aware if this page/module supports authz.
+ * If so, also implement the correct authz checks in the page itself, and here you can add ADMIN/EDITOR/VIEWER,
+ * and also update/include the route at {@link routeWithInitialAuthZSupport}
+ */
 export const routePermission: Record<keyof typeof ROUTES, ROLES[]> = {
 	HOME: ['ADMIN', 'EDITOR', 'VIEWER'],
 	ALERTS_NEW: ['ADMIN', 'EDITOR'],
 	ORG_SETTINGS: ['ADMIN'],
-	MY_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
+	MY_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER'],
 	SERVICE_MAP: ['ADMIN', 'EDITOR', 'VIEWER'],
 	ALL_CHANNELS: ['ADMIN', 'EDITOR', 'VIEWER'],
 	INGESTION_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER'],
@@ -75,13 +85,15 @@ export const routePermission: Record<keyof typeof ROUTES, ROLES[]> = {
 	NOT_FOUND: ['ADMIN', 'VIEWER', 'EDITOR', 'ANONYMOUS'],
 	PASSWORD_RESET: ['ADMIN', 'EDITOR', 'VIEWER'],
 	SERVICE_METRICS: ['ADMIN', 'EDITOR', 'VIEWER'],
-	SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
+	SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER'],
 	SIGN_UP: ['ADMIN', 'EDITOR', 'VIEWER'],
 	TRACES_EXPLORER: ['ADMIN', 'EDITOR', 'VIEWER'],
 	TRACE: ['ADMIN', 'EDITOR', 'VIEWER'],
 	TRACE_DETAIL: ['ADMIN', 'EDITOR', 'VIEWER'],
 	TRACE_DETAIL_OLD: ['ADMIN', 'EDITOR', 'VIEWER'],
-	UN_AUTHORIZED: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
+	// Every role must be able to land here - a role missing from this list is
+	// redirected to /un-authorized and then redirected off it again, looping.
+	UN_AUTHORIZED: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS', 'AUTHOR'],
 	USAGE_EXPLORER: ['ADMIN', 'EDITOR', 'VIEWER'],
 	VERSION: ['ADMIN', 'EDITOR', 'VIEWER'],
 	LOGS: ['ADMIN', 'EDITOR', 'VIEWER'],
@@ -95,12 +107,12 @@ export const routePermission: Record<keyof typeof ROUTES, ROLES[]> = {
 	GET_STARTED_WITH_CLOUD: ['ADMIN', 'EDITOR'],
 	WORKSPACE_LOCKED: ['ADMIN', 'EDITOR', 'VIEWER'],
 	WORKSPACE_SUSPENDED: ['ADMIN', 'EDITOR', 'VIEWER'],
-	ROLES_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
-	ROLE_CREATE: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
-	ROLE_DETAILS: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
-	ROLE_EDIT: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
+	ROLES_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER'],
+	ROLE_CREATE: ['ADMIN', 'EDITOR', 'VIEWER'],
+	ROLE_DETAILS: ['ADMIN', 'EDITOR', 'VIEWER'],
+	ROLE_EDIT: ['ADMIN', 'EDITOR', 'VIEWER'],
 	MEMBERS_SETTINGS: ['ADMIN'],
-	SERVICE_ACCOUNTS_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
+	SERVICE_ACCOUNTS_SETTINGS: ['ADMIN', 'EDITOR', 'VIEWER'],
 	BILLING: ['ADMIN'],
 	SUPPORT: ['ADMIN', 'EDITOR', 'VIEWER', 'ANONYMOUS'],
 	SOMETHING_WENT_WRONG: ['ADMIN', 'EDITOR', 'VIEWER'],
@@ -141,3 +153,34 @@ export const routePermission: Record<keyof typeof ROUTES, ROLES[]> = {
 	AI_OBSERVABILITY_OVERVIEW: ['ADMIN', 'EDITOR', 'VIEWER'],
 	AI_OBSERVABILITY_CONFIGURATION: ['ADMIN', 'EDITOR', 'VIEWER'],
 };
+
+/**
+ * Any route that will start be supported under AuthZ should be added here.
+ * This will help correctly identify when fallback to show the page
+ * or just return unauthorized.
+ *
+ * This prevents us from adding `ANONYMOUS` on the `routePermission`
+ */
+export const routeWithInitialAuthZSupport = {
+	MY_SETTINGS: true,
+	SETTINGS: true,
+	TRACES_EXPLORER: true,
+	TRACE: true,
+	TRACE_DETAIL: true,
+	TRACE_DETAIL_OLD: true,
+	LOGS: true,
+	LOGS_EXPLORER: true,
+	LIVE_LOGS: true,
+	ROLES_SETTINGS: true,
+	ROLE_CREATE: true,
+	ROLE_DETAILS: true,
+	ROLE_EDIT: true,
+	SERVICE_ACCOUNTS_SETTINGS: true,
+	SUPPORT: true,
+	OLD_LOGS_EXPLORER: true,
+	METRICS_EXPLORER: true,
+	METRICS_EXPLORER_EXPLORER: true,
+	METRICS_EXPLORER_VOLUME_CONTROL: true,
+	METER_EXPLORER: true,
+	METER: true,
+} as const satisfies Partial<Record<keyof typeof ROUTES, true>>;

frontend/vite.config.ts

@@ -143,6 +143,12 @@ export default defineConfig(({ mode }): UserConfig => {
 		plugins,
 		resolve: {
 			alias: {
+				// @grafana/data imports bare CJS `lodash`, whose UMD footer checks for an
+				// AMD loader before assigning module.exports. Any third-party script that
+				// defines window.define.amd first leaves the bundled namespace empty, so
+				// every lodash method reached through it is undefined at runtime. lodash-es
+				// is the same version, real ESM, and tree-shakes.
+				lodash: 'lodash-es',
 				'@': resolve(__dirname, './src'),
 				utils: resolve(__dirname, './src/utils'),
 				types: resolve(__dirname, './src/types'),

go.mod

@@ -4,7 +4,7 @@ go 1.25.7
 
 require (
 	dario.cat/mergo v1.0.2
-	github.com/AfterShip/clickhouse-sql-parser v0.5.2
+	github.com/AfterShip/clickhouse-sql-parser v0.5.3
 	github.com/ClickHouse/clickhouse-go/v2 v2.44.0
 	github.com/DATA-DOG/go-sqlmock v1.5.2
 	github.com/SigNoz/clickhouse-go-mock v0.14.0

go.sum

@@ -66,8 +66,8 @@ dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
 dmitri.shuralyov.com/gpu/mtl v0.0.0-20190408044501-666a987793e9/go.mod h1:H6x//7gZCb22OMCxBHrMx7a5I7Hp++hsVxbQ4BYO7hU=
 filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
-github.com/AfterShip/clickhouse-sql-parser v0.5.2 h1:KCxdmvuVawVF4yl0ZS33q7olgmLZwvZG5BjWHp6o414=
-github.com/AfterShip/clickhouse-sql-parser v0.5.2/go.mod h1:Qi3qvPTfZb/aFwI5V4WFOahgjsLJa4MzVijIAfwOhDw=
+github.com/AfterShip/clickhouse-sql-parser v0.5.3 h1:6iap8XGjuSjD3w7r1UNrg66ljBugcv2P39s4eo/ZLRw=
+github.com/AfterShip/clickhouse-sql-parser v0.5.3/go.mod h1:Qi3qvPTfZb/aFwI5V4WFOahgjsLJa4MzVijIAfwOhDw=
 github.com/Azure/azure-sdk-for-go v68.0.0+incompatible h1:fcYLmCpyNYRnvJbPerq7U0hS+6+I79yEDJBqVNcqUzU=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 h1:fou+2+WFTib47nS+nz/ozhEBnvU96bKHy6LjRsY4E28=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0/go.mod h1:t76Ruy8AHvUAC8GfMWJMa0ElSbuIcO03NLpynfbgsPA=

pkg/modules/llmpricingrule/impllmpricingrule/module.go

@@ -213,18 +213,18 @@ func (module *module) discoverModels(ctx context.Context, orgID valuer.UUID) ([]
 					Spec: qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
 						Name:   "A",
 						Signal: telemetrytypes.SignalTraces,
-						Filter: &qbtypes.Filter{Expression: fmt.Sprintf("%s EXISTS", llmpricingruletypes.GenAIRequestModel)},
+						Filter: &qbtypes.Filter{Expression: fmt.Sprintf("%s EXISTS", telemetrytypes.GenAIRequestModel)},
 						Aggregations: []qbtypes.TraceAggregation{
 							{Expression: "count()", Alias: "spanCount"},
 						},
 						GroupBy: []qbtypes.GroupByKey{
 							{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
-								Name:          llmpricingruletypes.GenAIRequestModel,
+								Name:          telemetrytypes.GenAIRequestModel,
 								FieldContext:  telemetrytypes.FieldContextSpan,
 								FieldDataType: telemetrytypes.FieldDataTypeString,
 							}},
 							{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
-								Name:          llmpricingruletypes.GenAIProviderName,
+								Name:          telemetrytypes.GenAIProviderName,
 								FieldContext:  telemetrytypes.FieldContextSpan,
 								FieldDataType: telemetrytypes.FieldDataTypeString,
 							}},
@@ -254,9 +254,9 @@ func (module *module) discoverModels(ctx context.Context, orgID valuer.UUID) ([]
 		switch c.Type {
 		case qbtypes.ColumnTypeGroup:
 			switch c.Name {
-			case llmpricingruletypes.GenAIRequestModel:
+			case telemetrytypes.GenAIRequestModel:
 				modelIdx = i
-			case llmpricingruletypes.GenAIProviderName:
+			case telemetrytypes.GenAIProviderName:
 				providerIdx = i
 			}
 		case qbtypes.ColumnTypeAggregation:

pkg/querier/api.go

@@ -249,7 +249,7 @@ func (handler *handler) ReplaceVariables(rw http.ResponseWriter, req *http.Reque
 	errs := []error{}
 
 	for idx, item := range queryRangeRequest.CompositeQuery.Queries {
-		if item.Type == qbtypes.QueryTypeBuilder {
+		if item.Type == qbtypes.QueryTypeBuilder || item.Type == qbtypes.QueryTypeBuilderAI {
 			switch spec := item.Spec.(type) {
 			case qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]:
 				if spec.Filter != nil && spec.Filter.Expression != "" {

pkg/querier/preview.go

@@ -249,6 +249,7 @@ func (q *querier) buildPreviewProviders(
 func rendersStandaloneStatement(t qbtypes.QueryType) bool {
 	switch t {
 	case qbtypes.QueryTypeBuilder,
+		qbtypes.QueryTypeBuilderAI,
 		qbtypes.QueryTypePromQL,
 		qbtypes.QueryTypeClickHouseSQL,
 		qbtypes.QueryTypeTraceOperator:

pkg/querier/querier.go

@@ -52,6 +52,7 @@ type querier struct {
 	metadataStore            telemetrytypes.MetadataStore
 	promEngine               prometheus.Prometheus
 	traceStmtBuilder         qbtypes.StatementBuilder[qbtypes.TraceAggregation]
+	aiTraceStmtBuilder       qbtypes.StatementBuilder[qbtypes.TraceAggregation]
 	logStmtBuilder           qbtypes.StatementBuilder[qbtypes.LogAggregation]
 	auditStmtBuilder         qbtypes.StatementBuilder[qbtypes.LogAggregation]
 	metricStmtBuilder        qbtypes.StatementBuilder[qbtypes.MetricAggregation]
@@ -71,6 +72,7 @@ func New(
 	metadataStore telemetrytypes.MetadataStore,
 	promEngine prometheus.Prometheus,
 	traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	aiTraceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
 	logStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	auditStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	metricStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation],
@@ -92,6 +94,7 @@ func New(
 		metadataStore:            metadataStore,
 		promEngine:               promEngine,
 		traceStmtBuilder:         traceStmtBuilder,
+		aiTraceStmtBuilder:       aiTraceStmtBuilder,
 		logStmtBuilder:           logStmtBuilder,
 		auditStmtBuilder:         auditStmtBuilder,
 		metricStmtBuilder:        metricStmtBuilder,
@@ -242,6 +245,16 @@ func (q *querier) buildQueries(
 			}
 			queries[traceOpQuery.Name] = toq
 			steps[traceOpQuery.Name] = traceOpQuery.StepInterval
+		case qbtypes.QueryTypeBuilderAI:
+			spec, ok := query.Spec.(qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation])
+			if !ok {
+				return nil, nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "invalid AI builder query spec %T", query.Spec)
+			}
+			spec.ShiftBy = extractShiftFromBuilderQuery(spec)
+			timeRange := adjustTimeRangeForShift(spec, qbtypes.TimeRange{From: req.Start, To: req.End}, req.RequestType)
+			bq := newBuilderQuery(q.logger, q.telemetryStore, orgID, q.aiTraceStmtBuilder, spec, timeRange, req.RequestType, tmplVars, builderConfig{})
+			queries[spec.Name] = bq
+			steps[spec.Name] = spec.StepInterval
 		case qbtypes.QueryTypeBuilder:
 			switch spec := query.Spec.(type) {
 			case qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]:
@@ -308,6 +321,11 @@ func (q *querier) populateQBEvent(event *qbtypes.QBEvent, queries []qbtypes.Quer
 			case qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]:
 				event.MetricsUsed = true
 			}
+		case qbtypes.QueryTypeBuilderAI:
+			filter := query.GetFilter()
+			event.FilterApplied = event.FilterApplied || (filter != nil && filter.Expression != "")
+			event.GroupByApplied = event.GroupByApplied || len(query.GetGroupBy()) > 0
+			event.TracesUsed = true
 		case qbtypes.QueryTypePromQL:
 			event.MetricsUsed = true
 		case qbtypes.QueryTypeTraceOperator:
@@ -870,7 +888,9 @@ func (q *querier) createRangedQuery(_ valuer.UUID, originalQuery qbtypes.Query,
 		specCopy := qt.spec.Copy()
 		specCopy.ShiftBy = extractShiftFromBuilderQuery(specCopy)
 		adjustedTimeRange := adjustTimeRangeForShift(specCopy, timeRange, qt.kind)
-		return newBuilderQuery(q.logger, q.telemetryStore, qt.orgID, q.traceStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
+		// Reuse the statement builder the original query was created with, so an AI
+		// query keeps its AI builder without re-deriving it from the spec.
+		return newBuilderQuery(q.logger, q.telemetryStore, qt.orgID, qt.stmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
 
 	case *builderQuery[qbtypes.LogAggregation]:
 		specCopy := qt.spec.Copy()
@@ -1227,6 +1247,8 @@ func (q *querier) adjustStepInterval(queries []qbtypes.QueryEnvelope, start, end
 			if qe.GetStepInterval().Seconds() == 0 {
 				qe.SetStepInterval(secondsStep(metricRecommended))
 			}
+		case qbtypes.QueryTypeBuilderAI:
+			clampStep(qe, traceLogRecommended, traceLogMin, &warnings)
 		case qbtypes.QueryTypeTraceOperator:
 			clampStep(qe, traceLogRecommended, traceLogMin, &warnings)
 		}

pkg/querier/querier_test.go

@@ -49,6 +49,7 @@ func TestQueryRange_MetricTypeMissing(t *testing.T) {
 		metadataStore,
 		nil,                // prometheus
 		nil,                // traceStmtBuilder
+		nil,                // aiTraceStmtBuilder
 		nil,                // logStmtBuilder
 		nil,                // auditStmtBuilder
 		nil,                // metricStmtBuilder
@@ -121,6 +122,7 @@ func TestQueryRange_MetricTypeFromStore(t *testing.T) {
 		metadataStore,
 		nil, // prometheus
 		nil, // traceStmtBuilder
+		nil, // aiTraceStmtBuilder
 		nil, // logStmtBuilder
 		nil, // auditStmtBuilder
 		&mockMetricStmtBuilder{},

pkg/querier/signozquerier/provider.go

@@ -20,6 +20,7 @@ func NewFactory(
 	prometheus prometheus.Prometheus,
 	metadataStore telemetrytypes.MetadataStore,
 	traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	aiTraceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
 	logStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	auditStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	metricStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation],
@@ -41,6 +42,7 @@ func NewFactory(
 				metadataStore,
 				prometheus,
 				traceStmtBuilder,
+				aiTraceStmtBuilder,
 				logStmtBuilder,
 				auditStmtBuilder,
 				metricStmtBuilder,

pkg/query-service/rules/managertestfactory.go

@@ -19,6 +19,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/sqlstore"
 	"github.com/SigNoz/signoz/pkg/sqlstore/sqlstoretest"
 	"github.com/SigNoz/signoz/pkg/statementbuilder"
+	"github.com/SigNoz/signoz/pkg/statementbuilder/aistatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/auditstatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/logsstatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/meterstatementbuilder"
@@ -117,6 +118,8 @@ func NewTestManager(t *testing.T, testOpts *TestManagerOptions) *Manager {
 	ctx := context.Background()
 	traceStmtBuilder, err := tracesstatementbuilder.NewFactory(telemetryStore, metadataStore, flagger).New(ctx, providerSettings, cfg)
 	require.NoError(t, err)
+	aiTraceStmtBuilder, err := aistatementbuilder.NewFactory(telemetryStore, metadataStore, flagger).New(ctx, providerSettings, cfg)
+	require.NoError(t, err)
 	traceOperatorStmtBuilder, err := tracesstatementbuilder.NewOperatorFactory(telemetryStore, metadataStore, flagger).New(ctx, providerSettings, cfg)
 	require.NoError(t, err)
 	logStmtBuilder, err := logsstatementbuilder.NewFactory(telemetryStore, metadataStore, flagger).New(ctx, providerSettings, cfg)
@@ -128,7 +131,7 @@ func NewTestManager(t *testing.T, testOpts *TestManagerOptions) *Manager {
 	meterStmtBuilder, err := meterstatementbuilder.NewFactory(metadataStore, flagger).New(ctx, providerSettings, cfg)
 	require.NoError(t, err)
 	bucketCache := querier.NewBucketCache(providerSettings, cache, 0, 0)
-	providerFactory := signozquerier.NewFactory(telemetryStore, prometheus, metadataStore, traceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, flagger)
+	providerFactory := signozquerier.NewFactory(telemetryStore, prometheus, metadataStore, traceStmtBuilder, aiTraceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, flagger)
 	mockQuerier, err := providerFactory.New(context.Background(), providerSettings, querier.Config{})
 	require.NoError(t, err)
 

pkg/query-service/rules/setups_test.go

@@ -41,6 +41,7 @@ func prepareQuerierForMetrics(t *testing.T, telemetryStore telemetrystore.Teleme
 		metadataStore,
 		nil, // prometheus
 		nil, // traceStmtBuilder
+		nil, // aiTraceStmtBuilder
 		nil, // logStmtBuilder
 		nil, // auditStmtBuilder
 		metricStmtBuilder,
@@ -75,6 +76,7 @@ func prepareQuerierForLogs(t *testing.T, telemetryStore telemetrystore.Telemetry
 		metadataStore,
 		nil, // prometheus
 		nil, // traceStmtBuilder
+		nil, // aiTraceStmtBuilder
 		logStmtBuilder,
 		nil, // auditStmtBuilder
 		nil, // metricStmtBuilder
@@ -110,6 +112,7 @@ func prepareQuerierForTraces(t *testing.T, telemetryStore telemetrystore.Telemet
 		metadataStore,
 		nil, // prometheus
 		traceStmtBuilder,
+		nil, // aiTraceStmtBuilder
 		nil, // logStmtBuilder
 		nil, // auditStmtBuilder
 		nil, // metricStmtBuilder

pkg/querybuilder/clickhouse_sql.go

@@ -9,6 +9,16 @@ import (
 	"github.com/SigNoz/signoz/pkg/errors"
 )
 
+var (
+	CodeClickHouseSQLParserPanic        = errors.MustNewCode("clickhouse_sql_parser_panic")
+	CodeClickHouseSQLUnparseable        = errors.MustNewCode("clickhouse_sql_unparseable")
+	CodeClickHouseSQLNotSingleStatement = errors.MustNewCode("clickhouse_sql_not_single_statement")
+	CodeClickHouseSQLNotSelect          = errors.MustNewCode("clickhouse_sql_not_select")
+	CodeClickHouseSQLTableFunction      = errors.MustNewCode("clickhouse_sql_table_function")
+	CodeClickHouseSQLInternalDatabase   = errors.MustNewCode("clickhouse_sql_internal_database")
+	CodeClickHouseSQLReadonlyOverride   = errors.MustNewCode("clickhouse_sql_readonly_override")
+)
+
 // internalDatabases hold server metadata, credentials and grants rather than telemetry.
 var internalDatabases = map[string]struct{}{
 	"system":             {},
@@ -20,30 +30,30 @@ func ErrIfStatementIsNotValid(query string) (err error) {
 	defer func() {
 		// The parser has a history of panicking on malformed input rather than returning an error.
 		if recovered := recover(); recovered != nil {
-			err = errors.NewInvalidInputf(errors.CodeInvalidInput, "invalid ClickHouse SQL (recovered): %v", recovered)
+			err = errors.NewInvalidInputf(CodeClickHouseSQLParserPanic, "invalid ClickHouse SQL (recovered): %v", recovered)
 		}
 	}()
 
 	stmts, parseErr := chparser.NewParser(query).ParseStmts()
 	if parseErr != nil {
 		// Wrapped rather than formatted in, so that callers can recover the parser's *ParseError and read the position off it.
-		return errors.WrapInvalidInputf(parseErr, errors.CodeInvalidInput, "invalid ClickHouse SQL: %s", parseErr.Error())
+		return errors.WrapInvalidInputf(parseErr, CodeClickHouseSQLUnparseable, "invalid ClickHouse SQL: %s", parseErr.Error())
 	}
 
 	if len(stmts) != 1 {
-		return errors.NewInvalidInputf(errors.CodeInvalidInput, "ClickHouse SQL must contain exactly one statement, found %d statements", len(stmts))
+		return errors.NewInvalidInputf(CodeClickHouseSQLNotSingleStatement, "ClickHouse SQL must contain exactly one statement, found %d statements", len(stmts))
 	}
 
 	selectQuery, ok := stmts[0].(*chparser.SelectQuery)
 	if !ok {
-		return errors.NewInvalidInputf(errors.CodeInvalidInput, "only SELECT statements are allowed in ClickHouse SQL queries")
+		return errors.NewInvalidInputf(CodeClickHouseSQLNotSelect, "only SELECT statements are allowed in ClickHouse SQL queries")
 	}
 
 	visitor := &chparser.DefaultASTVisitor{Visit: func(node chparser.Expr) error {
 		switch expr := node.(type) {
 		case *chparser.TableFunctionExpr:
 			// Source table functions remain usable in ClickHouse read-only mode.
-			return errors.NewInvalidInputf(errors.CodeInvalidInput, "ClickHouse table functions are not allowed in SQL queries: %s", chparser.Format(expr.Name))
+			return errors.NewInvalidInputf(CodeClickHouseSQLTableFunction, "ClickHouse table functions are not allowed in SQL queries: %s", chparser.Format(expr.Name))
 
 		case *chparser.TableIdentifier:
 			// Reading these is unaffected by ClickHouse read-only mode.
@@ -52,13 +62,13 @@ func ErrIfStatementIsNotValid(query string) (err error) {
 			}
 
 			if _, ok := internalDatabases[strings.ToLower(expr.Database.Name)]; ok {
-				return errors.NewInvalidInputf(errors.CodeInvalidInput, "the ClickHouse %s database is not allowed in SQL queries", expr.Database.Name)
+				return errors.NewInvalidInputf(CodeClickHouseSQLInternalDatabase, "the ClickHouse %s database is not allowed in SQL queries", expr.Database.Name)
 			}
 
 		case *chparser.SettingExpr:
 			// A query-level setting takes precedence over the context setting.
 			if strings.EqualFold(expr.Name.Name, "readonly") {
-				return errors.NewInvalidInputf(errors.CodeInvalidInput, "the ClickHouse readonly setting cannot be overridden")
+				return errors.NewInvalidInputf(CodeClickHouseSQLReadonlyOverride, "the ClickHouse readonly setting cannot be overridden")
 			}
 		}
 

pkg/querybuilder/clickhouse_sql_test.go

@@ -3,6 +3,8 @@ package querybuilder
 import (
 	"testing"
 
+	"github.com/SigNoz/signoz/pkg/errors"
+
 	chparser "github.com/AfterShip/clickhouse-sql-parser/parser"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -30,10 +32,15 @@ func TestErrIfStatementIsNotValid_Pass(t *testing.T) {
 		{"TrailingUnterminatedBlockComment", "SELECT count() FROM t /* unterminated"},
 		// The rule keys on the database, not on the table name.
 		{"TableNamedSystemInTelemetryDatabase", "SELECT * FROM signoz_logs.system"},
-		{"SignedLiteralAfterClosingParen", "SELECT (toUnixTimestamp(now()) - 3600)*1000000000"},
+		{"SignedLiteralAfterClosingParenSpaced", "SELECT (toUnixTimestamp(now()) - 3600)*1000000000"},
 		// order by interval
 		{"OrderByInterval", "SELECT toStartOfInterval(timestamp, INTERVAL 1 MINUTE) AS interval ORDER BY interval"},
 		{"OrderByIntervalAndDirection", "SELECT toStartOfInterval(timestamp, INTERVAL 1 MINUTE) AS `interval` ORDER BY `interval` ASC"},
+		// Unspaced, so rejected until the parser stopped lexing a signed literal after a
+		// closing bracket. The spaced form above no longer needs to be spaced.
+		// https://github.com/AfterShip/clickhouse-sql-parser/issues/286
+		{"SignedLiteralAfterClosingParenUnspaced", "SELECT now() AS ts, toFloat64(count()) AS value FROM ( SELECT attributes_string['TableName'] AS T, attributes_string['MissingId'] AS M, max(fromUnixTimestamp64Nano(timestamp)) AS last_seen, dateDiff('minute', min(fromUnixTimestamp64Nano(timestamp)), max(fromUnixTimestamp64Nano(timestamp))) AS age_min FROM signoz_logs.distributed_logs_v2 WHERE body='missing_map_record' AND timestamp >= (toUnixTimestamp(now())-3600)*1000000000 GROUP BY T, M ) WHERE age_min >= 20 AND last_seen >= now() - toIntervalMinute(8)"},
+		{"SignedLiteralAfterClosingParenMinimal", "SELECT (1)-1"},
 		{"TrimFunction", "SELECT trimBoth('/api/endpoint/', '/');"},
 	}
 
@@ -47,49 +54,52 @@ func TestErrIfStatementIsNotValid_Pass(t *testing.T) {
 
 func TestErrIfStatementIsNotValid_Fail(t *testing.T) {
 	testCases := []struct {
-		name  string
-		query string
+		name         string
+		query        string
+		expectedCode errors.Code
 	}{
 		// Not a single statement, or not a statement at all.
-		{"Empty", ""},
-		{"UnterminatedBlockCommentOnly", "/* x"},
-		{"Unparseable", "SELECT FROM WHERE"},
-		{"MultipleStatements", "SELECT 1; DROP TABLE signoz_logs.logs_v2"},
+		{"Empty", "", CodeClickHouseSQLNotSingleStatement},
+		{"UnterminatedBlockCommentOnly", "/* x", CodeClickHouseSQLUnparseable},
+		{"Unparseable", "SELECT FROM WHERE", CodeClickHouseSQLUnparseable},
+		{"MultipleStatements", "SELECT 1; DROP TABLE signoz_logs.logs_v2", CodeClickHouseSQLNotSingleStatement},
 		// Parses, but is not a SELECT.
-		{"Drop", "DROP TABLE signoz_logs.logs_v2"},
-		{"Insert", "INSERT INTO signoz_logs.logs_v2 SELECT * FROM signoz_logs.logs_v2"},
-		{"AlterDelete", "ALTER TABLE signoz_logs.logs_v2 DELETE WHERE 1 = 1"},
-		{"CreateTable", "CREATE TABLE evil (a Int) ENGINE = Memory"},
-		{"Grant", "GRANT ALL ON *.* TO admin"},
-		{"Set", "SET readonly = 0"},
+		{"Drop", "DROP TABLE signoz_logs.logs_v2", CodeClickHouseSQLNotSelect},
+		{"Insert", "INSERT INTO signoz_logs.logs_v2 SELECT * FROM signoz_logs.logs_v2", CodeClickHouseSQLNotSelect},
+		{"AlterDelete", "ALTER TABLE signoz_logs.logs_v2 DELETE WHERE 1 = 1", CodeClickHouseSQLNotSelect},
+		{"CreateTable", "CREATE TABLE evil (a Int) ENGINE = Memory", CodeClickHouseSQLNotSelect},
+		{"Grant", "GRANT ALL ON *.* TO admin", CodeClickHouseSQLNotSelect},
+		{"Set", "SET readonly = 0", CodeClickHouseSQLNotSelect},
 		// These the parser rejects outright rather than classifying.
-		{"ShowGrants", "SHOW GRANTS"},
-		{"IntoOutfile", "SELECT * FROM t INTO OUTFILE '/tmp/x.csv'"},
+		{"ShowGrants", "SHOW GRANTS", CodeClickHouseSQLUnparseable},
+		{"IntoOutfile", "SELECT * FROM t INTO OUTFILE '/tmp/x.csv'", CodeClickHouseSQLUnparseable},
 		// Table functions, which read through something other than a telemetry table.
-		{"UrlTableFunction", "SELECT * FROM url('http://attacker.example/x', CSV, 'a String')"},
-		{"FileTableFunction", "SELECT * FROM file('/etc/passwd', CSV, 'a String')"},
-		{"ExecutableTableFunction", "SELECT * FROM executable('script.sh', CSV, 'a String')"},
-		{"TableFunctionInJoin", "SELECT * FROM t1 JOIN url('http://x', CSV, 'a String') u ON 1 = 1"},
-		{"TableFunctionInCommonTableExpression", "WITH c AS (SELECT * FROM url('http://x', CSV, 'a String')) SELECT * FROM c"},
-		{"TableFunctionInWhereSubquery", "SELECT * FROM t WHERE a IN (SELECT * FROM file('/etc/passwd', CSV, 'a String'))"},
-		{"TableFunctionInUnion", "SELECT * FROM t UNION ALL SELECT * FROM url('http://x', CSV, 'a String')"},
+		{"UrlTableFunction", "SELECT * FROM url('http://attacker.example/x', CSV, 'a String')", CodeClickHouseSQLTableFunction},
+		{"FileTableFunction", "SELECT * FROM file('/etc/passwd', CSV, 'a String')", CodeClickHouseSQLTableFunction},
+		{"ExecutableTableFunction", "SELECT * FROM executable('script.sh', CSV, 'a String')", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInJoin", "SELECT * FROM t1 JOIN url('http://x', CSV, 'a String') u ON 1 = 1", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInCommonTableExpression", "WITH c AS (SELECT * FROM url('http://x', CSV, 'a String')) SELECT * FROM c", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInWhereSubquery", "SELECT * FROM t WHERE a IN (SELECT * FROM file('/etc/passwd', CSV, 'a String'))", CodeClickHouseSQLTableFunction},
+		{"TableFunctionInUnion", "SELECT * FROM t UNION ALL SELECT * FROM url('http://x', CSV, 'a String')", CodeClickHouseSQLTableFunction},
 		// Internal databases, which hold grants and server metadata rather than telemetry.
-		{"SystemUsers", "SELECT * FROM system.users"},
-		{"SystemUppercase", "SELECT * FROM SYSTEM.USERS"},
-		{"SystemQuoted", "SELECT count() FROM `system`.`tables`"},
-		{"SystemInSubquery", "SELECT * FROM (SELECT name FROM system.parts)"},
-		{"SystemInJoin", "SELECT * FROM signoz_logs.distributed_logs_v2 AS l JOIN system.users AS u ON 1 = 1"},
-		{"SystemInIntersect", "SELECT * FROM t INTERSECT SELECT * FROM system.users"},
-		{"InformationSchema", "SELECT * FROM information_schema.tables"},
+		{"SystemUsers", "SELECT * FROM system.users", CodeClickHouseSQLInternalDatabase},
+		{"SystemUppercase", "SELECT * FROM SYSTEM.USERS", CodeClickHouseSQLInternalDatabase},
+		{"SystemQuoted", "SELECT count() FROM `system`.`tables`", CodeClickHouseSQLInternalDatabase},
+		{"SystemInSubquery", "SELECT * FROM (SELECT name FROM system.parts)", CodeClickHouseSQLInternalDatabase},
+		{"SystemInJoin", "SELECT * FROM signoz_logs.distributed_logs_v2 AS l JOIN system.users AS u ON 1 = 1", CodeClickHouseSQLInternalDatabase},
+		{"SystemInIntersect", "SELECT * FROM t INTERSECT SELECT * FROM system.users", CodeClickHouseSQLInternalDatabase},
+		{"InformationSchema", "SELECT * FROM information_schema.tables", CodeClickHouseSQLInternalDatabase},
 		// A query-level setting takes precedence over the one the caller applies.
-		{"ReadonlySettingOverride", "SELECT * FROM t SETTINGS readonly = 0"},
-		{"ReadonlySettingOverrideAmongOthers", "SELECT * FROM t SETTINGS max_threads = 4, readonly = 0"},
+		{"ReadonlySettingOverride", "SELECT * FROM t SETTINGS readonly = 0", CodeClickHouseSQLReadonlyOverride},
+		{"ReadonlySettingOverrideAmongOthers", "SELECT * FROM t SETTINGS max_threads = 4, readonly = 0", CodeClickHouseSQLReadonlyOverride},
 	}
 
 	for _, testCase := range testCases {
 		t.Run(testCase.name, func(t *testing.T) {
 			err := ErrIfStatementIsNotValid(testCase.query)
+
 			assert.Error(t, err)
+			assert.True(t, errors.Asc(err, testCase.expectedCode), "expected code %s, got %v", testCase.expectedCode, err)
 		})
 	}
 }
@@ -122,18 +132,6 @@ func TestErrIfStatementIsNotValid_ShouldPassButFails(t *testing.T) {
 			expectedStopsAfter: "trim(BOTH '",
 			fix:                "SELECT trimBoth(replaceOne( JSONExtractString(body, 'Action'), 'health_status: ', '' ), ' ')",
 		},
-		{
-			name:               "SignedLiteralAfterClosingParen",
-			query:              "SELECT now() AS ts, toFloat64(count()) AS value FROM ( SELECT attributes_string['TableName'] AS T, attributes_string['MissingId'] AS M, max(fromUnixTimestamp64Nano(timestamp)) AS last_seen, dateDiff('minute', min(fromUnixTimestamp64Nano(timestamp)), max(fromUnixTimestamp64Nano(timestamp))) AS age_min FROM signoz_logs.distributed_logs_v2 WHERE body='missing_map_record' AND timestamp >= (toUnixTimestamp(now())-3600)*1000000000 GROUP BY T, M ) WHERE age_min >= 20 AND last_seen >= now() - toIntervalMinute(8)",
-			expectedStopsAfter: "(toUnixTimestamp(now())",
-			fix:                "SELECT (toUnixTimestamp(now()) - 3600) * 1000000000",
-		},
-		{
-			name:               "SignedLiteralAfterClosingParenMinimal",
-			query:              "SELECT (1)-1",
-			expectedStopsAfter: "(1)",
-			fix:                "SELECT (1) - 1",
-		},
 	}
 
 	for _, testCase := range testCases {

pkg/querybuilder/filter_split.go

@@ -0,0 +1,176 @@
+package querybuilder
+
+import (
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/antlr4-go/antlr/v4"
+)
+
+// SplitFilterForAggregates partitions a single filter expression into a span-level
+// part (a WHERE over spans) and a trace-level part (a HAVING over per-trace
+// aggregates), splitting on the top-level AND.
+//
+// A key is trace-level when it carries the trace field context (`trace.completion_tokens`)
+// or, with no context, its bare name is in aggregateNames. Any other explicit context
+// (`span.`, `resource.`, …) is span-level. Trace-level and span-level keys may be
+// AND-combined (they run at different query stages) but not OR-combined; an OR that
+// mixes the two is an error.
+func SplitFilterForAggregates(query string, aggregateNames map[string]struct{}) (spanExpr string, havingExpr string, err error) {
+	if strings.TrimSpace(query) == "" {
+		return "", "", nil
+	}
+
+	tree, syntaxErrors := parseFilterQuery(query)
+	if len(syntaxErrors) > 0 {
+		combinedErrors := errors.Newf(
+			errors.TypeInvalidInput,
+			errors.CodeInvalidInput,
+			"Found %d syntax errors while parsing the filter expression.",
+			len(syntaxErrors),
+		)
+		additionals := make([]string, 0, len(syntaxErrors))
+		for _, syntaxError := range syntaxErrors {
+			if syntaxError.Error() != "" {
+				additionals = append(additionals, syntaxError.Error())
+			}
+		}
+		// TODO: add troubleshooting link to the filter query syntax guide once it's published.
+		return "", "", combinedErrors.WithAdditional(additionals...)
+	}
+
+	s := filterSplitter{query: []rune(query), aggregateNames: aggregateNames}
+	s.visit(tree)
+
+	if s.mixed {
+		return "", "", errors.NewInvalidInputf(errors.CodeInvalidInput,
+			"trace-level and span-level filters cannot be combined within an OR/NOT group; separate them with a top-level AND")
+	}
+	return strings.Join(s.span, " AND "), strings.Join(s.having, " AND "), nil
+}
+
+func parseFilterQuery(query string) (antlr.Tree, []*SyntaxErr) {
+	lexerErrorListener := NewErrorListener()
+	lexer := grammar.NewFilterQueryLexer(antlr.NewInputStream(query))
+	lexer.RemoveErrorListeners()
+	lexer.AddErrorListener(lexerErrorListener)
+
+	parserErrorListener := NewErrorListener()
+	parser := grammar.NewFilterQueryParser(antlr.NewCommonTokenStream(lexer, 0))
+	parser.RemoveErrorListeners()
+	parser.AddErrorListener(parserErrorListener)
+
+	tree := parser.Query()
+	return tree, append(lexerErrorListener.SyntaxErrors, parserErrorListener.SyntaxErrors...)
+}
+
+// filterSplitter walks the parse tree once, flattening the top-level AND chain and
+// routing each atom (a comparison, a NOT expression, or a whole multi-branch OR group)
+// to the span or having bucket by the class of the keys it references.
+type filterSplitter struct {
+	query          []rune
+	aggregateNames map[string]struct{}
+	span           []string
+	having         []string
+	mixed          bool
+}
+
+func (s *filterSplitter) visit(node antlr.Tree) {
+	switch n := node.(type) {
+	case *grammar.QueryContext:
+		if n.Expression() != nil {
+			s.visit(n.Expression())
+		}
+	case *grammar.ExpressionContext:
+		if n.OrExpression() != nil {
+			s.visit(n.OrExpression())
+		}
+	case *grammar.OrExpressionContext:
+		// a single branch is just an AND chain; multiple branches are a real OR, kept
+		// whole so a class-mixing OR can be rejected.
+		if ands := n.AllAndExpression(); len(ands) == 1 {
+			s.visit(ands[0])
+		} else {
+			s.route(n)
+		}
+	case *grammar.AndExpressionContext:
+		for _, u := range n.AllUnaryExpression() {
+			s.visit(u)
+		}
+	case *grammar.UnaryExpressionContext:
+		if n.NOT() != nil {
+			s.route(n)
+		} else if n.Primary() != nil {
+			s.visit(n.Primary())
+		}
+	case *grammar.PrimaryContext:
+		if n.OrExpression() != nil { // parenthesized sub-expression
+			s.visit(n.OrExpression())
+		} else {
+			s.route(n)
+		}
+	}
+}
+
+// route classifies an atom and appends its original source text to the right bucket.
+func (s *filterSplitter) route(atom antlr.ParserRuleContext) {
+	isTrace, isSpan := classifyKeys(atom, s.aggregateNames)
+	if isTrace && isSpan {
+		s.mixed = true
+		return
+	}
+	text := atomSourceText(s.query, atom)
+	// A multi-branch OR group's source slice excludes its enclosing parens (they belong
+	// to the parent Primary). Re-wrap it so rejoining a bucket with " AND " cannot invert
+	// OR/AND precedence, e.g. `a AND (b OR c)` must not flatten to `a AND b OR c`.
+	if or, ok := atom.(*grammar.OrExpressionContext); ok && len(or.AllAndExpression()) > 1 {
+		text = "(" + text + ")"
+	}
+	if isTrace {
+		s.having = append(s.having, text)
+	} else {
+		s.span = append(s.span, text)
+	}
+}
+
+// classifyKeys reports whether a subtree references trace-level and/or span-level keys.
+// A key is trace-level when it carries the trace field context or, with no context,
+// its name is a known aggregate; an unknown name under the trace context stays
+// trace-level so the aggregate validation rejects it with a targeted error. Any other
+// explicit context (`span.`, `resource.`, …) is span-level.
+func classifyKeys(node antlr.Tree, aggregateNames map[string]struct{}) (isTrace, isSpan bool) {
+	kc, ok := node.(*grammar.KeyContext)
+	if ok {
+		key := telemetrytypes.GetFieldKeyFromKeyText(kc.GetText())
+		switch key.FieldContext {
+		case telemetrytypes.FieldContextTrace:
+			isTrace = true
+		case telemetrytypes.FieldContextUnspecified:
+			_, isTrace = aggregateNames[key.Name]
+			isSpan = !isTrace
+		default:
+			isSpan = true
+		}
+		return
+	}
+	for i := 0; i < node.GetChildCount(); i++ {
+		t, s := classifyKeys(node.GetChild(i), aggregateNames)
+		isTrace = isTrace || t
+		isSpan = isSpan || s
+	}
+	return
+}
+
+// atomSourceText returns the original source substring for an atom, preserving
+// whitespace. The token stream drops skipped whitespace, which would glue word
+// operators (OR/AND/NOT) to their operands, so slice the input by token offsets.
+// ANTLR offsets are rune indices (InputStream holds []rune), hence the rune slice.
+func atomSourceText(query []rune, atom antlr.ParserRuleContext) string {
+	start, stop := atom.GetStart(), atom.GetStop()
+	if start == nil || stop == nil || start.GetStart() < 0 || stop.GetStop() >= len(query) || stop.GetStop() < start.GetStart() {
+		return atom.GetText()
+	}
+	return string(query[start.GetStart() : stop.GetStop()+1])
+}

pkg/querybuilder/filter_split_test.go

@@ -0,0 +1,222 @@
+package querybuilder
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSplitFilterForAggregates(t *testing.T) {
+	agg := map[string]struct{}{"completion_tokens": {}, "span_count": {}, "prompt_tokens": {}}
+
+	type tc struct {
+		name    string
+		query   string
+		span    string // expected span-level (WHERE) part; "" => empty
+		having  string // expected trace-level (HAVING) part; "" => empty
+		wantErr bool
+	}
+
+	cases := []tc{
+		// --- empty input ---------------------------------------------------------
+		{
+			name: "empty",
+		},
+		{
+			name:  "whitespace only",
+			query: "   ",
+		},
+
+		// --- single class --------------------------------------------------------
+		{
+			name:  "span only",
+			query: "service.name = 'x'",
+			span:  "service.name = 'x'",
+		},
+		{
+			name:   "agg only bare",
+			query:  "completion_tokens > 1000",
+			having: "completion_tokens > 1000",
+		},
+		{
+			// the user-facing `trace.` prefix marks a trace-level aggregate.
+			name:   "agg only trace prefix",
+			query:  "trace.completion_tokens > 1000",
+			having: "trace.completion_tokens > 1000",
+		},
+		{
+			// an unknown name under the trace context still routes trace-level, so the
+			// aggregate validation rejects it with a targeted error instead of the span
+			// path failing on an unknown field.
+			name:   "unknown aggregate under trace context stays trace-level",
+			query:  "trace.not_an_aggregate > 1000",
+			having: "trace.not_an_aggregate > 1000",
+		},
+
+		{
+			// ANTLR token offsets are rune indices; slicing must not shift after a
+			// multi-byte char (this used to truncate 1000 → 100).
+			name:   "unicode value before the split",
+			query:  "service.name = 'héllo' AND completion_tokens > 1000",
+			span:   "service.name = 'héllo'",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- top-level AND splits across the two buckets -------------------------
+		{
+			name:   "span AND agg",
+			query:  "service.name = 'x' AND completion_tokens > 1000",
+			span:   "service.name = 'x'",
+			having: "completion_tokens > 1000",
+		},
+		{
+			// order within a bucket is preserved; the two span atoms join with AND.
+			name:   "span AND span AND agg",
+			query:  "service.name = 'x' AND kind_string = 'Internal' AND completion_tokens > 1000",
+			span:   "service.name = 'x' AND kind_string = 'Internal'",
+			having: "completion_tokens > 1000",
+		},
+		{
+			// a parenthesized top-level AND still splits across the two buckets.
+			name:   "parenthesized span AND agg",
+			query:  "(service.name = 'x' AND completion_tokens > 1000)",
+			span:   "service.name = 'x'",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- OR groups are re-wrapped in parens so a later AND-join can't invert
+		//     precedence (`a AND (b OR c)` must not flatten to `a AND b OR c`) ------
+		{
+			name:   "agg OR agg",
+			query:  "completion_tokens > 1000 OR span_count > 3",
+			having: "(completion_tokens > 1000 OR span_count > 3)",
+		},
+		{
+			name:  "span OR span",
+			query: "service.name = 'x' OR kind_string = 'Internal'",
+			span:  "(service.name = 'x' OR kind_string = 'Internal')",
+		},
+		{
+			name:  "span AND (span OR span)",
+			query: "service.name = 'x' AND (kind_string = 'Internal' OR kind_string = 'Client')",
+			span:  "service.name = 'x' AND (kind_string = 'Internal' OR kind_string = 'Client')",
+		},
+		{
+			name:   "agg AND (agg OR agg)",
+			query:  "prompt_tokens > 5 AND (completion_tokens > 1000 OR span_count > 3)",
+			having: "prompt_tokens > 5 AND (completion_tokens > 1000 OR span_count > 3)",
+		},
+		{
+			// the OR group routes to span, the trailing aggregate to having.
+			name:   "span AND (span OR span) AND agg",
+			query:  "a.b = 'x' AND (c.d = 'y' OR e.f = 'z') AND completion_tokens > 1000",
+			span:   "a.b = 'x' AND (c.d = 'y' OR e.f = 'z')",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- a nested AND group flattens across the buckets (no spurious parens) --
+		{
+			name:   "(span AND agg) AND agg",
+			query:  "(service.name = 'x' AND completion_tokens > 1000) AND prompt_tokens > 5",
+			span:   "service.name = 'x'",
+			having: "completion_tokens > 1000 AND prompt_tokens > 5",
+		},
+
+		// --- NOT wrapping a single-class group is routed whole to that class ------
+		{
+			name:   "not agg",
+			query:  "NOT (completion_tokens > 1000)",
+			having: "NOT (completion_tokens > 1000)",
+		},
+		{
+			name:  "not span",
+			query: "NOT (service.name = 'x')",
+			span:  "NOT (service.name = 'x')",
+		},
+
+		// --- an explicit non-trace context escapes the aggregate-alias shadow -----
+		{
+			// a span attribute named like an aggregate stays reachable via `attribute.`.
+			name:  "attribute prefix on aggregate name routes span-level",
+			query: "attribute.completion_tokens > 5",
+			span:  "attribute.completion_tokens > 5",
+		},
+		{
+			name:  "span prefix on aggregate name routes span-level",
+			query: "span.completion_tokens > 5",
+			span:  "span.completion_tokens > 5",
+		},
+		{
+			name:   "prefixed attribute AND bare aggregate split across buckets",
+			query:  "attribute.completion_tokens > 5 AND completion_tokens > 1000",
+			span:   "attribute.completion_tokens > 5",
+			having: "completion_tokens > 1000",
+		},
+
+		// --- class-mixing is rejected in an OR group, a NOT group, or a nested OR -
+		{
+			name:    "agg OR span rejected",
+			query:   "completion_tokens > 1000 OR service.name = 'x'",
+			wantErr: true,
+		},
+		{
+			name:    "not mixed rejected",
+			query:   "NOT (completion_tokens > 1000 AND service.name = 'x')",
+			wantErr: true,
+		},
+		{
+			name:    "span AND (agg OR span) rejected",
+			query:   "service.name = 'x' AND (completion_tokens > 1000 OR kind_string = 'Client')",
+			wantErr: true,
+		},
+
+		// --- syntax errors are rejected, not silently dropped by error recovery ---
+		{
+			// recovery would yield an empty tree → both buckets empty → filter ignored.
+			name:    "lone paren rejected",
+			query:   ")",
+			wantErr: true,
+		},
+		{
+			name:    "unbalanced parens rejected",
+			query:   "((",
+			wantErr: true,
+		},
+		{
+			name:    "bare operator rejected",
+			query:   "AND",
+			wantErr: true,
+		},
+		{
+			// lexer-level error: recovery drops the whole expression.
+			name:    "unterminated quote rejected",
+			query:   "'unterminated",
+			wantErr: true,
+		},
+		{
+			// recovery would drop only the malformed atom and keep the rest — a
+			// partially applied filter with no error.
+			name:    "garbage atom alongside valid agg rejected",
+			query:   ") AND completion_tokens > 5",
+			wantErr: true,
+		},
+		{
+			name:    "missing value rejected",
+			query:   "completion_tokens >",
+			wantErr: true,
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			span, having, err := SplitFilterForAggregates(c.query, agg)
+			if c.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			require.Equal(t, c.span, span, "span part")
+			require.Equal(t, c.having, having, "having part")
+		})
+	}
+}

pkg/querybuilder/having_rewriter.go

@@ -18,6 +18,19 @@ func NewHavingExpressionRewriter() *HavingExpressionRewriter {
 	}
 }
 
+// Rewrite rewrites and validates a HAVING expression against a caller-supplied
+// column map (user-facing name -> SQL identifier/expression). Values are inlined, so
+// the result is a bare SQL boolean expression with no bound args. Used by callers
+// that project their own aggregate columns (e.g. the AI trace list) rather than the
+// query's Aggregations.
+func (r *HavingExpressionRewriter) Rewrite(expression string, columnMap map[string]string) (string, error) {
+	if len(strings.TrimSpace(expression)) == 0 {
+		return "", nil
+	}
+	r.columnMap = columnMap
+	return r.rewriteAndValidate(expression)
+}
+
 // RewriteForTraces rewrites and validates the HAVING expression for a traces query.
 func (r *HavingExpressionRewriter) RewriteForTraces(expression string, aggregations []qbtypes.TraceAggregation) (string, error) {
 	if len(strings.TrimSpace(expression)) == 0 {

pkg/querybuilder/query_range_resources.go

@@ -82,6 +82,10 @@ func resourcesForQuery(query gjson.Result, variables map[string]qbtypes.Variable
 	switch queryType {
 	case qbtypes.QueryTypeBuilder.StringValue(), qbtypes.QueryTypeSubQuery.StringValue():
 		return resourcesForBuilderQuery(queryType, query.Get("spec"), variables)
+	case qbtypes.QueryTypeBuilderAI.StringValue():
+		// An AI builder query is always a traces query; the signal is implied by the
+		// type (and may be absent from the payload), so pin the resource directly.
+		return builderQueryResourceRefs(queryType, coretypes.ResourceTelemetryResourceTraces, query.Get("spec"), variables)
 	case qbtypes.QueryTypePromQL.StringValue():
 		return []coretypes.ResourceWithID{{Resource: coretypes.ResourceTelemetryResourceMetrics, ID: typeWildcard}}, nil
 	case qbtypes.QueryTypeClickHouseSQL.StringValue():
@@ -103,7 +107,10 @@ func resourcesForBuilderQuery(queryType string, spec gjson.Result, variables map
 	if err != nil {
 		return nil, err
 	}
+	return builderQueryResourceRefs(queryType, resource, spec, variables)
+}
 
+func builderQueryResourceRefs(queryType string, resource coretypes.Resource, spec gjson.Result, variables map[string]qbtypes.VariableItem) ([]coretypes.ResourceWithID, error) {
 	ids, err := builderQuerySelectors(queryType, spec.Get("filter.expression").String(), variables)
 	if err != nil {
 		return nil, err

pkg/querybuilder/query_range_resources_test.go

@@ -92,6 +92,20 @@ func TestQueryRangeResources(t *testing.T) {
 				{Resource: coretypes.ResourceTelemetryResourceAuditLogs, ID: "builder_query/signoz.workspace.key.id/a"},
 			},
 		},
+		{
+			name: "ai builder query maps to traces resource without a signal",
+			body: `{"compositeQuery":{"queries":[{"type":"builder_ai_query","spec":{"filter":{"expression":"signoz.workspace.key.id = 'checkout'"}}}]}}`,
+			expected: []coretypes.ResourceWithID{
+				{Resource: coretypes.ResourceTelemetryResourceTraces, ID: "builder_ai_query/signoz.workspace.key.id/checkout"},
+			},
+		},
+		{
+			name: "ai builder query without filter is wildcard",
+			body: `{"compositeQuery":{"queries":[{"type":"builder_ai_query","spec":{}}]}}`,
+			expected: []coretypes.ResourceWithID{
+				{Resource: coretypes.ResourceTelemetryResourceTraces, ID: "builder_ai_query/*"},
+			},
+		},
 		{
 			name: "promql is wildcard only",
 			body: `{"compositeQuery":{"queries":[{"type":"promql","spec":{"query":"up"}}]}}`,

pkg/signoz/provider.go

@@ -230,6 +230,7 @@ func NewSQLMigrationProviderFactories(
 		sqlmigration.NewAddTagRelationRankFactory(sqlstore, sqlschema),
 		sqlmigration.NewMigrateDashboardsV1ToV2Factory(sqlstore, sqlschema, dashboardStore, tagModule),
 		sqlmigration.NewFillDashboardMeterSourceFactory(sqlstore, dashboardStore),
+		sqlmigration.NewUpdateRoleTransactionGroupsFactory(),
 	)
 }
 
@@ -288,9 +289,9 @@ func NewStatsReporterProviderFactories(aggregator statsreporter.Aggregator, orgG
 	)
 }
 
-func NewQuerierProviderFactories(telemetryStore telemetrystore.TelemetryStore, prometheus prometheus.Prometheus, metadataStore telemetrytypes.MetadataStore, traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation], logStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation], auditStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation], metricStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation], meterStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation], traceOperatorStmtBuilder qbtypes.TraceOperatorStatementBuilder, bucketCache querier.BucketCache, flagger flagger.Flagger) factory.NamedMap[factory.ProviderFactory[querier.Querier, querier.Config]] {
+func NewQuerierProviderFactories(telemetryStore telemetrystore.TelemetryStore, prometheus prometheus.Prometheus, metadataStore telemetrytypes.MetadataStore, traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation], aiTraceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation], logStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation], auditStmtBuilder qbtypes.StatementBuilder[qbtypes.LogAggregation], metricStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation], meterStmtBuilder qbtypes.StatementBuilder[qbtypes.MetricAggregation], traceOperatorStmtBuilder qbtypes.TraceOperatorStatementBuilder, bucketCache querier.BucketCache, flagger flagger.Flagger) factory.NamedMap[factory.ProviderFactory[querier.Querier, querier.Config]] {
 	return factory.MustNewNamedMap(
-		signozquerier.NewFactory(telemetryStore, prometheus, metadataStore, traceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, flagger),
+		signozquerier.NewFactory(telemetryStore, prometheus, metadataStore, traceStmtBuilder, aiTraceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, flagger),
 	)
 }
 

pkg/signoz/signoz.go

@@ -48,6 +48,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/sqlmigrator"
 	"github.com/SigNoz/signoz/pkg/sqlschema"
 	"github.com/SigNoz/signoz/pkg/sqlstore"
+	"github.com/SigNoz/signoz/pkg/statementbuilder/aistatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/auditstatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/logsstatementbuilder"
 	"github.com/SigNoz/signoz/pkg/statementbuilder/meterstatementbuilder"
@@ -99,9 +100,9 @@ type SigNoz struct {
 
 // newQueryStack assembles the query stack once and returns, in order: the shared
 // telemetry metadata store (reused elsewhere in signoz.New), the per-signal
-// statement builders (trace, log, audit, metric, meter, trace-operator), and the
-// bucket cache. It is the only place that imports the concrete statement-builder
-// sub-packages.
+// statement builders (trace, ai-trace, log, audit, metric, meter, trace-operator),
+// and the bucket cache. It is the only place that imports the concrete
+// statement-builder sub-packages.
 func newQueryStack(
 	ctx context.Context,
 	settings factory.ProviderSettings,
@@ -112,6 +113,7 @@ func newQueryStack(
 ) (
 	telemetrytypes.MetadataStore,
 	qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	qbtypes.StatementBuilder[qbtypes.TraceAggregation],
 	qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	qbtypes.StatementBuilder[qbtypes.LogAggregation],
 	qbtypes.StatementBuilder[qbtypes.MetricAggregation],
@@ -125,32 +127,36 @@ func newQueryStack(
 	cfg := config.StatementBuilder
 	traceStmtBuilder, err := tracesstatementbuilder.NewFactory(telemetryStore, metadataStore, fl).New(ctx, settings, cfg)
 	if err != nil {
-		return nil, nil, nil, nil, nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
+	}
+	aiTraceStmtBuilder, err := aistatementbuilder.NewFactory(telemetryStore, metadataStore, fl).New(ctx, settings, cfg)
+	if err != nil {
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
 	}
 	traceOperatorStmtBuilder, err := tracesstatementbuilder.NewOperatorFactory(telemetryStore, metadataStore, fl).New(ctx, settings, cfg)
 	if err != nil {
-		return nil, nil, nil, nil, nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
 	}
 	logStmtBuilder, err := logsstatementbuilder.NewFactory(telemetryStore, metadataStore, fl).New(ctx, settings, cfg)
 	if err != nil {
-		return nil, nil, nil, nil, nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
 	}
 	auditStmtBuilder, err := auditstatementbuilder.NewFactory(metadataStore, fl).New(ctx, settings, cfg)
 	if err != nil {
-		return nil, nil, nil, nil, nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
 	}
 	metricStmtBuilder, err := metricsstatementbuilder.NewFactory(metadataStore, fl).New(ctx, settings, cfg)
 	if err != nil {
-		return nil, nil, nil, nil, nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
 	}
 	meterStmtBuilder, err := meterstatementbuilder.NewFactory(metadataStore, fl).New(ctx, settings, cfg)
 	if err != nil {
-		return nil, nil, nil, nil, nil, nil, nil, nil, err
+		return nil, nil, nil, nil, nil, nil, nil, nil, nil, err
 	}
 
 	bucketCache := querier.NewBucketCache(settings, cache, config.Querier.CacheTTL, config.Querier.FluxInterval)
 
-	return metadataStore, traceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, nil
+	return metadataStore, traceStmtBuilder, aiTraceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, nil
 }
 
 func New(
@@ -313,7 +319,7 @@ func New(
 
 	// Assemble the query stack (metadata store, statement builders, bucket cache) once,
 	// and reuse the single metadata store everywhere downstream.
-	telemetryMetadataStore, traceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, err := newQueryStack(ctx, providerSettings, config, telemetrystore, cache, flagger)
+	telemetryMetadataStore, traceStmtBuilder, aiTraceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, err := newQueryStack(ctx, providerSettings, config, telemetrystore, cache, flagger)
 	if err != nil {
 		return nil, err
 	}
@@ -323,7 +329,7 @@ func New(
 		ctx,
 		providerSettings,
 		config.Querier,
-		NewQuerierProviderFactories(telemetrystore, prometheus, telemetryMetadataStore, traceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, flagger),
+		NewQuerierProviderFactories(telemetrystore, prometheus, telemetryMetadataStore, traceStmtBuilder, aiTraceStmtBuilder, logStmtBuilder, auditStmtBuilder, metricStmtBuilder, meterStmtBuilder, traceOperatorStmtBuilder, bucketCache, flagger),
 		config.Querier.Provider(),
 	)
 	if err != nil {

pkg/sqlmigration/105_update_role_transaction_groups.go

@@ -0,0 +1,77 @@
+package sqlmigration
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/types/authtypes"
+	"github.com/SigNoz/signoz/pkg/types/coretypes"
+	"github.com/uptrace/bun"
+	"github.com/uptrace/bun/migrate"
+)
+
+type updateRoleTransactionGroups struct{}
+
+func NewUpdateRoleTransactionGroupsFactory() factory.ProviderFactory[SQLMigration, Config] {
+	return factory.NewProviderFactory(
+		factory.MustNewName("update_role_transaction_groups"),
+		func(ctx context.Context, ps factory.ProviderSettings, c Config) (SQLMigration, error) {
+			return &updateRoleTransactionGroups{}, nil
+		},
+	)
+}
+
+func (migration *updateRoleTransactionGroups) Register(migrations *migrate.Migrations) error {
+	return migrations.Register(migration.Up, migration.Down)
+}
+
+func (migration *updateRoleTransactionGroups) Up(ctx context.Context, db *bun.DB) error {
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+
+	defer func() {
+		_ = tx.Rollback()
+	}()
+
+	var orgIDs []string
+	err = tx.NewSelect().
+		Table("organizations").
+		Column("id").
+		Scan(ctx, &orgIDs)
+	if err != nil && err != sql.ErrNoRows {
+		return err
+	}
+
+	managedRoleGroups := make(map[string]string, len(coretypes.ManagedRoleToTransactions))
+	for roleName, transactions := range coretypes.ManagedRoleToTransactions {
+		data, err := json.Marshal(authtypes.NewTransactionGroupsFromTransactions(transactions))
+		if err != nil {
+			return err
+		}
+		managedRoleGroups[roleName] = string(data)
+	}
+
+	for _, orgID := range orgIDs {
+		for roleName, data := range managedRoleGroups {
+			if _, err := tx.NewUpdate().
+				Model(new(roles)).
+				Set("transaction_groups = ?", data).
+				Where("org_id = ?", orgID).
+				Where("type = ?", authtypes.RoleTypeManaged.StringValue()).
+				Where("name = ?", roleName).
+				Exec(ctx); err != nil {
+				return err
+			}
+		}
+	}
+
+	return tx.Commit()
+}
+
+func (migration *updateRoleTransactionGroups) Down(context.Context, *bun.DB) error {
+	return nil
+}

pkg/statementbuilder/aistatementbuilder/statement_builder.go

@@ -0,0 +1,84 @@
+package aistatementbuilder
+
+import (
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/statementbuilder"
+	scopedtraces "github.com/SigNoz/signoz/pkg/statementbuilder/scopedtracesstatementbuilder"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// NewFactory returns a provider factory for the AI trace statement builder
+// (builder_ai_query): the gen_ai Scope paired with the domain-neutral scoped-trace
+// topology, which owns the query construction.
+//
+// The gen_ai gate/column keys are surfaced by the metadata store itself
+// (enrichWithGenAIKeys), so queries work before any gen_ai metadata is ingested.
+func NewFactory(
+	telemetryStore telemetrystore.TelemetryStore,
+	metadataStore telemetrytypes.MetadataStore,
+	fl flagger.Flagger,
+) factory.ProviderFactory[qbtypes.StatementBuilder[qbtypes.TraceAggregation], statementbuilder.Config] {
+	return scopedtraces.NewFactory(factory.MustNewName("ai"), Scope(), telemetryStore, metadataStore, fl)
+}
+
+// Scope describes gen_ai for the scoped trace builder: an AI trace has >=1 gen_ai
+// LLM, tool, or agent span, and its list adds AI/LLM per-trace metrics on top of the
+// common columns. This package holds only gen_ai domain knowledge; the query
+// topology lives in scopedtracesstatementbuilder.
+func Scope() scopedtraces.TraceScope {
+	gateKeyNames := []string{telemetrytypes.GenAIRequestModel, telemetrytypes.GenAIToolName, telemetrytypes.GenAIAgentName}
+	gateExprs := make([]string, 0, len(gateKeyNames))
+	gateKeys := make([]*telemetrytypes.TelemetryFieldKey, 0, len(gateKeyNames))
+	for _, name := range gateKeyNames {
+		gateExprs = append(gateExprs, name+" EXISTS")
+		gateKeys = append(gateKeys, &telemetrytypes.TelemetryFieldKey{
+			Name:         name,
+			Signal:       telemetrytypes.SignalTraces,
+			FieldContext: telemetrytypes.FieldContextAttribute,
+		})
+	}
+
+	defs := telemetrytypes.GenAIFieldDefinitions
+	reqModel := defs[telemetrytypes.GenAIRequestModel]
+	toolName := defs[telemetrytypes.GenAIToolName]
+	inTok := defs[telemetrytypes.GenAIUsageInputTokens]
+	outTok := defs[telemetrytypes.GenAIUsageOutputTokens]
+	cost := defs[telemetrytypes.SignozGenAITotalCost]
+	inMsg := defs[telemetrytypes.GenAIInputMessages]
+	outMsg := defs[telemetrytypes.GenAIOutputMessages]
+
+	str := telemetrytypes.FieldDataTypeString
+	columns := append(scopedtraces.CommonTraceColumns(),
+		// LLM calls only (request model present), not the full gate.
+		scopedtraces.TraceColumn{Alias: "llm_call_count", Orderable: true, Expr: scopedtraces.CountExists(&reqModel)},
+		scopedtraces.TraceColumn{Alias: "tool_call_count", Orderable: true, Expr: scopedtraces.CountExists(&toolName)},
+		scopedtraces.TraceColumn{Alias: "distinct_tool_count", Orderable: true, Expr: scopedtraces.UniqCount(&toolName, str)},
+		// tokens live only on LLM spans, so a plain sum needs no gate scoping.
+		scopedtraces.TraceColumn{Alias: "input_tokens", Orderable: true, Expr: scopedtraces.Reduce(scopedtraces.AggSum, &inTok)},
+		scopedtraces.TraceColumn{Alias: "output_tokens", Orderable: true, Expr: scopedtraces.Reduce(scopedtraces.AggSum, &outTok)},
+		scopedtraces.TraceColumn{Alias: "total_tokens", Orderable: true, Expr: scopedtraces.SumOfKeys(telemetrytypes.FieldDataTypeFloat64, &inTok, &outTok)},
+		// per-span cost attached by the SigNoz LLM pricing processor.
+		scopedtraces.TraceColumn{Alias: "estimated_total_cost", Orderable: true, Expr: scopedtraces.Reduce(scopedtraces.AggSum, &cost)},
+		// slowest single LLM call in the trace.
+		scopedtraces.TraceColumn{Alias: "max_llm_duration_nano", Orderable: true, Expr: scopedtraces.ScopedToKeyColumn(scopedtraces.AggMax, scopedtraces.IntrinsicSpanKey("duration_nano"), &reqModel)},
+		// errors across the whole trace (any span), so display-only.
+		scopedtraces.TraceColumn{Alias: "error_count", Expr: scopedtraces.CondCount(scopedtraces.IntrinsicSpanKey("has_error"), qbtypes.FilterOperatorEqual, true)},
+		// timestamp of the last gen_ai span (LLM/tool/agent), hence gate-scoped.
+		scopedtraces.TraceColumn{Alias: "last_activity_time", Orderable: true, Expr: scopedtraces.ScopedReduce(scopedtraces.AggMax, scopedtraces.IntrinsicSpanKey("timestamp"))},
+		// previews: first call's input (the prompt), last call's output (the answer).
+		scopedtraces.TraceColumn{Alias: "input", SpanLevel: true, Expr: scopedtraces.PickBy(&inMsg, str, scopedtraces.IntrinsicSpanKey("timestamp"), scopedtraces.PickEarliest)},
+		scopedtraces.TraceColumn{Alias: "output", SpanLevel: true, Expr: scopedtraces.PickBy(&outMsg, str, scopedtraces.IntrinsicSpanKey("timestamp"), scopedtraces.PickLatest)},
+	)
+
+	return scopedtraces.TraceScope{
+		FilterExpression:  strings.Join(gateExprs, " OR "),
+		FieldKeys:         gateKeys,
+		Columns:           columns,
+		DefaultOrderAlias: "last_activity_time",
+	}
+}

pkg/statementbuilder/auditstatementbuilder/statement_builder.go

@@ -205,7 +205,7 @@ func (b *auditQueryStatementBuilder) adjustKeys(ctx context.Context, keys map[st
 	}
 
 	for _, action := range actions {
-		b.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 
 	return query

pkg/statementbuilder/logsstatementbuilder/statement_builder.go

@@ -274,8 +274,7 @@ func (b *logQueryStatementBuilder) adjustKeys(ctx context.Context, keys map[stri
 	}
 
 	for _, action := range actions {
-		// TODO: change to debug level once we are confident about the behavior
-		b.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 
 	return query

pkg/statementbuilder/scopedtracesstatementbuilder/aggregate.go

@@ -0,0 +1,208 @@
+package scopedtracesstatementbuilder
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// This file holds the Aggregate constructors a TraceScope's columns are declared
+// with. All SQL rendering goes through the fieldMapper.
+
+// Aggregate renders one column's SQL through the fieldMapper and lists the attribute
+// keys it references so the builder can pre-fetch their metadata. Build one with the
+// constructors below; the zero value is not usable.
+type Aggregate struct {
+	keys   []*telemetrytypes.TelemetryFieldKey
+	render func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (expr string, args []any, err error)
+}
+
+// IntrinsicSpanKey references an intrinsic span-index field (timestamp, name, …) by
+// its canonical name; the field mapper resolves it to the physical column.
+func IntrinsicSpanKey(name string) *telemetrytypes.TelemetryFieldKey {
+	return &telemetrytypes.TelemetryFieldKey{
+		Name:         name,
+		Signal:       telemetrytypes.SignalTraces,
+		FieldContext: telemetrytypes.FieldContextSpan,
+	}
+}
+
+// AggFunc is a ClickHouse aggregate function name.
+type AggFunc string
+
+const (
+	AggSum AggFunc = "sum"
+	AggMax AggFunc = "max"
+	AggMin AggFunc = "min"
+)
+
+// PickDirection selects the earliest (argMin) or latest (argMax) span by ordering.
+type PickDirection int
+
+const (
+	PickLatest PickDirection = iota
+	PickEarliest
+)
+
+// CountAll renders count().
+func CountAll() Aggregate {
+	return Aggregate{render: func(context.Context, valuer.UUID, uint64, uint64, *fieldMapper) (string, []any, error) {
+		return "count()", nil, nil
+	}}
+}
+
+// FieldReduce renders <fn>(<field>) over a field-mapper-resolved column.
+func FieldReduce(fn AggFunc, key *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		f, err := m.FieldFor(ctx, orgID, startNs, endNs, key)
+		if err != nil {
+			return "", nil, err
+		}
+		return fmt.Sprintf("%s(%s)", fn, f), nil, nil
+	}}
+}
+
+// TraceDuration renders the full-trace wall duration: last span end minus first
+// span start.
+func TraceDuration(tsKey, durationKey *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		ts, err := m.FieldFor(ctx, orgID, startNs, endNs, tsKey)
+		if err != nil {
+			return "", nil, err
+		}
+		dur, err := m.FieldFor(ctx, orgID, startNs, endNs, durationKey)
+		if err != nil {
+			return "", nil, err
+		}
+		return fmt.Sprintf("(max(toUnixTimestamp64Nano(%s) + %s) - min(toUnixTimestamp64Nano(%s)))", ts, dur, ts), nil, nil
+	}}
+}
+
+// FieldAnyWhere renders anyIf(<field>, <cond>) — the field value from any span
+// matching the condition.
+func FieldAnyWhere(valueKey, condKey *telemetrytypes.TelemetryFieldKey, op qbtypes.FilterOperator, condValue any) Aggregate {
+	return Aggregate{render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		v, err := m.FieldFor(ctx, orgID, startNs, endNs, valueKey)
+		if err != nil {
+			return "", nil, err
+		}
+		cond, args, err := m.ConditionFor(ctx, orgID, startNs, endNs, condKey, op, condValue)
+		return fmt.Sprintf("anyIf(%s, %s)", v, cond), args, err
+	}}
+}
+
+// AnyValue renders any(<value>) over a metadata-resolved attribute value.
+func AnyValue(key *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType) Aggregate {
+	return Aggregate{keys: keysOf(key), render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		v, args, err := m.ValueFor(ctx, orgID, startNs, endNs, key, dt)
+		return fmt.Sprintf("any(%s)", v), args, err
+	}}
+}
+
+// CountExists renders countIf(<key> EXISTS) — counts spans carrying key.
+func CountExists(key *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: keysOf(key), render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		cond, args, err := m.ExistsFor(ctx, orgID, startNs, endNs, key)
+		return fmt.Sprintf("countIf(%s)", cond), args, err
+	}}
+}
+
+// CondCount renders countIf(<cond>) over a condition-builder-resolved predicate.
+func CondCount(key *telemetrytypes.TelemetryFieldKey, op qbtypes.FilterOperator, value any) Aggregate {
+	return Aggregate{render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		cond, args, err := m.ConditionFor(ctx, orgID, startNs, endNs, key, op, value)
+		return fmt.Sprintf("countIf(%s)", cond), args, err
+	}}
+}
+
+// Reduce renders <fn>(<value>) over a resolved numeric attribute value.
+func Reduce(fn AggFunc, valueKey *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: keysOf(valueKey), render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		v, args, err := m.ValueFor(ctx, orgID, startNs, endNs, valueKey, telemetrytypes.FieldDataTypeFloat64)
+		return fmt.Sprintf("%s(%s)", fn, v), args, err
+	}}
+}
+
+// ScopedReduce renders <fn>If(<field>, <gate mask>) over a field-mapper-resolved column.
+func ScopedReduce(fn AggFunc, key *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		f, err := m.FieldFor(ctx, orgID, startNs, endNs, key)
+		if err != nil {
+			return "", nil, err
+		}
+		return fmt.Sprintf("%sIf(%s, %s)", fn, f, m.maskExpr), append([]any{}, m.maskArgs...), nil
+	}}
+}
+
+// ScopedToKeyColumn renders <fn>If(<field>, <scopeKey> EXISTS) — a span-index field
+// aggregated over spans carrying scopeKey (e.g. max LLM latency).
+func ScopedToKeyColumn(fn AggFunc, columnKey, scopeKey *telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: keysOf(scopeKey), render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		col, err := m.FieldFor(ctx, orgID, startNs, endNs, columnKey)
+		if err != nil {
+			return "", nil, err
+		}
+		cond, args, err := m.ExistsFor(ctx, orgID, startNs, endNs, scopeKey)
+		return fmt.Sprintf("%sIf(%s, %s)", fn, col, cond), args, err
+	}}
+}
+
+// PickBy renders argMinIf/argMaxIf(<value>, <orderField>, <value> EXISTS) — the value
+// from the earliest/latest span that carries it.
+func PickBy(valueKey *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType, orderKey *telemetrytypes.TelemetryFieldKey, dir PickDirection) Aggregate {
+	fn := "argMaxIf"
+	if dir == PickEarliest {
+		fn = "argMinIf"
+	}
+	return Aggregate{keys: keysOf(valueKey), render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		v, vargs, err := m.ValueFor(ctx, orgID, startNs, endNs, valueKey, dt)
+		if err != nil {
+			return "", nil, err
+		}
+		order, err := m.FieldFor(ctx, orgID, startNs, endNs, orderKey)
+		if err != nil {
+			return "", nil, err
+		}
+		cond, cargs, err := m.ExistsFor(ctx, orgID, startNs, endNs, valueKey)
+		return fmt.Sprintf("%s(%s, %s, %s)", fn, v, order, cond), append(vargs, cargs...), err
+	}}
+}
+
+// UniqCount renders uniqIf(<value>, <value> EXISTS) — distinct count of an attribute.
+func UniqCount(valueKey *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType) Aggregate {
+	return Aggregate{keys: keysOf(valueKey), render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		v, vargs, err := m.ValueFor(ctx, orgID, startNs, endNs, valueKey, dt)
+		if err != nil {
+			return "", nil, err
+		}
+		cond, cargs, err := m.ExistsFor(ctx, orgID, startNs, endNs, valueKey)
+		return fmt.Sprintf("uniqIf(%s, %s)", v, cond), append(vargs, cargs...), err
+	}}
+}
+
+// SumOfKeys renders coalesce(sum(<v1>), 0) + coalesce(sum(<v2>), 0) + … over several
+// numeric attributes. Coalesced because a key absent from every span sums to NULL and
+// NULL + n = NULL — a trace with only output tokens would otherwise total NULL.
+func SumOfKeys(dt telemetrytypes.FieldDataType, valueKeys ...*telemetrytypes.TelemetryFieldKey) Aggregate {
+	return Aggregate{keys: valueKeys, render: func(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, m *fieldMapper) (string, []any, error) {
+		parts := make([]string, 0, len(valueKeys))
+		var args []any
+		for _, k := range valueKeys {
+			v, vargs, err := m.ValueFor(ctx, orgID, startNs, endNs, k, dt)
+			if err != nil {
+				return "", nil, err
+			}
+			parts = append(parts, fmt.Sprintf("coalesce(sum(%s), 0)", v))
+			args = append(args, vargs...)
+		}
+		return strings.Join(parts, " + "), args, nil
+	}}
+}
+
+func keysOf(k *telemetrytypes.TelemetryFieldKey) []*telemetrytypes.TelemetryFieldKey {
+	return []*telemetrytypes.TelemetryFieldKey{k}
+}

pkg/statementbuilder/scopedtracesstatementbuilder/field_mapper.go

@@ -0,0 +1,82 @@
+package scopedtracesstatementbuilder
+
+import (
+	"context"
+	"strings"
+
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/huandu/go-sqlbuilder"
+)
+
+// fieldMapper resolves aggregate-column SQL through the shared field mapper and
+// condition builder, following their method shapes (FieldFor / ConditionFor / …) so
+// column resolution reads like the other statement builders. keys is the fetched
+// metadata for the keys the columns reference; the gate mask is set by the builder
+// after resolveMask (Scoped* aggregates embed it). All returned expressions are
+// escaped once, ready to embed in an outer builder.
+type fieldMapper struct {
+	fm       qbtypes.FieldMapper
+	cb       qbtypes.ConditionBuilder
+	keys     map[string][]*telemetrytypes.TelemetryFieldKey
+	maskExpr string
+	maskArgs []any
+}
+
+func newFieldMapper(fm qbtypes.FieldMapper, cb qbtypes.ConditionBuilder, keys map[string][]*telemetrytypes.TelemetryFieldKey) *fieldMapper {
+	return &fieldMapper{fm: fm, cb: cb, keys: keys}
+}
+
+// FieldFor returns the column expression for key via the field mapper.
+func (r *fieldMapper) FieldFor(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, key *telemetrytypes.TelemetryFieldKey) (string, error) {
+	return r.fm.FieldFor(ctx, orgID, startNs, endNs, key)
+
+}
+
+// ConditionFor returns a boolean predicate for key via the condition builder
+// (materialized column when present, else map access).
+func (r *fieldMapper) ConditionFor(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, key *telemetrytypes.TelemetryFieldKey, op qbtypes.FilterOperator, value any) (string, []any, error) {
+	sb := sqlbuilder.NewSelectBuilder()
+	// The condition builder owns key resolution: hand it the raw key plus the full
+	// metadata map and it matches/synthesizes the candidates itself.
+	conds, _, err := r.cb.ConditionFor(ctx, orgID, startNs, endNs, key, r.keys, qbtypes.ConditionBuilderOptions{}, op, value, sb)
+	if err != nil {
+		return "", nil, err
+	}
+	if len(conds) == 0 {
+		return "", nil, nil
+	}
+	// One condition per candidate variant (a key can be ingested under several data
+	// types); OR them all, like the visitor does for EXISTS.
+	if len(conds) == 1 {
+		sb.Where(conds[0])
+	} else {
+		sb.Where(sb.Or(conds...))
+	}
+	expr, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	expr = strings.TrimPrefix(expr, "WHERE ")
+	return sqlbuilder.Escape(expr), args, nil
+}
+
+// ExistsFor returns the EXISTS predicate for key.
+func (r *fieldMapper) ExistsFor(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, key *telemetrytypes.TelemetryFieldKey) (string, []any, error) {
+	return r.ConditionFor(ctx, orgID, startNs, endNs, key, qbtypes.FilterOperatorExists, nil)
+}
+
+// ValueFor returns the value expression for an attribute key.
+func (r *fieldMapper) ValueFor(ctx context.Context, orgID valuer.UUID, startNs, endNs uint64, key *telemetrytypes.TelemetryFieldKey, dt telemetrytypes.FieldDataType) (string, []any, error) {
+	// The scope declares keys statically, so a key like service.name can have evolutions.
+	// this is added for the evolution.
+	if cands := r.keys[key.Name]; len(cands) > 0 {
+		key = cands[0]
+	}
+	expr, err := r.fm.ColumnExpressionFor(ctx, orgID, startNs, endNs, key, dt, r.keys)
+	if err != nil {
+		return "", nil, err
+	}
+	// Escape before embedding in the outer builder: a materialized column name carries
+	// `$$` (from the dotted attribute name), which go-sqlbuilder's Build would otherwise
+	// unescape to a single `$` and reference the wrong column.
+	return sqlbuilder.Escape(expr), nil, nil
+}

pkg/statementbuilder/scopedtracesstatementbuilder/scope.go

@@ -0,0 +1,66 @@
+package scopedtracesstatementbuilder
+
+import (
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// TraceScope is the configuration the scoped trace builder accepts: which spans are
+// in scope and which per-trace columns the list computes. It only declares the gate
+// and the columns; the builder resolves everything through the field mapper, so
+// attribute access stays materialization-aware. A new span category only needs a
+// new TraceScope.
+type TraceScope struct {
+	// FilterExpression is the grammar-level (EXISTS) gate, used on the delegated
+	// span-list path.
+	FilterExpression string
+	// FieldKeys are the gate's keys, used to build the per-span mask
+	// (OR of resolved EXISTS conditions).
+	FieldKeys []*telemetrytypes.TelemetryFieldKey
+	// Columns are the per-trace output columns.
+	Columns []TraceColumn
+	// DefaultOrderAlias is sorted by (desc) when the query gives no order.
+	DefaultOrderAlias string
+}
+
+// TraceColumn is one per-trace output column.
+type TraceColumn struct {
+	// Alias must not reuse a physical span-index column name (e.g. duration_nano):
+	// ClickHouse resolves bare identifiers to same-SELECT aliases first, so any
+	// expression referencing that column would silently bind to the alias.
+	Alias string
+	// Orderable columns can be used in ORDER BY and the aggregate filter. All-span
+	// aggregates (span_count, trace_duration_nano, …) are display-only and set false.
+	Orderable bool
+	// SpanLevel columns surface a real span/resource attribute (service.name,
+	// input/output messages); a filter on them is applied span-level, so they are
+	// excluded from the trace-level aliases.
+	SpanLevel bool
+	Expr      Aggregate
+}
+
+// CommonTraceColumns are domain-neutral columns any trace list can reuse. All
+// aggregate over every span, so none is Orderable.
+func CommonTraceColumns() []TraceColumn {
+	ts := IntrinsicSpanKey("timestamp")
+	duration := IntrinsicSpanKey("duration_nano")
+	name := IntrinsicSpanKey("name")
+	parentSpanID := IntrinsicSpanKey("parent_span_id")
+	serviceName := &telemetrytypes.TelemetryFieldKey{
+		Name:          "service.name",
+		Signal:        telemetrytypes.SignalTraces,
+		FieldContext:  telemetrytypes.FieldContextResource,
+		FieldDataType: telemetrytypes.FieldDataTypeString,
+	}
+	return []TraceColumn{
+		{Alias: "start_time", Expr: FieldReduce(AggMin, ts)},
+		{Alias: "end_time", Expr: FieldReduce(AggMax, ts)},
+		// Not plain "duration_nano": that name is the intrinsic span field, and an
+		// alias would shadow it — both in ClickHouse identifier resolution and in
+		// bare-name filter classification.
+		{Alias: "trace_duration_nano", Expr: TraceDuration(ts, duration)},
+		{Alias: "span_count", Expr: CountAll()},
+		{Alias: "root_span_name", Expr: FieldAnyWhere(name, parentSpanID, qbtypes.FilterOperatorEqual, "")},
+		{Alias: "service.name", SpanLevel: true, Expr: AnyValue(serviceName, telemetrytypes.FieldDataTypeString)},
+	}
+}

pkg/statementbuilder/scopedtracesstatementbuilder/statement_builder.go

@@ -0,0 +1,802 @@
+package scopedtracesstatementbuilder
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sort"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/statementbuilder"
+	"github.com/SigNoz/signoz/pkg/statementbuilder/resourcefilter"
+	"github.com/SigNoz/signoz/pkg/statementbuilder/tracesstatementbuilder"
+	"github.com/SigNoz/signoz/pkg/telemetryschema/tracestelemetryschema"
+	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	qbvariables "github.com/SigNoz/signoz/pkg/variables"
+	"github.com/huandu/go-sqlbuilder"
+)
+
+var (
+	ErrUnsupportedRequestType = errors.NewInvalidInputf(errors.CodeInvalidInput, "unsupported request type for the scoped trace builder")
+)
+
+// scopedTraceStatementBuilder builds a trace list scoped to one span category
+// (e.g. gen_ai spans). The query shape is fixed; the TraceScope decides which spans
+// are in scope and which per-trace columns to compute, so a new category only needs
+// a new scope.
+type scopedTraceStatementBuilder struct {
+	logger                    *slog.Logger
+	metadataStore             telemetrytypes.MetadataStore
+	fm                        qbtypes.FieldMapper
+	cb                        qbtypes.ConditionBuilder
+	scope                     TraceScope
+	traceStmtBuilder          qbtypes.StatementBuilder[qbtypes.TraceAggregation]
+	resourceFilterStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation]
+}
+
+var _ qbtypes.StatementBuilder[qbtypes.TraceAggregation] = (*scopedTraceStatementBuilder)(nil)
+
+// NewFactory returns a provider factory for a scoped trace statement builder. Unlike
+// the per-signal factories this package is domain-neutral, so the caller supplies the
+// factory name and the TraceScope (see aistatementbuilder for the gen_ai scope). Its
+// New delegates the span-list path to a trace statement builder built via the traces
+// factory — mirroring how the meter factory builds its own metrics builder.
+func NewFactory(
+	name factory.Name,
+	scope TraceScope,
+	telemetryStore telemetrystore.TelemetryStore,
+	metadataStore telemetrytypes.MetadataStore,
+	fl flagger.Flagger,
+) factory.ProviderFactory[qbtypes.StatementBuilder[qbtypes.TraceAggregation], statementbuilder.Config] {
+	return factory.NewProviderFactory(
+		name,
+		func(ctx context.Context, settings factory.ProviderSettings, cfg statementbuilder.Config) (qbtypes.StatementBuilder[qbtypes.TraceAggregation], error) {
+			traceStmtBuilder, err := tracesstatementbuilder.NewFactory(telemetryStore, metadataStore, fl).New(ctx, settings, cfg)
+			if err != nil {
+				return nil, err
+			}
+			return NewScopedTraceStatementBuilder(settings, metadataStore, scope, traceStmtBuilder, fl), nil
+		},
+	)
+}
+
+// NewScopedTraceStatementBuilder wires the generic trace-list builder. The field
+// mapper / condition builder are built here, not injected — the list always scans the
+// traces span index. traceStmtBuilder (the delegate for the span-list path) is
+// injected because NewFactory already builds the canonical instance.
+func NewScopedTraceStatementBuilder(
+	settings factory.ProviderSettings,
+	metadataStore telemetrytypes.MetadataStore,
+	scope TraceScope,
+	traceStmtBuilder qbtypes.StatementBuilder[qbtypes.TraceAggregation],
+	fl flagger.Flagger,
+) qbtypes.StatementBuilder[qbtypes.TraceAggregation] {
+	scopedSettings := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/statementbuilder/scopedtracesstatementbuilder")
+
+	fm := tracestelemetryschema.NewFieldMapper()
+	cb := tracestelemetryschema.NewConditionBuilder(fm)
+
+	// Same resource-fingerprint prune as the standard trace builder — the list scans
+	// the same span index.
+	resourceFilterStmtBuilder := resourcefilter.New[qbtypes.TraceAggregation](
+		settings,
+		tracestelemetryschema.DBName,
+		tracestelemetryschema.TracesResourceV3TableName,
+		telemetrytypes.SignalTraces,
+		telemetrytypes.SourceUnspecified,
+		metadataStore,
+		nil,
+		fl,
+	)
+
+	return &scopedTraceStatementBuilder{
+		logger:                    scopedSettings.Logger(),
+		metadataStore:             metadataStore,
+		fm:                        fm,
+		cb:                        cb,
+		scope:                     scope,
+		traceStmtBuilder:          traceStmtBuilder,
+		resourceFilterStmtBuilder: resourceFilterStmtBuilder,
+	}
+}
+
+func (b *scopedTraceStatementBuilder) Build(
+	ctx context.Context,
+	orgID valuer.UUID,
+	start uint64,
+	end uint64,
+	requestType qbtypes.RequestType,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+	switch requestType {
+	case qbtypes.RequestTypeTrace:
+		return b.buildTraceListQuery(ctx, orgID, querybuilder.ToNanoSecs(start), querybuilder.ToNanoSecs(end), query, variables)
+	case qbtypes.RequestTypeRaw:
+		return b.buildDelegated(ctx, orgID, start, end, requestType, query, variables)
+	default:
+		return nil, ErrUnsupportedRequestType
+	}
+}
+
+// buildDelegated ANDs the base gate into the user filter and delegates to the
+// standard trace builder (the span-list / raw path).
+func (b *scopedTraceStatementBuilder) buildDelegated(
+	ctx context.Context,
+	orgID valuer.UUID,
+	start, end uint64,
+	requestType qbtypes.RequestType,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+	gate := b.scope.FilterExpression
+	expr := gate
+	if query.Filter != nil && strings.TrimSpace(query.Filter.Expression) != "" {
+		expr = fmt.Sprintf("(%s) AND (%s)", gate, query.Filter.Expression)
+	}
+
+	// shallow copy; only Filter is replaced, caller's query untouched
+	gated := query
+	gated.Filter = &qbtypes.Filter{Expression: expr}
+
+	return b.traceStmtBuilder.Build(ctx, orgID, start, end, requestType, gated, variables)
+}
+
+// buildTraceListQuery wires the CTE pipeline: one windowed pass picks the top-N
+// traces, then a bucket-pruned pass enriches only those.
+// Helpers appear in this file in the order they run. start/end are nanoseconds.
+//
+//	RESOLVE (keys/columns → SQL via the field mapper)
+//	  fetchKeys         metadata for every key we reference
+//	  resolveMask       the "span is in scope" predicate (OR of EXISTS)
+//	  resolveColumns    per-trace column SQL
+//	  resolveListOrders which columns to ORDER BY
+//	  splitFilter       span-level predicate + trace-level HAVING
+//
+//	BUILD
+//	  matched    one windowed, mask-pruned GROUP BY trace_id scan fusing gate + span
+//	     │       filter + HAVING + ORDER BY + LIMIT/OFFSET → the top-N trace_ids
+//	     ▼
+//	  ranked     [start,end] bounds of those traces, from the small summary table
+//	     ▼
+//	  buckets    the ts_bucket_start values they touch, to prune the next scan
+//	     ▼
+//	  enrichment every per-trace column for those traces over their full extent
+//	             (not window-clipped), scanning only their buckets
+//
+// Only Orderable columns are computable in the mask-pruned matched pass, so only they
+// can be ordered or filtered on; all-span columns (span_count, …) are output-only.
+func (b *scopedTraceStatementBuilder) buildTraceListQuery(
+	ctx context.Context,
+	orgID valuer.UUID,
+	start, end uint64,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	variables map[string]qbtypes.VariableItem,
+) (*qbtypes.Statement, error) {
+
+	startBucket := start/querybuilder.NsToSeconds - querybuilder.BucketAdjustment
+	endBucket := end / querybuilder.NsToSeconds
+
+	limit := query.Limit
+	if limit <= 0 {
+		limit = 100
+	}
+
+	// Resolve keys and columns once; all attribute access goes through the field mapper.
+	keys, err := b.fetchKeys(ctx, orgID)
+	if err != nil {
+		return nil, err
+	}
+	mapper := newFieldMapper(b.fm, b.cb, keys)
+	maskExpr, maskArgs, err := b.resolveMask(ctx, orgID, start, end, mapper)
+	if err != nil {
+		return nil, err
+	}
+	mapper.maskExpr, mapper.maskArgs = maskExpr, maskArgs
+	resolved, err := b.resolveColumns(ctx, orgID, start, end, mapper)
+	if err != nil {
+		return nil, err
+	}
+	orders, err := b.resolveListOrders(query.Order, resolved)
+	if err != nil {
+		return nil, err
+	}
+	orderableSet := orderableAliasSet(resolved)
+
+	// If the filter references resource attributes, add a __resource_filter CTE and
+	// narrow the matched scan by resource_fingerprint; the span predicate drops those
+	// keys so they aren't applied twice.
+	resourceFrag, resourceArgs, resourcePred, err := b.maybeAttachResourceFilter(ctx, orgID, query, start, end, variables)
+	if err != nil {
+		return nil, err
+	}
+
+	// Split the user filter: span-level predicate + trace-level HAVING expression.
+	fp, err := b.splitFilter(ctx, orgID, query, b.aggregateAliasSet(), orderableSet, start, end, variables)
+	if err != nil {
+		return nil, err
+	}
+
+	// matched → ranked → buckets → enrichment
+	matchedFrag, matchedArgs, err := b.buildMatchedCTE(start, end, startBucket, endBucket, resolved, orders, orderableSet, maskExpr, maskArgs, fp, resourcePred, limit, query.Offset)
+	if err != nil {
+		return nil, err
+	}
+	rankedFrag, rankedArgs := b.buildRankedCTE(start, end)
+	bucketsFrag := buildBucketsCTE()
+	mainSQL, mainArgs := b.buildEnrichmentSelect(resolved, orders)
+
+	cteFragments := []string{matchedFrag, rankedFrag, bucketsFrag}
+	cteArgs := [][]any{matchedArgs, rankedArgs, nil}
+
+	// __resource_filter must precede `matched`, which references it.
+	if resourceFrag != "" {
+		cteFragments = append([]string{resourceFrag}, cteFragments...)
+		cteArgs = append([][]any{resourceArgs}, cteArgs...)
+	}
+
+	finalSQL := querybuilder.CombineCTEs(cteFragments) + mainSQL + " SETTINGS distributed_product_mode='allow', max_memory_usage=10000000000"
+	finalArgs := querybuilder.PrependArgs(cteArgs, mainArgs)
+
+	return &qbtypes.Statement{
+		Query:          finalSQL,
+		Args:           finalArgs,
+		Warnings:       fp.warnings,
+		WarningsDocURL: fp.warningsURL,
+	}, nil
+}
+
+// maybeAttachResourceFilter builds the __resource_filter CTE (fingerprints matching
+// the filter's resource conditions) and the predicate narrowing the span scan by
+// resource_fingerprint; with no resource conditions it returns empty fragments.
+//
+// Unlike the standard trace builder there is deliberately no skip-fingerprint
+// fallback: falling back would leave the resource conditions inside the OR'd
+// span-filter bucket, which changes trace membership (any span from the resource +
+// any gen_ai span, instead of a gen_ai span from the resource). Resource conditions
+// always scope the whole matched scan.
+func (b *scopedTraceStatementBuilder) maybeAttachResourceFilter(
+	ctx context.Context,
+	orgID valuer.UUID,
+	query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation],
+	start, end uint64,
+	variables map[string]qbtypes.VariableItem,
+) (cteFrag string, cteArgs []any, fingerprintPred string, err error) {
+	stmt, err := b.resourceFilterStmtBuilder.Build(
+		ctx, orgID, start, end, qbtypes.RequestTypeRaw, query, variables,
+	)
+	if err != nil {
+		return "", nil, "", err
+	}
+	if stmt == nil {
+		return "", nil, "", nil
+	}
+	return fmt.Sprintf("__resource_filter AS (%s)", stmt.Query), stmt.Args,
+		"resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter)", nil
+}
+
+// ---------------------------------------------------------------------------
+// RESOLVE — turn keys/columns into field-mapper-aware SQL
+// ---------------------------------------------------------------------------
+
+func (b *scopedTraceStatementBuilder) fetchKeys(ctx context.Context, orgID valuer.UUID) (map[string][]*telemetrytypes.TelemetryFieldKey, error) {
+	fields := b.resolverFieldKeys()
+	selectors := make([]*telemetrytypes.FieldKeySelector, 0, len(fields))
+	for _, k := range fields {
+		selectors = append(selectors, &telemetrytypes.FieldKeySelector{
+			Name:              k.Name,
+			Signal:            k.Signal,
+			FieldContext:      k.FieldContext,
+			SelectorMatchType: telemetrytypes.FieldSelectorMatchTypeExact,
+		})
+	}
+	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, selectors)
+	return keys, err
+}
+
+func (b *scopedTraceStatementBuilder) resolverFieldKeys() []*telemetrytypes.TelemetryFieldKey {
+	seen := make(map[string]struct{})
+	var out []*telemetrytypes.TelemetryFieldKey
+	add := func(k *telemetrytypes.TelemetryFieldKey) {
+		if k == nil {
+			return
+		}
+		if _, dup := seen[k.Name]; dup {
+			return
+		}
+		seen[k.Name] = struct{}{}
+		out = append(out, k)
+	}
+	for _, k := range b.scope.FieldKeys {
+		add(k)
+	}
+	for _, c := range b.scope.Columns {
+		for _, k := range c.Expr.keys {
+			add(k)
+		}
+	}
+	return out
+}
+
+// resolveMask builds the per-span in-scope mask: OR of resolved EXISTS predicates
+// over the base condition's field keys.
+func (b *scopedTraceStatementBuilder) resolveMask(ctx context.Context, orgID valuer.UUID, start, end uint64, mapper *fieldMapper) (string, []any, error) {
+	fieldKeys := b.scope.FieldKeys
+	parts := make([]string, 0, len(fieldKeys))
+	var args []any
+	for _, key := range fieldKeys {
+		e, a, err := mapper.ExistsFor(ctx, orgID, start, end, key)
+		if err != nil {
+			return "", nil, err
+		}
+		parts = append(parts, e)
+		args = append(args, a...)
+	}
+	return "(" + strings.Join(parts, " OR ") + ")", args, nil
+}
+
+// resolvedColumn is a column resolved to SQL via the field mapper; expr is escaped
+// once, ready to embed in an outer SELECT.
+type resolvedColumn struct {
+	alias     string
+	expr      string
+	args      []any
+	orderable bool
+}
+
+// resolveColumns turns the declarative columns into SQL through the resolver, so all
+// attribute access goes through the field mapper / condition builder.
+func (b *scopedTraceStatementBuilder) resolveColumns(ctx context.Context, orgID valuer.UUID, start, end uint64, mapper *fieldMapper) ([]resolvedColumn, error) {
+	cols := b.scope.Columns
+	out := make([]resolvedColumn, 0, len(cols))
+	for _, c := range cols {
+		expr, args, err := c.Expr.render(ctx, orgID, start, end, mapper)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, resolvedColumn{alias: c.Alias, expr: expr, args: args, orderable: c.Orderable})
+	}
+	return out, nil
+}
+
+// listOrder is a sort key resolved to a column alias + direction; both the matched
+// CTE and the enrichment ORDER BY it.
+type listOrder struct {
+	alias     string
+	direction string
+}
+
+// resolveListOrders maps order keys to the resolved orderable columns; non-orderable
+// columns are rejected. Defaults to the column provider's default order.
+func (b *scopedTraceStatementBuilder) resolveListOrders(order []qbtypes.OrderBy, resolved []resolvedColumn) ([]listOrder, error) {
+	byAlias := make(map[string]resolvedColumn, len(resolved))
+	orderable := make([]string, 0, len(resolved))
+	for _, rc := range resolved {
+		byAlias[rc.alias] = rc
+		if rc.orderable {
+			orderable = append(orderable, rc.alias)
+		}
+	}
+
+	if len(order) == 0 {
+		return []listOrder{{alias: b.scope.DefaultOrderAlias, direction: "DESC"}}, nil
+	}
+
+	orders := make([]listOrder, 0, len(order))
+	for _, o := range order {
+		direction := "DESC"
+		if o.Direction == qbtypes.OrderDirectionAsc {
+			direction = "ASC"
+		}
+		rc, ok := byAlias[o.Key.Name]
+		if !ok || !rc.orderable {
+			return nil, errors.NewInvalidInputf(errors.CodeInvalidInput,
+				"unsupported order key %q for the trace list; orderable keys: %s", o.Key.Name, strings.Join(orderable, ", "))
+		}
+		orders = append(orders, listOrder{alias: rc.alias, direction: direction})
+	}
+	return orders, nil
+}
+
+// filterParts is the user filter split into a span-level predicate (widens the
+// matched WHERE prune and becomes a countIf existence check in HAVING) and a
+// trace-level HAVING expression.
+type filterParts struct {
+	spanPred      string
+	spanArgs      []any
+	hasSpanFilter bool
+	havingExpr    string
+	warnings      []string
+	warningsURL   string
+}
+
+// splitFilter splits query.Filter into a span-level predicate and a trace-level
+// HAVING expression (an explicit query.Having is ANDed onto the latter), then
+// validates the trace-level part against the matched-pass aggregates.
+func (b *scopedTraceStatementBuilder) splitFilter(ctx context.Context, orgID valuer.UUID, query qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation], classifySet, orderableSet map[string]struct{}, start, end uint64, variables map[string]qbtypes.VariableItem) (filterParts, error) {
+	var fp filterParts
+	if query.Filter != nil && strings.TrimSpace(query.Filter.Expression) != "" {
+		spanExpr, traceExpr, err := querybuilder.SplitFilterForAggregates(query.Filter.Expression, classifySet)
+		if err != nil {
+			return fp, err
+		}
+		fp.havingExpr = traceExpr
+		if strings.TrimSpace(spanExpr) != "" {
+			pred, args, warnings, url, err := b.resolveSpanPredicate(ctx, orgID, start, end, spanExpr, variables)
+			if err != nil {
+				return fp, err
+			}
+			// pred is empty when the span-level keys were all resource attributes
+			// already handled by the __resource_filter CTE.
+			if strings.TrimSpace(pred) != "" {
+				fp.spanPred, fp.spanArgs, fp.hasSpanFilter = pred, args, true
+			}
+			fp.warnings, fp.warningsURL = warnings, url
+		}
+	}
+	if query.Having != nil && strings.TrimSpace(query.Having.Expression) != "" {
+		if fp.havingExpr != "" {
+			fp.havingExpr = fmt.Sprintf("(%s) AND (%s)", fp.havingExpr, query.Having.Expression)
+		} else {
+			fp.havingExpr = query.Having.Expression
+		}
+	}
+	// The span predicate binds variables via PrepareWhereClause; the HAVING is a plain
+	// text rewrite, so substitute variables here (list/IN quoting, __all__ drops the
+	// condition) before validating.
+	if strings.TrimSpace(fp.havingExpr) != "" && len(variables) > 0 {
+		replaced, err := qbvariables.ReplaceVariablesInExpression(fp.havingExpr, variables)
+		if err != nil {
+			return fp, err
+		}
+		fp.havingExpr = replaced
+	}
+	if err := validateAggregateFilter(fp.havingExpr, orderableSet); err != nil {
+		return fp, err
+	}
+	return fp, nil
+}
+
+// resolveSpanPredicate resolves a span-level filter expression to a bare boolean
+// SQL predicate + args via the field mapper.
+func (b *scopedTraceStatementBuilder) resolveSpanPredicate(ctx context.Context, orgID valuer.UUID, start, end uint64, expr string, variables map[string]qbtypes.VariableItem) (string, []any, []string, string, error) {
+	selectors := querybuilder.QueryStringToKeysSelectors(expr)
+	for i := range selectors {
+		selectors[i].Signal = telemetrytypes.SignalTraces
+	}
+	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, selectors)
+	if err != nil {
+		return "", nil, nil, "", err
+	}
+	prepared, err := querybuilder.PrepareWhereClause(expr, querybuilder.FilterExprVisitorOpts{
+		Context:          ctx,
+		Logger:           b.logger,
+		FieldMapper:      b.fm,
+		ConditionBuilder: b.cb,
+		FieldKeys:        keys,
+		// resource conditions are always handled by the __resource_filter CTE
+		SkipResourceFilter: true,
+		Variables:          variables,
+		StartNs:            start,
+		EndNs:              end,
+	})
+	if err != nil {
+		return "", nil, nil, "", err
+	}
+	if prepared.IsEmpty() {
+		return "", nil, nil, "", nil
+	}
+	sb := sqlbuilder.NewSelectBuilder()
+	sb.AddWhereClause(prepared.WhereClause)
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	pred := sql[strings.Index(sql, "WHERE ")+len("WHERE "):]
+	return sqlbuilder.Escape(pred), args, prepared.Warnings, prepared.WarningsDocURL, nil
+}
+
+// buildMatchedCTE builds `matched`: the single windowed GROUP BY trace_id scan that
+// fuses gate + span filter + HAVING + ORDER BY + LIMIT/OFFSET, selecting only the
+// aliases the ORDER BY / HAVING reference.
+func (b *scopedTraceStatementBuilder) buildMatchedCTE(start, end, startBucket, endBucket uint64, resolved []resolvedColumn, orders []listOrder, orderableSet map[string]struct{}, maskExpr string, maskArgs []any, fp filterParts, resourcePred string, limit, offset int) (string, []any, error) {
+	sb := sqlbuilder.NewSelectBuilder()
+
+	// SELECT trace_id + only the aggregates ORDER BY / HAVING reference (as aliases).
+	needed := neededMatchedAliases(orders, fp.havingExpr, orderableSet)
+	selects := []string{"trace_id"}
+	for _, rc := range resolved {
+		if _, ok := needed[rc.alias]; !ok {
+			continue
+		}
+		colExpr, err := embedExpr(sb, rc.expr, rc.args)
+		if err != nil {
+			return "", nil, err
+		}
+		selects = append(selects, colExpr+" AS "+quoteAlias(rc.alias))
+	}
+	sb.Select(selects...)
+	sb.From(spanTable())
+
+	// WHERE: window + prune to in-scope spans, widened by the span filter so its
+	// spans survive for the countIf existence check below.
+	win := windowWhere(sb, start, end, startBucket, endBucket)
+	mask, err := embedExpr(sb, maskExpr, maskArgs)
+	if err != nil {
+		return "", nil, err
+	}
+	prune := "(" + mask
+	if fp.hasSpanFilter {
+		spanPred, err := embedExpr(sb, fp.spanPred, fp.spanArgs)
+		if err != nil {
+			return "", nil, err
+		}
+		prune += " OR " + spanPred
+	}
+	prune += ")"
+	where := append(win, prune)
+	if resourcePred != "" {
+		where = append(where, resourcePred)
+	}
+	sb.Where(where...)
+	sb.GroupBy("trace_id")
+
+	// HAVING: the gate/span existence checks are only needed when the WHERE was
+	// widened by a span filter; otherwise the mask alone already enforces the gate.
+	var having []string
+	if fp.hasSpanFilter {
+		havingMask, err := embedExpr(sb, maskExpr, maskArgs)
+		if err != nil {
+			return "", nil, err
+		}
+		havingPred, err := embedExpr(sb, fp.spanPred, fp.spanArgs)
+		if err != nil {
+			return "", nil, err
+		}
+		having = append(having, "countIf("+havingMask+") > 0")
+		having = append(having, "countIf("+havingPred+") > 0")
+	}
+	if strings.TrimSpace(fp.havingExpr) != "" {
+		hv, err := b.buildHaving(fp.havingExpr, orderableSet)
+		if err != nil {
+			return "", nil, err
+		}
+		if hv != "" {
+			// hv carries user text with values inlined by the rewriter; escape it so a
+			// literal $ can't be read as an interpolation marker at Build time. The
+			// countIf entries above hold live placeholders and must stay unescaped.
+			having = append(having, sqlbuilder.Escape(hv))
+		}
+	}
+	if len(having) > 0 {
+		sb.Having(strings.Join(having, " AND "))
+	}
+
+	sb.OrderBy(orderClause(orders)...)
+	sb.Limit(limit)
+	if offset > 0 {
+		sb.Offset(offset)
+	}
+
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return fmt.Sprintf("matched AS (%s)", sql), args, nil
+}
+
+// buildRankedCTE builds `ranked`: [start,end] bounds per matched trace, read from the
+// small trace-summary table.
+func (b *scopedTraceStatementBuilder) buildRankedCTE(start, end uint64) (string, []any) {
+	sb := sqlbuilder.NewSelectBuilder()
+	sb.Select("trace_id", "min(start) AS t_start", "max(end) AS t_end")
+	sb.From(summaryTable())
+	sb.Where(
+		"trace_id GLOBAL IN (SELECT trace_id FROM matched)",
+		"end >= fromUnixTimestamp64Nano("+sb.Var(start)+")",
+		"start < fromUnixTimestamp64Nano("+sb.Var(end)+")",
+	)
+	sb.GroupBy("trace_id")
+	sql, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return fmt.Sprintf("ranked AS (%s)", sql), args
+}
+
+// buildBucketsCTE builds `buckets`: the ts_bucket_start values the matched traces
+// span, so the enrichment scan is primary-key pruned. No args.
+func buildBucketsCTE() string {
+	adj := querybuilder.BucketAdjustment // 30-min bucket width in seconds
+	return fmt.Sprintf("buckets AS (SELECT DISTINCT b AS ts_bucket FROM ranked "+
+		"ARRAY JOIN range("+
+		"toUInt64(intDiv(toUnixTimestamp(t_start), %d) * %d - %d), "+
+		"toUInt64(intDiv(toUnixTimestamp(t_end), %d) * %d + %d), "+
+		"%d) AS b)", adj, adj, adj, adj, adj, adj, adj)
+}
+
+// buildEnrichmentSelect builds the final SELECT: every per-trace column for the
+// matched traces over their full extent, scanning only their buckets.
+//
+// Accepted discrepancy: matched ranks/paginates on window-clipped values (and, with a
+// resource filter, only over fingerprint-matching spans), while this pass recomputes
+// and ORDER BYs full-trace values — so a trace with activity outside the window or
+// resource can sort differently than it ranked. Page membership is unaffected
+// (LIMIT/OFFSET runs only in matched); rows still sort by the values the user sees.
+// Ordering by matched's values instead would re-run the matched scan (ClickHouse
+// re-executes a CTE per reference) without fixing the visible cross-page artifact.
+func (b *scopedTraceStatementBuilder) buildEnrichmentSelect(resolved []resolvedColumn, orders []listOrder) (string, []any) {
+	sb := sqlbuilder.NewSelectBuilder()
+	selects, selectArgs := selectAllColumns(resolved)
+	sb.Select(selects...)
+	sb.From(spanTable())
+	sb.Where(
+		"ts_bucket_start GLOBAL IN (SELECT ts_bucket FROM buckets)",
+		"trace_id GLOBAL IN (SELECT trace_id FROM ranked)",
+	)
+	sb.GroupBy("trace_id")
+	sb.OrderBy(orderClause(orders)...)
+	sql, builtArgs := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+	return sql, append(append([]any{}, selectArgs...), builtArgs...)
+}
+
+// buildHaving rewrites a trace-level HAVING expression to the matched-pass column
+// aliases. The rewriter matches raw key text, so the trace. form is mapped alongside
+// the bare name.
+func (b *scopedTraceStatementBuilder) buildHaving(havingExpr string, orderableSet map[string]struct{}) (string, error) {
+	columnMap := make(map[string]string, len(orderableSet)*2)
+	for a := range orderableSet {
+		columnMap[a] = quoteAlias(a)
+		columnMap[telemetrytypes.FieldContextTrace.StringValue()+"."+a] = quoteAlias(a)
+	}
+	return querybuilder.NewHavingExpressionRewriter().Rewrite(havingExpr, columnMap)
+}
+
+// ---------------------------------------------------------------------------
+// Small shared SQL-builder utilities
+// ---------------------------------------------------------------------------
+
+// spanTable is the fully-qualified span index table.
+func spanTable() string {
+	return fmt.Sprintf("%s.%s", tracestelemetryschema.DBName, tracestelemetryschema.SpanIndexV3TableName)
+}
+
+// summaryTable is the fully-qualified trace-summary table.
+func summaryTable() string {
+	return fmt.Sprintf("%s.%s", tracestelemetryschema.DBName, tracestelemetryschema.TraceSummaryTableName)
+}
+
+// aggregateAliasSet is every trace-level column alias, used to classify filter keys
+// as trace-level vs span-level. Derived from the scope's columns so a new column
+// can't be forgotten; SpanLevel columns are filtered span-level, so skip them.
+func (b *scopedTraceStatementBuilder) aggregateAliasSet() map[string]struct{} {
+	set := make(map[string]struct{}, len(b.scope.Columns))
+	for _, c := range b.scope.Columns {
+		if !c.SpanLevel {
+			set[c.Alias] = struct{}{}
+		}
+	}
+	return set
+}
+
+// orderableAliasSet is the subset of aliases computable in the matched pass — the
+// only ones usable in ORDER BY and the aggregate filter.
+func orderableAliasSet(resolved []resolvedColumn) map[string]struct{} {
+	set := make(map[string]struct{})
+	for _, rc := range resolved {
+		if rc.orderable {
+			set[rc.alias] = struct{}{}
+		}
+	}
+	return set
+}
+
+// neededMatchedAliases is the minimal alias set the matched pass must select: those
+// in ORDER BY plus those in the aggregate HAVING. Everything else is left to the
+// enrichment scan.
+func neededMatchedAliases(orders []listOrder, havingExpr string, orderableSet map[string]struct{}) map[string]struct{} {
+	needed := make(map[string]struct{})
+	for _, o := range orders {
+		needed[o.alias] = struct{}{}
+	}
+	for _, name := range traceAggregateNames(havingExpr) {
+		if _, ok := orderableSet[name]; ok {
+			needed[name] = struct{}{}
+		}
+	}
+	return needed
+}
+
+// traceAggregateNames extracts the aggregate names a trace-level HAVING expression
+// references. QueryStringToKeysSelectors emits an extra attribute-context fallback
+// selector for context-prefixed keys (`trace.x` → attribute "trace.x"); only the
+// unspecified- and trace-context selectors name aggregates.
+func traceAggregateNames(havingExpr string) []string {
+	var names []string
+	for _, sel := range querybuilder.QueryStringToKeysSelectors(havingExpr) {
+		if sel.FieldContext == telemetrytypes.FieldContextUnspecified || sel.FieldContext == telemetrytypes.FieldContextTrace {
+			names = append(names, sel.Name)
+		}
+	}
+	return names
+}
+
+// validateAggregateFilter rejects a trace-level filter referencing an aggregate not
+// computable in the matched pass (e.g. span_count, trace_duration_nano).
+func validateAggregateFilter(havingExpr string, orderableSet map[string]struct{}) error {
+	if strings.TrimSpace(havingExpr) == "" {
+		return nil
+	}
+	allowed := make([]string, 0, len(orderableSet))
+	for a := range orderableSet {
+		allowed = append(allowed, a)
+	}
+	sort.Strings(allowed)
+	for _, name := range traceAggregateNames(havingExpr) {
+		if _, ok := orderableSet[name]; !ok {
+			return errors.NewInvalidInputf(errors.CodeInvalidInput,
+				"aggregate %q cannot be used in the trace-list filter; filterable aggregates: %s", name, strings.Join(allowed, ", "))
+		}
+	}
+	return nil
+}
+
+// embedExpr inlines a resolved expr into sb, replacing each `?` placeholder with a
+// builder Var so the args are tracked in appearance order. Resolved exprs carry
+// values only as bound args, so every `?` is a placeholder; a count mismatch would
+// silently shift args into the wrong slots — error out instead.
+func embedExpr(sb *sqlbuilder.SelectBuilder, expr string, args []any) (string, error) {
+	if n := strings.Count(expr, "?"); n != len(args) {
+		return "", errors.NewInternalf(errors.CodeInternal,
+			"scoped trace builder: %d placeholders != %d args embedding %q", n, len(args), expr)
+	}
+	var out strings.Builder
+	ai := 0
+	for i := 0; i < len(expr); i++ {
+		if expr[i] == '?' {
+			out.WriteString(sb.Var(args[ai]))
+			ai++
+			continue
+		}
+		out.WriteByte(expr[i])
+	}
+	return out.String(), nil
+}
+
+// windowWhere binds the time-window predicates to sb and returns them so the caller
+// can add its own predicates in the same Where call.
+func windowWhere(sb *sqlbuilder.SelectBuilder, start, end, startBucket, endBucket uint64) []string {
+	return []string{
+		sb.GE("timestamp", fmt.Sprintf("%d", start)),
+		sb.L("timestamp", fmt.Sprintf("%d", end)),
+		sb.GE("ts_bucket_start", startBucket),
+		sb.LE("ts_bucket_start", endBucket),
+	}
+}
+
+// orderClause renders the ORDER BY terms plus the trace_id tiebreak.
+func orderClause(orders []listOrder) []string {
+	out := make([]string, 0, len(orders)+1)
+	for _, o := range orders {
+		out = append(out, fmt.Sprintf("%s %s", quoteAlias(o.alias), o.direction))
+	}
+	return append(out, "trace_id DESC")
+}
+
+// selectAllColumns renders `expr AS alias` for every resolved column, args in select
+// order.
+func selectAllColumns(resolved []resolvedColumn) ([]string, []any) {
+	selects := []string{"trace_id"}
+	var args []any
+	for _, rc := range resolved {
+		selects = append(selects, rc.expr+" AS "+quoteAlias(rc.alias))
+		args = append(args, rc.args...)
+	}
+	return selects, args
+}
+
+// quoteAlias backticks an alias containing characters special to the SQL builder.
+func quoteAlias(alias string) string {
+	if strings.ContainsAny(alias, ".$`") {
+		return "`" + alias + "`"
+	}
+	return alias
+}

pkg/statementbuilder/scopedtracesstatementbuilder/statement_builder_test.go

@@ -0,0 +1,31 @@
+package scopedtracesstatementbuilder
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/huandu/go-sqlbuilder"
+	"github.com/stretchr/testify/require"
+)
+
+// The full-pipeline golden tests live in pkg/statementbuilder/aistatementbuilder,
+// which exercises this
+// builder through its production provider pair. The tests here cover only what
+// needs the package internals.
+
+// embedExpr treats every `?` byte as a placeholder; a count/args mismatch (an expr
+// carrying a literal `?`, or a dropped arg) must fail loudly instead of silently
+// shifting every subsequent arg into the wrong placeholder.
+func TestEmbedExpr_PlaceholderArgMismatch(t *testing.T) {
+	sb := sqlbuilder.NewSelectBuilder()
+
+	out, err := embedExpr(sb, "x = ? AND y = ?", []any{1, 2})
+	require.NoError(t, err)
+	require.Equal(t, 2, strings.Count(out, "$"), "both placeholders bound as builder vars")
+
+	_, err = embedExpr(sb, "x = ? AND y LIKE 'a?b'", []any{1})
+	require.Error(t, err, "literal ? in the expr must not pass as a placeholder")
+
+	_, err = embedExpr(sb, "x = ?", []any{1, 2})
+	require.Error(t, err, "extra args must not be silently dropped")
+}

pkg/statementbuilder/tracesstatementbuilder/statement_builder.go

@@ -127,8 +127,7 @@ func (b *traceQueryStatementBuilder) Build(
 	}
 
 	for _, action := range adjustTraceKeys(keys, &query, requestType) {
-		// TODO: change to debug level once we are confident about the behavior
-		b.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 	// Create SQL builder
 	q := sqlbuilder.NewSelectBuilder()

pkg/statementbuilder/tracesstatementbuilder/trace_operator_cte_builder.go

@@ -223,8 +223,7 @@ func (b *traceOperatorCTEBuilder) buildQueryCTE(ctx context.Context, queryName s
 	// The CTE only selects spans matching the filter. Aggregations, group by
 	// and order by run later in buildFinalQuery, so RequestTypeRaw is fine here.
 	for _, action := range adjustTraceKeys(keys, query, qbtypes.RequestTypeRaw) {
-		// TODO: change to debug level once we are confident about the behavior
-		b.stmtBuilder.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.stmtBuilder.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 
 	// Build resource filter CTE for this specific query
@@ -576,7 +575,7 @@ func (b *traceOperatorCTEBuilder) adjustOperatorKeys(ctx context.Context, keys m
 	b.operator.Order = tmp.Order
 
 	for _, action := range actions {
-		b.stmtBuilder.logger.InfoContext(ctx, "key adjustment action", slog.String("action", action))
+		b.stmtBuilder.logger.DebugContext(ctx, "key adjustment action", slog.String("action", action))
 	}
 }
 

pkg/telemetrymetadata/metadata.go

@@ -1168,6 +1168,27 @@ func enrichWithIntrinsicMetricKeys(keys map[string][]*telemetrytypes.TelemetryFi
 	return keys
 }
 
+// enrichWithGenAIKeys adds keys that can be queried for GenAI signals, even though they have not been ingested yet.
+func enrichWithGenAIKeys(keys map[string][]*telemetrytypes.TelemetryFieldKey, selectors []*telemetrytypes.FieldKeySelector) map[string][]*telemetrytypes.TelemetryFieldKey {
+	for _, selector := range selectors {
+		if selector.Signal != telemetrytypes.SignalTraces && selector.Signal != telemetrytypes.SignalUnspecified {
+			continue
+		}
+		for name, def := range telemetrytypes.GenAIFieldDefinitions {
+			if len(keys[name]) > 0 {
+				continue // already resolved from ingested data
+			}
+			if !selectorMatchesIntrinsicField(selector, def) {
+				continue
+			}
+			keyCopy := def
+			keys[name] = []*telemetrytypes.TelemetryFieldKey{&keyCopy}
+		}
+	}
+
+	return keys
+}
+
 func selectorMatchesIntrinsicField(selector *telemetrytypes.FieldKeySelector, definition telemetrytypes.TelemetryFieldKey) bool {
 	if selector.FieldContext != telemetrytypes.FieldContextUnspecified && selector.FieldContext != definition.FieldContext {
 		return false
@@ -1253,6 +1274,9 @@ func (t *telemetryMetaStore) GetKeys(ctx context.Context, orgID valuer.UUID, fie
 
 	applyBackwardCompatibleKeys(mapOfKeys)
 	mapOfKeys = enrichWithIntrinsicMetricKeys(mapOfKeys, selectors)
+	if t.fl.BooleanOrEmpty(ctx, flagger.FeatureEnableAIObservability, featuretypes.NewFlaggerEvaluationContext(orgID)) {
+		mapOfKeys = enrichWithGenAIKeys(mapOfKeys, selectors)
+	}
 
 	return mapOfKeys, complete, nil
 }
@@ -1331,6 +1355,9 @@ func (t *telemetryMetaStore) GetKeysMulti(ctx context.Context, orgID valuer.UUID
 
 	applyBackwardCompatibleKeys(mapOfKeys)
 	mapOfKeys = enrichWithIntrinsicMetricKeys(mapOfKeys, fieldKeySelectors)
+	if t.fl.BooleanOrEmpty(ctx, flagger.FeatureEnableAIObservability, featuretypes.NewFlaggerEvaluationContext(orgID)) {
+		mapOfKeys = enrichWithGenAIKeys(mapOfKeys, fieldKeySelectors)
+	}
 
 	return mapOfKeys, complete, nil
 }

pkg/types/llmpricingruletypes/pricing.go

@@ -16,18 +16,10 @@ import (
 const (
 	LLMCostFeatureType agentConf.AgentFeatureType = "llm_pricing"
 
-	GenAIRequestModel                  = "gen_ai.request.model"
-	GenAIProviderName                  = "gen_ai.provider.name"
-	GenAIUsageInputTokens              = "gen_ai.usage.input_tokens"
-	GenAIUsageOutputTokens             = "gen_ai.usage.output_tokens"
-	GenAIUsageCacheReadInputTokens     = "gen_ai.usage.cache_read.input_tokens"
-	GenAIUsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens"
-
 	SignozGenAICostInput      = "_signoz.gen_ai.cost_input"
 	SignozGenAICostOutput     = "_signoz.gen_ai.cost_output"
 	SignozGenAICostCacheRead  = "_signoz.gen_ai.cost_cache_read"
 	SignozGenAICostCacheWrite = "_signoz.gen_ai.cost_cache_write"
-	SignozGenAITotalCost      = "_signoz.gen_ai.total_cost"
 )
 
 var (

pkg/types/llmpricingruletypes/processorconfig.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"gopkg.in/yaml.v3"
 )
 
@@ -83,11 +84,11 @@ func buildProcessorConfig(rules []*LLMPricingRule) *LLMPricingRuleProcessorConfi
 
 	return &LLMPricingRuleProcessorConfig{
 		Attrs: LLMPricingRuleProcessorAttrs{
-			Model:      GenAIRequestModel,
-			In:         GenAIUsageInputTokens,
-			Out:        GenAIUsageOutputTokens,
-			CacheRead:  GenAIUsageCacheReadInputTokens,
-			CacheWrite: GenAIUsageCacheCreationInputTokens,
+			Model:      telemetrytypes.GenAIRequestModel,
+			In:         telemetrytypes.GenAIUsageInputTokens,
+			Out:        telemetrytypes.GenAIUsageOutputTokens,
+			CacheRead:  telemetrytypes.GenAIUsageCacheReadInputTokens,
+			CacheWrite: telemetrytypes.GenAIUsageCacheCreationInputTokens,
 		},
 		DefaultPricing: LLMPricingRuleProcessorDefaultPricing{
 			Rules: pricingRules,
@@ -97,7 +98,7 @@ func buildProcessorConfig(rules []*LLMPricingRule) *LLMPricingRuleProcessorConfi
 			Out:        SignozGenAICostOutput,
 			CacheRead:  SignozGenAICostCacheRead,
 			CacheWrite: SignozGenAICostCacheWrite,
-			Total:      SignozGenAITotalCost,
+			Total:      telemetrytypes.SignozGenAITotalCost,
 		},
 	}
 }

pkg/types/querybuildertypes/querybuildertypesv5/query_type.go

@@ -9,6 +9,7 @@ type QueryType struct {
 var (
 	QueryTypeUnknown       = QueryType{valuer.NewString("unknown")}
 	QueryTypeBuilder       = QueryType{valuer.NewString("builder_query")}
+	QueryTypeBuilderAI     = QueryType{valuer.NewString("builder_ai_query")}
 	QueryTypeFormula       = QueryType{valuer.NewString("builder_formula")}
 	QueryTypeSubQuery      = QueryType{valuer.NewString("builder_sub_query")}
 	QueryTypeJoin          = QueryType{valuer.NewString("builder_join")}
@@ -21,6 +22,7 @@ var (
 func (QueryType) Enum() []any {
 	return []any{
 		QueryTypeBuilder,
+		QueryTypeBuilderAI,
 		QueryTypeFormula,
 		// Not yet supported.
 		// QueryTypeSubQuery,

pkg/types/querybuildertypes/querybuildertypesv5/req.go

@@ -62,6 +62,13 @@ type queryEnvelopeBuilder struct {
 	Spec builderQuerySpec `json:"spec" description:"The builder query specification."`
 }
 
+// queryEnvelopeBuilderAI is the OpenAPI schema for a builder_ai_query QueryEnvelope.
+// The spec is always a traces builder query (the signal is implied by the type).
+type queryEnvelopeBuilderAI struct {
+	Type QueryType                           `json:"type" required:"true" description:"The type of the query."`
+	Spec QueryBuilderQuery[TraceAggregation] `json:"spec" description:"The AI builder query specification."`
+}
+
 // queryEnvelopeFormula is the OpenAPI schema for a QueryEnvelope with type=builder_formula.
 type queryEnvelopeFormula struct {
 	Type QueryType           `json:"type" required:"true" description:"The type of the query."`
@@ -100,6 +107,7 @@ var _ jsonschema.OneOfExposer = QueryEnvelope{}
 func (QueryEnvelope) JSONSchemaOneOf() []any {
 	return []any{
 		queryEnvelopeBuilder{},
+		queryEnvelopeBuilderAI{},
 		queryEnvelopeFormula{},
 		// queryEnvelopeJoin{}, // deferred — see commented queryEnvelopeJoin above
 		queryEnvelopeTraceOperator{},
@@ -120,6 +128,7 @@ func (QueryEnvelope) PrepareJSONSchema(s *jsonschema.Schema) error {
 		"propertyName": "type",
 		"mapping": map[string]string{
 			QueryTypeBuilder.StringValue():       "#/components/schemas/Querybuildertypesv5QueryEnvelopeBuilder",
+			QueryTypeBuilderAI.StringValue():     "#/components/schemas/Querybuildertypesv5QueryEnvelopeBuilderAI",
 			QueryTypeFormula.StringValue():       "#/components/schemas/Querybuildertypesv5QueryEnvelopeFormula",
 			QueryTypeTraceOperator.StringValue(): "#/components/schemas/Querybuildertypesv5QueryEnvelopeTraceOperator",
 			QueryTypePromQL.StringValue():        "#/components/schemas/Querybuildertypesv5QueryEnvelopePromQL",
@@ -150,6 +159,16 @@ func (q *QueryEnvelope) UnmarshalJSON(data []byte) error {
 		}
 		q.Spec = spec
 
+	case QueryTypeBuilderAI:
+		// A dedicated AI query is always a traces builder query; the signal is
+		// implied by the type, so pin it rather than requiring the caller to send it.
+		var spec QueryBuilderQuery[TraceAggregation]
+		if err := json.Unmarshal(shadow.Spec, &spec); err != nil {
+			return err
+		}
+		spec.Signal = telemetrytypes.SignalTraces
+		q.Spec = spec
+
 	case QueryTypeFormula:
 		var spec QueryBuilderFormula
 		if err := json.Unmarshal(shadow.Spec, &spec); err != nil {
@@ -194,7 +213,7 @@ func (q *QueryEnvelope) UnmarshalJSON(data []byte) error {
 			"unknown query type %q",
 			shadow.Type,
 		).WithAdditional(
-			"Valid query types are: builder_query, builder_sub_query, builder_formula, builder_join, builder_trace_operator, promql, clickhouse_sql",
+			"Valid query types are: builder_query, builder_ai_query, builder_sub_query, builder_formula, builder_join, builder_trace_operator, promql, clickhouse_sql",
 		).WithSuggestions(errors.NewValidReferences(errors.NounQueryTypes, QueryType{}.Enum()...))
 	}
 

pkg/types/querybuildertypes/querybuildertypesv5/validation.go

@@ -641,7 +641,7 @@ func (r *QueryRangeRequest) ValidateRequestScope() ([]ValidationOption, error) {
 	// Builder query names must be unique across the composite query.
 	queryNames := make(map[string]bool)
 	for _, envelope := range r.CompositeQuery.Queries {
-		if envelope.Type == QueryTypeBuilder || envelope.Type == QueryTypeSubQuery {
+		if envelope.Type == QueryTypeBuilder || envelope.Type == QueryTypeSubQuery || envelope.Type == QueryTypeBuilderAI {
 			name := envelope.GetQueryName()
 			if name != "" {
 				if queryNames[name] {
@@ -710,7 +710,7 @@ func (c *CompositeQuery) Validate(opts ...ValidationOption) error {
 		}
 
 		// Check name uniqueness for builder queries
-		if envelope.Type == QueryTypeBuilder || envelope.Type == QueryTypeSubQuery {
+		if envelope.Type == QueryTypeBuilder || envelope.Type == QueryTypeSubQuery || envelope.Type == QueryTypeBuilderAI {
 			name := envelope.GetQueryName()
 			if name != "" {
 				if queryNames[name] {
@@ -744,6 +744,15 @@ func validateQueryEnvelope(envelope QueryEnvelope, opts ...ValidationOption) err
 				"unknown query spec type",
 			)
 		}
+	case QueryTypeBuilderAI:
+		spec, ok := envelope.Spec.(QueryBuilderQuery[TraceAggregation])
+		if !ok {
+			return errors.NewInvalidInputf(
+				errors.CodeInvalidInput,
+				"invalid AI builder query spec",
+			)
+		}
+		return spec.Validate(opts...)
 	case QueryTypeFormula:
 		spec, ok := envelope.Spec.(QueryBuilderFormula)
 		if !ok {
@@ -813,7 +822,7 @@ func validateQueryEnvelope(envelope QueryEnvelope, opts ...ValidationOption) err
 			"unknown query type: %s",
 			envelope.Type,
 		).WithAdditional(
-			"Valid query types are: builder_query, builder_sub_query, builder_formula, builder_join, promql, clickhouse_sql, trace_operator",
+			"Valid query types are: builder_query, builder_ai_query, builder_sub_query, builder_formula, builder_join, promql, clickhouse_sql, trace_operator",
 		).WithSuggestions(errors.NewValidReferences(errors.NounQueryTypes, QueryType{}.Enum()...))
 	}
 }

pkg/types/telemetrytypes/field_context.go

@@ -76,6 +76,7 @@ var (
 		"log":        FieldContextLog,
 		"metric":     FieldContextMetric,
 		"tracefield": FieldContextTrace,
+		"trace":      FieldContextTrace,
 	}
 )
 

pkg/types/telemetrytypes/genai_semconv.go

@@ -0,0 +1,43 @@
+package telemetrytypes
+
+// OpenTelemetry gen_ai semantic-convention attribute keys. Single source of truth
+// shared by the AI query builder and the LLM pricing pipeline.
+const (
+	GenAIRequestModel = "gen_ai.request.model"
+	GenAIToolName     = "gen_ai.tool.name"
+	GenAIAgentName    = "gen_ai.agent.name"
+	GenAIProviderName = "gen_ai.provider.name"
+
+	GenAIUsageInputTokens              = "gen_ai.usage.input_tokens"
+	GenAIUsageOutputTokens             = "gen_ai.usage.output_tokens"
+	GenAIUsageCacheReadInputTokens     = "gen_ai.usage.cache_read.input_tokens"
+	GenAIUsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens"
+
+	GenAIInputMessages  = "gen_ai.input.messages"
+	GenAIOutputMessages = "gen_ai.output.messages"
+
+	// SignozGenAITotalCost is not OTel semconv: it is the per-span total cost the
+	// SigNoz LLM pricing processor computes and attaches (see llmpricingruletypes).
+	SignozGenAITotalCost = "_signoz.gen_ai.total_cost"
+)
+
+// GenAIFieldDefinitions are the gen_ai semantic-convention span attributes the AI
+// query builder relies on. They are surfaced by the metadata store for trace
+// queries regardless of whether they have been ingested yet, so the AI gate/columns
+// resolve on a fresh install (mirrors intrinsic metric keys). String keys are the
+// gate; the usage keys are numeric.
+var GenAIFieldDefinitions = map[string]TelemetryFieldKey{
+	GenAIRequestModel: {Name: GenAIRequestModel, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIToolName:     {Name: GenAIToolName, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIAgentName:    {Name: GenAIAgentName, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIProviderName: {Name: GenAIProviderName, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+
+	GenAIUsageInputTokens:              {Name: GenAIUsageInputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	GenAIUsageOutputTokens:             {Name: GenAIUsageOutputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	GenAIUsageCacheReadInputTokens:     {Name: GenAIUsageCacheReadInputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	GenAIUsageCacheCreationInputTokens: {Name: GenAIUsageCacheCreationInputTokens, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+	SignozGenAITotalCost:               {Name: SignozGenAITotalCost, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeFloat64},
+
+	GenAIInputMessages:  {Name: GenAIInputMessages, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+	GenAIOutputMessages: {Name: GenAIOutputMessages, Signal: SignalTraces, FieldContext: FieldContextAttribute, FieldDataType: FieldDataTypeString},
+}

pkg/types/telemetrytypes/selector.go

@@ -10,6 +10,7 @@ const wildcardSelector = "*"
 
 var telemetryGrantQueryTypes = map[string]bool{
 	"builder_query":     true,
+	"builder_ai_query":  true,
 	"builder_sub_query": true,
 	"promql":            false,
 	"clickhouse_sql":    false,