fix: make threshold value non-nullable

* chore: json tags for error struct

* fix: udpate unit tests

conf/example.yaml

@@ -141,6 +141,10 @@ querier:
   flux_interval: 5m
   # The maximum number of concurrent queries for missing ranges.
   max_concurrent_queries: 4
+  # When filtering logs by trace_id, clamp the query window to the trace time
+  # range with padding to include slightly delayed log exports. Logs only; set
+  # to 0 to disable.
+  log_trace_id_window_padding: 5m
 
 ##################### TelemetryStore #####################
 telemetrystore:

docs/api/openapi.yml

@@ -2553,17 +2553,6 @@ components:
         url:
           type: string
       type: object
-    DashboardTextVariableSpec:
-      properties:
-        constant:
-          type: boolean
-        display:
-          $ref: '#/components/schemas/VariableDisplay'
-        name:
-          type: string
-        value:
-          type: string
-      type: object
     DashboardtypesAxes:
       properties:
         isLogScale:
@@ -2637,7 +2626,6 @@ components:
         unit:
           type: string
         value:
-          format: double
           type: number
       required:
       - value
@@ -2673,6 +2661,22 @@ components:
         updatedBy:
           type: string
       type: object
+    DashboardtypesDashboardPanelRef:
+      properties:
+        dashboardId:
+          type: string
+        dashboardName:
+          type: string
+        panelId:
+          type: string
+        panelName:
+          type: string
+      required:
+      - dashboardId
+      - dashboardName
+      - panelId
+      - panelName
+      type: object
     DashboardtypesDashboardSpec:
       properties:
         datasources:
@@ -2745,24 +2749,23 @@ components:
     DashboardtypesDatasourcePlugin:
       discriminator:
         mapping:
-          signoz/Datasource: '#/components/schemas/DashboardtypesDatasourcePluginVariantStruct'
+          signoz/Datasource: '#/components/schemas/DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpec'
         propertyName: kind
       oneOf:
-      - $ref: '#/components/schemas/DashboardtypesDatasourcePluginVariantStruct'
+      - $ref: '#/components/schemas/DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpec'
       type: object
     DashboardtypesDatasourcePluginKind:
       enum:
       - signoz/Datasource
       type: string
-    DashboardtypesDatasourcePluginVariantStruct:
+    DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpec:
       properties:
         kind:
           enum:
           - signoz/Datasource
           type: string
         spec:
-          nullable: true
-          type: object
+          $ref: '#/components/schemas/DashboardtypesSigNozDatasourceSpec'
       required:
       - kind
       - spec
@@ -2928,9 +2931,15 @@ components:
             type: string
           nullable: true
           type: object
+        mode:
+          $ref: '#/components/schemas/DashboardtypesLegendMode'
         position:
           $ref: '#/components/schemas/DashboardtypesLegendPosition'
       type: object
+    DashboardtypesLegendMode:
+      enum:
+      - list
+      type: string
     DashboardtypesLegendPosition:
       enum:
       - bottom
@@ -2977,19 +2986,30 @@ components:
         customAllValue:
           type: string
         defaultValue:
-          $ref: '#/components/schemas/VariableDefaultValue'
+          $ref: '#/components/schemas/DashboardtypesVariableDefaultValue'
         display:
           $ref: '#/components/schemas/DashboardtypesDisplay'
         name:
+          minLength: 1
           type: string
         plugin:
           $ref: '#/components/schemas/DashboardtypesVariablePlugin'
         sort:
-          nullable: true
-          type: string
+          $ref: '#/components/schemas/DashboardtypesListVariableSpecSort'
       required:
       - display
+      - name
       type: object
+    DashboardtypesListVariableSpecSort:
+      enum:
+      - none
+      - alphabetical-asc
+      - alphabetical-desc
+      - numerical-asc
+      - numerical-desc
+      - alphabetical-ci-asc
+      - alphabetical-ci-desc
+      type: string
     DashboardtypesListableDashboardForUserV2:
       properties:
         dashboards:
@@ -3287,7 +3307,6 @@ components:
         queries:
           items:
             $ref: '#/components/schemas/DashboardtypesQuery'
-          nullable: true
           type: array
       required:
       - display
@@ -3490,6 +3509,8 @@ components:
       required:
       - queryValue
       type: object
+    DashboardtypesSigNozDatasourceSpec:
+      type: object
     DashboardtypesSource:
       enum:
       - user
@@ -3499,8 +3520,13 @@ components:
     DashboardtypesSpanGaps:
       properties:
         fillLessThan:
+          description: The maximum gap size to connect when fillOnlyBelow is true.
+            Gaps larger than this duration are left disconnected.
           type: string
         fillOnlyBelow:
+          description: Controls whether lines connect across null values. When false
+            (default), all gaps are connected. When true, only gaps smaller than fillLessThan
+            are connected.
           type: boolean
       type: object
     DashboardtypesStorableDashboardData:
@@ -3541,13 +3567,28 @@ components:
         unit:
           type: string
         value:
-          format: double
           type: number
       required:
       - value
       - color
       - columnName
       type: object
+    DashboardtypesTextVariableSpec:
+      properties:
+        constant:
+          type: boolean
+        display:
+          $ref: '#/components/schemas/DashboardtypesDisplay'
+        name:
+          minLength: 1
+          type: string
+        value:
+          type: string
+      required:
+      - display
+      - value
+      - name
+      type: object
     DashboardtypesThresholdFormat:
       enum:
       - text
@@ -3562,12 +3603,10 @@ components:
         unit:
           type: string
         value:
-          format: double
           type: number
       required:
       - value
       - color
-      - label
       type: object
     DashboardtypesTimePreference:
       enum:
@@ -3652,24 +3691,18 @@ components:
       discriminator:
         mapping:
           ListVariable: '#/components/schemas/DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpec'
-          TextVariable: '#/components/schemas/DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpec'
+          TextVariable: '#/components/schemas/DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpec'
         propertyName: kind
       oneOf:
       - $ref: '#/components/schemas/DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpec'
-      - $ref: '#/components/schemas/DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpec'
+      - $ref: '#/components/schemas/DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpec'
       type: object
-    DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpec:
-      properties:
-        kind:
-          enum:
-          - TextVariable
+    DashboardtypesVariableDefaultValue:
+      oneOf:
+      - type: string
+      - items:
           type: string
-        spec:
-          $ref: '#/components/schemas/DashboardTextVariableSpec'
-      required:
-      - kind
-      - spec
-      type: object
+        type: array
     DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpec:
       properties:
         kind:
@@ -3682,6 +3715,18 @@ components:
       - kind
       - spec
       type: object
+    DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpec:
+      properties:
+        kind:
+          enum:
+          - TextVariable
+          type: string
+        spec:
+          $ref: '#/components/schemas/DashboardtypesTextVariableSpec'
+      required:
+      - kind
+      - spec
+      type: object
     DashboardtypesVariablePlugin:
       discriminator:
         mapping:
@@ -3755,15 +3800,12 @@ components:
         type:
           type: string
         url:
-          nullable: true
           type: string
       required:
       - type
       - code
       - message
-      - url
       - errors
-      - retry
       - suggestions
       type: object
     ErrorsResponseerroradditional:
@@ -3779,7 +3821,6 @@ components:
       - suggestions
       type: object
     ErrorsResponseretryjson:
-      nullable: true
       properties:
         delay:
           $ref: '#/components/schemas/TimeDuration'
@@ -5590,6 +5631,16 @@ components:
       - widgetId
       - widgetName
       type: object
+    MetricsexplorertypesMetricDashboardPanelsResponse:
+      properties:
+        dashboards:
+          items:
+            $ref: '#/components/schemas/DashboardtypesDashboardPanelRef'
+          nullable: true
+          type: array
+      required:
+      - dashboards
+      type: object
     MetricsexplorertypesMetricDashboardsResponse:
       properties:
         dashboards:
@@ -8118,17 +8169,6 @@ components:
       required:
       - id
       type: object
-    VariableDefaultValue:
-      type: object
-    VariableDisplay:
-      properties:
-        description:
-          type: string
-        hidden:
-          type: boolean
-        name:
-          type: string
-      type: object
     ZeustypesGettableHost:
       properties:
         hosts:
@@ -22763,6 +22803,75 @@ paths:
       summary: Put profile in Zeus for a deployment.
       tags:
       - zeus
+  /api/v3/metrics/dashboards:
+    get:
+      deprecated: false
+      description: This endpoint returns associated v2 dashboards for a specified
+        metric
+      operationId: GetMetricDashboardsV2
+      parameters:
+      - description: The name of the metric. May contain slashes (e.g. cloud-provider
+          metrics like run.googleapis.com/request_latencies).
+        in: query
+        name: metricName
+        required: true
+        schema:
+          description: The name of the metric. May contain slashes (e.g. cloud-provider
+            metrics like run.googleapis.com/request_latencies).
+          type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/MetricsexplorertypesMetricDashboardPanelsResponse'
+                  status:
+                    type: string
+                required:
+                - status
+                - data
+                type: object
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Bad Request
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Forbidden
+        "404":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Not Found
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenderErrorResponse'
+          description: Internal Server Error
+      security:
+      - api_key:
+        - VIEWER
+      - tokenizer:
+        - VIEWER
+      summary: Get metric dashboards (v2)
+      tags:
+      - metrics
   /api/v3/traces/{traceID}/flamegraph:
     post:
       deprecated: false

ee/modules/dashboard/impldashboard/module.go

@@ -290,6 +290,10 @@ func (module *module) GetByMetricNames(ctx context.Context, orgID valuer.UUID, m
 	return module.pkgDashboardModule.GetByMetricNames(ctx, orgID, metricNames)
 }
 
+func (module *module) GetByMetricNamesV2(ctx context.Context, orgID valuer.UUID, metricNames []string) (map[string][]dashboardtypes.DashboardPanelRef, error) {
+	return module.pkgDashboardModule.GetByMetricNamesV2(ctx, orgID, metricNames)
+}
+
 func (module *module) List(ctx context.Context, orgID valuer.UUID) ([]*dashboardtypes.Dashboard, error) {
 	return module.pkgDashboardModule.List(ctx, orgID)
 }

ee/sqlstore/postgressqlstore/formatter.go

@@ -152,3 +152,7 @@ func (f *formatter) LowerExpression(expression string) []byte {
 	sql = append(sql, ')')
 	return sql
 }
+
+func (f *formatter) EscapeLikePattern(value string) string {
+	return strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(value)
+}

frontend/src/api/generated/services/metrics/index.ts

@@ -26,6 +26,8 @@ import type {
 	GetMetricAttributesParams,
 	GetMetricDashboards200,
 	GetMetricDashboardsParams,
+	GetMetricDashboardsV2200,
+	GetMetricDashboardsV2Params,
 	GetMetricHighlights200,
 	GetMetricHighlightsParams,
 	GetMetricMetadata200,
@@ -1787,3 +1789,100 @@ export const useGetMetricsTreemap = <
 > => {
 	return useMutation(getGetMetricsTreemapMutationOptions(options));
 };
+/**
+ * This endpoint returns associated v2 dashboards for a specified metric
+ * @summary Get metric dashboards (v2)
+ */
+export const getMetricDashboardsV2 = (
+	params: GetMetricDashboardsV2Params,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<GetMetricDashboardsV2200>({
+		url: `/api/v3/metrics/dashboards`,
+		method: 'GET',
+		params,
+		signal,
+	});
+};
+
+export const getGetMetricDashboardsV2QueryKey = (
+	params?: GetMetricDashboardsV2Params,
+) => {
+	return [`/api/v3/metrics/dashboards`, ...(params ? [params] : [])] as const;
+};
+
+export const getGetMetricDashboardsV2QueryOptions = <
+	TData = Awaited<ReturnType<typeof getMetricDashboardsV2>>,
+	TError = ErrorType<RenderErrorResponseDTO>,
+>(
+	params: GetMetricDashboardsV2Params,
+	options?: {
+		query?: UseQueryOptions<
+			Awaited<ReturnType<typeof getMetricDashboardsV2>>,
+			TError,
+			TData
+		>;
+	},
+) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey =
+		queryOptions?.queryKey ?? getGetMetricDashboardsV2QueryKey(params);
+
+	const queryFn: QueryFunction<
+		Awaited<ReturnType<typeof getMetricDashboardsV2>>
+	> = ({ signal }) => getMetricDashboardsV2(params, signal);
+
+	return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
+		Awaited<ReturnType<typeof getMetricDashboardsV2>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type GetMetricDashboardsV2QueryResult = NonNullable<
+	Awaited<ReturnType<typeof getMetricDashboardsV2>>
+>;
+export type GetMetricDashboardsV2QueryError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Get metric dashboards (v2)
+ */
+
+export function useGetMetricDashboardsV2<
+	TData = Awaited<ReturnType<typeof getMetricDashboardsV2>>,
+	TError = ErrorType<RenderErrorResponseDTO>,
+>(
+	params: GetMetricDashboardsV2Params,
+	options?: {
+		query?: UseQueryOptions<
+			Awaited<ReturnType<typeof getMetricDashboardsV2>>,
+			TError,
+			TData
+		>;
+	},
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getGetMetricDashboardsV2QueryOptions(params, options);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	return { ...query, queryKey: queryOptions.queryKey };
+}
+
+/**
+ * @summary Get metric dashboards (v2)
+ */
+export const invalidateGetMetricDashboardsV2 = async (
+	queryClient: QueryClient,
+	params: GetMetricDashboardsV2Params,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries(
+		{ queryKey: getGetMetricDashboardsV2QueryKey(params) },
+		options,
+	);
+
+	return queryClient;
+};

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

@@ -2185,14 +2185,9 @@ export interface ErrorsResponseerroradditionalDTO {
 	suggestions: string[];
 }
 
-export type ErrorsResponseretryjsonDTOAnyOf = {
+export interface ErrorsResponseretryjsonDTO {
 	delay: TimeDurationDTO;
-};
-
-/**
- * @nullable
- */
-export type ErrorsResponseretryjsonDTO = ErrorsResponseretryjsonDTOAnyOf | null;
+}
 
 export interface ErrorsJSONDTO {
 	/**
@@ -2207,7 +2202,7 @@ export interface ErrorsJSONDTO {
 	 * @type string
 	 */
 	message: string;
-	retry: ErrorsResponseretryjsonDTO | null;
+	retry?: ErrorsResponseretryjsonDTO;
 	/**
 	 * @type array
 	 */
@@ -2217,9 +2212,9 @@ export interface ErrorsJSONDTO {
 	 */
 	type: string;
 	/**
-	 * @type string,null
+	 * @type string
 	 */
-	url: string | null;
+	url?: string;
 }
 
 export interface AuthtypesOrgSessionContextDTO {
@@ -3271,37 +3266,6 @@ export interface DashboardLinkDTO {
 	url?: string;
 }
 
-export interface VariableDisplayDTO {
-	/**
-	 * @type string
-	 */
-	description?: string;
-	/**
-	 * @type boolean
-	 */
-	hidden?: boolean;
-	/**
-	 * @type string
-	 */
-	name?: string;
-}
-
-export interface DashboardTextVariableSpecDTO {
-	/**
-	 * @type boolean
-	 */
-	constant?: boolean;
-	display?: VariableDisplayDTO;
-	/**
-	 * @type string
-	 */
-	name?: string;
-	/**
-	 * @type string
-	 */
-	value?: string;
-}
-
 export interface DashboardtypesAxesDTO {
 	/**
 	 * @type boolean
@@ -3333,6 +3297,9 @@ export interface DashboardtypesPanelFormattingDTO {
 	unit?: string;
 }
 
+export enum DashboardtypesLegendModeDTO {
+	list = 'list',
+}
 export enum DashboardtypesLegendPositionDTO {
 	bottom = 'bottom',
 	right = 'right',
@@ -3352,6 +3319,7 @@ export interface DashboardtypesLegendDTO {
 	 * @type object,null
 	 */
 	customColors?: DashboardtypesLegendDTOCustomColors;
+	mode?: DashboardtypesLegendModeDTO;
 	position?: DashboardtypesLegendPositionDTO;
 }
 
@@ -3363,14 +3331,13 @@ export interface DashboardtypesThresholdWithLabelDTO {
 	/**
 	 * @type string
 	 */
-	label: string;
+	label?: string;
 	/**
 	 * @type string
 	 */
 	unit?: string;
 	/**
 	 * @type number
-	 * @format double
 	 */
 	value: number;
 }
@@ -3898,7 +3865,6 @@ export interface DashboardtypesComparisonThresholdDTO {
 	unit?: string;
 	/**
 	 * @type number
-	 * @format double
 	 */
 	value: number;
 }
@@ -3954,33 +3920,43 @@ export interface DashboardtypesDashboardDTO {
 	updatedBy?: string;
 }
 
-export enum DashboardtypesDatasourcePluginVariantStructDTOKind {
+export interface DashboardtypesDashboardPanelRefDTO {
+	/**
+	 * @type string
+	 */
+	dashboardId: string;
+	/**
+	 * @type string
+	 */
+	dashboardName: string;
+	/**
+	 * @type string
+	 */
+	panelId: string;
+	/**
+	 * @type string
+	 */
+	panelName: string;
+}
+
+export enum DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpecDTOKind {
 	'signoz/Datasource' = 'signoz/Datasource',
 }
-export type DashboardtypesDatasourcePluginVariantStructDTOSpecAnyOf = {
+export interface DashboardtypesSigNozDatasourceSpecDTO {
 	[key: string]: unknown;
-};
+}
 
-/**
- * @nullable
- */
-export type DashboardtypesDatasourcePluginVariantStructDTOSpec =
-	DashboardtypesDatasourcePluginVariantStructDTOSpecAnyOf | null;
-
-export interface DashboardtypesDatasourcePluginVariantStructDTO {
+export interface DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpecDTO {
 	/**
 	 * @enum signoz/Datasource
 	 * @type string
 	 */
-	kind: DashboardtypesDatasourcePluginVariantStructDTOKind;
-	/**
-	 * @type object,null
-	 */
-	spec: DashboardtypesDatasourcePluginVariantStructDTOSpec;
+	kind: DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpecDTOKind;
+	spec: DashboardtypesSigNozDatasourceSpecDTO;
 }
 
 export type DashboardtypesDatasourcePluginDTO =
-	DashboardtypesDatasourcePluginVariantStructDTO;
+	DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpecDTO;
 
 export interface DashboardtypesDatasourceSpecDTO {
 	/**
@@ -4030,10 +4006,12 @@ export enum DashboardtypesLineStyleDTO {
 export interface DashboardtypesSpanGapsDTO {
 	/**
 	 * @type string
+	 * @description The maximum gap size to connect when fillOnlyBelow is true. Gaps larger than this duration are left disconnected.
 	 */
 	fillLessThan?: string;
 	/**
 	 * @type boolean
+	 * @description Controls whether lines connect across null values. When false (default), all gaps are connected. When true, only gaps smaller than fillLessThan are connected.
 	 */
 	fillOnlyBelow?: boolean;
 }
@@ -4167,7 +4145,6 @@ export interface DashboardtypesTableThresholdDTO {
 	unit?: string;
 	/**
 	 * @type number
-	 * @format double
 	 */
 	value: number;
 }
@@ -4573,9 +4550,9 @@ export interface DashboardtypesPanelSpecDTO {
 	links?: DashboardLinkDTO[];
 	plugin: DashboardtypesPanelPluginDTO;
 	/**
-	 * @type array,null
+	 * @type array
 	 */
-	queries: DashboardtypesQueryDTO[] | null;
+	queries: DashboardtypesQueryDTO[];
 }
 
 export interface DashboardtypesPanelDTO {
@@ -4605,9 +4582,7 @@ export type DashboardtypesLayoutDTO =
 export enum DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpecDTOKind {
 	ListVariable = 'ListVariable',
 }
-export interface VariableDefaultValueDTO {
-	[key: string]: unknown;
-}
+export type DashboardtypesVariableDefaultValueDTO = string | string[];
 
 export enum DashboardtypesVariablePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesDynamicVariableSpecDTOKind {
 	'signoz/DynamicVariable' = 'signoz/DynamicVariable',
@@ -4665,6 +4640,15 @@ export type DashboardtypesVariablePluginDTO =
 	| DashboardtypesVariablePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesQueryVariableSpecDTO
 	| DashboardtypesVariablePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesCustomVariableSpecDTO;
 
+export enum DashboardtypesListVariableSpecSortDTO {
+	none = 'none',
+	'alphabetical-asc' = 'alphabetical-asc',
+	'alphabetical-desc' = 'alphabetical-desc',
+	'numerical-asc' = 'numerical-asc',
+	'numerical-desc' = 'numerical-desc',
+	'alphabetical-ci-asc' = 'alphabetical-ci-asc',
+	'alphabetical-ci-desc' = 'alphabetical-ci-desc',
+}
 export interface DashboardtypesListVariableSpecDTO {
 	/**
 	 * @type boolean
@@ -4682,17 +4666,15 @@ export interface DashboardtypesListVariableSpecDTO {
 	 * @type string
 	 */
 	customAllValue?: string;
-	defaultValue?: VariableDefaultValueDTO;
+	defaultValue?: DashboardtypesVariableDefaultValueDTO;
 	display: DashboardtypesDisplayDTO;
 	/**
 	 * @type string
+	 * @minLength 1
 	 */
-	name?: string;
+	name: string;
 	plugin?: DashboardtypesVariablePluginDTO;
-	/**
-	 * @type string,null
-	 */
-	sort?: string | null;
+	sort?: DashboardtypesListVariableSpecSortDTO;
 }
 
 export interface DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpecDTO {
@@ -4704,21 +4686,38 @@ export interface DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDash
 	spec: DashboardtypesListVariableSpecDTO;
 }
 
-export enum DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpecDTOKind {
+export enum DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpecDTOKind {
 	TextVariable = 'TextVariable',
 }
-export interface DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpecDTO {
+export interface DashboardtypesTextVariableSpecDTO {
+	/**
+	 * @type boolean
+	 */
+	constant?: boolean;
+	display: DashboardtypesDisplayDTO;
+	/**
+	 * @type string
+	 * @minLength 1
+	 */
+	name: string;
+	/**
+	 * @type string
+	 */
+	value: string;
+}
+
+export interface DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpecDTO {
 	/**
 	 * @enum TextVariable
 	 * @type string
 	 */
-	kind: DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpecDTOKind;
-	spec: DashboardTextVariableSpecDTO;
+	kind: DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpecDTOKind;
+	spec: DashboardtypesTextVariableSpecDTO;
 }
 
 export type DashboardtypesVariableDTO =
 	| DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpecDTO
-	| DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpecDTO;
+	| DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpecDTO;
 
 export interface DashboardtypesDashboardSpecDTO {
 	/**
@@ -7174,6 +7173,13 @@ export interface MetricsexplorertypesMetricDashboardDTO {
 	widgetName: string;
 }
 
+export interface MetricsexplorertypesMetricDashboardPanelsResponseDTO {
+	/**
+	 * @type array,null
+	 */
+	dashboards: DashboardtypesDashboardPanelRefDTO[] | null;
+}
+
 export interface MetricsexplorertypesMetricDashboardsResponseDTO {
 	/**
 	 * @type array,null
@@ -11455,6 +11461,22 @@ export type GetHosts200 = {
 	status: string;
 };
 
+export type GetMetricDashboardsV2Params = {
+	/**
+	 * @type string
+	 * @description The name of the metric. May contain slashes (e.g. cloud-provider metrics like run.googleapis.com/request_latencies).
+	 */
+	metricName: string;
+};
+
+export type GetMetricDashboardsV2200 = {
+	data: MetricsexplorertypesMetricDashboardPanelsResponseDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
 export type GetFlamegraphPathParameters = {
 	traceID: string;
 };

frontend/src/pages/DashboardPageV2/DashboardContainer/DashboardSettings/Variables/VariableForm/useVariableForm.ts

@@ -150,7 +150,7 @@ export function useVariableForm({
 		const next: VariableFormModel = {
 			...model,
 			name: trimmedName,
-			defaultValue: defaultValue ? { value: defaultValue } : undefined,
+			defaultValue: defaultValue || undefined,
 		};
 
 		const cycle = detectVariableCycle([...siblings, next]);

frontend/src/pages/DashboardPageV2/DashboardContainer/DashboardSettings/Variables/variableAdapters.ts

@@ -1,5 +1,5 @@
 import {
-	DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpecDTOKind as TextEnvelopeKind,
+	DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpecDTOKind as TextEnvelopeKind,
 	DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpecDTOKind as ListEnvelopeKind,
 	DashboardtypesVariablePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesCustomVariableSpecDTOKind as CustomPluginKind,
 	DashboardtypesVariablePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesDynamicVariableSpecDTOKind as DynamicPluginKind,
@@ -9,7 +9,7 @@ import type {
 	DashboardtypesListVariableSpecDTO,
 	DashboardtypesVariableDTO,
 	DashboardtypesVariablePluginDTO,
-	DashboardTextVariableSpecDTO,
+	DashboardtypesTextVariableSpecDTO,
 } from 'api/generated/services/sigNoz.schemas';
 
 import {
@@ -19,7 +19,6 @@ import {
 	signalForApi,
 	VARIABLE_SORT_DISABLED,
 	type VariableFormModel,
-	type VariableSort,
 } from './variableFormModel';
 
 /** DTO envelope → flat form model (for display / editing). */
@@ -37,7 +36,7 @@ export function dtoToFormModel(
 
 	// Text variable — a distinct envelope (no list plugin).
 	if (dto.kind === TextEnvelopeKind.TextVariable) {
-		const spec = dto.spec as DashboardTextVariableSpecDTO;
+		const spec = dto.spec as DashboardtypesTextVariableSpecDTO;
 		return {
 			...common,
 			type: 'TEXT',
@@ -52,7 +51,7 @@ export function dtoToFormModel(
 		...common,
 		multiSelect: spec.allowMultiple ?? false,
 		showAllOption: spec.allowAllValue ?? false,
-		sort: (spec.sort as VariableSort) ?? VARIABLE_SORT_DISABLED,
+		sort: spec.sort ?? VARIABLE_SORT_DISABLED,
 		defaultValue: spec.defaultValue,
 	};
 	const plugin = spec.plugin;

frontend/src/pages/DashboardPageV2/DashboardContainer/DashboardSettings/Variables/variableFormModel.ts

@@ -1,5 +1,8 @@
-import { TelemetrytypesSignalDTO } from 'api/generated/services/sigNoz.schemas';
-import type { VariableDefaultValueDTO } from 'api/generated/services/sigNoz.schemas';
+import {
+	DashboardtypesListVariableSpecSortDTO,
+	TelemetrytypesSignalDTO,
+} from 'api/generated/services/sigNoz.schemas';
+import type { DashboardtypesVariableDefaultValueDTO } from 'api/generated/services/sigNoz.schemas';
 import { sortBy } from 'lodash-es';
 
 /**
@@ -24,19 +27,19 @@ export const DYNAMIC_SIGNAL_ALL = 'all' as const;
 export type DynamicSignalOption = TelemetrySignal | typeof DYNAMIC_SIGNAL_ALL;
 
 /**
- * Sort order for list-variable values. The wire (Perses) validates `sort`
- * against a fixed method set. There is no generated TS enum for it
- * (`DashboardtypesListOrderDTO` is the query-builder order, a different field),
- * so we mirror the Perses `Sort` tokens here.
+ * Sort order for list-variable values, keyed by the generated wire enum so the
+ * form model and the DTO `sort` field share one source of truth. The friendly
+ * keys (`DISABLED` / `ASC` / …) are UI-facing; the values are the Perses `Sort`
+ * tokens the wire validates against.
  */
 export const VARIABLE_SORT = {
-	DISABLED: 'none',
-	ASC: 'alphabetical-asc',
-	DESC: 'alphabetical-desc',
-	NUMERICAL_ASC: 'numerical-asc',
-	NUMERICAL_DESC: 'numerical-desc',
-	CI_ASC: 'alphabetical-ci-asc',
-	CI_DESC: 'alphabetical-ci-desc',
+	DISABLED: DashboardtypesListVariableSpecSortDTO.none,
+	ASC: DashboardtypesListVariableSpecSortDTO['alphabetical-asc'],
+	DESC: DashboardtypesListVariableSpecSortDTO['alphabetical-desc'],
+	NUMERICAL_ASC: DashboardtypesListVariableSpecSortDTO['numerical-asc'],
+	NUMERICAL_DESC: DashboardtypesListVariableSpecSortDTO['numerical-desc'],
+	CI_ASC: DashboardtypesListVariableSpecSortDTO['alphabetical-ci-asc'],
+	CI_DESC: DashboardtypesListVariableSpecSortDTO['alphabetical-ci-desc'],
 } as const;
 
 export type VariableSort = (typeof VARIABLE_SORT)[keyof typeof VARIABLE_SORT];
@@ -133,7 +136,7 @@ export interface VariableFormModel {
 	 * Runtime-selected default, not editable in the management tab yet; carried
 	 * through edits so saving a definition doesn't clobber it.
 	 */
-	defaultValue?: VariableDefaultValueDTO;
+	defaultValue?: DashboardtypesVariableDefaultValueDTO;
 }
 
 export function emptyVariableFormModel(): VariableFormModel {

frontend/src/pages/DashboardPageV2/DashboardContainer/PanelsAndSectionsLayout/Panel/PanelStatus/__tests__/utils.test.ts

@@ -30,7 +30,6 @@ describe('panelStatusFromError', () => {
 				{ message: 'missing aggregation', suggestions: [] },
 				{ message: 'bad filter', suggestions: [] },
 			],
-			retry: null,
 			suggestions: [],
 			type: '',
 		});
@@ -59,7 +58,6 @@ describe('panelStatusFromError', () => {
 				message: 'y',
 				url: '',
 				errors: [],
-				retry: null,
 				suggestions: [],
 				type: '',
 			},

pkg/apiserver/signozapiserver/metricsexplorer.go

@@ -187,6 +187,26 @@ func (provider *provider) addMetricsExplorerRoutes(router *mux.Router) error {
 		return err
 	}
 
+	if err := router.Handle("/api/v3/metrics/dashboards", handler.New(
+		provider.authzMiddleware.ViewAccess(provider.metricsExplorerHandler.GetMetricDashboardsV2),
+		handler.OpenAPIDef{
+			ID:                  "GetMetricDashboardsV2",
+			Tags:                []string{"metrics"},
+			Summary:             "Get metric dashboards (v2)",
+			Description:         "This endpoint returns associated v2 dashboards for a specified metric",
+			Request:             nil,
+			RequestQuery:        new(metricsexplorertypes.MetricNameQuery),
+			RequestContentType:  "",
+			Response:            new(metricsexplorertypes.MetricDashboardPanelsResponse),
+			ResponseContentType: "application/json",
+			SuccessStatusCode:   http.StatusOK,
+			ErrorStatusCodes:    []int{http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError},
+			Deprecated:          false,
+			SecuritySchemes:     newSecuritySchemes(types.RoleViewer),
+		})).Methods(http.MethodGet).GetError(); err != nil {
+		return err
+	}
+
 	if err := router.Handle("/api/v2/metrics/inspect", handler.New(
 		provider.authzMiddleware.ViewAccess(provider.metricsExplorerHandler.InspectMetrics),
 		handler.OpenAPIDef{

pkg/errors/http.go

@@ -7,12 +7,12 @@ import (
 )
 
 type JSON struct {
-	Type        string                    `json:"type" required:"true"`
-	Code        string                    `json:"code" required:"true"`
-	Message     string                    `json:"message" required:"true"`
-	Url         string                    `json:"url" required:"true" nullable:"true"`
+	Type        string                    `json:"type" required:"true" nullable:"false"`
+	Code        string                    `json:"code" required:"true" nullable:"false"`
+	Message     string                    `json:"message" required:"true" nullable:"false"`
+	Url         string                    `json:"url,omitempty" required:"false"`
 	Errors      []responseerroradditional `json:"errors" required:"true" nullable:"false"`
-	Retry       *responseretryjson        `json:"retry" required:"true" nullable:"true"`
+	Retry       *responseretryjson        `json:"retry,omitempty" required:"false"`
 	Suggestions []string                  `json:"suggestions" required:"true" nullable:"false"`
 }
 
@@ -21,7 +21,7 @@ type responseretryjson struct {
 }
 
 type responseerroradditional struct {
-	Message     string   `json:"message" required:"true"`
+	Message     string   `json:"message" required:"true" nullable:"false"`
 	Suggestions []string `json:"suggestions" required:"true" nullable:"false"`
 }
 

pkg/http/render/render_test.go

@@ -99,13 +99,13 @@ func TestError(t *testing.T) {
 			name:       "AlreadyExists",
 			statusCode: http.StatusConflict,
 			err:        errors.New(errors.TypeAlreadyExists, errors.MustNewCode("already_exists"), "already exists").WithUrl("https://already_exists"),
-			expected:   []byte(`{"status":"error","error":{"type":"already-exists","code":"already_exists","message":"already exists","url":"https://already_exists","errors":[],"retry":null,"suggestions":[]}}`),
+			expected:   []byte(`{"status":"error","error":{"type":"already-exists","code":"already_exists","message":"already exists","url":"https://already_exists","errors":[],"suggestions":[]}}`),
 		},
 		"/unauthenticated": {
 			name:       "Unauthenticated",
 			statusCode: http.StatusUnauthorized,
 			err:        errors.New(errors.TypeUnauthenticated, errors.MustNewCode("not_allowed"), "not allowed").WithUrl("https://unauthenticated").WithAdditional("a1", "a2"),
-			expected:   []byte(`{"status":"error","error":{"type":"unauthenticated","code":"not_allowed","message":"not allowed","url":"https://unauthenticated","errors":[{"message":"a1","suggestions":[]},{"message":"a2","suggestions":[]}],"retry":null,"suggestions":[]}}`),
+			expected:   []byte(`{"status":"error","error":{"type":"unauthenticated","code":"not_allowed","message":"not allowed","url":"https://unauthenticated","errors":[{"message":"a1","suggestions":[]},{"message":"a2","suggestions":[]}],"suggestions":[]}}`),
 		},
 	}
 
@@ -177,8 +177,7 @@ func TestErrorRetryAfterHeader(t *testing.T) {
 			name:                "BareErrorNoHeaderNoRetryBlock",
 			err:                 errors.New(errors.TypeInternal, errors.MustNewCode("boom"), "boom"),
 			wantRetryAfter:      "",
-			wantBodyContains:    `"retry":null`,
-			wantBodyNotContains: `"delay"`,
+			wantBodyNotContains: `"retry"`, // omitempty drops the nil retry block entirely
 		},
 	}
 

pkg/modules/dashboard/dashboard.go

@@ -88,6 +88,8 @@ type Module interface {
 	UpdateView(ctx context.Context, orgID valuer.UUID, id valuer.UUID, updateable dashboardtypes.UpdatableDashboardView) (*dashboardtypes.DashboardView, error)
 
 	DeleteView(ctx context.Context, orgID valuer.UUID, id valuer.UUID) error
+
+	GetByMetricNamesV2(ctx context.Context, orgID valuer.UUID, metricNames []string) (map[string][]dashboardtypes.DashboardPanelRef, error)
 }
 
 type Handler interface {

pkg/modules/dashboard/impldashboard/listfilter_visitor.go

@@ -285,9 +285,9 @@ func (v *visitor) buildStringOperation(builder *sqlbuilder.SelectBuilder, ctx *g
 			like = "NOT LIKE"
 		}
 		// Escape the user's % and _ so they match literally, then wrap in wildcards.
-		// ESCAPE declares the backslash we just injected as the escape char — needed
-		// on SQLite (no default) and a harmless restatement of the Postgres default.
-		escaped := strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(val)
+		// ESCAPE declares the backslash the escaper injected as the escape char —
+		// needed on SQLite (no default) and a harmless restatement of the Postgres default.
+		escaped := v.formatter.EscapeLikePattern(val)
 		return fmt.Sprintf("%s %s %s ESCAPE '\\'", columnExpression, like, builder.Var("%"+escaped+"%"))
 	case qbtypesv5.FilterOperatorRegexp, qbtypesv5.FilterOperatorNotRegexp:
 		v.addError("REGEXP filtering on %q is not yet supported", keyForError)

pkg/modules/dashboard/impldashboard/store.go

@@ -213,6 +213,41 @@ func (store *store) sortExprForListV2(sort dashboardtypes.ListSort) (string, err
 		"unsupported sort field %q", sort)
 }
 
+func (store *store) ListByDataContainsAny(ctx context.Context, orgID valuer.UUID, searches []string) ([]*dashboardtypes.StorableDashboard, error) {
+	storableDashboards := make([]*dashboardtypes.StorableDashboard, 0)
+	if len(searches) == 0 {
+		return storableDashboards, nil
+	}
+
+	clause, args := buildContainsAnyClauseForDataColumn(store.sqlstore.Formatter(), searches)
+	err := store.
+		sqlstore.
+		BunDB().
+		NewSelect().
+		Model(&storableDashboards).
+		Where("org_id = ?", orgID).
+		Where(clause, args...).
+		Scan(ctx)
+	if err != nil {
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "couldn't list dashboards by data")
+	}
+
+	return storableDashboards, nil
+}
+
+// buildContainsAnyClauseForDataColumn builds a parenthesised OR of `data LIKE` predicates, one
+// per search, matching the raw substring literally (LIKE wildcards escaped). It
+// returns the predicate and its bind args, ready for a single bun Where call.
+func buildContainsAnyClauseForDataColumn(formatter sqlstore.SQLFormatter, searches []string) (string, []any) {
+	conditions := make([]string, 0, len(searches))
+	args := make([]any, 0, len(searches))
+	for _, search := range searches {
+		conditions = append(conditions, "data LIKE ? ESCAPE '\\'")
+		args = append(args, "%"+formatter.EscapeLikePattern(search)+"%")
+	}
+	return "(" + strings.Join(conditions, " OR ") + ")", args
+}
+
 func (store *store) GetPublic(ctx context.Context, dashboardID string) (*dashboardtypes.StorablePublicDashboard, error) {
 	storable := new(dashboardtypes.StorablePublicDashboard)
 	err := store.

pkg/modules/dashboard/impldashboard/store_test.go

@@ -0,0 +1,43 @@
+package impldashboard
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestBuildContainsAnyClauseForDataColumn(t *testing.T) {
+	cases := []struct {
+		subtestName  string
+		searches     []string
+		expectedSQL  string
+		expectedArgs []any
+	}{
+		{
+			subtestName:  "single search",
+			searches:     []string{"http.server.duration"},
+			expectedSQL:  `(data LIKE ? ESCAPE '\')`,
+			expectedArgs: []any{`%http.server.duration%`},
+		},
+		{
+			subtestName:  "multiple searches are OR-ed",
+			searches:     []string{"metric.a", "metric.b", "metric.c"},
+			expectedSQL:  `(data LIKE ? ESCAPE '\' OR data LIKE ? ESCAPE '\' OR data LIKE ? ESCAPE '\')`,
+			expectedArgs: []any{`%metric.a%`, `%metric.b%`, `%metric.c%`},
+		},
+		{
+			subtestName:  "like wildcards in the search are escaped",
+			searches:     []string{`a%b_c\d`},
+			expectedSQL:  `(data LIKE ? ESCAPE '\')`,
+			expectedArgs: []any{`%a\%b\_c\\d%`},
+		},
+	}
+
+	for _, c := range cases {
+		t.Run(c.subtestName, func(t *testing.T) {
+			clause, args := buildContainsAnyClauseForDataColumn(formatter(t), c.searches)
+			assert.Equal(t, c.expectedSQL, clause)
+			assert.Equal(t, c.expectedArgs, args)
+		})
+	}
+}

pkg/modules/dashboard/impldashboard/v2_dashboards_by_metric_name.go

@@ -0,0 +1,132 @@
+package impldashboard
+
+import (
+	"context"
+	"log/slog"
+	"maps"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/types/dashboardtypes"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+func (m *module) GetByMetricNamesV2(ctx context.Context, orgID valuer.UUID, metricNames []string) (map[string][]dashboardtypes.DashboardPanelRef, error) {
+	metricNamesMap := make(map[string]bool, len(metricNames))
+	for _, name := range metricNames {
+		metricNamesMap[name] = true
+	}
+
+	candidateDashboards, err := m.getCandidatesDashboardsForMetricNames(ctx, orgID, metricNames)
+	if err != nil {
+		return nil, err
+	}
+
+	return m.selectDashboardsFromCandidates(ctx, metricNamesMap, candidateDashboards), nil
+}
+
+func (m *module) getCandidatesDashboardsForMetricNames(ctx context.Context, orgID valuer.UUID, metricNames []string) ([]*dashboardtypes.DashboardV2, error) {
+	storables, err := m.store.ListByDataContainsAny(ctx, orgID, metricNames)
+	if err != nil {
+		return nil, err
+	}
+
+	candidates := make([]*dashboardtypes.DashboardV2, 0, len(storables))
+	for _, storable := range storables {
+		if storable.Source == dashboardtypes.SourceSystem {
+			continue
+		}
+
+		// tags are not required for this process so sending a nil list here.
+		dashboard, err := storable.ToDashboardV2(nil)
+		if err != nil {
+			m.settings.Logger().WarnContext(ctx, "skipping dashboard that couldn't be parsed as v2", slog.String("dashboard_id", storable.ID.StringValue()), errors.Attr(err))
+			continue
+		}
+		candidates = append(candidates, dashboard)
+	}
+	return candidates, nil
+}
+
+func (m *module) selectDashboardsFromCandidates(ctx context.Context, metricNamesMap map[string]bool, candidateDashboards []*dashboardtypes.DashboardV2) map[string][]dashboardtypes.DashboardPanelRef {
+	result := make(map[string][]dashboardtypes.DashboardPanelRef)
+	for _, dashboard := range candidateDashboards {
+		for panelID, panel := range dashboard.Spec.Panels {
+			if panel == nil {
+				continue
+			}
+			metricsInPanel := make(map[string]bool)
+			for _, query := range panel.Spec.Queries {
+				maps.Copy(metricsInPanel, m.extractMetricNamesFromQuerySpec(ctx, query.Spec.Plugin.Spec))
+			}
+			for metricName := range metricsInPanel {
+				if !metricNamesMap[metricName] {
+					continue
+				}
+				result[metricName] = append(result[metricName], dashboardtypes.DashboardPanelRef{
+					DashboardID:   dashboard.ID.StringValue(),
+					DashboardName: dashboard.Spec.Display.Name,
+					PanelID:       panelID,
+					PanelName:     panel.Spec.Display.Name,
+				})
+			}
+		}
+	}
+	return result
+}
+
+func (m *module) extractMetricNamesFromQuerySpec(ctx context.Context, spec any) map[string]bool {
+	found := make(map[string]bool)
+	switch s := spec.(type) {
+	case *qbtypes.CompositeQuery:
+		for _, envelope := range s.Queries {
+			maps.Copy(found, m.extractMetricNamesFromQueryEnvelope(ctx, envelope))
+		}
+	case *dashboardtypes.BuilderQuerySpec:
+		if builder, ok := s.Spec.(qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]); ok {
+			for _, aggregation := range builder.Aggregations {
+				if aggregation.MetricName != "" {
+					found[aggregation.MetricName] = true
+				}
+			}
+		}
+	case *qbtypes.PromQuery:
+		maps.Copy(found, m.extractMetricNamesFromRawQuery(ctx, qbtypes.QueryTypePromQL, s.Query))
+	case *qbtypes.ClickHouseQuery:
+		maps.Copy(found, m.extractMetricNamesFromRawQuery(ctx, qbtypes.QueryTypeClickHouseSQL, s.Query))
+	}
+	return found
+}
+
+func (m *module) extractMetricNamesFromQueryEnvelope(ctx context.Context, envelope qbtypes.QueryEnvelope) map[string]bool {
+	found := make(map[string]bool)
+	switch s := envelope.Spec.(type) {
+	case qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]:
+		for _, aggregation := range s.Aggregations {
+			if aggregation.MetricName != "" {
+				found[aggregation.MetricName] = true
+			}
+		}
+	case qbtypes.PromQuery:
+		maps.Copy(found, m.extractMetricNamesFromRawQuery(ctx, qbtypes.QueryTypePromQL, s.Query))
+	case qbtypes.ClickHouseQuery:
+		maps.Copy(found, m.extractMetricNamesFromRawQuery(ctx, qbtypes.QueryTypeClickHouseSQL, s.Query))
+	}
+	return found
+}
+
+func (m *module) extractMetricNamesFromRawQuery(ctx context.Context, queryType qbtypes.QueryType, query string) map[string]bool {
+	found := make(map[string]bool)
+	if query == "" {
+		return found
+	}
+	result, err := m.queryParser.AnalyzeQueryFilter(ctx, queryType, query)
+	if err != nil {
+		m.settings.Logger().WarnContext(ctx, "failed to parse query for metric names", slog.String("query", query), errors.Attr(err))
+		return found
+	}
+	for _, metricName := range result.MetricNames {
+		found[metricName] = true
+	}
+	return found
+}

pkg/modules/metricsexplorer/implmetricsexplorer/handler.go

@@ -228,6 +228,38 @@ func (h *handler) GetMetricDashboards(rw http.ResponseWriter, req *http.Request)
 	render.Success(rw, http.StatusOK, out)
 }
 
+func (h *handler) GetMetricDashboardsV2(rw http.ResponseWriter, req *http.Request) {
+	claims, err := authtypes.ClaimsFromContext(req.Context())
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	var in metricsexplorertypes.MetricNameQuery
+	if err := binding.Query.BindQuery(req.URL.Query(), &in); err != nil {
+		render.Error(rw, err)
+		return
+	}
+	if err := in.Validate(); err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	orgID := valuer.MustNewUUID(claims.OrgID)
+
+	if err := h.checkMetricExists(req.Context(), orgID, in.MetricName); err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	out, err := h.module.GetMetricDashboardsV2(req.Context(), orgID, in.MetricName)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+	render.Success(rw, http.StatusOK, out)
+}
+
 func (h *handler) GetMetricHighlights(rw http.ResponseWriter, req *http.Request) {
 	claims, err := authtypes.ClaimsFromContext(req.Context())
 	if err != nil {

pkg/modules/metricsexplorer/implmetricsexplorer/module.go

@@ -373,22 +373,35 @@ func (m *module) GetMetricDashboards(ctx context.Context, orgID valuer.UUID, met
 		return nil, errors.WrapInternalf(err, errors.CodeInternal, "failed to get dashboards for metric")
 	}
 
-	dashboards := make([]metricsexplorertypes.MetricDashboard, 0)
-	if dashboardList, ok := data[metricName]; ok {
-		dashboards = make([]metricsexplorertypes.MetricDashboard, 0, len(dashboardList))
-		for _, item := range dashboardList {
-			dashboards = append(dashboards, metricsexplorertypes.MetricDashboard{
-				DashboardName: item["dashboard_name"],
-				DashboardID:   item["dashboard_id"],
-				WidgetID:      item["widget_id"],
-				WidgetName:    item["widget_name"],
-			})
-		}
+	return newMetricDashboardsResponse(data[metricName]), nil
+}
+
+func (m *module) GetMetricDashboardsV2(ctx context.Context, orgID valuer.UUID, metricName string) (*metricsexplorertypes.MetricDashboardPanelsResponse, error) {
+	if metricName == "" {
+		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "metricName is required")
+	}
+	data, err := m.dashboardModule.GetByMetricNamesV2(ctx, orgID, []string{metricName})
+	if err != nil {
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "failed to get dashboards for metric")
+	}
+
+	return metricsexplorertypes.NewMetricDashboardPanelsResponse(data[metricName]), nil
+}
+
+func newMetricDashboardsResponse(dashboardList []map[string]string) *metricsexplorertypes.MetricDashboardsResponse {
+	dashboards := make([]metricsexplorertypes.MetricDashboard, 0, len(dashboardList))
+	for _, item := range dashboardList {
+		dashboards = append(dashboards, metricsexplorertypes.MetricDashboard{
+			DashboardName: item["dashboard_name"],
+			DashboardID:   item["dashboard_id"],
+			WidgetID:      item["widget_id"],
+			WidgetName:    item["widget_name"],
+		})
 	}
 
 	return &metricsexplorertypes.MetricDashboardsResponse{
 		Dashboards: dashboards,
-	}, nil
+	}
 }
 
 // GetMetricHighlights returns highlights for a metric including data points, last received, total time series, and active time series.

pkg/modules/metricsexplorer/metricsexplorer.go

@@ -18,6 +18,7 @@ type Handler interface {
 	UpdateMetricMetadata(http.ResponseWriter, *http.Request)
 	GetMetricAlerts(http.ResponseWriter, *http.Request)
 	GetMetricDashboards(http.ResponseWriter, *http.Request)
+	GetMetricDashboardsV2(http.ResponseWriter, *http.Request)
 	GetMetricHighlights(http.ResponseWriter, *http.Request)
 	GetOnboardingStatus(http.ResponseWriter, *http.Request)
 	InspectMetrics(http.ResponseWriter, *http.Request)
@@ -33,6 +34,7 @@ type Module interface {
 	UpdateMetricMetadata(ctx context.Context, orgID valuer.UUID, req *metricsexplorertypes.UpdateMetricMetadataRequest) error
 	GetMetricAlerts(ctx context.Context, orgID valuer.UUID, metricName string) (*metricsexplorertypes.MetricAlertsResponse, error)
 	GetMetricDashboards(ctx context.Context, orgID valuer.UUID, metricName string) (*metricsexplorertypes.MetricDashboardsResponse, error)
+	GetMetricDashboardsV2(ctx context.Context, orgID valuer.UUID, metricName string) (*metricsexplorertypes.MetricDashboardPanelsResponse, error)
 	GetMetricHighlights(ctx context.Context, orgID valuer.UUID, metricName string) (*metricsexplorertypes.MetricHighlightsResponse, error)
 	GetMetricAttributes(ctx context.Context, orgID valuer.UUID, req *metricsexplorertypes.MetricAttributesRequest) (*metricsexplorertypes.MetricAttributesResponse, error)
 	HasNonSigNozMetrics(ctx context.Context) (bool, error)

pkg/querier/builder_query.go

@@ -31,10 +31,16 @@ type builderQuery[T any] struct {
 	fromMS uint64
 	toMS   uint64
 	kind   qbtypes.RequestType
+
+	builderConfig builderConfig
 }
 
 var _ qbtypes.Query = (*builderQuery[any])(nil)
 
+type builderConfig struct {
+	logTraceIDWindowPaddingMS uint64
+}
+
 func newBuilderQuery[T any](
 	logger *slog.Logger,
 	telemetryStore telemetrystore.TelemetryStore,
@@ -43,6 +49,7 @@ func newBuilderQuery[T any](
 	tr qbtypes.TimeRange,
 	kind qbtypes.RequestType,
 	variables map[string]qbtypes.VariableItem,
+	cfg builderConfig,
 ) *builderQuery[T] {
 	return &builderQuery[T]{
 		logger:         logger,
@@ -53,6 +60,7 @@ func newBuilderQuery[T any](
 		fromMS:         tr.From,
 		toMS:           tr.To,
 		kind:           kind,
+		builderConfig:  cfg,
 	}
 }
 
@@ -286,9 +294,20 @@ func (q *builderQuery[T]) narrowWindowByTraceID(ctx context.Context, fromMS, toM
 		return fromMS, toMS, true, ""
 	}
 
+	// Logs can be flushed slightly after the span ends. The trace
+	// time range comes from the spans table, so for logs we widen it by the
+	// configured padding before clamping. Keep the actual recorded bounds for
+	// the user-facing warning so it reports where the trace truly lies, not the
+	// padded range.
+	actualStartMS, actualEndMS := traceStartMS, traceEndMS
+	if q.spec.Signal == telemetrytypes.SignalLogs {
+		traceStartMS -= q.builderConfig.logTraceIDWindowPaddingMS
+		traceEndMS += q.builderConfig.logTraceIDWindowPaddingMS
+	}
+
 	if traceStartMS > toMS || traceEndMS < fromMS {
-		traceStartUTC := time.UnixMilli(int64(traceStartMS)).UTC().Format(time.RFC3339)
-		traceEndUTC := time.UnixMilli(int64(traceEndMS)).UTC().Format(time.RFC3339)
+		traceStartUTC := time.UnixMilli(int64(actualStartMS)).UTC().Format(time.RFC3339)
+		traceEndUTC := time.UnixMilli(int64(actualEndMS)).UTC().Format(time.RFC3339)
 		return fromMS, toMS, false, fmt.Sprintf(traceOutsideRangeWarn, q.spec.Name, traceStartUTC, traceEndUTC)
 	}
 	if traceStartMS > fromMS {

pkg/querier/config.go

@@ -23,6 +23,8 @@ type Config struct {
 	MaxConcurrentQueries int `yaml:"max_concurrent_queries" mapstructure:"max_concurrent_queries"`
 	// SkipResourceFingerprint configures when the resource fingerprint subquery is skipped in favor of main-table filtering.
 	SkipResourceFingerprint SkipResourceFingerprint `yaml:"skip_resource_fingerprint" mapstructure:"skip_resource_fingerprint"`
+	// LogTraceIDWindowPadding is the padding added to narrowed down timerange from trace summary to logs with trace_id filter.
+	LogTraceIDWindowPadding time.Duration `yaml:"log_trace_id_window_padding" mapstructure:"log_trace_id_window_padding"`
 }
 
 // NewConfigFactory creates a new config factory for querier.
@@ -40,6 +42,7 @@ func newConfig() factory.Config {
 			Enabled:   false,
 			Threshold: 100000,
 		},
+		LogTraceIDWindowPadding: 5 * time.Minute,
 	}
 }
 
@@ -57,6 +60,9 @@ func (c Config) Validate() error {
 	if c.SkipResourceFingerprint.Enabled && c.SkipResourceFingerprint.Threshold == 0 {
 		return errors.NewInvalidInputf(errors.CodeInvalidInput, "skip_resource_fingerprint.threshold must be > 0 when enabled")
 	}
+	if c.LogTraceIDWindowPadding < 0 {
+		return errors.NewInvalidInputf(errors.CodeInvalidInput, "log_trace_id_window_padding must not be negative, got %v", c.LogTraceIDWindowPadding)
+	}
 	return nil
 }
 

pkg/querier/querier.go

@@ -35,19 +35,20 @@ var (
 )
 
 type querier struct {
-	logger                   *slog.Logger
-	fl                       flagger.Flagger
-	telemetryStore           telemetrystore.TelemetryStore
-	metadataStore            telemetrytypes.MetadataStore
-	promEngine               prometheus.Prometheus
-	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              BucketCache
-	liveDataRefresh          time.Duration
+	logger                    *slog.Logger
+	fl                        flagger.Flagger
+	telemetryStore            telemetrystore.TelemetryStore
+	metadataStore             telemetrytypes.MetadataStore
+	promEngine                prometheus.Prometheus
+	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               BucketCache
+	liveDataRefresh           time.Duration
+	builderConfig             builderConfig
 }
 
 var _ Querier = (*querier)(nil)
@@ -65,22 +66,26 @@ func New(
 	traceOperatorStmtBuilder qbtypes.TraceOperatorStatementBuilder,
 	bucketCache BucketCache,
 	flagger flagger.Flagger,
+	logTraceIDWindowPadding time.Duration,
 ) *querier {
 	querierSettings := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/querier")
 	return &querier{
-		logger:                   querierSettings.Logger(),
-		fl:                       flagger,
-		telemetryStore:           telemetryStore,
-		metadataStore:            metadataStore,
-		promEngine:               promEngine,
-		traceStmtBuilder:         traceStmtBuilder,
-		logStmtBuilder:           logStmtBuilder,
-		auditStmtBuilder:         auditStmtBuilder,
-		metricStmtBuilder:        metricStmtBuilder,
-		meterStmtBuilder:         meterStmtBuilder,
-		traceOperatorStmtBuilder: traceOperatorStmtBuilder,
-		bucketCache:              bucketCache,
-		liveDataRefresh:          5 * time.Second,
+		logger:                    querierSettings.Logger(),
+		fl:                        flagger,
+		telemetryStore:            telemetryStore,
+		metadataStore:             metadataStore,
+		promEngine:                promEngine,
+		traceStmtBuilder:          traceStmtBuilder,
+		logStmtBuilder:            logStmtBuilder,
+		auditStmtBuilder:          auditStmtBuilder,
+		metricStmtBuilder:         metricStmtBuilder,
+		meterStmtBuilder:          meterStmtBuilder,
+		traceOperatorStmtBuilder:  traceOperatorStmtBuilder,
+		bucketCache:               bucketCache,
+		liveDataRefresh:           5 * time.Second,
+		builderConfig: builderConfig{
+			logTraceIDWindowPaddingMS: uint64(logTraceIDWindowPadding.Milliseconds()),
+		},
 	}
 }
 
@@ -223,7 +228,7 @@ func (q *querier) buildQueries(
 			case qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]:
 				spec.ShiftBy = extractShiftFromBuilderQuery(spec)
 				timeRange := adjustTimeRangeForShift(spec, qbtypes.TimeRange{From: req.Start, To: req.End}, req.RequestType)
-				bq := newBuilderQuery(q.logger, q.telemetryStore, q.traceStmtBuilder, spec, timeRange, req.RequestType, tmplVars)
+				bq := newBuilderQuery(q.logger, q.telemetryStore, q.traceStmtBuilder, spec, timeRange, req.RequestType, tmplVars, builderConfig{})
 				queries[spec.Name] = bq
 				steps[spec.Name] = spec.StepInterval
 			case qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]:
@@ -233,7 +238,7 @@ func (q *querier) buildQueries(
 				if spec.Source == telemetrytypes.SourceAudit {
 					stmtBuilder = q.auditStmtBuilder
 				}
-				bq := newBuilderQuery(q.logger, q.telemetryStore, stmtBuilder, spec, timeRange, req.RequestType, tmplVars)
+				bq := newBuilderQuery(q.logger, q.telemetryStore, stmtBuilder, spec, timeRange, req.RequestType, tmplVars, q.builderConfig)
 				queries[spec.Name] = bq
 				steps[spec.Name] = spec.StepInterval
 			case qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]:
@@ -250,9 +255,9 @@ func (q *querier) buildQueries(
 
 				if spec.Source == telemetrytypes.SourceMeter {
 					event.Source = telemetrytypes.SourceMeter.StringValue()
-					bq = newBuilderQuery(q.logger, q.telemetryStore, q.meterStmtBuilder, spec, timeRange, req.RequestType, tmplVars)
+					bq = newBuilderQuery(q.logger, q.telemetryStore, q.meterStmtBuilder, spec, timeRange, req.RequestType, tmplVars, builderConfig{})
 				} else {
-					bq = newBuilderQuery(q.logger, q.telemetryStore, q.metricStmtBuilder, spec, timeRange, req.RequestType, tmplVars)
+					bq = newBuilderQuery(q.logger, q.telemetryStore, q.metricStmtBuilder, spec, timeRange, req.RequestType, tmplVars, builderConfig{})
 				}
 
 				queries[spec.Name] = bq
@@ -527,7 +532,7 @@ func (q *querier) QueryRawStream(ctx context.Context, orgID valuer.UUID, req *qb
 				"id": {
 					Value: updatedLogID,
 				},
-			})
+			}, q.builderConfig)
 			queries[spec.Name] = bq
 
 			qbResp, qbErr := q.run(ctx, orgID, queries, req, nil, event, nil)
@@ -823,7 +828,7 @@ func (q *querier) createRangedQuery(originalQuery qbtypes.Query, timeRange qbtyp
 		specCopy := qt.spec.Copy()
 		specCopy.ShiftBy = extractShiftFromBuilderQuery(specCopy)
 		adjustedTimeRange := adjustTimeRangeForShift(specCopy, timeRange, qt.kind)
-		return newBuilderQuery(q.logger, q.telemetryStore, q.traceStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables)
+		return newBuilderQuery(q.logger, q.telemetryStore, q.traceStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
 
 	case *builderQuery[qbtypes.LogAggregation]:
 		specCopy := qt.spec.Copy()
@@ -833,16 +838,16 @@ func (q *querier) createRangedQuery(originalQuery qbtypes.Query, timeRange qbtyp
 		if qt.spec.Source == telemetrytypes.SourceAudit {
 			shiftStmtBuilder = q.auditStmtBuilder
 		}
-		return newBuilderQuery(q.logger, q.telemetryStore, shiftStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables)
+		return newBuilderQuery(q.logger, q.telemetryStore, shiftStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, q.builderConfig)
 
 	case *builderQuery[qbtypes.MetricAggregation]:
 		specCopy := qt.spec.Copy()
 		specCopy.ShiftBy = extractShiftFromBuilderQuery(specCopy)
 		adjustedTimeRange := adjustTimeRangeForShift(specCopy, timeRange, qt.kind)
 		if qt.spec.Source == telemetrytypes.SourceMeter {
-			return newBuilderQuery(q.logger, q.telemetryStore, q.meterStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables)
+			return newBuilderQuery(q.logger, q.telemetryStore, q.meterStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
 		}
-		return newBuilderQuery(q.logger, q.telemetryStore, q.metricStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables)
+		return newBuilderQuery(q.logger, q.telemetryStore, q.metricStmtBuilder, specCopy, adjustedTimeRange, qt.kind, qt.variables, builderConfig{})
 	case *traceOperatorQuery:
 		specCopy := qt.spec.Copy()
 		return &traceOperatorQuery{

pkg/querier/querier_test.go

@@ -54,6 +54,7 @@ func TestQueryRange_MetricTypeMissing(t *testing.T) {
 		nil,                // traceOperatorStmtBuilder
 		nil,                // bucketCache
 		flaggertest.New(t), // flagger
+		0,
 	)
 
 	req := &qbtypes.QueryRangeRequest{
@@ -124,6 +125,7 @@ func TestQueryRange_MetricTypeFromStore(t *testing.T) {
 		nil,                      // traceOperatorStmtBuilder
 		nil,                      // bucketCache
 		flaggertest.New(t),       // flagger
+		0,
 	)
 
 	req := &qbtypes.QueryRangeRequest{

pkg/querier/signozquerier/provider.go

@@ -192,5 +192,6 @@ func newProvider(
 		traceOperatorStmtBuilder,
 		bucketCache,
 		flagger,
+		cfg.LogTraceIDWindowPadding,
 	), nil
 }

pkg/query-service/rules/setups_test.go

@@ -3,6 +3,7 @@ package rules
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
@@ -54,6 +55,7 @@ func prepareQuerierForMetrics(t *testing.T, telemetryStore telemetrystore.Teleme
 		nil, // traceOperatorStmtBuilder
 		nil, // bucketCache
 		flagger,
+		0,
 	), metadataStore
 }
 
@@ -107,6 +109,7 @@ func prepareQuerierForLogs(t *testing.T, telemetryStore telemetrystore.Telemetry
 		nil,            // traceOperatorStmtBuilder
 		nil,            // bucketCache
 		fl,
+		5*time.Minute, // logTraceIDWindowPadding
 	)
 }
 
@@ -154,5 +157,6 @@ func prepareQuerierForTraces(t *testing.T, telemetryStore telemetrystore.Telemet
 		nil,              // traceOperatorStmtBuilder
 		nil,              // bucketCache
 		fl,
+		0,
 	)
 }

pkg/sqlstore/sqlitesqlstore/formatter.go

@@ -1,6 +1,8 @@
 package sqlitesqlstore
 
 import (
+	"strings"
+
 	"github.com/SigNoz/signoz/pkg/sqlstore"
 	"github.com/uptrace/bun/schema"
 )
@@ -105,3 +107,7 @@ func (f *formatter) LowerExpression(expression string) []byte {
 	sql = append(sql, ')')
 	return sql
 }
+
+func (f *formatter) EscapeLikePattern(value string) string {
+	return strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(value)
+}

pkg/sqlstore/sqlstore.go

@@ -119,4 +119,8 @@ type SQLFormatter interface {
 
 	// LowerExpression wraps any SQL expression with lower() function for case-insensitive operations
 	LowerExpression(expression string) []byte
+
+	// EscapeLikePattern escapes LIKE wildcards (`%`, `_`, and the escape char `\`)
+	// in a value so it matches literally. Pair the pattern with `ESCAPE '\'`.
+	EscapeLikePattern(value string) string
 }

pkg/sqlstore/sqlstoretest/formatter.go

@@ -1,6 +1,8 @@
 package sqlstoretest
 
 import (
+	"strings"
+
 	"github.com/SigNoz/signoz/pkg/sqlstore"
 	"github.com/uptrace/bun/schema"
 )
@@ -105,3 +107,7 @@ func (f *formatter) LowerExpression(expression string) []byte {
 	sql = append(sql, ')')
 	return sql
 }
+
+func (f *formatter) EscapeLikePattern(value string) string {
+	return strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`).Replace(value)
+}

pkg/transition/migrate_common.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/SigNoz/signoz/pkg/telemetrytraces"
+	"github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 )
 
 type migrateCommon struct {
@@ -23,119 +24,10 @@ func NewMigrateCommon(logger *slog.Logger) *migrateCommon {
 	}
 }
 
+// WrapInV5Envelope delegates to querybuildertypesv5.WrapInV5Envelope; the
+// transform is stateless and shared with the v1→v2 dashboard conversion.
 func (migration *migrateCommon) WrapInV5Envelope(name string, queryMap map[string]any, queryType string) map[string]any {
-	// Create a properly structured v5 query
-	v5Query := map[string]any{
-		"name":     name,
-		"disabled": queryMap["disabled"],
-		"legend":   queryMap["legend"],
-	}
-
-	if name != queryMap["expression"] {
-		// formula
-		queryType = "builder_formula"
-		v5Query["expression"] = queryMap["expression"]
-		if functions, ok := queryMap["functions"]; ok {
-			v5Query["functions"] = functions
-		}
-		return map[string]any{
-			"type": queryType,
-			"spec": v5Query,
-		}
-	}
-
-	// Add signal based on data source
-	if dataSource, ok := queryMap["dataSource"].(string); ok {
-		switch dataSource {
-		case "traces":
-			v5Query["signal"] = "traces"
-		case "logs":
-			v5Query["signal"] = "logs"
-		case "metrics":
-			v5Query["signal"] = "metrics"
-		}
-	}
-
-	if stepInterval, ok := queryMap["stepInterval"]; ok {
-		v5Query["stepInterval"] = stepInterval
-	}
-
-	if aggregations, ok := queryMap["aggregations"]; ok {
-		v5Query["aggregations"] = aggregations
-	}
-
-	if filter, ok := queryMap["filter"]; ok {
-		v5Query["filter"] = filter
-	}
-
-	// Copy groupBy with proper structure
-	if groupBy, ok := queryMap["groupBy"].([]any); ok {
-		v5GroupBy := make([]any, len(groupBy))
-		for i, gb := range groupBy {
-			if gbMap, ok := gb.(map[string]any); ok {
-				v5GroupBy[i] = map[string]any{
-					"name":          gbMap["key"],
-					"fieldDataType": gbMap["dataType"],
-					"fieldContext":  gbMap["type"],
-				}
-			}
-		}
-		v5Query["groupBy"] = v5GroupBy
-	}
-
-	// Copy orderBy with proper structure
-	if orderBy, ok := queryMap["orderBy"].([]any); ok {
-		v5OrderBy := make([]any, len(orderBy))
-		for i, ob := range orderBy {
-			if obMap, ok := ob.(map[string]any); ok {
-				v5OrderBy[i] = map[string]any{
-					"key": map[string]any{
-						"name":          obMap["columnName"],
-						"fieldDataType": obMap["dataType"],
-						"fieldContext":  obMap["type"],
-					},
-					"direction": obMap["order"],
-				}
-			}
-		}
-		v5Query["order"] = v5OrderBy
-	}
-
-	// Copy selectColumns as selectFields
-	if selectColumns, ok := queryMap["selectColumns"].([]any); ok {
-		v5SelectFields := make([]any, len(selectColumns))
-		for i, col := range selectColumns {
-			if colMap, ok := col.(map[string]any); ok {
-				v5SelectFields[i] = map[string]any{
-					"name":          colMap["key"],
-					"fieldDataType": colMap["dataType"],
-					"fieldContext":  colMap["type"],
-				}
-			}
-		}
-		v5Query["selectFields"] = v5SelectFields
-	}
-
-	// Copy limit and offset
-	if limit, ok := queryMap["limit"]; ok {
-		v5Query["limit"] = limit
-	}
-	if offset, ok := queryMap["offset"]; ok {
-		v5Query["offset"] = offset
-	}
-
-	if having, ok := queryMap["having"]; ok {
-		v5Query["having"] = having
-	}
-
-	if functions, ok := queryMap["functions"]; ok {
-		v5Query["functions"] = functions
-	}
-
-	return map[string]any{
-		"type": queryType,
-		"spec": v5Query,
-	}
+	return querybuildertypesv5.WrapInV5Envelope(name, queryMap, queryType)
 }
 
 func (mc *migrateCommon) updateQueryData(ctx context.Context, queryData map[string]any, version, widgetType string) bool {

pkg/types/dashboardtypes/dashboard.go

@@ -7,7 +7,6 @@ import (
 	"time"
 
 	"github.com/SigNoz/signoz/pkg/errors"
-	"github.com/SigNoz/signoz/pkg/transition"
 	"github.com/SigNoz/signoz/pkg/types"
 	"github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -22,6 +21,7 @@ var (
 	ErrCodeDashboardInvalidSource      = errors.MustNewCode("dashboard_invalid_source")
 	ErrCodeDashboardImmutable          = errors.MustNewCode("dashboard_immutable")
 	ErrCodeDashboardInvalidPatch       = errors.MustNewCode("dashboard_invalid_patch")
+	ErrCodeDashboardMigrationFailed    = errors.MustNewCode("dashboard_migration_failed")
 )
 
 type StorableDashboard struct {
@@ -406,27 +406,26 @@ func (dashboard *Dashboard) GetWidgetQuery(startTime, endTime, widgetIndex uint6
 	widgetData := data.Widgets[widgetIndex]
 	switch widgetData.Query.QueryType {
 	case "builder":
-		migrate := transition.NewMigrateCommon(logger)
 		for _, query := range widgetData.Query.Builder.QueryData {
 			queryName, ok := query["queryName"].(string)
 			if !ok {
 				return nil, errors.New(errors.TypeInvalidInput, ErrCodeDashboardInvalidWidgetQuery, "cannot type cast query name as string")
 			}
-			compositeQueries = append(compositeQueries, migrate.WrapInV5Envelope(queryName, query, "builder_query"))
+			compositeQueries = append(compositeQueries, querybuildertypesv5.WrapInV5Envelope(queryName, query, "builder_query"))
 		}
 		for _, query := range widgetData.Query.Builder.QueryFormulas {
 			queryName, ok := query["queryName"].(string)
 			if !ok {
 				return nil, errors.New(errors.TypeInvalidInput, ErrCodeDashboardInvalidWidgetQuery, "cannot type cast query name as string")
 			}
-			compositeQueries = append(compositeQueries, migrate.WrapInV5Envelope(queryName, query, "builder_formula"))
+			compositeQueries = append(compositeQueries, querybuildertypesv5.WrapInV5Envelope(queryName, query, "builder_formula"))
 		}
 		for _, query := range widgetData.Query.Builder.QueryTraceOperator {
 			queryName, ok := query["queryName"].(string)
 			if !ok {
 				return nil, errors.New(errors.TypeInvalidInput, ErrCodeDashboardInvalidWidgetQuery, "cannot type cast query name as string")
 			}
-			compositeQueries = append(compositeQueries, migrate.WrapInV5Envelope(queryName, query, "builder_trace_operator"))
+			compositeQueries = append(compositeQueries, querybuildertypesv5.WrapInV5Envelope(queryName, query, "builder_trace_operator"))
 		}
 	case "clickhouse_sql":
 		for _, query := range widgetData.Query.ClickhouseSQL {

pkg/types/dashboardtypes/dashboards_metric_usage.go

@@ -0,0 +1,11 @@
+package dashboardtypes
+
+// DashboardPanelRef identifies a single panel within a dashboard. The
+// "dashboards by metric name" lookup returns these to report each panel that
+// references a given metric.
+type DashboardPanelRef struct {
+	DashboardID   string `json:"dashboardId" required:"true"`
+	DashboardName string `json:"dashboardName" required:"true"`
+	PanelID       string `json:"panelId" required:"true"`
+	PanelName     string `json:"panelName" required:"true"`
+}

pkg/types/dashboardtypes/perses_dashboard_convertors_test.go

@@ -38,7 +38,7 @@ func newTestDashboardV2(t *testing.T, orgID valuer.UUID, source Source) *Dashboa
 								FillMode:          FillModeSolid,
 								SpanGaps:          SpanGaps{FillLessThan: valuer.MustParseTextDuration("60s")},
 							},
-							Legend: Legend{Position: LegendPositionBottom},
+							Legend: Legend{Position: LegendPositionBottom, Mode: LegendModeList},
 						},
 					},
 					Queries: []Query{

pkg/types/dashboardtypes/perses_dashboard_data.go

@@ -48,7 +48,42 @@ func (d *DashboardSpec) UnmarshalJSON(data []byte) error {
 // ══════════════════════════════════════════════
 
 func (d *DashboardSpec) Validate() error {
+	if err := d.validateVariables(); err != nil {
+		return err
+	}
+	if err := d.validatePanels(); err != nil {
+		return err
+	}
+	return d.validateLayouts()
+}
+
+// validateVariables rejects two variables sharing the same name.
+func (d *DashboardSpec) validateVariables() error {
+	seen := make(map[string]struct{}, len(d.Variables))
+	for i, v := range d.Variables {
+		var name string
+		switch s := v.Spec.(type) {
+		case *ListVariableSpec:
+			name = s.Name
+		case *TextVariableSpec:
+			name = s.Name
+		default:
+			// Unreachable via UnmarshalJSON; reaching here means a Go caller broke the Kind/Spec pairing.
+			return errors.NewInternalf(errors.CodeInternal, "spec.variables[%d].spec: unexpected variable spec type %T", i, v.Spec)
+		}
+		if _, dup := seen[name]; dup {
+			return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "spec.variables[%d]: duplicate variable name %q", i, name)
+		}
+		seen[name] = struct{}{}
+	}
+	return nil
+}
+
+func (d *DashboardSpec) validatePanels() error {
 	for key, panel := range d.Panels {
+		if err := common.ValidateID(key); err != nil {
+			return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "spec.panels: %s", err.Error())
+		}
 		if panel == nil {
 			return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "spec.panels.%s: panel must not be null", key)
 		}
@@ -69,6 +104,13 @@ func (d *DashboardSpec) Validate() error {
 }
 
 func validateQueryAllowedForPanel(plugin QueryPlugin, allowed []QueryPluginKind, panelKind PanelPluginKind, path string) error {
+	compositeSubQueryTypeToPluginKind := map[qb.QueryType]QueryPluginKind{
+		qb.QueryTypeBuilder:       QueryKindBuilder,
+		qb.QueryTypeFormula:       QueryKindFormula,
+		qb.QueryTypeTraceOperator: QueryKindTraceOperator,
+		qb.QueryTypePromQL:        QueryKindPromQL,
+		qb.QueryTypeClickHouseSQL: QueryKindClickHouseSQL,
+	}
 	if !slices.Contains(allowed, plugin.Kind) {
 		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput,
 			"%s: query kind %q is not supported by panel kind %q", path, plugin.Kind, panelKind)
@@ -96,12 +138,35 @@ func validateQueryAllowedForPanel(plugin QueryPlugin, allowed []QueryPluginKind,
 	return nil
 }
 
-var (
-	compositeSubQueryTypeToPluginKind = map[qb.QueryType]QueryPluginKind{
-		qb.QueryTypeBuilder:       QueryKindBuilder,
-		qb.QueryTypeFormula:       QueryKindFormula,
-		qb.QueryTypeTraceOperator: QueryKindTraceOperator,
-		qb.QueryTypePromQL:        QueryKindPromQL,
-		qb.QueryTypeClickHouseSQL: QueryKindClickHouseSQL,
+// validateLayouts rejects grid items referencing a panel that doesn't exist.
+func (d *DashboardSpec) validateLayouts() error {
+	for li, layout := range d.Layouts {
+		grid, ok := layout.Spec.(*dashboard.GridLayoutSpec)
+		if !ok {
+			// Unreachable via UnmarshalJSON; reaching here means a Go caller broke the Kind/Spec pairing.
+			return errors.NewInternalf(errors.CodeInternal, "spec.layouts[%d].spec: unexpected layout spec type %T", li, layout.Spec)
+		}
+		for ii, item := range grid.Items {
+			path := fmt.Sprintf("spec.layouts[%d].spec.items[%d].content", li, ii)
+			if item.Content == nil {
+				return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "%s: content reference is required", path)
+			}
+			key, err := panelKeyFromRef(item.Content.Path, item.Content.Ref, path)
+			if err != nil {
+				return err
+			}
+			if _, ok := d.Panels[key]; !ok {
+				return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "%s: references unknown panel %q", path, key)
+			}
+		}
 	}
-)
+	return nil
+}
+
+// panelKeyFromRef extracts <key> from a "#/spec/panels/<key>" content ref.
+func panelKeyFromRef(refPath []string, ref string, path string) (string, error) {
+	if len(refPath) != 3 || refPath[0] != "spec" || refPath[1] != "panels" {
+		return "", errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "%s: %q must reference a panel as \"#/spec/panels/<key>\"", path, ref)
+	}
+	return refPath[2], nil
+}

pkg/types/dashboardtypes/perses_dashboard_patch.go

@@ -73,7 +73,7 @@ func (p PatchableDashboardV2) Apply(existing *DashboardV2) (*UpdatableDashboardV
 	}
 	patched, err := p.patch.ApplyWithOptions(raw, &jsonpatch.ApplyOptions{AllowMissingPathOnRemove: true, EnsurePathExistsOnAdd: true})
 	if err != nil {
-		return nil, errors.Wrap(err, errors.TypeInvalidInput, ErrCodeDashboardInvalidPatch, "JSON Patch could not be applied to the target dashboard")
+		return nil, errors.Wrap(err, errors.TypeInvalidInput, ErrCodeDashboardInvalidPatch, "JSON Patch could not be applied to the target dashboard").WithAdditional(err.Error())
 	}
 	out := &UpdatableDashboardV2{}
 	if err := json.Unmarshal(patched, out); err != nil {

pkg/types/dashboardtypes/perses_dashboard_patch_test.go

@@ -405,6 +405,7 @@ func TestPatchableDashboardV2_Apply(t *testing.T) {
 		out, err := decode(t, `[
 			{"op": "replace", "path": "/spec/display/name", "value": "Multi-step"},
 			{"op": "remove",  "path": "/spec/panels/p2"},
+			{"op": "remove",  "path": "/spec/layouts/0/spec/items/1"},
 			{"op": "add",     "path": "/tags/-", "value": {"key": "env", "value": "staging"}}
 		]`).Apply(base)
 		require.NoError(t, err)

pkg/types/dashboardtypes/perses_dashboard_test.go

@@ -112,6 +112,174 @@ func TestValidateOnlyVariables(t *testing.T) {
 	require.NoError(t, err, "expected valid")
 }
 
+func TestInvalidateDuplicateVariableNames(t *testing.T) {
+	data := []byte(`{
+		"variables": [
+			{
+				"kind": "TextVariable",
+				"spec": {"name": "env", "value": "prod"}
+			},
+			{
+				"kind": "ListVariable",
+				"spec": {
+					"name": "env",
+					"allowAllValue": false,
+					"allowMultiple": false,
+					"plugin": {
+						"kind": "signoz/DynamicVariable",
+						"spec": {"name": "service.name", "signal": "metrics"}
+					}
+				}
+			}
+		],
+		"layouts": []
+	}`)
+	_, err := unmarshalDashboard(data)
+	require.Error(t, err, "expected error for duplicate variable name")
+	require.Contains(t, err.Error(), `duplicate variable name "env"`)
+}
+
+func TestInvalidateVariableNameWithInvalidChars(t *testing.T) {
+	listVarWithName := func(name string) []byte {
+		return []byte(`{
+			"variables": [
+				{
+					"kind": "ListVariable",
+					"spec": {
+						"name": "` + name + `",
+						"allowAllValue": false,
+						"allowMultiple": false,
+						"plugin": {
+							"kind": "signoz/DynamicVariable",
+							"spec": {"name": "service.name", "signal": "metrics"}
+						}
+					}
+				}
+			],
+			"layouts": []
+		}`)
+	}
+	for _, name := range []string{"my var", "cost$", "bad!", "a/b"} {
+		t.Run(name, func(t *testing.T) {
+			_, err := unmarshalDashboard(listVarWithName(name))
+			require.Error(t, err, "expected error for invalid variable name %q", name)
+			require.Contains(t, err.Error(), "is not a correct name")
+		})
+	}
+	for _, name := range []string{"service", "my_var", "MY_VAR", "MixedCase9", "with-hyphen", "with.dot"} {
+		t.Run(name, func(t *testing.T) {
+			_, err := unmarshalDashboard(listVarWithName(name))
+			require.NoError(t, err, "expected valid variable name %q", name)
+		})
+	}
+	t.Run("digits only", func(t *testing.T) {
+		_, err := unmarshalDashboard(listVarWithName("123"))
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "cannot contain only digits")
+	})
+}
+
+func TestInvalidatePanelKey(t *testing.T) {
+	data := []byte(`{
+		"panels": {
+			"bad key!": {
+				"kind": "Panel",
+				"spec": {
+					"plugin": {"kind": "signoz/TablePanel", "spec": {}},
+					"queries": [{
+						"kind": "time_series",
+						"spec": {"plugin": {"kind": "signoz/BuilderQuery", "spec": {
+							"name": "A", "signal": "logs", "aggregations": [{"expression": "count()"}]
+						}}}
+					}]
+				}
+			}
+		},
+		"layouts": []
+	}`)
+	_, err := unmarshalDashboard(data)
+	require.Error(t, err, "expected error for invalid panel key")
+	require.Contains(t, err.Error(), "is not a correct name")
+}
+
+func TestInvalidateListVariableCrossFields(t *testing.T) {
+	listVar := func(specFields string) []byte {
+		return []byte(`{
+			"variables": [
+				{
+					"kind": "ListVariable",
+					"spec": {
+						"name": "service",
+						` + specFields + `
+						"plugin": {
+							"kind": "signoz/DynamicVariable",
+							"spec": {"name": "service.name", "signal": "metrics"}
+						}
+					}
+				}
+			],
+			"layouts": []
+		}`)
+	}
+
+	t.Run("customAllValue without allowAllValue", func(t *testing.T) {
+		_, err := unmarshalDashboard(listVar(`"allowAllValue": false, "allowMultiple": false, "customAllValue": "*",`))
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "customAllValue cannot be set")
+	})
+
+	t.Run("list defaultValue without allowMultiple", func(t *testing.T) {
+		_, err := unmarshalDashboard(listVar(`"allowAllValue": false, "allowMultiple": false, "defaultValue": ["a", "b"],`))
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "allowMultiple")
+	})
+
+	t.Run("single-element list default without allowMultiple", func(t *testing.T) {
+		_, err := unmarshalDashboard(listVar(`"allowAllValue": false, "allowMultiple": false, "defaultValue": ["only"],`))
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "allowMultiple")
+	})
+
+	t.Run("valid sort is accepted", func(t *testing.T) {
+		_, err := unmarshalDashboard(listVar(`"sort": "alphabetical-asc",`))
+		require.NoError(t, err)
+	})
+
+	t.Run("unknown sort is rejected", func(t *testing.T) {
+		_, err := unmarshalDashboard(listVar(`"sort": "bogus",`))
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "unknown sort")
+	})
+}
+
+func TestInvalidateEmptyVariableName(t *testing.T) {
+	cases := map[string][]byte{
+		"text variable": []byte(`{
+			"variables": [{"kind": "TextVariable", "spec": {"name": "", "value": "x"}}],
+			"layouts": []
+		}`),
+		"list variable": []byte(`{
+			"variables": [{
+				"kind": "ListVariable",
+				"spec": {
+					"name": "",
+					"allowAllValue": false,
+					"allowMultiple": false,
+					"plugin": {"kind": "signoz/DynamicVariable", "spec": {"name": "service.name", "signal": "metrics"}}
+				}
+			}],
+			"layouts": []
+		}`),
+	}
+	for name, data := range cases {
+		t.Run(name, func(t *testing.T) {
+			_, err := unmarshalDashboard(data)
+			require.Error(t, err, "expected error for empty variable name")
+			require.Contains(t, err.Error(), "name cannot be empty")
+		})
+	}
+}
+
 func TestInvalidateUnknownPluginKind(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -270,6 +438,65 @@ func TestInvalidateOneInvalidPanel(t *testing.T) {
 	require.Contains(t, err.Error(), "FakePanel", "error should mention FakePanel")
 }
 
+func TestInvalidateLayoutPanelReferences(t *testing.T) {
+	validPanels := `"panels": {
+		"p1": {
+			"kind": "Panel",
+			"spec": {
+				"plugin": {"kind": "signoz/TablePanel", "spec": {}},
+				"queries": [{
+					"kind": "time_series",
+					"spec": {"plugin": {"kind": "signoz/BuilderQuery", "spec": {
+						"name": "A", "signal": "logs", "aggregations": [{"expression": "count()"}]
+					}}}
+				}]
+			}
+		}
+	}`
+	layout := func(items string) []byte {
+		return []byte(`{` + validPanels + `, "layouts": [{"kind": "Grid", "spec": {"items": [` + items + `]}}]}`)
+	}
+
+	tests := []struct {
+		name        string
+		data        []byte
+		wantContain string
+	}{
+		{
+			name:        "reference to unknown panel",
+			data:        layout(`{"x": 0, "y": 0, "width": 6, "height": 6, "content": {"$ref": "#/spec/panels/ghost"}}`),
+			wantContain: `references unknown panel "ghost"`,
+		},
+		{
+			name:        "reference not pointing at a panel",
+			data:        layout(`{"x": 0, "y": 0, "width": 6, "height": 6, "content": {"$ref": "#/spec/variables/p1"}}`),
+			wantContain: "must reference a panel",
+		},
+		{
+			name:        "reference missing spec prefix",
+			data:        layout(`{"x": 0, "y": 0, "width": 6, "height": 6, "content": {"$ref": "#/panels/p1"}}`),
+			wantContain: "must reference a panel",
+		},
+		{
+			name:        "valid reference",
+			data:        layout(`{"x": 0, "y": 0, "width": 6, "height": 6, "content": {"$ref": "#/spec/panels/p1"}}`),
+			wantContain: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := unmarshalDashboard(tt.data)
+			if tt.wantContain == "" {
+				require.NoError(t, err)
+				return
+			}
+			require.Error(t, err)
+			require.Contains(t, err.Error(), tt.wantContain)
+		})
+	}
+}
+
 func TestRejectUnknownFieldsInPluginSpec(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -569,6 +796,24 @@ func TestInvalidateBadPanelSpecValues(t *testing.T) {
 			}`,
 			wantContain: "legend position",
 		},
+		{
+			name: "bad legend mode",
+			data: `{
+				"panels": {
+					"p1": {
+						"kind": "Panel",
+						"spec": {
+							"plugin": {
+								"kind": "signoz/BarChartPanel",
+								"spec": {"legend": {"mode": "grid"}}
+							}
+						}
+					}
+				},
+				"layouts": []
+			}`,
+			wantContain: "legend mode",
+		},
 		{
 			name: "bad threshold format",
 			data: `{
@@ -634,6 +879,39 @@ func TestInvalidateBadPanelSpecValues(t *testing.T) {
 	}
 }
 
+// Label on ThresholdWithLabel is optional — the backend never reads it, so a
+// threshold with an omitted or empty label must validate cleanly.
+func TestThresholdLabelOptional(t *testing.T) {
+	for _, tt := range []struct {
+		name      string
+		threshold string
+	}{
+		{name: "label omitted", threshold: `{"value": 100, "color": "Red"}`},
+		{name: "label empty", threshold: `{"value": 100, "color": "Red", "label": ""}`},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			data := []byte(`{
+				"panels": {
+					"p1": {
+						"kind": "Panel",
+						"spec": {
+							"plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {"thresholds": [` + tt.threshold + `]}},
+							"queries": [{"kind": "time_series", "spec": {"plugin": {"kind": "signoz/PromQLQuery", "spec": {"name": "A", "query": "up"}}}}]
+						}
+					}
+				},
+				"layouts": []
+			}`)
+			d, err := unmarshalDashboard(data)
+			require.NoError(t, err, "threshold without a label should validate")
+
+			spec := d.Panels["p1"].Spec.Plugin.Spec.(*TimeSeriesPanelSpec)
+			require.Len(t, spec.Thresholds, 1)
+			require.Empty(t, spec.Thresholds[0].Label, "label should remain empty")
+		})
+	}
+}
+
 func TestInvalidatePanelWithoutQueries(t *testing.T) {
 	data := []byte(`{
 		"panels": {
@@ -749,11 +1027,6 @@ func TestValidateRequiredFields(t *testing.T) {
 			data:        wrapPanel("signoz/TimeSeriesPanel", `{"thresholds": [{"value": 100, "label": "high", "color": ""}]}`),
 			wantContain: "Color",
 		},
-		{
-			name:        "ThresholdWithLabel missing label",
-			data:        wrapPanel("signoz/TimeSeriesPanel", `{"thresholds": [{"value": 100, "color": "Red", "label": ""}]}`),
-			wantContain: "Label",
-		},
 		{
 			name:        "ComparisonThreshold missing value",
 			data:        wrapPanel("signoz/NumberPanel", `{"thresholds": [{"operator": "above", "format": "text", "color": "Red"}]}`),
@@ -785,6 +1058,34 @@ func TestValidateRequiredFields(t *testing.T) {
 	}
 }
 
+// TestThresholdZeroValueAcceptedMissingRejected documents the *float64 Value:
+// a threshold at 0 (or 0.0) is valid, because the pointer lets validate:"required"
+// tell a present zero (non-nil) from an absent value (nil) — while a genuinely
+// missing value is still rejected.
+func TestThresholdZeroValueAcceptedMissingRejected(t *testing.T) {
+	numberPanel := func(thresholdSpec string) string {
+		return `{
+			"panels": {"p1": {"kind": "Panel", "spec": {
+				"plugin": {"kind": "signoz/NumberPanel", "spec": {"thresholds": [` + thresholdSpec + `]}},
+				"queries": [{"kind": "time_series", "spec": {"plugin": {"kind": "signoz/PromQLQuery", "spec": {"name": "A", "query": "up"}}}}]
+			}}},
+			"layouts": []
+		}`
+	}
+
+	_, errZero := unmarshalDashboard([]byte(numberPanel(`{"value": 0, "operator": "above", "format": "text", "color": "Red"}`)))
+	require.NoError(t, errZero, `a threshold "value": 0 is valid`)
+
+	// "value": 0.0 is the same float64 zero as "value": 0 — JSON has one number
+	// type — and is accepted identically.
+	_, errZeroFloat := unmarshalDashboard([]byte(numberPanel(`{"value": 0.0, "operator": "above", "format": "text", "color": "Red"}`)))
+	require.NoError(t, errZeroFloat, `"value": 0.0 is the same valid zero`)
+
+	_, errMissing := unmarshalDashboard([]byte(numberPanel(`{"operator": "above", "format": "text", "color": "Red"}`)))
+	require.Error(t, errMissing, "a genuinely missing value is still rejected")
+	require.Contains(t, errMissing.Error(), "Value")
+}
+
 func TestTimeSeriesPanelDefaults(t *testing.T) {
 	data := []byte(`{
 		"panels": {
@@ -811,10 +1112,11 @@ func TestTimeSeriesPanelDefaults(t *testing.T) {
 	require.Equal(t, "2", spec.Formatting.DecimalPrecision.ValueOrDefault(), "expected DecimalPrecision default 2")
 	require.Equal(t, "spline", spec.ChartAppearance.LineInterpolation.ValueOrDefault(), "expected LineInterpolation default spline")
 	require.Equal(t, "solid", spec.ChartAppearance.LineStyle.ValueOrDefault(), "expected LineStyle default solid")
-	require.Equal(t, "solid", spec.ChartAppearance.FillMode.ValueOrDefault(), "expected FillMode default solid")
+	require.Equal(t, "none", spec.ChartAppearance.FillMode.ValueOrDefault(), "expected FillMode default none")
 	require.False(t, spec.ChartAppearance.SpanGaps.FillOnlyBelow, "expected SpanGaps.FillOnlyBelow default false")
 	require.Equal(t, "global_time", spec.Visualization.TimePreference.ValueOrDefault(), "expected TimePreference default global_time")
 	require.Equal(t, "bottom", spec.Legend.Position.ValueOrDefault(), "expected LegendPosition default bottom")
+	require.Equal(t, "list", spec.Legend.Mode.ValueOrDefault(), "expected LegendMode default list")
 
 	// Re-marshal the full dashboard (what we'd store in DB / return in API response)
 	// and verify the output contains the default values.
@@ -825,9 +1127,10 @@ func TestTimeSeriesPanelDefaults(t *testing.T) {
 		"decimalPrecision":  `"2"`,
 		"lineInterpolation": `"spline"`,
 		"lineStyle":         `"solid"`,
-		"fillMode":          `"solid"`,
+		"fillMode":          `"none"`,
 		"timePreference":    `"global_time"`,
 		"position":          `"bottom"`,
+		"mode":              `"list"`,
 	} {
 		assert.Contains(t, outputStr, `"`+field+`":`+want, "expected stored/response JSON to contain %s:%s", field, want)
 	}
@@ -930,7 +1233,7 @@ func TestStorageRoundTrip(t *testing.T) {
 	assert.Equal(t, "2", tsSpec.Formatting.DecimalPrecision.ValueOrDefault())
 	assert.Equal(t, "spline", tsSpec.ChartAppearance.LineInterpolation.ValueOrDefault())
 	assert.Equal(t, "solid", tsSpec.ChartAppearance.LineStyle.ValueOrDefault())
-	assert.Equal(t, "solid", tsSpec.ChartAppearance.FillMode.ValueOrDefault())
+	assert.Equal(t, "none", tsSpec.ChartAppearance.FillMode.ValueOrDefault())
 	assert.Equal(t, "global_time", tsSpec.Visualization.TimePreference.ValueOrDefault())
 	assert.Equal(t, "bottom", tsSpec.Legend.Position.ValueOrDefault())
 	numSpec := d.Panels["p2"].Spec.Plugin.Spec.(*NumberPanelSpec)
@@ -950,7 +1253,7 @@ func TestStorageRoundTrip(t *testing.T) {
 	assert.Equal(t, "2", tsLoaded.Formatting.DecimalPrecision.ValueOrDefault(), "after load")
 	assert.Equal(t, "spline", tsLoaded.ChartAppearance.LineInterpolation.ValueOrDefault(), "after load")
 	assert.Equal(t, "solid", tsLoaded.ChartAppearance.LineStyle.ValueOrDefault(), "after load")
-	assert.Equal(t, "solid", tsLoaded.ChartAppearance.FillMode.ValueOrDefault(), "after load")
+	assert.Equal(t, "none", tsLoaded.ChartAppearance.FillMode.ValueOrDefault(), "after load")
 	assert.Equal(t, "global_time", tsLoaded.Visualization.TimePreference.ValueOrDefault(), "after load")
 	assert.Equal(t, "bottom", tsLoaded.Legend.Position.ValueOrDefault(), "after load")
 	numLoaded := loaded.Panels["p2"].Spec.Plugin.Spec.(*NumberPanelSpec)
@@ -966,7 +1269,7 @@ func TestStorageRoundTrip(t *testing.T) {
 		"decimalPrecision":  `"2"`,
 		"lineInterpolation": `"spline"`,
 		"lineStyle":         `"solid"`,
-		"fillMode":          `"solid"`,
+		"fillMode":          `"none"`,
 		"timePreference":    `"global_time"`,
 		"position":          `"bottom"`,
 		"format":            `"text"`,

pkg/types/dashboardtypes/perses_drift_test.go

@@ -30,6 +30,7 @@ func TestDashboardSpecMatchesPerses(t *testing.T) {
 		{"DatasourceSpec", typeOf[DatasourceSpec](), typeOf[datasource.Spec]()},
 		{"Variable", typeOf[Variable](), typeOf[dashboard.Variable]()},
 		{"ListVariableSpec", typeOf[ListVariableSpec](), typeOf[dashboard.ListVariableSpec]()},
+		{"TextVariableSpec", typeOf[TextVariableSpec](), typeOf[dashboard.TextVariableSpec]()},
 		{"Layout", typeOf[Layout](), typeOf[dashboard.Layout]()},
 	}
 

pkg/types/dashboardtypes/perses_plugin_wrappers.go

@@ -51,7 +51,7 @@ func (p *PanelPlugin) UnmarshalJSON(data []byte) error {
 		return err
 	}
 	p.Kind = PanelPluginKind(kind)
-	p.Spec = spec
+	p.Spec = *spec
 	return nil
 }
 
@@ -110,7 +110,7 @@ func (p *QueryPlugin) UnmarshalJSON(data []byte) error {
 		return err
 	}
 	p.Kind = QueryPluginKind(kind)
-	p.Spec = spec
+	p.Spec = *spec
 	return nil
 }
 
@@ -165,7 +165,7 @@ func (p *VariablePlugin) UnmarshalJSON(data []byte) error {
 		return err
 	}
 	p.Kind = VariablePluginKind(kind)
-	p.Spec = spec
+	p.Spec = *spec
 	return nil
 }
 
@@ -197,7 +197,7 @@ type DatasourcePlugin struct {
 
 func (DatasourcePlugin) PrepareJSONSchema(s *jsonschema.Schema) error {
 	return markDiscriminator(s, "kind", map[string]string{
-		string(DatasourceKindSigNoz): schemaRef("DashboardtypesDatasourcePluginVariantStruct"),
+		string(DatasourceKindSigNoz): schemaRef("DashboardtypesDatasourcePluginVariantGithubComSigNozSignozPkgTypesDashboardtypesSigNozDatasourceSpec"),
 	})
 }
 
@@ -215,13 +215,13 @@ func (p *DatasourcePlugin) UnmarshalJSON(data []byte) error {
 		return err
 	}
 	p.Kind = DatasourcePluginKind(kind)
-	p.Spec = spec
+	p.Spec = *spec
 	return nil
 }
 
 func (DatasourcePlugin) JSONSchemaOneOf() []any {
 	return []any{
-		DatasourcePluginVariant[struct{}]{Kind: string(DatasourceKindSigNoz)},
+		DatasourcePluginVariant[SigNozDatasourceSpec]{Kind: string(DatasourceKindSigNoz)},
 	}
 }
 
@@ -262,7 +262,7 @@ var (
 		VariableKindCustom:  func() any { return new(CustomVariableSpec) },
 	}
 	datasourcePluginSpecs = map[DatasourcePluginKind]func() any{
-		DatasourceKindSigNoz: func() any { return new(struct{}) },
+		DatasourceKindSigNoz: func() any { return new(SigNozDatasourceSpec) },
 	}
 
 	allowedQueryKinds = map[PanelPluginKind][]QueryPluginKind{
@@ -297,8 +297,7 @@ func extractKindAndSpec(data []byte) (string, []byte, error) {
 	return head.Kind, head.Spec, nil
 }
 
-// decodeSpec strict-decodes a spec JSON into target and runs struct-tag validation (go-playground/validator).
-func decodeSpec(specJSON []byte, target any, kind string) (any, error) {
+func decodeSpec[T any](specJSON []byte, target T, kind string) (*T, error) {
 	if len(specJSON) == 0 {
 		return nil, errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "kind %q: spec is required", kind)
 	}
@@ -310,7 +309,12 @@ func decodeSpec(specJSON []byte, target any, kind string) (any, error) {
 	if err := validator.New().Struct(target); err != nil {
 		return nil, errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "kind %q: spec failed validation", kind)
 	}
-	return target, nil
+	if v, ok := any(target).(interface{ validate() error }); ok {
+		if err := v.validate(); err != nil {
+			return nil, errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "kind %q: %s", kind, err.Error())
+		}
+	}
+	return &target, nil
 }
 
 // signozDiscriminatorKey is the extension key that signoz.attachDiscriminators

pkg/types/dashboardtypes/perses_replicas.go

@@ -4,9 +4,11 @@ import (
 	"encoding/json"
 	"maps"
 	"slices"
+	"strconv"
 
 	"github.com/SigNoz/signoz/pkg/errors"
 	qb "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/valuer"
 	"github.com/perses/spec/go/common"
 	"github.com/perses/spec/go/dashboard"
 	"github.com/perses/spec/go/dashboard/variable"
@@ -61,7 +63,7 @@ func (k *PanelKind) UnmarshalJSON(data []byte) error {
 type PanelSpec struct {
 	Display Display          `json:"display" required:"true"`
 	Plugin  PanelPlugin      `json:"plugin" required:"true"`
-	Queries []Query          `json:"queries" required:"true"`
+	Queries []Query          `json:"queries" required:"true" nullable:"false"`
 	Links   []dashboard.Link `json:"links,omitempty"`
 }
 
@@ -84,7 +86,7 @@ type QuerySpec struct {
 // ══════════════════════════════════════════════
 
 // Variable is the list/text sum type. Spec is set to *ListVariableSpec or
-// *dashboard.TextVariableSpec by UnmarshalJSON based on Kind. The schema is a
+// *TextVariableSpec by UnmarshalJSON based on Kind. The schema is a
 // discriminated oneOf (see JSONSchemaOneOf).
 type Variable struct {
 	Kind variable.Kind `json:"kind" required:"true"`
@@ -94,7 +96,7 @@ type Variable struct {
 func (Variable) PrepareJSONSchema(s *jsonschema.Schema) error {
 	return markDiscriminator(s, "kind", map[string]string{
 		string(variable.KindList): schemaRef("DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesListVariableSpec"),
-		string(variable.KindText): schemaRef("DashboardtypesVariableEnvelopeGithubComPersesSpecGoDashboardTextVariableSpec"),
+		string(variable.KindText): schemaRef("DashboardtypesVariableEnvelopeGithubComSigNozSignozPkgTypesDashboardtypesTextVariableSpec"),
 	})
 }
 
@@ -110,14 +112,14 @@ func (v *Variable) UnmarshalJSON(data []byte) error {
 			return err
 		}
 		v.Kind = variable.KindList
-		v.Spec = spec
+		v.Spec = *spec
 	case string(variable.KindText):
-		spec, err := decodeSpec(specJSON, new(dashboard.TextVariableSpec), kind)
+		spec, err := decodeSpec(specJSON, new(TextVariableSpec), kind)
 		if err != nil {
 			return err
 		}
 		v.Kind = variable.KindText
-		v.Spec = spec
+		v.Spec = *spec
 	default:
 		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "unknown variable kind %q; allowed values: %s", kind, allowedValuesForKind([]variable.Kind{variable.KindList, variable.KindText}))
 	}
@@ -127,7 +129,7 @@ func (v *Variable) UnmarshalJSON(data []byte) error {
 func (Variable) JSONSchemaOneOf() []any {
 	return []any{
 		VariableEnvelope[ListVariableSpec]{Kind: string(variable.KindList)},
-		VariableEnvelope[dashboard.TextVariableSpec]{Kind: string(variable.KindText)},
+		VariableEnvelope[TextVariableSpec]{Kind: string(variable.KindText)},
 	}
 }
 
@@ -143,15 +145,137 @@ func (v VariableEnvelope[S]) PrepareJSONSchema(s *jsonschema.Schema) error {
 // ListVariableSpec mirrors dashboard.ListVariableSpec (variable.ListSpec
 // fields + Name) but with a typed VariablePlugin replacing common.Plugin.
 type ListVariableSpec struct {
-	Display         Display                `json:"display" required:"true"`
-	DefaultValue    *variable.DefaultValue `json:"defaultValue,omitempty"`
-	AllowAllValue   bool                   `json:"allowAllValue"`
-	AllowMultiple   bool                   `json:"allowMultiple"`
-	CustomAllValue  string                 `json:"customAllValue,omitempty"`
-	CapturingRegexp string                 `json:"capturingRegexp,omitempty"`
-	Sort            *variable.Sort         `json:"sort,omitempty"`
-	Plugin          VariablePlugin         `json:"plugin"`
-	Name            string                 `json:"name"`
+	Display         Display               `json:"display" required:"true"`
+	DefaultValue    *VariableDefaultValue `json:"defaultValue,omitempty"`
+	AllowAllValue   bool                  `json:"allowAllValue"`
+	AllowMultiple   bool                  `json:"allowMultiple"`
+	CustomAllValue  string                `json:"customAllValue,omitempty"`
+	CapturingRegexp string                `json:"capturingRegexp,omitempty"`
+	Sort            ListVariableSpecSort  `json:"sort,omitzero"`
+	Plugin          VariablePlugin        `json:"plugin"`
+	Name            string                `json:"name" required:"true" minLength:"1"`
+}
+
+// VariableDefaultValue is a list variable's defaultValue: the string | []string
+// union. It subclasses the perses variable.DefaultValue (which marshals as a
+// scalar-or-array) so SigNoz can attach the oneOf schema to it as a named
+// component.
+//
+// Emitting it as a named oneOf component (and having defaultValue $ref it),
+// instead of inlining the union onto the property, gives downstream codegen a
+// hook to canonicalize: oapi-codegen generates the union's Marshal/UnmarshalJSON
+// and skaff's scalar-union pre-pass flattens it to a string attribute. An inline
+// oneOf has no such named component to hook.
+type VariableDefaultValue struct {
+	variable.DefaultValue
+}
+
+// PrepareJSONSchema shapes the component as the string | []string oneOf; the
+// reflected struct shape (a bare object) is wrong because the value marshals as
+// a scalar-or-array, not an object.
+func (VariableDefaultValue) PrepareJSONSchema(s *jsonschema.Schema) error {
+	stringItem := jsonschema.String.ToSchemaOrBool()
+	s.Type = nil
+	s.Properties = nil
+	s.WithOneOf(
+		jsonschema.String.ToSchemaOrBool(),
+		(&jsonschema.Schema{}).
+			WithType(jsonschema.Array.Type()).
+			WithItems(jsonschema.Items{SchemaOrBool: &stringItem}).
+			ToSchemaOrBool(),
+	)
+	return nil
+}
+
+// validate mirrors perses ListVariableSpec validation (plus the digits-only name
+// check perses only applies to text variables); run by decodeSpec on unmarshal.
+func (s *ListVariableSpec) validate() error {
+	if err := common.ValidateID(s.Name); err != nil {
+		return err
+	}
+	if _, err := strconv.Atoi(s.Name); err == nil {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "variable name cannot contain only digits")
+	}
+	if s.CustomAllValue != "" && !s.AllowAllValue {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "customAllValue cannot be set if allowAllValue is not set to true")
+	}
+	if s.DefaultValue != nil && len(s.DefaultValue.SliceValues) > 0 && !s.AllowMultiple {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "defaultValue cannot be a list if allowMultiple is not set to true")
+	}
+	return nil
+}
+
+// ListVariableSpecSort is the value-list sort method, mirrored from Perses as a
+// stable enum so the allowed values surface in the generated OpenAPI schema.
+type ListVariableSpecSort struct{ valuer.String }
+
+var (
+	SortNone                            = ListVariableSpecSort{valuer.NewString("none")}
+	SortAlphabeticalAsc                 = ListVariableSpecSort{valuer.NewString("alphabetical-asc")}
+	SortAlphabeticalDesc                = ListVariableSpecSort{valuer.NewString("alphabetical-desc")}
+	SortNumericalAsc                    = ListVariableSpecSort{valuer.NewString("numerical-asc")}
+	SortNumericalDesc                   = ListVariableSpecSort{valuer.NewString("numerical-desc")}
+	SortAlphabeticalCaseInsensitiveAsc  = ListVariableSpecSort{valuer.NewString("alphabetical-ci-asc")}
+	SortAlphabeticalCaseInsensitiveDesc = ListVariableSpecSort{valuer.NewString("alphabetical-ci-desc")}
+)
+
+func (ListVariableSpecSort) Enum() []any {
+	return []any{
+		SortNone,
+		SortAlphabeticalAsc,
+		SortAlphabeticalDesc,
+		SortNumericalAsc,
+		SortNumericalDesc,
+		SortAlphabeticalCaseInsensitiveAsc,
+		SortAlphabeticalCaseInsensitiveDesc,
+	}
+}
+
+func (s ListVariableSpecSort) IsValid() bool {
+	return slices.ContainsFunc(s.Enum(), func(v any) bool { return v == s })
+}
+
+// UnmarshalJSON validates against the enum on decode (valuer.String alone
+// accepts any string). An empty value is allowed and means "no sort", matching
+// Perses.
+func (s *ListVariableSpecSort) UnmarshalJSON(data []byte) error {
+	var v string
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid sort: must be a string, one of `none`, `alphabetical-asc`, `alphabetical-desc`, `numerical-asc`, `numerical-desc`, `alphabetical-ci-asc`, or `alphabetical-ci-desc`")
+	}
+	if v == "" {
+		*s = ListVariableSpecSort{}
+		return nil
+	}
+	sort := ListVariableSpecSort{valuer.NewString(v)}
+	if !sort.IsValid() {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "unknown sort %q: must be `none`, `alphabetical-asc`, `alphabetical-desc`, `numerical-asc`, `numerical-desc`, `alphabetical-ci-asc`, or `alphabetical-ci-desc`", v)
+	}
+	*s = sort
+	return nil
+}
+
+// TextVariableSpec replicates dashboard.TextVariableSpec so name can carry the
+// required/non-empty schema tags perses leaves off.
+type TextVariableSpec struct {
+	Display  Display `json:"display" required:"true"`
+	Value    string  `json:"value" required:"true"`
+	Constant bool    `json:"constant,omitempty"`
+	Name     string  `json:"name" required:"true" minLength:"1"`
+}
+
+// validate mirrors perses TextVariableSpec validation; run by decodeSpec on unmarshal.
+func (s *TextVariableSpec) validate() error {
+	if err := common.ValidateID(s.Name); err != nil {
+		return err
+	}
+	if _, err := strconv.Atoi(s.Name); err == nil {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "variable name cannot contain only digits")
+	}
+	if s.Value == "" && s.Constant {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "value for a constant text variable cannot be empty")
+	}
+	return nil
 }
 
 // ══════════════════════════════════════════════
@@ -194,7 +318,7 @@ func (l *Layout) UnmarshalJSON(data []byte) error {
 		return err
 	}
 	l.Kind = dashboard.LayoutKind(kind)
-	l.Spec = spec
+	l.Spec = *spec
 	return nil
 }
 

pkg/types/dashboardtypes/perses_signoz_plugins.go

@@ -146,6 +146,11 @@ func (DatasourcePluginKind) Enum() []any {
 	return []any{DatasourceKindSigNoz}
 }
 
+// SigNozDatasourceSpec is the (empty) signoz/Datasource plugin spec. Naming the
+// type gives the variant a concrete, non-nullable spec schema instead of an
+// inline free-form one.
+type SigNozDatasourceSpec struct{}
+
 type TimeSeriesPanelSpec struct {
 	Visualization   TimeSeriesVisualization   `json:"visualization"`
 	Formatting      PanelFormatting           `json:"formatting"`
@@ -241,18 +246,25 @@ type TableFormatting struct {
 
 type Legend struct {
 	Position     LegendPosition    `json:"position"`
+	Mode         LegendMode        `json:"mode"`
 	CustomColors map[string]string `json:"customColors"`
 }
 
 type ThresholdWithLabel struct {
-	Value float64 `json:"value" validate:"required" required:"true"`
-	Unit  string  `json:"unit"`
-	Color string  `json:"color" validate:"required" required:"true"`
-	Label string  `json:"label" validate:"required" required:"true"`
+	// Value is a pointer so a threshold at 0 is valid: validate:"required" treats
+	// the float64 zero as "missing", but a non-nil *float64 to 0 passes (and nil
+	// still fails, so a genuinely absent value is still rejected). nullable:"false"
+	// keeps it a plain required number in the schema — it is never null in valid
+	// data (validation rejects nil), so the pointer must not leak as `number|null`.
+	Value *float64 `json:"value" validate:"required" required:"true" nullable:"false"`
+	Unit  string   `json:"unit"`
+	Color string   `json:"color" validate:"required" required:"true"`
+	Label string   `json:"label"`
 }
 
 type ComparisonThreshold struct {
-	Value    float64            `json:"value" validate:"required" required:"true"`
+	// Value is a pointer so a threshold at 0 is valid (see ThresholdWithLabel.Value).
+	Value    *float64           `json:"value" validate:"required" required:"true" nullable:"false"`
 	Operator ComparisonOperator `json:"operator"`
 	Unit     string             `json:"unit"`
 	Color    string             `json:"color" validate:"required" required:"true"`
@@ -358,6 +370,47 @@ func (l *LegendPosition) UnmarshalJSON(data []byte) error {
 	}
 }
 
+type LegendMode struct{ valuer.String }
+
+var (
+	LegendModeList  = LegendMode{valuer.NewString("list")} // default
+	LegendModeTable = LegendMode{valuer.NewString("table")}
+)
+
+func (LegendMode) Enum() []any {
+	return []any{LegendModeList} // others are not supported in UI yet
+}
+
+func (m LegendMode) ValueOrDefault() string {
+	if m.IsZero() {
+		return LegendModeList.StringValue()
+	}
+	return m.StringValue()
+}
+
+func (m LegendMode) MarshalJSON() ([]byte, error) {
+	return json.Marshal(m.ValueOrDefault())
+}
+
+func (m *LegendMode) UnmarshalJSON(data []byte) error {
+	var v string
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid legend mode: must be a string, one of `list` or `table`")
+	}
+	if v == "" {
+		*m = LegendModeList
+		return nil
+	}
+	lm := LegendMode{valuer.NewString(v)}
+	switch lm {
+	case LegendModeList, LegendModeTable:
+		*m = lm
+		return nil
+	default:
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid legend mode %q: must be `list` or `table`", v)
+	}
+}
+
 type ThresholdFormat struct{ valuer.String }
 
 var (
@@ -534,9 +587,9 @@ func (ls *LineStyle) UnmarshalJSON(data []byte) error {
 type FillMode struct{ valuer.String }
 
 var (
-	FillModeSolid    = FillMode{valuer.NewString("solid")} // default
+	FillModeSolid    = FillMode{valuer.NewString("solid")}
 	FillModeGradient = FillMode{valuer.NewString("gradient")}
-	FillModeNone     = FillMode{valuer.NewString("none")}
+	FillModeNone     = FillMode{valuer.NewString("none")} // default
 )
 
 func (FillMode) Enum() []any {
@@ -545,7 +598,7 @@ func (FillMode) Enum() []any {
 
 func (fm FillMode) ValueOrDefault() string {
 	if fm.IsZero() {
-		return FillModeSolid.StringValue()
+		return FillModeNone.StringValue()
 	}
 	return fm.StringValue()
 }
@@ -560,7 +613,7 @@ func (fm *FillMode) UnmarshalJSON(data []byte) error {
 		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid fill mode: must be a string, one of `solid`, `gradient`, or `none`")
 	}
 	if v == "" {
-		*fm = FillModeSolid
+		*fm = FillModeNone
 		return nil
 	}
 	val := FillMode{valuer.NewString(v)}
@@ -573,12 +626,9 @@ func (fm *FillMode) UnmarshalJSON(data []byte) error {
 	}
 }
 
-// SpanGaps controls whether lines connect across null values.
-// When FillOnlyBelow is false (default), all gaps are connected.
-// When FillOnlyBelow is true, only gaps smaller than FillLessThan are connected.
 type SpanGaps struct {
-	FillOnlyBelow bool                `json:"fillOnlyBelow"`
-	FillLessThan  valuer.TextDuration `json:"fillLessThan"`
+	FillOnlyBelow bool                `json:"fillOnlyBelow" description:"Controls whether lines connect across null values. When false (default), all gaps are connected. When true, only gaps smaller than fillLessThan are connected."`
+	FillLessThan  valuer.TextDuration `json:"fillLessThan" description:"The maximum gap size to connect when fillOnlyBelow is true. Gaps larger than this duration are left disconnected."`
 }
 
 type PrecisionOption struct{ valuer.String }

pkg/types/dashboardtypes/perses_v1_to_v2.go

@@ -0,0 +1,82 @@
+package dashboardtypes
+
+import (
+	"github.com/SigNoz/signoz/pkg/errors"
+)
+
+// V1 → V2 migration. The v1 storable shape is the frontend's `DashboardData`
+// (see frontend/src/types/api/dashboard/getAll.ts); v2 is DashboardV2 /
+// DashboardSpec.
+//
+// Assumes the v1 widget query data has already been migrated to v5 shape
+// (transition.dashboardMigrateV5). Pre-v5 builder queries will produce
+// invalid v2 envelopes — run the v4→v5 migration first.
+//
+// The conversion is split across sibling files by concern:
+//   - perses_v1_to_v2_tags.go      tags
+//   - perses_v1_to_v2_panels.go    widgets → panels (+ panel field mappers)
+//   - perses_v1_to_v2_queries.go   widget queries
+//   - perses_v1_to_v2_layouts.go   grid layouts and sections
+//   - perses_v1_to_v2_variables.go variables
+//   - perses_v1_to_v2_decoder.go   v1Decoder: typed field reads + malformed-field detection
+
+// ══════════════════════════════════════════════
+// Entry point
+// ══════════════════════════════════════════════
+
+func (storable StorableDashboard) IsV2() bool {
+	metadata, _ := storable.Data["metadata"].(map[string]any)
+	if metadata == nil {
+		return false
+	}
+	version, _ := metadata["schemaVersion"].(string)
+	return version == SchemaVersion
+}
+
+func (storable StorableDashboard) ConvertV1ToV2() (result *DashboardV2, err error) {
+	// Legacy v1 data can be arbitrarily malformed. The accessors degrade
+	// gracefully, but recover from any unforeseen panic so one bad dashboard
+	// surfaces as an error (to be logged and skipped) rather than crashing the run.
+	defer func() {
+		if r := recover(); r != nil {
+			result, err = nil, errors.Newf(errors.TypeInternal, ErrCodeDashboardMigrationFailed, "panic converting dashboard %s: %v", storable.ID, r)
+		}
+	}()
+
+	if storable.IsV2() {
+		return nil, errors.Newf(errors.TypeInvalidInput, ErrCodeDashboardMigrationFailed, "dashboard %s is already in %s schema", storable.ID, SchemaVersion)
+	}
+
+	d := &v1Decoder{}
+	title := d.readString(storable.Data, "title")
+	description := d.readString(storable.Data, "description")
+	image := d.readString(storable.Data, "image")
+
+	spec := DashboardSpec{
+		Display:   Display{Name: title, Description: description},
+		Variables: d.convertV1Variables(storable.Data["variables"]),
+		Panels:    d.convertV1Panels(storable.Data["widgets"]),
+		Layouts:   d.convertV1Layouts(storable.Data),
+	}
+	tags := d.convertV1TagsForOrg(storable.OrgID, storable.Data["tags"])
+
+	if err := d.errIfHasMalformedFields(); err != nil {
+		return nil, err
+	}
+
+	return &DashboardV2{
+		Identifiable:  storable.Identifiable,
+		TimeAuditable: storable.TimeAuditable,
+		UserAuditable: storable.UserAuditable,
+		OrgID:         storable.OrgID,
+		Locked:        storable.Locked,
+		Source:        storable.Source,
+		DashboardV2MetadataBase: DashboardV2MetadataBase{
+			SchemaVersion: SchemaVersion,
+			Image:         image,
+		},
+		Name: generateDashboardName(title),
+		Tags: tags,
+		Spec: spec,
+	}, nil
+}

pkg/types/dashboardtypes/perses_v1_to_v2_decoder.go

@@ -0,0 +1,146 @@
+package dashboardtypes
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+)
+
+// ══════════════════════════════════════════════
+// v1 decoder
+// ══════════════════════════════════════════════
+
+// v1Decoder reads fields out of the untyped v1 dashboard blob. Every read*
+// method follows the same contract: a field that is absent or null yields the
+// zero value; a field present with the wrong type yields zero AND records a
+// malformed-field error. Conversion proceeds (so one bad field doesn't abort
+// the rest) and ConvertV1ToV2 returns d.malformedFieldsErr() at the end so the
+// dashboard is logged and skipped.
+//
+// Polymorphic v1 fields (spanGaps bool|number, selectedValue string|array, …)
+// are read with a type switch on the already-extracted value, never through
+// these accessors, so they stay lenient by construction.
+type v1Decoder struct {
+	bad  []string
+	seen map[string]struct{}
+}
+
+// note records a decoding problem (malformed field, unknown value, swallowed
+// sub-parse error), deduping identical messages. ConvertV1ToV2 surfaces these
+// via errIfHasMalformedFields.
+func (d *v1Decoder) note(format string, args ...any) {
+	msg := fmt.Sprintf(format, args...)
+	if _, dup := d.seen[msg]; dup {
+		return
+	}
+	if d.seen == nil {
+		d.seen = make(map[string]struct{})
+	}
+	d.seen[msg] = struct{}{}
+	d.bad = append(d.bad, msg)
+}
+
+// noteMalformedField records a v1 field present with the wrong Go type.
+func (d *v1Decoder) noteMalformedField(field string, raw any) {
+	d.note("%q has unexpected type %T", field, raw)
+}
+
+func (d *v1Decoder) errIfHasMalformedFields() error {
+	if len(d.bad) == 0 {
+		return nil
+	}
+	return errors.Newf(errors.TypeInvalidInput, ErrCodeDashboardInvalidData, "malformed v1 dashboard fields: %s", strings.Join(d.bad, "; "))
+}
+
+func readField[T any](d *v1Decoder, m map[string]any, key string) T {
+	var zero T
+	v, present := m[key]
+	if !present || v == nil {
+		return zero
+	}
+	t, ok := v.(T)
+	if !ok {
+		d.noteMalformedField(key, v)
+		return zero
+	}
+	return t
+}
+
+func (d *v1Decoder) readString(m map[string]any, key string) string {
+	return readField[string](d, m, key)
+}
+func (d *v1Decoder) readFloat(m map[string]any, key string) float64 {
+	return readField[float64](d, m, key)
+}
+func (d *v1Decoder) readBool(m map[string]any, key string) bool   { return readField[bool](d, m, key) }
+func (d *v1Decoder) readArray(m map[string]any, key string) []any { return readField[[]any](d, m, key) }
+func (d *v1Decoder) readObject(m map[string]any, key string) map[string]any {
+	return readField[map[string]any](d, m, key)
+}
+
+// readInt narrows a numeric field to int (JSON numbers decode as float64).
+func (d *v1Decoder) readInt(m map[string]any, key string) int { return int(d.readFloat(m, key)) }
+
+func (d *v1Decoder) readFloatPtr(m map[string]any, key string) *float64 {
+	v, present := m[key]
+	if !present || v == nil {
+		return nil
+	}
+	f, ok := v.(float64)
+	if !ok {
+		d.noteMalformedField(key, v)
+		return nil
+	}
+	return &f
+}
+
+func (d *v1Decoder) readStringMap(m map[string]any, key string) map[string]string {
+	raw := d.readObject(m, key)
+	if len(raw) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(raw))
+	for k, v := range raw {
+		s, ok := v.(string)
+		if !ok {
+			d.noteMalformedField(key+"."+k, v)
+			continue
+		}
+		out[k] = s
+	}
+	return out
+}
+
+func (d *v1Decoder) readObjects(m map[string]any, key string) []map[string]any {
+	raw := d.readArray(m, key)
+	if len(raw) == 0 {
+		return nil
+	}
+	out := make([]map[string]any, 0, len(raw))
+	for i, item := range raw {
+		obj, ok := item.(map[string]any)
+		if !ok {
+			d.noteMalformedField(fmt.Sprintf("%s[%d]", key, i), item)
+			continue
+		}
+		out = append(out, obj)
+	}
+	return out
+}
+
+// decodeMapInto converts an untyped map[string]any into a typed T by
+// round-tripping through JSON, letting encoding/json (struct tags, custom
+// UnmarshalJSON) do the field mapping instead of hand-copying out of the map.
+func decodeMapInto[T any](src map[string]any) (T, error) {
+	var dst T
+	bytes, err := json.Marshal(src)
+	if err != nil {
+		return dst, err
+	}
+	if err := json.Unmarshal(bytes, &dst); err != nil {
+		return dst, err
+	}
+	return dst, nil
+}

pkg/types/dashboardtypes/perses_v1_to_v2_layouts.go

@@ -0,0 +1,150 @@
+package dashboardtypes
+
+import (
+	"fmt"
+	"sort"
+
+	"github.com/perses/spec/go/common"
+	"github.com/perses/spec/go/dashboard"
+)
+
+// ══════════════════════════════════════════════
+// Layouts (data.layout + data.panelMap)
+// ══════════════════════════════════════════════
+
+// convertV1Layouts groups v1 react-grid-layout entries into v2 grid layouts.
+// Membership is positional (as the frontend renders): each row widget owns the
+// panels below it until the next row; panels above the first row form an unnamed
+// grid with no section header. Collapsed rows are the exception — their children
+// live in panelMap[rowID].widgets, not `layout`.
+func (d *v1Decoder) convertV1Layouts(data StorableDashboardData) []Layout {
+	layout := d.readObjects(data, "layout")
+	if len(layout) == 0 {
+		return nil
+	}
+
+	rows := d.extractRowsAndCollapsedWidgets(data)
+
+	// `layout` ids must correspond to a real widget. react-grid-layout leaks a
+	// "__dropping-elem__" drag placeholder (and stale entries can outlive a
+	// deleted widget) into the saved layout; both would otherwise become grid
+	// items referencing a non-existent panel.
+	widgetIDs := make(map[string]bool)
+	for _, w := range d.readObjects(data, "widgets") {
+		if id := d.readString(w, "id"); id != "" {
+			widgetIDs[id] = true
+		}
+	}
+
+	// Skip collapsed-row children a malformed dashboard lists in `layout` too.
+	isWidgetCollapsed := make(map[string]bool)
+	for _, row := range rows {
+		for _, child := range row.collapsedWidgets {
+			if id := d.readString(child, "i"); id != "" {
+				isWidgetCollapsed[id] = true
+			}
+		}
+	}
+
+	d.sortByPosition(layout)
+
+	type section struct {
+		row   *rowInfo // nil for the unnamed grid of ungrouped panels
+		items []map[string]any
+	}
+	topSectionWithoutHeader := &section{}
+	sectionsWithHeader := make([]*section, 0, len(rows))
+	currentRowHeader := topSectionWithoutHeader
+	for _, item := range layout {
+		id := d.readString(item, "i")
+		if id == "" || isWidgetCollapsed[id] || !widgetIDs[id] {
+			continue
+		}
+		if row, ok := rows[id]; ok {
+			newRowHeader := &section{row: row, items: row.collapsedWidgets}
+			sectionsWithHeader = append(sectionsWithHeader, newRowHeader)
+			// A collapsed row owns only its stashed children; later panels → ungrouped.
+			if row.collapsed {
+				currentRowHeader = topSectionWithoutHeader
+			} else {
+				currentRowHeader = newRowHeader
+			}
+			continue
+		}
+		currentRowHeader.items = append(currentRowHeader.items, item)
+	}
+
+	out := make([]Layout, 0, len(sectionsWithHeader)+1)
+	if len(topSectionWithoutHeader.items) > 0 {
+		out = append(out, d.buildV2GridLayout(nil, topSectionWithoutHeader.items))
+	}
+	for _, sec := range sectionsWithHeader {
+		out = append(out, d.buildV2GridLayout(sec.row, sec.items))
+	}
+	return out
+}
+
+type rowInfo struct {
+	title            string
+	collapsed        bool
+	collapsedWidgets []map[string]any
+}
+
+// extractRowsAndCollapsedWidgets returns the row widgets keyed by id; collapsed
+// rows also carry their children stashed under panelMap[id].widgets.
+func (d *v1Decoder) extractRowsAndCollapsedWidgets(data StorableDashboardData) map[string]*rowInfo {
+	panelMap := d.readObject(data, "panelMap")
+	rows := make(map[string]*rowInfo)
+	for _, w := range d.readObjects(data, "widgets") {
+		id := d.readString(w, "id")
+		if d.readString(w, "panelTypes") != "row" || id == "" {
+			continue
+		}
+		row := &rowInfo{title: d.readString(w, "title")}
+		if pm := d.readObject(panelMap, id); pm != nil && d.readBool(pm, "collapsed") {
+			row.collapsed = true
+			row.collapsedWidgets = d.readObjects(pm, "widgets")
+		}
+		rows[id] = row
+	}
+	return rows
+}
+
+// buildV2GridLayout builds one v2 grid. row is nil for the unnamed grid (no
+// display); otherwise the grid takes the row's title and collapse state. Items
+// are sorted by (y, x) and their y's normalized so the topmost sits at 0.
+func (d *v1Decoder) buildV2GridLayout(row *rowInfo, items []map[string]any) Layout {
+	d.sortByPosition(items)
+
+	spec := dashboard.GridLayoutSpec{Items: make([]dashboard.GridItem, 0, len(items))}
+	if row != nil {
+		spec.Display = &dashboard.GridLayoutDisplay{
+			Title:    row.title,
+			Collapse: &dashboard.GridLayoutCollapse{Open: !row.collapsed},
+		}
+	}
+
+	minY := 0
+	if len(items) > 0 {
+		minY = d.readInt(items[0], "y") // sorted by y, so the first item is topmost
+	}
+	for _, item := range items {
+		spec.Items = append(spec.Items, dashboard.GridItem{
+			X:       d.readInt(item, "x"),
+			Y:       d.readInt(item, "y") - minY,
+			Width:   d.readInt(item, "w"),
+			Height:  d.readInt(item, "h"),
+			Content: &common.JSONRef{Ref: fmt.Sprintf("#/spec/panels/%s", d.readString(item, "i"))},
+		})
+	}
+	return Layout{Kind: dashboard.KindGridLayout, Spec: &spec}
+}
+
+func (d *v1Decoder) sortByPosition(items []map[string]any) {
+	sort.SliceStable(items, func(i, j int) bool {
+		if yi, yj := d.readInt(items[i], "y"), d.readInt(items[j], "y"); yi != yj {
+			return yi < yj
+		}
+		return d.readInt(items[i], "x") < d.readInt(items[j], "x")
+	})
+}

pkg/types/dashboardtypes/perses_v1_to_v2_panels.go

@@ -0,0 +1,463 @@
+package dashboardtypes
+
+import (
+	"encoding/json"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// ══════════════════════════════════════════════
+// Widgets → Panels
+// ══════════════════════════════════════════════
+
+// convertV1Panels walks the v1 `widgets` array and produces v2 panels keyed by
+// the v1 widget id. WidgetRow entries (panelTypes == "row") are dropped here
+// and consumed by convertV1Layouts as section headers.
+func (d *v1Decoder) convertV1Panels(raw any) map[string]*Panel {
+	if raw == nil {
+		return nil
+	}
+	widgetsRaw, ok := raw.([]any)
+	if !ok {
+		d.noteMalformedField("widgets", raw)
+		return nil
+	}
+	panels := make(map[string]*Panel, len(widgetsRaw))
+	for i, widgetRaw := range widgetsRaw {
+		widget, ok := widgetRaw.(map[string]any)
+		if !ok {
+			d.noteMalformedField(fmt.Sprintf("widgets[%d]", i), widgetRaw)
+			continue
+		}
+		id := d.readString(widget, "id")
+		if id == "" {
+			continue
+		}
+		var panel *Panel
+		panelType := d.readString(widget, "panelTypes")
+		switch panelType {
+		case "graph":
+			panel = d.convertGraphWidget(widget)
+		case "bar":
+			panel = d.convertBarWidget(widget)
+		case "value":
+			panel = d.convertValueWidget(widget)
+		case "pie":
+			panel = d.convertPieWidget(widget)
+		case "table":
+			panel = d.convertTableWidget(widget)
+		case "histogram":
+			panel = d.convertHistogramWidget(widget)
+		case "list":
+			panel = d.convertListWidget(widget)
+		case "row":
+			// "row" (section header) is handled by the layout pass;
+			continue
+		default:
+			d.note("widgets[%d] has unknown panel type %q", i, panelType)
+		}
+		if panel == nil {
+			continue
+		}
+		panels[id] = panel
+	}
+	return panels
+}
+
+func (d *v1Decoder) convertGraphWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindTimeSeries,
+				Spec: &TimeSeriesPanelSpec{
+					Visualization: TimeSeriesVisualization{
+						BasicVisualization: d.basicVisualization(w),
+						FillSpans:          d.readBool(w, "fillSpans"),
+					},
+					Formatting: d.panelFormatting(w),
+					ChartAppearance: TimeSeriesChartAppearance{
+						LineInterpolation: mapV1Enum(d.readString(w, "lineInterpolation"), LineInterpolationSpline,
+							LineInterpolationLinear, LineInterpolationSpline, LineInterpolationStepAfter, LineInterpolationStepBefore),
+						ShowPoints: d.readBool(w, "showPoints"),
+						LineStyle:  mapV1Enum(d.readString(w, "lineStyle"), LineStyleSolid, LineStyleSolid, LineStyleDashed),
+						FillMode:   mapV1Enum(d.readString(w, "fillMode"), FillModeSolid, FillModeSolid, FillModeGradient, FillModeNone),
+						SpanGaps:   mapV1SpanGaps(w["spanGaps"]),
+					},
+					Axes:       d.axesFromWidget(w),
+					Legend:     d.legendFromWidget(w),
+					Thresholds: d.mapV1ThresholdsWithLabel(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindTimeSeries),
+		},
+	}
+}
+
+func (d *v1Decoder) convertBarWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindBarChart,
+				Spec: &BarChartPanelSpec{
+					Visualization: BarChartVisualization{
+						BasicVisualization: d.basicVisualization(w),
+						FillSpans:          d.readBool(w, "fillSpans"),
+						StackedBarChart:    d.readBool(w, "stackedBarChart"),
+					},
+					Formatting: d.panelFormatting(w),
+					Axes:       d.axesFromWidget(w),
+					Legend:     d.legendFromWidget(w),
+					Thresholds: d.mapV1ThresholdsWithLabel(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindBarChart),
+		},
+	}
+}
+
+func (d *v1Decoder) convertValueWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindNumber,
+				Spec: &NumberPanelSpec{
+					Visualization: d.basicVisualization(w),
+					Formatting:    d.panelFormatting(w),
+					Thresholds:    d.mapV1ComparisonThresholds(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindNumber),
+		},
+	}
+}
+
+func (d *v1Decoder) convertPieWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindPieChart,
+				Spec: &PieChartPanelSpec{
+					Visualization: d.basicVisualization(w),
+					Formatting:    d.panelFormatting(w),
+					Legend:        d.legendFromWidget(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindPieChart),
+		},
+	}
+}
+
+func (d *v1Decoder) convertTableWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindTable,
+				Spec: &TablePanelSpec{
+					Visualization: d.basicVisualization(w),
+					Formatting: TableFormatting{
+						ColumnUnits:      d.readStringMap(w, "columnUnits"),
+						DecimalPrecision: mapV1Precision(w["decimalPrecision"]),
+					},
+					Thresholds: d.mapV1TableThresholds(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindTable),
+		},
+	}
+}
+
+func (d *v1Decoder) convertHistogramWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindHistogram,
+				Spec: &HistogramPanelSpec{
+					HistogramBuckets: HistogramBuckets{
+						BucketCount:           d.readFloatPtr(w, "bucketCount"),
+						BucketWidth:           d.readFloatPtr(w, "bucketWidth"),
+						MergeAllActiveQueries: d.readBool(w, "mergeAllActiveQueries"),
+					},
+					Legend: d.legendFromWidget(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindHistogram),
+		},
+	}
+}
+
+func (d *v1Decoder) convertListWidget(w map[string]any) *Panel {
+	return &Panel{
+		Kind: "Panel",
+		Spec: PanelSpec{
+			Display: d.widgetDisplay(w),
+			Plugin: PanelPlugin{
+				Kind: PanelKindList,
+				Spec: &ListPanelSpec{
+					SelectFields: d.mapV1SelectFields(w),
+				},
+			},
+			Queries: d.convertV1WidgetQuery(w, PanelKindList),
+		},
+	}
+}
+
+// ══════════════════════════════════════════════
+// Panel-spec shared helpers
+// ══════════════════════════════════════════════
+
+func (d *v1Decoder) widgetDisplay(w map[string]any) Display {
+	return Display{Name: d.readString(w, "title"), Description: d.readString(w, "description")}
+}
+
+func (d *v1Decoder) basicVisualization(w map[string]any) BasicVisualization {
+	return BasicVisualization{TimePreference: mapV1TimePreference(d.readString(w, "timePreferance"))}
+}
+
+func (d *v1Decoder) panelFormatting(w map[string]any) PanelFormatting {
+	return PanelFormatting{Unit: d.readString(w, "yAxisUnit"), DecimalPrecision: mapV1Precision(w["decimalPrecision"])}
+}
+
+func (d *v1Decoder) axesFromWidget(w map[string]any) Axes {
+	return Axes{
+		SoftMin:    d.readFloatPtr(w, "softMin"),
+		SoftMax:    d.readFloatPtr(w, "softMax"),
+		IsLogScale: d.readBool(w, "isLogScale"),
+	}
+}
+
+func (d *v1Decoder) legendFromWidget(w map[string]any) Legend {
+	return Legend{
+		Position:     mapV1Enum(d.readString(w, "legendPosition"), LegendPositionBottom, LegendPositionBottom, LegendPositionRight),
+		CustomColors: d.readStringMap(w, "customLegendColors"),
+	}
+}
+
+func (d *v1Decoder) mapV1SelectFields(w map[string]any) []telemetrytypes.TelemetryFieldKey {
+	field := "selectedLogFields"
+	raw := d.readArray(w, field)
+	if len(raw) == 0 {
+		field = "selectedTracesFields"
+		raw = d.readArray(w, field)
+	}
+	if len(raw) == 0 {
+		return nil
+	}
+	fields, err := decodeTelemetryFields(raw)
+	if err != nil {
+		d.note("widget %q has malformed %s: %v", d.readString(w, "id"), field, err)
+		return nil
+	}
+	return fields
+}
+
+func decodeTelemetryFields(raw []any) ([]telemetrytypes.TelemetryFieldKey, error) {
+	bytes, err := json.Marshal(raw)
+	if err != nil {
+		return nil, err
+	}
+	var fields []telemetrytypes.TelemetryFieldKey
+	if err := json.Unmarshal(bytes, &fields); err != nil {
+		return nil, err
+	}
+	return fields, nil
+}
+
+// ══════════════════════════════════════════════
+// Panel field mappers
+// ══════════════════════════════════════════════
+
+// v1 stores timePreferance as `GLOBAL_TIME`, `LAST_5_MIN`, … (see
+// frontend/src/container/NewWidget/RightContainer/timeItems.ts). v2 uses the
+// lowercase form, so the translation is just downcase.
+func mapV1TimePreference(s string) TimePreference {
+	if s == "" {
+		return TimePreferenceGlobalTime
+	}
+	candidate := TimePreference{valuer.NewString(strings.ToLower(s))}
+	for _, allowed := range candidate.Enum() {
+		if allowed == candidate {
+			return candidate
+		}
+	}
+	return TimePreferenceGlobalTime
+}
+
+// mapV1Precision is polymorphic (string|number), so it type-switches the raw
+// value rather than reading through a typed accessor.
+func mapV1Precision(raw any) PrecisionOption {
+	switch v := raw.(type) {
+	case string:
+		candidate := PrecisionOption{valuer.NewString(v)}
+		for _, allowed := range candidate.Enum() {
+			if allowed == candidate {
+				return candidate
+			}
+		}
+	case float64:
+		n := int(v)
+		if n >= 0 && n <= 4 {
+			return PrecisionOption{valuer.NewString(strconv.Itoa(n))}
+		}
+	}
+	return PrecisionOption2
+}
+
+// mapV1Enum picks the v1 string value if it matches one of the allowed v2
+// values, otherwise returns the fallback. v1 frontend enums (lineInterpolation,
+// lineStyle, fillMode, legendPosition) already use the v2 lowercase form.
+func mapV1Enum[T interface{ StringValue() string }](s string, fallback T, allowed ...T) T {
+	if s == "" {
+		return fallback
+	}
+	for _, a := range allowed {
+		if a.StringValue() == s {
+			return a
+		}
+	}
+	return fallback
+}
+
+// v1 spanGaps is `boolean | number`. true → span every gap; false → never span;
+// a number is interpreted (per frontend SeriesProps.spanGaps docs) as an
+// X-axis threshold in seconds. Polymorphic, so it type-switches the raw value.
+func mapV1SpanGaps(raw any) SpanGaps {
+	switch v := raw.(type) {
+	case bool:
+		if v {
+			return SpanGaps{FillOnlyBelow: false}
+		}
+		return SpanGaps{FillOnlyBelow: true}
+	case float64:
+		dur, err := valuer.ParseTextDuration(time.Duration(v * float64(time.Second)).String())
+		if err != nil {
+			return SpanGaps{FillOnlyBelow: false}
+		}
+		return SpanGaps{FillOnlyBelow: true, FillLessThan: dur}
+	}
+	return SpanGaps{FillOnlyBelow: false}
+}
+
+func (d *v1Decoder) mapV1ThresholdsWithLabel(w map[string]any) []ThresholdWithLabel {
+	rawSlice := d.readObjects(w, "thresholds")
+	if len(rawSlice) == 0 {
+		return nil
+	}
+	out := make([]ThresholdWithLabel, 0, len(rawSlice))
+	for _, t := range rawSlice {
+		color := d.readString(t, "thresholdColor")
+		label := d.readString(t, "thresholdLabel")
+		if color == "" || label == "" {
+			// v2 ThresholdWithLabel requires both; drop entries that wouldn't validate.
+			continue
+		}
+		value := d.readFloat(t, "thresholdValue")
+		out = append(out, ThresholdWithLabel{Value: &value, Unit: d.readString(t, "thresholdUnit"), Color: color, Label: label})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func (d *v1Decoder) mapV1ComparisonThresholds(w map[string]any) []ComparisonThreshold {
+	rawSlice := d.readObjects(w, "thresholds")
+	if len(rawSlice) == 0 {
+		return nil
+	}
+	out := make([]ComparisonThreshold, 0, len(rawSlice))
+	for _, t := range rawSlice {
+		color := d.readString(t, "thresholdColor")
+		if color == "" {
+			continue
+		}
+		value := d.readFloat(t, "thresholdValue")
+		out = append(out, ComparisonThreshold{
+			Value:    &value,
+			Operator: d.mapV1ComparisonOperator(d.readString(t, "thresholdOperator")),
+			Unit:     d.readString(t, "thresholdUnit"),
+			Color:    color,
+			Format:   mapV1ThresholdFormat(d.readString(t, "thresholdFormat")),
+		})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func (d *v1Decoder) mapV1TableThresholds(w map[string]any) []TableThreshold {
+	rawSlice := d.readObjects(w, "thresholds")
+	if len(rawSlice) == 0 {
+		return nil
+	}
+	out := make([]TableThreshold, 0, len(rawSlice))
+	for _, t := range rawSlice {
+		color := d.readString(t, "thresholdColor")
+		columnName := d.readString(t, "thresholdTableOptions")
+		if color == "" || columnName == "" {
+			continue
+		}
+		value := d.readFloat(t, "thresholdValue")
+		out = append(out, TableThreshold{
+			ComparisonThreshold: ComparisonThreshold{
+				Value:    &value,
+				Operator: d.mapV1ComparisonOperator(d.readString(t, "thresholdOperator")),
+				Unit:     d.readString(t, "thresholdUnit"),
+				Color:    color,
+				Format:   mapV1ThresholdFormat(d.readString(t, "thresholdFormat")),
+			},
+			ColumnName: columnName,
+		})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func (d *v1Decoder) mapV1ComparisonOperator(s string) ComparisonOperator {
+	switch s {
+	case ">":
+		return ComparisonOperatorAbove
+	case ">=":
+		return ComparisonOperatorAboveOrEqual
+	case "<":
+		return ComparisonOperatorBelow
+	case "<=":
+		return ComparisonOperatorBelowOrEqual
+	case "=":
+		return ComparisonOperatorEqual
+	case "!=":
+		return ComparisonOperatorNotEqual
+	default:
+		d.note("threshold has unknown comparison operator %q", s)
+		return ComparisonOperatorAbove
+	}
+}
+
+func mapV1ThresholdFormat(s string) ThresholdFormat {
+	switch strings.ToLower(s) {
+	case "background":
+		return ThresholdFormatBackground
+	case "text":
+		return ThresholdFormatText
+	}
+	return ThresholdFormatText
+}

pkg/types/dashboardtypes/perses_v1_to_v2_queries.go

@@ -0,0 +1,246 @@
+package dashboardtypes
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+	qb "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+)
+
+// ══════════════════════════════════════════════
+// Queries
+// ══════════════════════════════════════════════
+
+// convertV1WidgetQuery returns exactly one Query (per Spec.Validate). The kind
+// chosen depends on the v1 widget query shape:
+//   - a single query (promql / clickhouse_sql / builder) → its native kind
+//   - multiple queries                                   → signoz/CompositeQuery
+//
+// A single query is never wrapped in a CompositeQuery; in particular List
+// panels accept only a bare signoz/BuilderQuery. Builder queries are routed
+// through qb.WrapInV5Envelope (in collectV1QueryEnvelopes), which translates v4
+// builder-field names (orderBy/selectColumns/dataSource) into their v5
+// equivalents and adds the `signal` field required by BuilderQuerySpec's
+// per-signal dispatch.
+func (d *v1Decoder) convertV1WidgetQuery(widget map[string]any, panelKind PanelPluginKind) []Query {
+	envelopes, signal := d.collectV1QueryEnvelopes(widget)
+	if len(envelopes) == 0 {
+		return nil
+	}
+	requestType := requestTypeForPanel(panelKind)
+
+	// A single query keeps its native kind — never wrapped in a CompositeQuery.
+	if len(envelopes) == 1 {
+		if q := singleQueryFromEnvelope(envelopes[0], requestType, signal); q != nil {
+			return []Query{*q}
+		}
+	}
+
+	// Default: wrap in CompositeQuery.
+	composite, err := parseCompositeFromEnvelopes(envelopes)
+	if err != nil || composite == nil {
+		d.note("widget %q: could not build query from %d envelope(s): %v", d.readString(widget, "id"), len(envelopes), err)
+		return nil
+	}
+	return []Query{{
+		Kind: requestType,
+		Spec: QuerySpec{
+			Plugin: QueryPlugin{Kind: QueryKindComposite, Spec: composite},
+		},
+	}}
+}
+
+// requestTypeForPanel maps a v2 panel plugin kind to the request type (result
+// shape) its queries produce. Mirrors the frontend's panelTypeToRequestType
+// (buildQueryRangeRequest.ts): time series for line/bar/histogram (histogram
+// bins client-side from raw time series, V1 parity), scalar for
+// number/pie/table, raw rows for list.
+func requestTypeForPanel(panelKind PanelPluginKind) qb.RequestType {
+	switch panelKind {
+	case PanelKindTimeSeries, PanelKindBarChart, PanelKindHistogram:
+		return qb.RequestTypeTimeSeries
+	case PanelKindNumber, PanelKindPieChart, PanelKindTable:
+		return qb.RequestTypeScalar
+	case PanelKindList:
+		return qb.RequestTypeRaw
+	}
+	return qb.RequestTypeTimeSeries
+}
+
+// collectV1QueryEnvelopes inspects widget.query.queryType and produces a
+// flattened list of v5-shaped envelopes. The returned signal is the dominant
+// builder signal (if any), used for typed builder-query dispatch.
+func (d *v1Decoder) collectV1QueryEnvelopes(widget map[string]any) ([]map[string]any, telemetrytypes.Signal) {
+	queryMap := d.readObject(widget, "query")
+	if queryMap == nil {
+		return nil, telemetrytypes.Signal{}
+	}
+
+	queryType := d.readString(queryMap, "queryType")
+	switch queryType {
+	case "promql":
+		var out []map[string]any
+		for _, q := range d.readObjects(queryMap, "promql") {
+			out = append(out, promQLEnvelope(q))
+		}
+		return out, telemetrytypes.Signal{}
+
+	case "clickhouse_sql":
+		var out []map[string]any
+		for _, q := range d.readObjects(queryMap, "clickhouse_sql") {
+			out = append(out, clickhouseEnvelope(q))
+		}
+		return out, telemetrytypes.Signal{}
+
+	case "builder":
+		builder := d.readObject(queryMap, "builder")
+		if builder == nil {
+			return nil, telemetrytypes.Signal{}
+		}
+		var out []map[string]any
+		var signal telemetrytypes.Signal
+		for _, q := range d.readObjects(builder, "queryData") {
+			name := d.readString(q, "queryName")
+			out = append(out, qb.WrapInV5Envelope(name, q, string(qb.QueryTypeBuilder.StringValue())))
+			if signal.IsZero() {
+				signal = signalFromDataSource(q["dataSource"])
+			}
+		}
+		for _, f := range d.readObjects(builder, "queryFormulas") {
+			name := d.readString(f, "queryName")
+			out = append(out, qb.WrapInV5Envelope(name, f, string(qb.QueryTypeFormula.StringValue())))
+		}
+		for _, op := range d.readObjects(builder, "queryTraceOperator") {
+			name := d.readString(op, "queryName")
+			out = append(out, qb.WrapInV5Envelope(name, op, string(qb.QueryTypeTraceOperator.StringValue())))
+		}
+		return out, signal
+	default:
+		d.note("widget %q has unknown queryType %q", d.readString(widget, "id"), queryType)
+	}
+	return nil, telemetrytypes.Signal{}
+}
+
+func promQLEnvelope(q map[string]any) map[string]any {
+	return map[string]any{
+		"type": qb.QueryTypePromQL.StringValue(),
+		"spec": map[string]any{
+			"name":     q["name"],
+			"query":    q["query"],
+			"disabled": q["disabled"],
+			"legend":   q["legend"],
+		},
+	}
+}
+
+func clickhouseEnvelope(q map[string]any) map[string]any {
+	return map[string]any{
+		"type": qb.QueryTypeClickHouseSQL.StringValue(),
+		"spec": map[string]any{
+			"name":     q["name"],
+			"query":    q["query"],
+			"disabled": q["disabled"],
+			"legend":   q["legend"],
+		},
+	}
+}
+
+// singleQueryFromEnvelope returns a typed Query for one envelope, using its
+// native query kind (promql/clickhouse_sql/builder) rather than wrapping it in
+// a CompositeQuery. A bare signoz/BuilderQuery is valid for every panel kind
+// and is the only kind List panels accept.
+func singleQueryFromEnvelope(envelope map[string]any, requestType qb.RequestType, signal telemetrytypes.Signal) *Query {
+	t, _ := envelope["type"].(string)
+	spec, _ := envelope["spec"].(map[string]any)
+	switch t {
+	case qb.QueryTypePromQL.StringValue():
+		prom, err := decodeMapInto[qb.PromQuery](spec)
+		if err != nil {
+			return nil
+		}
+		return &Query{
+			Kind: requestType,
+			Spec: QuerySpec{
+				Name:   prom.Name,
+				Plugin: QueryPlugin{Kind: QueryKindPromQL, Spec: &prom},
+			},
+		}
+	case qb.QueryTypeClickHouseSQL.StringValue():
+		ch, err := decodeMapInto[qb.ClickHouseQuery](spec)
+		if err != nil {
+			return nil
+		}
+		return &Query{
+			Kind: requestType,
+			Spec: QuerySpec{
+				Name:   ch.Name,
+				Plugin: QueryPlugin{Kind: QueryKindClickHouseSQL, Spec: &ch},
+			},
+		}
+	case qb.QueryTypeBuilder.StringValue():
+		builderSpec := parseBuilderQuerySpec(spec, signal)
+		if builderSpec == nil {
+			return nil
+		}
+		name, _ := spec["name"].(string)
+		return &Query{
+			Kind: requestType,
+			Spec: QuerySpec{
+				Name:   name,
+				Plugin: QueryPlugin{Kind: QueryKindBuilder, Spec: &BuilderQuerySpec{Spec: builderSpec}},
+			},
+		}
+	}
+	return nil
+}
+
+func parseCompositeFromEnvelopes(envelopes []map[string]any) (*CompositeQuerySpec, error) {
+	bytes, err := json.Marshal(envelopes)
+	if err != nil {
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "marshal v1 query envelopes")
+	}
+	var parsed []qb.QueryEnvelope
+	if err := json.Unmarshal(bytes, &parsed); err != nil {
+		return nil, errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidWidgetQuery, "decode v5 query envelopes")
+	}
+	return &CompositeQuerySpec{Queries: parsed}, nil
+}
+
+func parseBuilderQuerySpec(rawSpec any, signal telemetrytypes.Signal) any {
+	spec, ok := rawSpec.(map[string]any)
+	if !ok {
+		return nil
+	}
+	if !signal.IsZero() {
+		spec["signal"] = signal.StringValue()
+	}
+	bytes, err := json.Marshal(spec)
+	if err != nil {
+		return nil
+	}
+	parsed, err := qb.UnmarshalBuilderQueryBySignal(bytes)
+	if err != nil {
+		return nil
+	}
+	return parsed
+}
+
+// signalFromDataSource maps a v1 data-source string to a v5 signal. Casing
+// varies by source: builder queries store lowercase ("traces"), while variable
+// `dynamicVariablesSource` stores capitalized ("Traces"), so match
+// case-insensitively. Unknown values (e.g. "All telemetry") map to the zero
+// Signal.
+func signalFromDataSource(raw any) telemetrytypes.Signal {
+	s, _ := raw.(string)
+	switch strings.ToLower(s) {
+	case "traces":
+		return telemetrytypes.SignalTraces
+	case "logs":
+		return telemetrytypes.SignalLogs
+	case "metrics":
+		return telemetrytypes.SignalMetrics
+	}
+	return telemetrytypes.Signal{}
+}

pkg/types/dashboardtypes/perses_v1_to_v2_tags.go

@@ -0,0 +1,122 @@
+package dashboardtypes
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/types/coretypes"
+	"github.com/SigNoz/signoz/pkg/types/tagtypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// ══════════════════════════════════════════════
+// Tags
+// ══════════════════════════════════════════════
+
+// v1 carries tags as a flat []string; v2 tags are (key, value) pairs. Each v1
+// string is normalized into a pair (separator split, empty-side fallback,
+// reserved-key prefix, `/` scrub). Tags that normalize to the same
+// (lower(key), lower(value)) within a dashboard are collapsed, first occurrence
+// winning the display casing.
+//
+// Characters still illegal after normalization (spaces, punctuation) are molded
+// to fit the tag validators: disallowed runs collapse to "_" (see moldTagField).
+
+// defaultV1TagKey is the key assigned when a v1 tag string has no usable
+// separator (or one side of the split is empty).
+const defaultV1TagKey = "tag"
+
+func (d *v1Decoder) convertV1TagsForOrg(orgID valuer.UUID, raw any) []*tagtypes.Tag {
+	if raw == nil {
+		return nil
+	}
+	rawTagsList, ok := raw.([]any)
+	if !ok {
+		d.noteMalformedField("tags", raw)
+		return nil
+	}
+	seen := make(map[string]struct{}, len(rawTagsList))
+	tagsV2 := make([]*tagtypes.Tag, 0, len(rawTagsList))
+	for i, rawTag := range rawTagsList {
+		s, ok := rawTag.(string)
+		if !ok {
+			d.noteMalformedField(fmt.Sprintf("tags[%d]", i), rawTag)
+			continue
+		}
+		key, value, ok := normalizeV1Tag(s)
+		if !ok {
+			continue
+		}
+		dedupKey := strings.ToLower(key) + "\x00" + strings.ToLower(value)
+		if _, dup := seen[dedupKey]; dup {
+			continue
+		}
+		seen[dedupKey] = struct{}{}
+		tagsV2 = append(tagsV2, tagtypes.NewTag(orgID, coretypes.KindDashboard, key, value))
+	}
+	return tagsV2
+}
+
+// normalizeV1Tag derives a (key, value) pair from one v1 tag string. After
+// splitting and molding both sides, a lone survivor becomes a value under the
+// default key; ok is false if neither survives.
+func normalizeV1Tag(s string) (string, string, bool) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return "", "", false
+	}
+
+	var rawKey, rawValue string
+	switch {
+	case strings.Contains(s, ":"):
+		rawKey, rawValue, _ = strings.Cut(s, ":")
+		// Only the first ":" separates key from value; collapse the rest.
+		rawValue = strings.ReplaceAll(rawValue, ":", "_")
+	case strings.Contains(s, "/"):
+		rawKey, rawValue, _ = strings.Cut(s, "/")
+	default:
+		rawValue = s
+	}
+	rawKey = strings.TrimSpace(rawKey)
+	rawValue = strings.TrimSpace(rawValue)
+
+	// Reserved-key collision: prefix "_" so the list-query DSL stays unambiguous.
+	if _, reserved := reservedDSLKeys[DSLKey(strings.ToLower(rawKey))]; rawKey != "" && reserved {
+		rawKey = "_" + rawKey
+	}
+
+	key := moldTagField(rawKey, tagKeyDisallowed, tagKeyNotLead, tagtypes.MAX_LEN_TAG_KEY)
+	value := moldTagField(rawValue, tagValueDisallowed, nil, tagtypes.MAX_LEN_TAG_VALUE)
+	switch {
+	case key == "" && value == "":
+		return "", "", false
+	case key == "":
+		return defaultV1TagKey, value, true
+	case value == "":
+		return defaultV1TagKey, key, true
+	default:
+		return key, value, true
+	}
+}
+
+// Inverse of tagKeyRegex/tagValueRegex ("/" always rejected); tagKeyNotLead
+// matches a bad first char for a key. TestMoldedV1TagsPassValidation guards drift.
+var (
+	tagKeyDisallowed   = regexp.MustCompile(`[^a-zA-Z0-9$_@#{}:-]+`)
+	tagValueDisallowed = regexp.MustCompile(`[^a-zA-Z0-9$_@#{}:.+=-]+`)
+	tagKeyNotLead      = regexp.MustCompile(`^[^a-zA-Z$_@{#]`)
+)
+
+// moldTagField collapses disallowed runs to "_", prefixes "_" if notLead hits
+// the first char, and caps at max. Keeps a leading "_", trims a trailing one.
+func moldTagField(s string, disallowed, notLead *regexp.Regexp, max int) string {
+	s = strings.TrimRight(disallowed.ReplaceAllString(s, "_"), "_")
+	if s != "" && notLead != nil && notLead.MatchString(s) {
+		s = "_" + s
+	}
+	if len(s) > max {
+		s = strings.TrimRight(s[:max], "_")
+	}
+	return s
+}

pkg/types/dashboardtypes/perses_v1_to_v2_variables.go

@@ -0,0 +1,169 @@
+package dashboardtypes
+
+import (
+	"sort"
+
+	"github.com/perses/spec/go/dashboard/variable"
+)
+
+// ══════════════════════════════════════════════
+// Variables
+// ══════════════════════════════════════════════
+
+// convertV1Variables walks the v1 `variables` map (UUID-keyed) and produces an
+// ordered []Variable. Variables sort by `order` first, then by id for stable
+// output. v1 variable types map as follows:
+//
+//	QUERY    → ListVariable + signoz/QueryVariable
+//	CUSTOM   → ListVariable + signoz/CustomVariable
+//	DYNAMIC  → ListVariable + signoz/DynamicVariable
+//	TEXTBOX  → TextVariable
+func (d *v1Decoder) convertV1Variables(raw any) []Variable {
+	if raw == nil {
+		return nil
+	}
+	rawVariablesMap, ok := raw.(map[string]any)
+	if !ok {
+		d.noteMalformedField("variables", raw)
+		return nil
+	}
+	type ordered struct {
+		variableID      string
+		variableContent map[string]any
+		order           float64
+	}
+	entries := make([]ordered, 0, len(rawVariablesMap))
+	for variableID, variableContentRaw := range rawVariablesMap {
+		variableContent, ok := variableContentRaw.(map[string]any)
+		if !ok {
+			d.noteMalformedField("variables."+variableID, variableContentRaw)
+			continue
+		}
+		entries = append(entries, ordered{variableID: variableID, variableContent: variableContent, order: d.readFloat(variableContent, "order")})
+	}
+	sort.SliceStable(entries, func(i, j int) bool {
+		if entries[i].order != entries[j].order {
+			return entries[i].order < entries[j].order
+		}
+		return entries[i].variableID < entries[j].variableID
+	})
+
+	variablesV2 := make([]Variable, 0, len(entries))
+	for _, e := range entries {
+		v, ok := d.convertV1Variable(e.variableContent)
+		if !ok {
+			continue
+		}
+		variablesV2 = append(variablesV2, v)
+	}
+	return variablesV2
+}
+
+func (d *v1Decoder) convertV1Variable(v map[string]any) (Variable, bool) {
+	name := d.readString(v, "name")
+	if name == "" {
+		return Variable{}, false
+	}
+	description := d.readString(v, "description")
+	kind := d.readString(v, "type")
+
+	switch kind {
+	case "TEXTBOX":
+		spec := &TextVariableSpec{
+			Display: Display{Name: name, Description: description},
+			Value:   d.readString(v, "textboxValue"),
+			Name:    name,
+		}
+		return Variable{Kind: variable.KindText, Spec: spec}, true
+
+	case "QUERY", "CUSTOM", "DYNAMIC":
+		listSpec := &ListVariableSpec{
+			Display:         Display{Name: name, Description: description},
+			AllowAllValue:   d.readBool(v, "showALLOption"),
+			AllowMultiple:   d.readBool(v, "multiSelect"),
+			CustomAllValue:  d.readString(v, "customAllValue"),
+			CapturingRegexp: d.readString(v, "capturingRegexp"),
+			Sort:            mapV1Sort(d.readString(v, "sort")),
+			Plugin:          d.variablePluginFor(kind, v),
+			Name:            name,
+		}
+		if dv := mapV1VariableDefault(v); dv != nil {
+			listSpec.DefaultValue = dv
+		}
+		return Variable{Kind: variable.KindList, Spec: listSpec}, true
+
+	default:
+		d.note("variable %q has unknown type %q", name, kind)
+		return Variable{}, false
+	}
+}
+
+func (d *v1Decoder) variablePluginFor(kind string, v map[string]any) VariablePlugin {
+	switch kind {
+	case "QUERY":
+		return VariablePlugin{
+			Kind: VariableKindQuery,
+			Spec: &QueryVariableSpec{QueryValue: d.readString(v, "queryValue")},
+		}
+	case "CUSTOM":
+		return VariablePlugin{
+			Kind: VariableKindCustom,
+			Spec: &CustomVariableSpec{CustomValue: d.readString(v, "customValue")},
+		}
+	case "DYNAMIC":
+		spec := &DynamicVariableSpec{Name: d.readString(v, "dynamicVariablesAttribute")}
+		if signal := signalFromDataSource(v["dynamicVariablesSource"]); !signal.IsZero() {
+			spec.Signal = signal
+		}
+		return VariablePlugin{Kind: VariableKindDynamic, Spec: spec}
+	}
+	return VariablePlugin{}
+}
+
+// mapV1VariableDefault reads selectedValue/defaultValue, both polymorphic
+// (string|array), so it indexes the raw value and lets defaultValueFromAny
+// type-switch — no typed accessor, intentionally lenient.
+func mapV1VariableDefault(v map[string]any) *VariableDefaultValue {
+	if raw, ok := v["selectedValue"]; ok {
+		return defaultValueFromAny(raw)
+	}
+	if raw, ok := v["defaultValue"]; ok {
+		return defaultValueFromAny(raw)
+	}
+	return nil
+}
+
+func defaultValueFromAny(raw any) *VariableDefaultValue {
+	switch v := raw.(type) {
+	case string:
+		if v == "" {
+			return nil
+		}
+		return &VariableDefaultValue{variable.DefaultValue{SingleValue: v}}
+	case []any:
+		if len(v) == 0 {
+			return nil
+		}
+		values := make([]string, 0, len(v))
+		for _, item := range v {
+			if s, ok := item.(string); ok && s != "" {
+				values = append(values, s)
+			}
+		}
+		if len(values) == 0 {
+			return nil
+		}
+		return &VariableDefaultValue{variable.DefaultValue{SliceValues: values}}
+	}
+	return nil
+}
+
+func mapV1Sort(s string) ListVariableSpecSort {
+	switch s {
+	case "ASC":
+		return SortAlphabeticalAsc
+	case "DESC":
+		return SortAlphabeticalDesc
+	}
+	return ListVariableSpecSort{} // zero (omitzero) — SortNone is the implicit default
+}

pkg/types/dashboardtypes/store.go

@@ -43,6 +43,10 @@ type Store interface {
 
 	ListForUser(ctx context.Context, orgID valuer.UUID, userID valuer.UUID, params *ListDashboardsV2Params) ([]*StorableDashboardWithPinInfo, int64, error)
 
+	// ListByDataContainsAny returns the org's dashboards whose raw `data` JSON
+	// contains any of the given substrings (matched literally; LIKE wildcards escaped).
+	ListByDataContainsAny(ctx context.Context, orgID valuer.UUID, searches []string) ([]*StorableDashboard, error)
+
 	// Returns ErrCodePinnedDashboardLimitHit when the user is at MaxPinnedDashboardsPerUser.
 	PinForUser(ctx context.Context, preference *UserDashboardPreference) error
 

pkg/types/metricsexplorertypes/metricsexplorer.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/types/dashboardtypes"
 	"github.com/SigNoz/signoz/pkg/types/metrictypes"
 	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
 	"github.com/SigNoz/signoz/pkg/valuer"
@@ -252,6 +253,22 @@ type MetricDashboardsResponse struct {
 	Dashboards []MetricDashboard `json:"dashboards" required:"true" nullable:"true"`
 }
 
+// MetricDashboardPanelsResponse is the response for the v2 metric dashboards
+// endpoint: the dashboard panels that reference the metric.
+type MetricDashboardPanelsResponse struct {
+	Dashboards []dashboardtypes.DashboardPanelRef `json:"dashboards" required:"true" nullable:"true"`
+}
+
+// NewMetricDashboardPanelsResponse wraps the dashboard panels that reference a
+// metric into the v2 API response.
+func NewMetricDashboardPanelsResponse(refs []dashboardtypes.DashboardPanelRef) *MetricDashboardPanelsResponse {
+	if refs == nil {
+		refs = []dashboardtypes.DashboardPanelRef{}
+	}
+
+	return &MetricDashboardPanelsResponse{Dashboards: refs}
+}
+
 // MetricHighlightsResponse is the output structure for the metric highlights endpoint.
 type MetricHighlightsResponse struct {
 	DataPoints       uint64 `json:"dataPoints" required:"true"`

pkg/types/querybuildertypes/querybuildertypesv5/migrate_envelope.go

@@ -0,0 +1,127 @@
+package querybuildertypesv5
+
+// WrapInV5Envelope translates a single v4 builder query/formula map into a
+// v5 query envelope ({"type": ..., "spec": ...}). It is a pure shape transform
+// over untyped maps: v4 builder field names (groupBy/orderBy/selectColumns/
+// dataSource) are rewritten to their v5 equivalents and a `signal` is derived
+// from the data source. queryType selects the envelope type, except a formula
+// (detected when name != queryMap["expression"]) is always emitted as
+// "builder_formula".
+//
+// Migration code (pkg/transition) and the v1→v2 dashboard conversion both
+// produce v5 envelopes, so this lives here with the v5 query types rather than
+// in an infra-level package.
+func WrapInV5Envelope(name string, queryMap map[string]any, queryType string) map[string]any {
+	// Create a properly structured v5 query
+	v5Query := map[string]any{
+		"name":     name,
+		"disabled": queryMap["disabled"],
+		"legend":   queryMap["legend"],
+	}
+
+	if name != queryMap["expression"] {
+		// formula
+		queryType = "builder_formula"
+		v5Query["expression"] = queryMap["expression"]
+		if functions, ok := queryMap["functions"]; ok {
+			v5Query["functions"] = functions
+		}
+		return map[string]any{
+			"type": queryType,
+			"spec": v5Query,
+		}
+	}
+
+	// Add signal based on data source
+	if dataSource, ok := queryMap["dataSource"].(string); ok {
+		switch dataSource {
+		case "traces":
+			v5Query["signal"] = "traces"
+		case "logs":
+			v5Query["signal"] = "logs"
+		case "metrics":
+			v5Query["signal"] = "metrics"
+		}
+	}
+
+	if stepInterval, ok := queryMap["stepInterval"]; ok {
+		v5Query["stepInterval"] = stepInterval
+	}
+
+	if aggregations, ok := queryMap["aggregations"]; ok {
+		v5Query["aggregations"] = aggregations
+	}
+
+	if filter, ok := queryMap["filter"]; ok {
+		v5Query["filter"] = filter
+	}
+
+	// Copy groupBy with proper structure
+	if groupBy, ok := queryMap["groupBy"].([]any); ok {
+		v5GroupBy := make([]any, len(groupBy))
+		for i, gb := range groupBy {
+			if gbMap, ok := gb.(map[string]any); ok {
+				v5GroupBy[i] = map[string]any{
+					"name":          gbMap["key"],
+					"fieldDataType": gbMap["dataType"],
+					"fieldContext":  gbMap["type"],
+				}
+			}
+		}
+		v5Query["groupBy"] = v5GroupBy
+	}
+
+	// Copy orderBy with proper structure
+	if orderBy, ok := queryMap["orderBy"].([]any); ok {
+		v5OrderBy := make([]any, len(orderBy))
+		for i, ob := range orderBy {
+			if obMap, ok := ob.(map[string]any); ok {
+				v5OrderBy[i] = map[string]any{
+					"key": map[string]any{
+						"name":          obMap["columnName"],
+						"fieldDataType": obMap["dataType"],
+						"fieldContext":  obMap["type"],
+					},
+					"direction": obMap["order"],
+				}
+			}
+		}
+		v5Query["order"] = v5OrderBy
+	}
+
+	// Copy selectColumns as selectFields
+	if selectColumns, ok := queryMap["selectColumns"].([]any); ok {
+		v5SelectFields := make([]any, len(selectColumns))
+		for i, col := range selectColumns {
+			if colMap, ok := col.(map[string]any); ok {
+				v5SelectFields[i] = map[string]any{
+					"name":          colMap["key"],
+					"fieldDataType": colMap["dataType"],
+					"fieldContext":  colMap["type"],
+				}
+			}
+		}
+		v5Query["selectFields"] = v5SelectFields
+	}
+
+	// Copy limit and offset
+	if limit, ok := queryMap["limit"]; ok {
+		v5Query["limit"] = limit
+	}
+	if offset, ok := queryMap["offset"]; ok {
+		v5Query["offset"] = offset
+	}
+
+	if having, ok := queryMap["having"]; ok {
+		v5Query["having"] = having
+	}
+
+	if functions, ok := queryMap["functions"]; ok {
+		v5Query["functions"] = functions
+	}
+
+	return map[string]any{
+		"type": queryType,
+		"spec": v5Query,
+	}
+}

tests/integration/tests/dashboard/03_v2_dashboard.py

@@ -6,6 +6,7 @@ import pytest
 import requests
 
 from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
+from fixtures.metrics import Metrics
 from fixtures.types import Operation, SigNoz
 
 BASE_URL = "/api/v2/dashboards"
@@ -934,3 +935,306 @@ def test_dashboard_v2_like_escaping(
         )
         assert response.status_code == HTTPStatus.OK, response.text
         assert {d["spec"]["display"]["name"] for d in response.json()["data"]["dashboards"]} == expected, query
+
+
+# ─── get dashboards by metric name (v3) ──────────────────────────────────────
+
+
+def test_dashboard_v2_get_by_metric_name(
+    signoz: SigNoz,
+    create_user_admin: Operation,  # pylint: disable=unused-argument
+    get_token: Callable[[str, str], str],
+    insert_metrics: Callable[[list[Metrics]], None],
+) -> None:
+    """The v3 endpoint shortlists dashboards via a coarse data prefilter, then
+    confirms matches by parsing the typed v2 panels. It must find the metric in
+    builder, promql, and clickhouse queries, and must NOT report a dashboard where
+    the metric appears only in panel names (the prefilter matches but the parse
+    rejects it)."""
+    token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
+    _wipe_all_dashboards(signoz, token)
+
+    target_metric = "system.network.dropped"
+    decoy_metric = "system.network.io"
+
+    # The endpoint gates on metric existence (checkMetricExists reads
+    # signoz_metrics.distributed_metadata), so seed the target metric there. A
+    # label is required for a metadata row to be written.
+    insert_metrics(
+        [
+            Metrics(
+                metric_name=target_metric,
+                labels={"host.name": "test-host"},
+                temporality="Cumulative",
+                value=1.0,
+            )
+        ]
+    )
+
+    # D1: a single builder query referencing the target metric.
+    response = requests.post(
+        signoz.self.host_configs["8080"].get(BASE_URL),
+        json={
+            "schemaVersion": "v6",
+            "name": "by-metric-builder",
+            "spec": {
+                "display": {"name": "by-metric-builder"},
+                "panels": {
+                    "p-builder": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": "D1 builder target"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/BuilderQuery",
+                                            "spec": {
+                                                "name": "A",
+                                                "signal": "metrics",
+                                                "aggregations": [
+                                                    {
+                                                        "metricName": target_metric,
+                                                        "timeAggregation": "rate",
+                                                        "spaceAggregation": "sum",
+                                                    }
+                                                ],
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    }
+                },
+            },
+            "tags": [],
+        },
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert response.status_code == HTTPStatus.CREATED, response.text
+    d1_id = response.json()["data"]["id"]
+
+    # D2: one clickhouse panel and one promql panel, both referencing the target
+    # metric (one query per panel is enforced by validation). Two matching panels
+    # in one dashboard also guards against a dashboard/widget being returned twice.
+    response = requests.post(
+        signoz.self.host_configs["8080"].get(BASE_URL),
+        json={
+            "schemaVersion": "v6",
+            "name": "by-metric-ch-promql",
+            "spec": {
+                "display": {"name": "by-metric-ch-promql"},
+                "panels": {
+                    "p-ch": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": "D2 clickhouse target"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/ClickHouseSQL",
+                                            "spec": {
+                                                "name": "A",
+                                                "query": f"select * from signoz_metrics.distributed_samples_v4 where metric_name IN ['{target_metric}']",
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    },
+                    "p-promql": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": "D2 promql target"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/PromQLQuery",
+                                            "spec": {
+                                                "name": "A",
+                                                "query": f'sum(rate({{"{target_metric}"}}[5m]))',
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    },
+                },
+            },
+            "tags": [],
+        },
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert response.status_code == HTTPStatus.CREATED, response.text
+    d2_id = response.json()["data"]["id"]
+
+    # D3: a promql-only dashboard referencing the target metric, so a promql
+    # extraction regression is caught independently of the clickhouse path above.
+    response = requests.post(
+        signoz.self.host_configs["8080"].get(BASE_URL),
+        json={
+            "schemaVersion": "v6",
+            "name": "by-metric-promql",
+            "spec": {
+                "display": {"name": "by-metric-promql"},
+                "panels": {
+                    "p-promql": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": "D3 promql target"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/PromQLQuery",
+                                            "spec": {
+                                                "name": "A",
+                                                "query": f'sum(rate({{"{target_metric}"}}[5m]))',
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    }
+                },
+            },
+            "tags": [],
+        },
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert response.status_code == HTTPStatus.CREATED, response.text
+    d3_id = response.json()["data"]["id"]
+
+    # D4: all three query types, but the target name appears only in the panel
+    # names; the queries reference a decoy metric. The data prefilter matches
+    # (panel names contain the target), but parsing the queries must not associate
+    # the target metric, so this dashboard must be excluded from the result.
+    response = requests.post(
+        signoz.self.host_configs["8080"].get(BASE_URL),
+        json={
+            "schemaVersion": "v6",
+            "name": "by-metric-false-positive",
+            "spec": {
+                "display": {"name": "by-metric-false-positive"},
+                "panels": {
+                    "p-builder": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": f"{target_metric} builder"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/BuilderQuery",
+                                            "spec": {
+                                                "name": "A",
+                                                "signal": "metrics",
+                                                "aggregations": [
+                                                    {
+                                                        "metricName": decoy_metric,
+                                                        "timeAggregation": "rate",
+                                                        "spaceAggregation": "sum",
+                                                    }
+                                                ],
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    },
+                    "p-ch": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": f"{target_metric} clickhouse"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/ClickHouseSQL",
+                                            "spec": {
+                                                "name": "A",
+                                                "query": f"select * from signoz_metrics.distributed_samples_v4 where metric_name IN ['{decoy_metric}']",
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    },
+                    "p-promql": {
+                        "kind": "Panel",
+                        "spec": {
+                            "display": {"name": f"{target_metric} promql"},
+                            "plugin": {"kind": "signoz/TimeSeriesPanel", "spec": {}},
+                            "queries": [
+                                {
+                                    "kind": "time_series",
+                                    "spec": {
+                                        "plugin": {
+                                            "kind": "signoz/PromQLQuery",
+                                            "spec": {
+                                                "name": "A",
+                                                "query": f'sum(rate({{"{decoy_metric}"}}[5m]))',
+                                            },
+                                        }
+                                    },
+                                }
+                            ],
+                        },
+                    },
+                },
+            },
+            "tags": [],
+        },
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert response.status_code == HTTPStatus.CREATED, response.text
+    d4_id = response.json()["data"]["id"]
+
+    response = requests.get(
+        signoz.self.host_configs["8080"].get("/api/v3/metrics/dashboards"),
+        params={"metricName": target_metric},
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=5,
+    )
+    assert response.status_code == HTTPStatus.OK, response.text
+    dashboards = response.json()["data"]["dashboards"]
+
+    # No dashboard/panel should be returned more than once.
+    pairs = [(d["dashboardId"], d["panelId"]) for d in dashboards]
+    assert len(pairs) == len(set(pairs))
+
+    # D1 (1 panel) + D2 (2 panels) + D3 (1 promql panel) match; D4 (target only in
+    # panel names) does not.
+    assert {d["dashboardId"] for d in dashboards} == {d1_id, d2_id, d3_id}
+    assert d4_id not in {d["dashboardId"] for d in dashboards}
+
+    by_dashboard: dict[str, list[str]] = {}
+    for d in dashboards:
+        by_dashboard.setdefault(d["dashboardId"], []).append(d["panelName"])
+    assert sorted(by_dashboard[d1_id]) == ["D1 builder target"]
+    assert sorted(by_dashboard[d2_id]) == ["D2 clickhouse target", "D2 promql target"]
+    assert sorted(by_dashboard[d3_id]) == ["D3 promql target"]

tests/integration/tests/querier/01_logs.py

@@ -2306,9 +2306,11 @@ def test_logs_list_filter_by_trace_id(
     """
     Tests that filtering logs by trace_id uses the trace_summary lookup to
     narrow the query window before scanning the logs table:
-    1. Returns the matching log (narrow window, single bucket).
+    1. Returns the matching logs (narrow window, single bucket), including a log
+       flushed shortly after the span ends — kept by the configured padding.
     2. Does not return duplicate logs when the query window should span multiple
-       exponential buckets (>1 h). But is clamped to the timerange of trace.
+       exponential buckets (>1 h). The window is clamped to the trace's recorded
+       range widened by the padding, so the post-span log survives the clamp.
     3. Returns no results when the query window does not contain the trace.
     4. Logs carrying a trace_id whose trace is NOT in trace_summary (e.g.
        traces disabled) are still returned — the lookup miss must not
@@ -2366,6 +2368,9 @@ def test_logs_list_filter_by_trace_id(
     # Insert logs:
     # - one with the target trace_id, at a timestamp within the trace's
     #   recorded window (now-10s..now-5s, padded ±1s).
+    # - one with the target trace_id flushed ~3s AFTER the span's recorded end
+    #   (now-2s). This is outside the ±1s base pad but inside the multi-minute
+    #   log_trace_id_window_padding, so it must still be returned.
     # - one with an orphan trace_id whose trace was never ingested — used to
     #   verify the lookup miss does NOT short-circuit logs queries.
     insert_logs(
@@ -2379,6 +2384,15 @@ def test_logs_list_filter_by_trace_id(
                 trace_id=target_trace_id,
                 span_id=target_root_span_id,
             ),
+            Logs(
+                timestamp=now - timedelta(seconds=2),
+                resources=common_resources,
+                attributes={"http.method": "POST"},
+                body="log flushed after the span ends, within padding window",
+                severity_text="INFO",
+                trace_id=target_trace_id,
+                span_id=target_root_span_id,
+            ),
             Logs(
                 timestamp=now - timedelta(seconds=2),
                 resources=common_resources,
@@ -2429,23 +2443,31 @@ def test_logs_list_filter_by_trace_id(
 
     now_ms = int(now.timestamp() * 1000)
 
+    inside_window_body = "log inside the target trace window"
+    post_span_body = "log flushed after the span ends, within padding window"
+
     # --- Test 1: narrow window (single bucket, <1 h) ---
     narrow_start_ms = int((now - timedelta(minutes=5)).timestamp() * 1000)
     narrow_rows, narrow_warnings = _query(narrow_start_ms, now_ms, target_trace_id)
 
-    assert len(narrow_rows) == 1, f"Expected 1 log for trace_id filter (narrow window), got {len(narrow_rows)}"
-    assert narrow_rows[0]["data"]["trace_id"] == target_trace_id
-    assert narrow_rows[0]["data"]["span_id"] == target_root_span_id
+    assert len(narrow_rows) == 2, f"Expected 2 logs for trace_id filter (narrow window), got {len(narrow_rows)}"
+    assert {r["data"]["trace_id"] for r in narrow_rows} == {target_trace_id}
+    narrow_bodies = {r["data"]["body"] for r in narrow_rows}
+    assert inside_window_body in narrow_bodies
+    assert post_span_body in narrow_bodies, "post-span log should be returned within the padding window"
     assert not any(outside_range_msg in m for m in narrow_warnings), f"Did not expect outside-range warning, got {narrow_warnings}"
 
-    # --- Test 2: wide window (>1 h, clamp to the timerange from trace_summary) ---
-    # Should still return exactly one log — no duplicates from multi-bucket scan.
+    # --- Test 2: wide window (>1 h, clamp to the padded timerange from trace_summary) ---
+    # Should return exactly the two target logs — no duplicates from multi-bucket
+    # scan, and the post-span log survives the clamp only because of the padding.
     wide_start_ms = int((now - timedelta(hours=12)).timestamp() * 1000)
     wide_rows, wide_warnings = _query(wide_start_ms, now_ms, target_trace_id)
 
-    assert len(wide_rows) == 1, f"Expected 1 log for trace_id filter (wide window, multi-bucket), got {len(wide_rows)} — possible duplicate-log regression"
-    assert wide_rows[0]["data"]["trace_id"] == target_trace_id
-    assert wide_rows[0]["data"]["span_id"] == target_root_span_id
+    assert len(wide_rows) == 2, f"Expected 2 logs for trace_id filter (wide window, multi-bucket), got {len(wide_rows)} — possible duplicate-log regression or padding not applied"
+    assert {r["data"]["trace_id"] for r in wide_rows} == {target_trace_id}
+    wide_bodies = {r["data"]["body"] for r in wide_rows}
+    assert inside_window_body in wide_bodies
+    assert post_span_body in wide_bodies, "post-span log should survive the clamp because of the padding"
     assert not any(outside_range_msg in m for m in wide_warnings), f"Did not expect outside-range warning, got {wide_warnings}"
 
     # --- Test 3: window that does not contain the trace returns no results + warning ---

tests/integration/tests/querier/03_metrics.py

@@ -15,7 +15,6 @@ from fixtures.querier import (
     build_builder_query,
     find_named_result,
     get_all_warnings,
-    get_error_message,
     index_series_by_label,
     make_query_request,
 )