Merge branch 'feat/ai-trace-thread' into feat/ai-trace-thread-normalize

<!--A few plain bullets saying what changed and why, for a reviewer
skimming it - not a wall of text, not a restatement of the diff, not
generated boilerplate.-->
#### Description

`max_over_time` expects a range vector as input, which is `labels ->
[(timestamp,value),...]`. it turns each entry into
`labelsWith__name__removed -> maxOfAllValues`.

However, if two entries have `labelsWith__name__removed` as the same,
then `max_over_time` throws an error. For eg if the input is:
1. {"host":"a", "__name__": "transpiled_1"} -> ....
2. {"host":"a", "__name__": "transpiled_2"} -> ....
then `max_over_time` will break.

Currently, `executeHybrid` in
`pkg/prometheus/clickhouseprometheusv2/transpiler_exec.go` always puts
in the `__name__` label as `signoz_transpiled_*`, which can lead to the
above scenario.

Removing this `__name__` label fixes that issue. Also, nothing ever
needs this label. When the engine asks for `signoz_transpiled_0`, our
storage finds the data with a map lookup on that name and returns it.
The series' own labels play no part in the lookup.

After this change, no synthetic `__name__` exists anymore. So, the code
that stripped it after the engine ran, and `mergeMatrixByLabelset`,
which re-merged the rows those names had split, are deleted. The
engine's own merging handles this now.

<!--Reference issues using `Closes #issue-number` to enable automatic
closure on merge. -->
#### Issues closed by this PR

Closes https://github.com/SigNoz/pulse-pod/issues/508

<!--If applicable, include screenshots or screen recordings that clearly
show the behavior before the change and the result after the change. -->
#### Screenshots / Screen Recordings

<!--Anything reviewers should keep in mind while reviewing -->
#### Additional Information

<!--Please delete paragraphs that you did not use before submitting.-->

---------

Co-authored-by: Srikanth Chekuri <srikanth.chekuri92@gmail.com>

.github/workflows/goci.yaml

@@ -67,7 +67,7 @@ jobs:
         with:
           go-version: "1.24"
       - name: check-semconv-generated-files
-        run: go run ./scripts/semconv -check
+        run: make semconv-check
   build:
     if: |
       github.event_name == 'merge_group' ||

.github/workflows/integrationci.yaml

@@ -68,6 +68,7 @@ jobs:
           - semconvfamilies
           - serviceaccount
           - spanmapper
+          - tracedetail
           - querier_json_body
           - querier_skip_resource_fingerprint
           - ttl

Makefile

@@ -262,6 +262,10 @@ py-clean: ## Clear all pycache and pytest cache from tests directory recursively
 semconv-generate: ## Regenerate semantic-convention families for Go and TypeScript
 	@go run ./scripts/semconv
 
+.PHONY: semconv-check
+semconv-check: ## Fail if the generated semantic-convention files are stale
+	@go run ./scripts/semconv -check
+
 .PHONY: gen-mocks
 gen-mocks:
 	@echo ">> Generating mocks"

docs/api/openapi.yml

@@ -1,5 +1,44 @@
 components:
   schemas:
+    AiobservabilitytypesMessage:
+      properties:
+        content:
+          items:
+            $ref: '#/components/schemas/AiobservabilitytypesPart'
+          type: array
+        finishReason:
+          type: string
+        role:
+          type: string
+      required:
+      - content
+      type: object
+    AiobservabilitytypesPart:
+      properties:
+        arguments: {}
+        content:
+          type: string
+        id:
+          type: string
+        isError:
+          type: boolean
+        name:
+          type: string
+        toolCallId:
+          type: string
+        type:
+          $ref: '#/components/schemas/AiobservabilitytypesPartType'
+      required:
+      - type
+      type: object
+    AiobservabilitytypesPartType:
+      enum:
+      - text
+      - thinking
+      - tool_call
+      - tool_result
+      - generic
+      type: string
     AlertmanagertypesChannel:
       properties:
         createdAt:
@@ -9693,6 +9732,19 @@ components:
       required:
       - aggregations
       type: object
+    SpantypesGettableTraceThread:
+      properties:
+        nextCursor:
+          type: string
+        prevCursor:
+          type: string
+        spans:
+          items:
+            $ref: '#/components/schemas/SpantypesThreadSpan'
+          type: array
+      required:
+      - spans
+      type: object
     SpantypesGettableWaterfallTrace:
       properties:
         endTimestampMillis:
@@ -10007,6 +10059,92 @@ components:
           nullable: true
           type: object
       type: object
+    SpantypesThreadSpan:
+      properties:
+        attributes:
+          additionalProperties: {}
+          nullable: true
+          type: object
+        db_name:
+          type: string
+        db_operation:
+          type: string
+        duration_nano:
+          minimum: 0
+          type: integer
+        events:
+          items:
+            $ref: '#/components/schemas/SpantypesEvent'
+          nullable: true
+          type: array
+        external_http_method:
+          type: string
+        external_http_url:
+          type: string
+        flags:
+          minimum: 0
+          type: integer
+        formatted_input:
+          items:
+            $ref: '#/components/schemas/AiobservabilitytypesMessage'
+          type: array
+        formatted_output:
+          items:
+            $ref: '#/components/schemas/AiobservabilitytypesMessage'
+          type: array
+        has_children:
+          type: boolean
+        has_error:
+          type: boolean
+        http_host:
+          type: string
+        http_method:
+          type: string
+        http_url:
+          type: string
+        is_remote:
+          type: string
+        kind_string:
+          type: string
+        level:
+          minimum: 0
+          type: integer
+        name:
+          type: string
+        parent_span_id:
+          type: string
+        references:
+          items:
+            $ref: '#/components/schemas/SpantypesOtelSpanRef'
+          type: array
+        resource:
+          additionalProperties:
+            type: string
+          nullable: true
+          type: object
+        response_status_code:
+          type: string
+        span_id:
+          type: string
+        status_code:
+          type: integer
+        status_code_string:
+          type: string
+        status_message:
+          type: string
+        sub_tree_node_count:
+          minimum: 0
+          type: integer
+        time_unix:
+          minimum: 0
+          type: integer
+        trace_id:
+          type: string
+        trace_state:
+          type: string
+      required:
+      - references
+      type: object
     SpantypesUpdatableSpanMapper:
       properties:
         config:
@@ -15731,6 +15869,90 @@ paths:
       tags:
       - tracedetail
       x-signoz-stability: alpha
+  /api/v1/traces/{traceID}/thread:
+    get:
+      deprecated: false
+      description: Returns the spans carrying gen_ai input or output messages in timestamp
+        order, each with the messages normalised into formatted_input and formatted_output.
+        Pass nextCursor as after or prevCursor as before to page, or spanId to open
+        the page around a span.
+      operationId: GetTraceThread
+      parameters:
+      - in: query
+        name: limit
+        schema:
+          type: integer
+      - in: query
+        name: after
+        schema:
+          type: string
+      - in: query
+        name: before
+        schema:
+          type: string
+      - in: query
+        name: spanId
+        schema:
+          type: string
+      - in: path
+        name: traceID
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    $ref: '#/components/schemas/SpantypesGettableTraceThread'
+                  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 thread view for a trace
+      tags:
+      - tracedetail
+      x-signoz-stability: alpha
   /api/v1/user/me:
     get:
       deprecated: true

docs/contributing/query-range.md

@@ -84,9 +84,9 @@ A storage answers four questions and nothing else:
 | WhenAbsent | Absent row reads | Positive filter | Raw select | Multi-candidate column | Field keys |
 |---|---|---|---|---|---|
 | `AlwaysPresent` | a real value | no guard | no guard | no branch, ends the candidate list | table columns |
-| `AbsentIsSentinel` | `''`, 0, false, and that is not a value | exists guard | exists guard | presence branch | map attributes, cast JSON paths, string families |
+| `AbsentIsSentinel` | `''`, 0, false, and that is not a value | exists guard | exists guard | presence branch | map attributes, cast JSON paths, string families of such members |
 | `AbsentIsNull` | NULL | no guard | no guard | presence branch | multi-era folds, body JSON paths, numeric families |
-| `AbsentIsValue` | `''`, and that is the keyless contract | no guard | no guard | no presence branch | metrics labels, rule state history labels |
+| `AbsentIsValue` | `''`, and that is the keyless contract | no guard | no guard | no presence branch | metrics labels, rule state history labels, and families of such members |
 
 ### The generic layer
 
@@ -109,7 +109,7 @@ The functions, from the outside in:
 | `RejectsBodyFunction(traits, operator)` | Runs before resolution. A storage without body functions (`has`, `hasAny`, `hasAll`, `hasToken`, `search`) errors. The fingerprint side of a split skips the term, because the main query evaluates it. After resolution, `Condition` errors when `has`, `hasAny`, `hasAll`, or `hasToken` lands on a map-backed key (resource, attribute, scope), before the split can drop it. |
 | `SharedCondition(...)` | The `Compile` of every storage without its own condition language: `LogicalRead`, the shared data-type collision cast, `OperatorCondition`, then the guard rule. |
 | `OperatorCondition(...)` | The operator switch over an already cast read. A storage with its own cast policy composes with it. |
-| `LogicalRead(...)` | The only place family expressions are built. A single-member field reads through its member. A family merges the member reads, current member first: `COALESCE(NULLIF(m1, ''), NULLIF(m2, ''), '')` for strings, `multiIf` with a NULL tail for numbers. It ORs the member presence tests. A row without any member reads what the tail of the merge reads. A member with a value map reads through `TransformRead`. `NOT EXISTS` is the read's `Absence`, the storage's own negated form. |
+| `LogicalRead(...)` | The only place family expressions are built. A single-member field reads through its member. A family merges the member reads, current member first: `COALESCE(NULLIF(m1, ''), NULLIF(m2, ''), '')` for strings, `multiIf` with a NULL tail for numbers. It ORs the member presence tests. A row without any member reads what the tail of the merge reads. When every member reads its sentinel as a value, so does the family. A member with a value map reads through `TransformRead`. `NOT EXISTS` is the read's `Absence`, the storage's own negated form. |
 
 ### A resolved key
 

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

@@ -4,6 +4,53 @@
  * * regenerate with 'pnpm generate:api'
  * SigNoz
  */
+export enum AiobservabilitytypesPartTypeDTO {
+	text = 'text',
+	thinking = 'thinking',
+	tool_call = 'tool_call',
+	tool_result = 'tool_result',
+	generic = 'generic',
+}
+export interface AiobservabilitytypesPartDTO {
+	arguments?: unknown;
+	/**
+	 * @type string
+	 */
+	content?: string;
+	/**
+	 * @type string
+	 */
+	id?: string;
+	/**
+	 * @type boolean
+	 */
+	isError?: boolean;
+	/**
+	 * @type string
+	 */
+	name?: string;
+	/**
+	 * @type string
+	 */
+	toolCallId?: string;
+	type: AiobservabilitytypesPartTypeDTO;
+}
+
+export interface AiobservabilitytypesMessageDTO {
+	/**
+	 * @type array
+	 */
+	content: AiobservabilitytypesPartDTO[];
+	/**
+	 * @type string
+	 */
+	finishReason?: string;
+	/**
+	 * @type string
+	 */
+	role?: string;
+}
+
 export interface AlertmanagertypesChannelDTO {
 	/**
 	 * @type string
@@ -11209,6 +11256,169 @@ export interface SpantypesOtelSpanRefDTO {
 	traceId?: string;
 }
 
+export type SpantypesThreadSpanDTOAttributesAnyOf = { [key: string]: unknown };
+
+/**
+ * @nullable
+ */
+export type SpantypesThreadSpanDTOAttributes =
+	SpantypesThreadSpanDTOAttributesAnyOf | null;
+
+export type SpantypesThreadSpanDTOResourceAnyOf = { [key: string]: string };
+
+/**
+ * @nullable
+ */
+export type SpantypesThreadSpanDTOResource =
+	SpantypesThreadSpanDTOResourceAnyOf | null;
+
+export interface SpantypesThreadSpanDTO {
+	/**
+	 * @type object,null
+	 */
+	attributes?: SpantypesThreadSpanDTOAttributes;
+	/**
+	 * @type string
+	 */
+	db_name?: string;
+	/**
+	 * @type string
+	 */
+	db_operation?: string;
+	/**
+	 * @type integer
+	 * @minimum 0
+	 */
+	duration_nano?: number;
+	/**
+	 * @type array,null
+	 */
+	events?: SpantypesEventDTO[] | null;
+	/**
+	 * @type string
+	 */
+	external_http_method?: string;
+	/**
+	 * @type string
+	 */
+	external_http_url?: string;
+	/**
+	 * @type integer
+	 * @minimum 0
+	 */
+	flags?: number;
+	/**
+	 * @type array
+	 */
+	formatted_input?: AiobservabilitytypesMessageDTO[];
+	/**
+	 * @type array
+	 */
+	formatted_output?: AiobservabilitytypesMessageDTO[];
+	/**
+	 * @type boolean
+	 */
+	has_children?: boolean;
+	/**
+	 * @type boolean
+	 */
+	has_error?: boolean;
+	/**
+	 * @type string
+	 */
+	http_host?: string;
+	/**
+	 * @type string
+	 */
+	http_method?: string;
+	/**
+	 * @type string
+	 */
+	http_url?: string;
+	/**
+	 * @type string
+	 */
+	is_remote?: string;
+	/**
+	 * @type string
+	 */
+	kind_string?: string;
+	/**
+	 * @type integer
+	 * @minimum 0
+	 */
+	level?: number;
+	/**
+	 * @type string
+	 */
+	name?: string;
+	/**
+	 * @type string
+	 */
+	parent_span_id?: string;
+	/**
+	 * @type array
+	 */
+	references: SpantypesOtelSpanRefDTO[];
+	/**
+	 * @type object,null
+	 */
+	resource?: SpantypesThreadSpanDTOResource;
+	/**
+	 * @type string
+	 */
+	response_status_code?: string;
+	/**
+	 * @type string
+	 */
+	span_id?: string;
+	/**
+	 * @type integer
+	 */
+	status_code?: number;
+	/**
+	 * @type string
+	 */
+	status_code_string?: string;
+	/**
+	 * @type string
+	 */
+	status_message?: string;
+	/**
+	 * @type integer
+	 * @minimum 0
+	 */
+	sub_tree_node_count?: number;
+	/**
+	 * @type integer
+	 * @minimum 0
+	 */
+	time_unix?: number;
+	/**
+	 * @type string
+	 */
+	trace_id?: string;
+	/**
+	 * @type string
+	 */
+	trace_state?: string;
+}
+
+export interface SpantypesGettableTraceThreadDTO {
+	/**
+	 * @type string
+	 */
+	nextCursor?: string;
+	/**
+	 * @type string
+	 */
+	prevCursor?: string;
+	/**
+	 * @type array
+	 */
+	spans: SpantypesThreadSpanDTO[];
+}
+
 export type SpantypesWaterfallSpanDTOAttributesAnyOf = {
 	[key: string]: unknown;
 };
@@ -12882,6 +13092,40 @@ export type GetTraceAggregations200 = {
 	status: string;
 };
 
+export type GetTraceThreadPathParameters = {
+	traceID: string;
+};
+export type GetTraceThreadParams = {
+	/**
+	 * @type integer
+	 * @description undefined
+	 */
+	limit?: number;
+	/**
+	 * @type string
+	 * @description undefined
+	 */
+	after?: string;
+	/**
+	 * @type string
+	 * @description undefined
+	 */
+	before?: string;
+	/**
+	 * @type string
+	 * @description undefined
+	 */
+	spanId?: string;
+};
+
+export type GetTraceThread200 = {
+	data: SpantypesGettableTraceThreadDTO;
+	/**
+	 * @type string
+	 */
+	status: string;
+};
+
 export type ListUserPreferences200 = {
 	/**
 	 * @type array

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

@@ -4,11 +4,17 @@
  * * regenerate with 'pnpm generate:api'
  * SigNoz
  */
-import { useMutation } from 'react-query';
+import { useMutation, useQuery } from 'react-query';
 import type {
+	InvalidateOptions,
 	MutationFunction,
+	QueryClient,
+	QueryFunction,
+	QueryKey,
 	UseMutationOptions,
 	UseMutationResult,
+	UseQueryOptions,
+	UseQueryResult,
 } from 'react-query';
 
 import type {
@@ -16,6 +22,9 @@ import type {
 	GetFlamegraphPathParameters,
 	GetTraceAggregations200,
 	GetTraceAggregationsPathParameters,
+	GetTraceThread200,
+	GetTraceThreadParams,
+	GetTraceThreadPathParameters,
 	GetWaterfallV4200,
 	GetWaterfallV4PathParameters,
 	RenderErrorResponseDTO,
@@ -27,6 +36,26 @@ import type {
 import { GeneratedAPIInstance } from '../../../generatedAPIInstance';
 import type { ErrorType, BodyType } from '../../../generatedAPIInstance';
 
+const withQueryKey = <T extends object, K>(
+	query: T,
+	queryKey: K,
+): T & { queryKey: K } => {
+	const result = { queryKey } as T & { queryKey: K };
+	for (const key of Object.keys(query)) {
+		// The explicit queryKey always wins, matching the previous
+		// `{ ...query, queryKey }` spread where it was set last.
+		if (key === 'queryKey') {
+			continue;
+		}
+		Object.defineProperty(result, key, {
+			enumerable: true,
+			configurable: true,
+			get: () => (query as Record<string, unknown>)[key],
+		});
+	}
+	return result;
+};
+
 /**
  * Computes span aggregations grouped by requested field.
  * @summary Get aggregations for a trace
@@ -127,6 +156,121 @@ export const useGetTraceAggregations = <
 > => {
 	return useMutation(getGetTraceAggregationsMutationOptions(options));
 };
+/**
+ * Returns the spans carrying gen_ai input or output messages in timestamp order, each with the messages normalised into formatted_input and formatted_output. Pass nextCursor as after or prevCursor as before to page, or spanId to open the page around a span.
+ * @summary Get thread view for a trace
+ */
+export const getTraceThread = (
+	{ traceID }: GetTraceThreadPathParameters,
+	params?: GetTraceThreadParams,
+	signal?: AbortSignal,
+) => {
+	return GeneratedAPIInstance<GetTraceThread200>({
+		url: `/api/v1/traces/${traceID}/thread`,
+		method: 'GET',
+		params,
+		signal,
+	});
+};
+
+export const getGetTraceThreadQueryKey = (
+	{ traceID }: GetTraceThreadPathParameters,
+	params?: GetTraceThreadParams,
+) => {
+	return [
+		`/api/v1/traces/${traceID}/thread`,
+		...(params ? [params] : []),
+	] as const;
+};
+
+export const getGetTraceThreadQueryOptions = <
+	TData = Awaited<ReturnType<typeof getTraceThread>>,
+	TError = ErrorType<RenderErrorResponseDTO>,
+>(
+	{ traceID }: GetTraceThreadPathParameters,
+	params?: GetTraceThreadParams,
+	options?: {
+		query?: UseQueryOptions<
+			Awaited<ReturnType<typeof getTraceThread>>,
+			TError,
+			TData
+		>;
+	},
+) => {
+	const { query: queryOptions } = options ?? {};
+
+	const queryKey =
+		queryOptions?.queryKey ?? getGetTraceThreadQueryKey({ traceID }, params);
+
+	const queryFn: QueryFunction<Awaited<ReturnType<typeof getTraceThread>>> = ({
+		signal,
+	}) => getTraceThread({ traceID }, params, signal);
+
+	return {
+		queryKey,
+		queryFn,
+		enabled: traceID !== null && traceID !== undefined,
+		...queryOptions,
+	} as UseQueryOptions<
+		Awaited<ReturnType<typeof getTraceThread>>,
+		TError,
+		TData
+	> & { queryKey: QueryKey };
+};
+
+export type GetTraceThreadQueryResult = NonNullable<
+	Awaited<ReturnType<typeof getTraceThread>>
+>;
+export type GetTraceThreadQueryError = ErrorType<RenderErrorResponseDTO>;
+
+/**
+ * @summary Get thread view for a trace
+ */
+
+export function useGetTraceThread<
+	TData = Awaited<ReturnType<typeof getTraceThread>>,
+	TError = ErrorType<RenderErrorResponseDTO>,
+>(
+	{ traceID }: GetTraceThreadPathParameters,
+	params?: GetTraceThreadParams,
+	options?: {
+		query?: UseQueryOptions<
+			Awaited<ReturnType<typeof getTraceThread>>,
+			TError,
+			TData
+		>;
+	},
+): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
+	const queryOptions = getGetTraceThreadQueryOptions(
+		{ traceID },
+		params,
+		options,
+	);
+
+	const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & {
+		queryKey: QueryKey;
+	};
+
+	return withQueryKey(query, queryOptions.queryKey);
+}
+
+/**
+ * @summary Get thread view for a trace
+ */
+export const invalidateGetTraceThread = async (
+	queryClient: QueryClient,
+	{ traceID }: GetTraceThreadPathParameters,
+	params?: GetTraceThreadParams,
+	options?: InvalidateOptions,
+): Promise<QueryClient> => {
+	await queryClient.invalidateQueries(
+		{ queryKey: getGetTraceThreadQueryKey({ traceID }, params) },
+		options,
+	);
+
+	return queryClient;
+};
+
 /**
  * Returns the flamegraph view of spans for a given trace ID.
  * @summary Get flamegraph view for a trace

frontend/src/constants/generated/semconvFamilies.gen.ts

@@ -1,32 +1,82 @@
 // Code generated by scripts/semconv. DO NOT EDIT.
 
-export type SemconvFamily = {
-	readonly current: string;
-	readonly old: readonly string[];
-	readonly kind: 'attribute' | 'metric';
+// An empty contexts/signals/applyToMetrics array places no constraint on
+// that axis.
+export type SemconvMember = {
+	readonly name: string;
 	readonly contexts: readonly string[];
 	readonly signals: readonly string[];
 	readonly applyToMetrics: readonly string[];
+};
+
+export type SemconvFamily = {
+	readonly current: string;
+	readonly kind: 'attribute' | 'metric';
+	readonly members: readonly SemconvMember[];
+	readonly contexts: readonly string[];
+	readonly signals: readonly string[];
 	readonly valueMap: Readonly<Record<string, string>>;
 };
 
 export const SEMCONV_FAMILIES: readonly SemconvFamily[] = [
 	{
-		current: 'db.system.name',
-		old: ['db.system'],
-		kind: 'attribute',
+		current: 'container.cpu.usage',
+		kind: 'metric',
+		members: [
+			{
+				name: 'container.cpu.utilization',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
 		contexts: [],
 		signals: [],
-		applyToMetrics: [],
 		valueMap: {},
 	},
 	{
 		current: 'deployment.environment.name',
-		old: ['deployment.environment'],
 		kind: 'attribute',
+		members: [
+			{
+				name: 'deployment.environment',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
+		contexts: ['attribute', 'resource'],
+		signals: ['logs', 'metrics', 'traces'],
+		valueMap: {},
+	},
+	{
+		current: 'k8s.node.cpu.usage',
+		kind: 'metric',
+		members: [
+			{
+				name: 'k8s.node.cpu.utilization',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
+		contexts: [],
+		signals: [],
+		valueMap: {},
+	},
+	{
+		current: 'k8s.pod.cpu.usage',
+		kind: 'metric',
+		members: [
+			{
+				name: 'k8s.pod.cpu.utilization',
+				contexts: [],
+				signals: [],
+				applyToMetrics: [],
+			},
+		],
 		contexts: [],
 		signals: [],
-		applyToMetrics: [],
 		valueMap: {},
 	},
 ] as const;

frontend/src/container/AllError/__tests__/useExceptionsStripInfo.test.tsx

@@ -0,0 +1,53 @@
+import { renderHook } from '@testing-library/react';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useExceptionsStripInfo } from '../useExceptionsStripInfo';
+
+describe('useExceptionsStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('shows the rows on the page against the total', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 25, totalCount: 500 }));
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '25 of 500 exceptions' },
+		]);
+	});
+
+	it('still says n of m when the whole list fits on one page', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 42, totalCount: 42 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '42 of 42 exceptions',
+		});
+	});
+
+	it('says exception, not exceptions, when there is one', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 1, totalCount: 1 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 of 1 exception',
+		});
+	});
+
+	it('shows zero before the counts land', () => {
+		renderHook(() => useExceptionsStripInfo({ shownCount: 0, totalCount: 0 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 of 0 exceptions',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		const { unmount } = renderHook(() =>
+			useExceptionsStripInfo({ shownCount: 25, totalCount: 500 }),
+		);
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/AllError/index.tsx

@@ -38,6 +38,7 @@ import { Exception, PayloadProps } from 'types/api/errors/getAll';
 import { GlobalReducer } from 'types/reducer/globalTime';
 
 import { FilterDropdownExtendsProps } from './types';
+import { useExceptionsStripInfo } from './useExceptionsStripInfo';
 import {
 	extractFilterValues,
 	getDefaultFilterValue,
@@ -160,6 +161,11 @@ function AllErrors(): JSX.Element {
 			},
 		]);
 
+	useExceptionsStripInfo({
+		shownCount: data?.payload?.length ?? 0,
+		totalCount: errorCountResponse.data?.payload ?? 0,
+	});
+
 	const isFetching = isErrorsFetching || errorCountResponse.isFetching;
 	useEffect(() => {
 		setIsFetching(isFetching);

frontend/src/container/AllError/useExceptionsStripInfo.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+interface UseExceptionsStripInfoArgs {
+	shownCount: number;
+	totalCount: number;
+}
+
+export function useExceptionsStripInfo({
+	shownCount,
+	totalCount,
+}: UseExceptionsStripInfoArgs): void {
+	const items = useMemo<StripItem[]>(
+		() => [
+			{
+				kind: StripItemKind.Text,
+				text: `${shownCount} of ${pluralize(totalCount, 'exception')}`,
+			},
+		],
+		[shownCount, totalCount],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/AppLayout/index.tsx

@@ -854,7 +854,9 @@ function AppLayout(props: AppLayoutProps): JSX.Element {
 					<ChangelogModal changelog={changelog} onClose={toggleChangelogModal} />
 				)}
 
-				<Toaster />
+				<Toaster
+					offset={{ bottom: 'calc(var(--bottom-strip-height, 0px) + 24px)' }}
+				/>
 			</Layout>
 		</TooltipProvider>
 	);

frontend/src/container/Home/Home.tsx

@@ -26,6 +26,7 @@ import { initialQueriesMap, PANEL_TYPES } from 'constants/queryBuilder';
 import { REACT_QUERY_KEY } from 'constants/reactQueryKeys';
 import ROUTES from 'constants/routes';
 import { DEFAULT_TIME_RANGE } from 'container/TopNav/DateTimeSelectionV2/constants';
+import { useHomeStripInfo } from 'container/Home/useHomeStripInfo';
 import { useGetQueryRange } from 'hooks/queryBuilder/useGetQueryRange';
 import { useIsDarkMode } from 'hooks/useDarkMode';
 import { useSafeNavigate } from 'hooks/useSafeNavigate';
@@ -64,6 +65,8 @@ const homeInterval = 30 * 60 * 1000;
 
 // eslint-disable-next-line sonarjs/cognitive-complexity
 export default function Home(): JSX.Element {
+	useHomeStripInfo();
+
 	const { user } = useAppContext();
 	const { safeNavigate } = useSafeNavigate();
 	const isDarkMode = useIsDarkMode();

frontend/src/container/Home/__tests__/useHomeStripInfo.test.tsx

@@ -0,0 +1,58 @@
+import { renderHook } from '@testing-library/react';
+import { useGetAlerts } from 'api/generated/services/alerts';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useHomeStripInfo } from '../useHomeStripInfo';
+
+jest.mock('api/generated/services/alerts', () => ({
+	useGetAlerts: jest.fn(),
+}));
+
+const mockUseGetAlerts = useGetAlerts as jest.Mock;
+
+describe('useHomeStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('counts the firing alert instances', () => {
+		mockUseGetAlerts.mockReturnValue({ data: { data: [{}, {}, {}] } });
+
+		renderHook(() => useHomeStripInfo());
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '3 alerts firing' },
+		]);
+	});
+
+	it('says alert, not alerts, when only one is firing', () => {
+		mockUseGetAlerts.mockReturnValue({ data: { data: [{}] } });
+
+		renderHook(() => useHomeStripInfo());
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 alert firing',
+		});
+	});
+
+	it('shows zero before the response lands', () => {
+		mockUseGetAlerts.mockReturnValue({ data: undefined });
+
+		renderHook(() => useHomeStripInfo());
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 alerts firing',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		mockUseGetAlerts.mockReturnValue({ data: { data: [{}, {}, {}] } });
+
+		const { unmount } = renderHook(() => useHomeStripInfo());
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/Home/useHomeStripInfo.ts

@@ -0,0 +1,21 @@
+import { useMemo } from 'react';
+import { useGetAlerts } from 'api/generated/services/alerts';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+export function useHomeStripInfo(): void {
+	// Firing instances, not rules, matching the triggered alerts page.
+	const { data } = useGetAlerts();
+
+	const count = data?.data?.length ?? 0;
+
+	const items = useMemo<StripItem[]>(
+		() => [
+			{ kind: StripItemKind.Text, text: `${pluralize(count, 'alert')} firing` },
+		],
+		[count],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/ListAlertRules/__tests__/useAlertRulesStripInfo.test.tsx

@@ -0,0 +1,53 @@
+import { renderHook } from '@testing-library/react';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useAlertRulesStripInfo } from '../useAlertRulesStripInfo';
+
+describe('useAlertRulesStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('shows the rows on the page against the total', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 15, totalCount: 17 }));
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '15 of 17 rules' },
+		]);
+	});
+
+	it('still says n of m when the whole list fits on one page', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 17, totalCount: 17 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '17 of 17 rules',
+		});
+	});
+
+	it('says rule, not rules, when there is only one', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 1, totalCount: 1 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 of 1 rule',
+		});
+	});
+
+	it('shows zero when nothing matched', () => {
+		renderHook(() => useAlertRulesStripInfo({ shownCount: 0, totalCount: 12 }));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 of 12 rules',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		const { unmount } = renderHook(() =>
+			useAlertRulesStripInfo({ shownCount: 15, totalCount: 17 }),
+		);
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/ListAlertRules/index.tsx

@@ -20,6 +20,7 @@ import { ALERT_RULES_PARAMS, useAlertRulesFilters } from './hooks';
 import styles from './ListAlertRules.module.scss';
 import { getAlertRuleColumns } from './table.config';
 import type { AlertRule } from './types';
+import { useAlertRulesStripInfo } from './useAlertRulesStripInfo';
 import { useAlertRulesData } from './useAlertRulesData';
 import { useAlertRulesHandlers } from './useAlertRulesHandlers';
 
@@ -87,6 +88,11 @@ function ListAlertRules(): JSX.Element {
 		return filteredRules.slice(start, start + limit);
 	}, [filteredRules, page, limit]);
 
+	useAlertRulesStripInfo({
+		shownCount: paginatedRules.length,
+		totalCount: filteredRules.length,
+	});
+
 	const columnsWithActions = useMemo(() => {
 		if (!action) {
 			return columns;

frontend/src/container/ListAlertRules/useAlertRulesStripInfo.ts

@@ -0,0 +1,27 @@
+import { useMemo } from 'react';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+interface UseAlertRulesStripInfoArgs {
+	/** Rows on the current page, matching the table's own footer. */
+	shownCount: number;
+	totalCount: number;
+}
+
+export function useAlertRulesStripInfo({
+	shownCount,
+	totalCount,
+}: UseAlertRulesStripInfoArgs): void {
+	const items = useMemo<StripItem[]>(
+		() => [
+			{
+				kind: StripItemKind.Text,
+				text: `${shownCount} of ${pluralize(totalCount, 'rule')}`,
+			},
+		],
+		[shownCount, totalCount],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/container/ResetPassword/__tests__/ResetPassword.test.tsx

@@ -155,6 +155,39 @@ describe('ResetPassword Component', () => {
 				{ timeout: 200 },
 			);
 		});
+
+		it('clears password mismatch error when confirm password is emptied', async () => {
+			const user = userEvent.setup({ pointerEventsCheck: 0 });
+
+			render(<ResetPassword version="1.0.0" />, undefined, {
+				initialRoute: '/password-reset?token=reset-token-123',
+			});
+
+			const passwordInput = screen.getByPlaceholderText(/enter new password/i);
+			const confirmPasswordInput = screen.getByPlaceholderText(
+				/confirm your new password/i,
+			);
+			const submitButton = screen.getByRole('button', {
+				name: /reset password/i,
+			});
+
+			await user.type(passwordInput, 'password123');
+			await user.type(confirmPasswordInput, 'password456');
+			await user.tab();
+
+			await waitFor(() => {
+				expect(screen.getByText(/passwords don't match/i)).toBeInTheDocument();
+			});
+
+			await user.clear(confirmPasswordInput);
+
+			await waitFor(() => {
+				expect(
+					screen.queryByText(/passwords don't match/i),
+				).not.toBeInTheDocument();
+				expect(submitButton).toBeDisabled();
+			});
+		});
 	});
 
 	describe('Successful Password Reset', () => {
@@ -288,6 +321,65 @@ describe('ResetPassword Component', () => {
 				expect(screen.queryByText(/invalid token/i)).not.toBeInTheDocument();
 			});
 		});
+
+		it('clears API error when the user edits the password', async () => {
+			const user = userEvent.setup({ pointerEventsCheck: 0 });
+
+			server.use(
+				rest.post(RESET_PASSWORD_ENDPOINT, (_req, res, ctx) =>
+					res(
+						ctx.status(400),
+						ctx.json({
+							error: {
+								code: 'invalid_password',
+								message: 'password must be at least 8 characters long',
+							},
+						}),
+					),
+				),
+			);
+
+			render(<ResetPassword version="1.0.0" />, undefined, {
+				initialRoute: '/password-reset?token=reset-token-123',
+			});
+
+			const passwordInput = screen.getByPlaceholderText(/enter new password/i);
+			const confirmPasswordInput = screen.getByPlaceholderText(
+				/confirm your new password/i,
+			);
+			const submitButton = screen.getByRole('button', {
+				name: /reset password/i,
+			});
+
+			await user.type(passwordInput, 'weak');
+			await user.type(confirmPasswordInput, 'weak');
+
+			await waitFor(() => {
+				expect(submitButton).not.toBeDisabled();
+			});
+
+			await user.click(submitButton);
+
+			await waitFor(() => {
+				expect(
+					screen.getByText(/password must be at least 8 characters long/i),
+				).toBeInTheDocument();
+			});
+
+			await user.type(passwordInput, 'Er1!');
+
+			await waitFor(() => {
+				expect(
+					screen.queryByText(/password must be at least 8 characters long/i),
+				).not.toBeInTheDocument();
+			});
+
+			await user.type(confirmPasswordInput, 'Er1!');
+
+			await waitFor(() => {
+				expect(submitButton).not.toBeDisabled();
+			});
+		});
 	});
 
 	describe('Loading States', () => {

frontend/src/container/ResetPassword/index.tsx

@@ -10,7 +10,6 @@ import { useResetPassword } from 'api/generated/services/users';
 import AuthError from 'components/AuthError/AuthError';
 import AuthPageContainer from 'components/AuthPageContainer';
 import ROUTES from 'constants/routes';
-import useDebouncedFn from 'hooks/useDebouncedFunction';
 import { useNotifications } from 'hooks/useNotifications';
 import history from 'lib/history';
 import { ArrowRight, CircleAlert, KeyRound } from '@signozhq/icons';
@@ -23,10 +22,7 @@ import './ResetPassword.styles.scss';
 type FormValues = { password: string; confirmPassword: string };
 
 function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
-	const [confirmPasswordError, setConfirmPasswordError] =
-		useState<boolean>(false);
-
-	const [isValidPassword, setIsValidPassword] = useState(false);
+	const [confirmPasswordTouched, setConfirmPasswordTouched] = useState(false);
 	const { t } = useTranslation(['common']);
 	const { search } = useLocation();
 	const params = new URLSearchParams(search);
@@ -37,6 +33,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 		mutate: resetPassword,
 		isLoading,
 		error: mutationError,
+		reset: resetMutation,
 	} = useResetPassword();
 
 	const errorMessage = useMemo(
@@ -45,11 +42,30 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 	);
 
 	const [form] = Form.useForm<FormValues>();
-	const handleFormSubmit = (): void => {
-		const { password } = form.getFieldsValue();
+	const password = Form.useWatch('password', form);
+	const confirmPassword = Form.useWatch('confirmPassword', form);
+
+	const isPasswordMismatch =
+		Boolean(confirmPassword) && password !== confirmPassword;
+	const showPasswordMismatchError = confirmPasswordTouched && isPasswordMismatch;
+	const isValidPassword =
+		Boolean(password?.trim()) &&
+		Boolean(confirmPassword?.trim()) &&
+		password === confirmPassword;
+
+	const handleValuesChange = (): void => {
+		if (mutationError) {
+			resetMutation();
+		}
+	};
+
+	const handleSubmit = (): void => {
+		if (!token) {
+			return;
+		}
 
 		resetPassword(
-			{ data: { password, token: token || '' } },
+			{ data: { password: form.getFieldValue('password'), token } },
 			{
 				onSuccess: (): void => {
 					notifications.success({
@@ -63,80 +79,6 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 		);
 	};
 
-	const validatePassword = (): boolean => {
-		const { password, confirmPassword } = form.getFieldsValue();
-
-		if (
-			password &&
-			confirmPassword &&
-			password.trim() &&
-			confirmPassword.trim() &&
-			password.length > 0 &&
-			confirmPassword.length > 0
-		) {
-			return password === confirmPassword;
-		}
-
-		return false;
-	};
-
-	const handleValuesChange = useDebouncedFn((): void => {
-		const { password, confirmPassword } = form.getFieldsValue();
-
-		if (!password || !confirmPassword) {
-			setIsValidPassword(false);
-		}
-
-		// Only clear error if passwords match while typing (but don't set error until blur)
-		if (
-			password &&
-			confirmPassword &&
-			password.trim() &&
-			confirmPassword.trim()
-		) {
-			const isValid = validatePassword();
-			setIsValidPassword(isValid);
-
-			// Only clear error if passwords match, don't set error on mismatch
-			if (isValid) {
-				setConfirmPasswordError(false);
-			}
-		}
-	}, 100);
-
-	const handlePasswordBlur = (): void => {
-		const { confirmPassword } = form.getFieldsValue();
-		// Only validate if confirm password has a value
-		if (confirmPassword && confirmPassword.trim()) {
-			const isValid = validatePassword();
-			setIsValidPassword(isValid);
-			setConfirmPasswordError(!isValid);
-		}
-	};
-
-	const handleConfirmPasswordBlur = (): void => {
-		const { password, confirmPassword } = form.getFieldsValue();
-		if (
-			password &&
-			password.trim() &&
-			confirmPassword &&
-			confirmPassword.trim()
-		) {
-			const isValid = validatePassword();
-			setIsValidPassword(isValid);
-			setConfirmPasswordError(!isValid);
-		}
-	};
-
-	const handleSubmit = (): void => {
-		const isValid = validatePassword();
-		setIsValidPassword(isValid);
-
-		if (token) {
-			handleFormSubmit();
-		}
-	};
-
 	return (
 		<AuthPageContainer>
 			<div className="reset-password-card">
@@ -158,6 +100,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 				<FormContainer
 					form={form}
 					onFinish={handleSubmit}
+					onValuesChange={handleValuesChange}
 					className="reset-password-form"
 				>
 					<div className="reset-password-form-container">
@@ -171,8 +114,6 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 								>
 									<AntdInput.Password
 										tabIndex={0}
-										onChange={handleValuesChange}
-										onBlur={handlePasswordBlur}
 										id="password"
 										data-testid="password"
 										placeholder="Enter new password"
@@ -189,8 +130,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 									rules={[{ required: true, message: 'Please enter confirm password!' }]}
 								>
 									<AntdInput.Password
-										onChange={handleValuesChange}
-										onBlur={handleConfirmPasswordBlur}
+										onBlur={(): void => setConfirmPasswordTouched(true)}
 										id="confirmPassword"
 										data-testid="confirmPassword"
 										placeholder="Confirm your new password"
@@ -201,7 +141,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 						</div>
 					</div>
 
-					{confirmPasswordError && (
+					{showPasswordMismatchError && (
 						<Callout
 							type="error"
 							size="small"
@@ -213,7 +153,7 @@ function ResetPassword({ version }: ResetPasswordProps): JSX.Element {
 						</Callout>
 					)}
 
-					{errorMessage && !confirmPasswordError && (
+					{errorMessage && !showPasswordMismatchError && (
 						<AuthError error={errorMessage} />
 					)}
 

frontend/src/container/ServiceApplication/ServiceMetrics/ServiceMetricTable.tsx

@@ -21,6 +21,7 @@ import { getTotalRPS } from 'utils/services';
 
 import { getColumns } from '../Columns/ServiceColumn';
 import { ServiceMetricsTableProps } from '../types';
+import { useServicesStripInfo } from '../useServicesStripInfo';
 import { getServiceListFromQuery } from '../utils';
 
 function ServiceMetricTable({
@@ -67,6 +68,8 @@ function ServiceMetricTable({
 		[isLoading, queries, topLevelOperations],
 	);
 
+	useServicesStripInfo(services.length);
+
 	const { search } = useLocation();
 	const tableColumns = useMemo(() => getColumns(search, true), [search]);
 	const [RPS, setRPS] = useState(0);

frontend/src/container/ServiceApplication/ServiceTraces/index.tsx

@@ -18,6 +18,7 @@ import { GlobalReducer } from 'types/reducer/globalTime';
 import { Tags } from 'hooks/useResourceAttribute/types';
 
 import SkipOnBoardingModal from '../SkipOnBoardModal';
+import { useServicesStripInfo } from '../useServicesStripInfo';
 import ServiceTraceTable from './ServiceTracesTable';
 
 function ServiceTraces(): JSX.Element {
@@ -42,6 +43,8 @@ function ServiceTraces(): JSX.Element {
 
 	const services = data || [];
 
+	useServicesStripInfo(services.length);
+
 	const [skipOnboarding, setSkipOnboarding] = useState(
 		localStorageGet(SKIP_ONBOARDING) === 'true',
 	);

frontend/src/container/ServiceApplication/__tests__/useServicesStripInfo.test.tsx

@@ -0,0 +1,43 @@
+import { renderHook } from '@testing-library/react';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useServicesStripInfo } from '../useServicesStripInfo';
+
+describe('useServicesStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('shows how many services are listed', () => {
+		renderHook(() => useServicesStripInfo(18));
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '18 services' },
+		]);
+	});
+
+	it('says service, not services, when there is one', () => {
+		renderHook(() => useServicesStripInfo(1));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 service',
+		});
+	});
+
+	it('shows zero when there are none', () => {
+		renderHook(() => useServicesStripInfo(0));
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 services',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		const { unmount } = renderHook(() => useServicesStripInfo(18));
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/container/ServiceApplication/useServicesStripInfo.ts

@@ -0,0 +1,13 @@
+import { useMemo } from 'react';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+export function useServicesStripInfo(count: number): void {
+	const items = useMemo<StripItem[]>(
+		() => [{ kind: StripItemKind.Text, text: pluralize(count, 'service') }],
+		[count],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/pages/AIAssistantPage/AIAssistantPage.tsx

@@ -11,6 +11,8 @@ import { useAIAssistantStore } from 'container/AIAssistant/store/useAIAssistantS
 import { VariantContext } from 'container/AIAssistant/VariantContext';
 import Noz from 'components/Noz/Noz';
 
+import { useAIAssistantStripInfo } from './useAIAssistantStripInfo';
+
 import styles from './AIAssistantPage.module.scss';
 import ConversationsList from 'container/AIAssistant/components/ConversationsList';
 
@@ -41,6 +43,8 @@ export default function AIAssistantPage(): JSX.Element {
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, []);
 
+	useAIAssistantStripInfo();
+
 	const conversations = useAIAssistantStore((s) => s.conversations);
 	const activeConversationId = useAIAssistantStore(
 		(s) => s.activeConversationId,

frontend/src/pages/AIAssistantPage/__tests__/useAIAssistantStripInfo.test.tsx

@@ -0,0 +1,60 @@
+import { renderHook } from '@testing-library/react';
+import { useAIAssistantStore } from 'container/AIAssistant/store/useAIAssistantStore';
+import { useBottomStripStore } from 'container/BottomStrip/store/useBottomStripStore';
+import { StripItemKind } from 'container/BottomStrip/types';
+
+import { useAIAssistantStripInfo } from '../useAIAssistantStripInfo';
+
+function seed(conversations: Record<string, unknown>): void {
+	useAIAssistantStore.setState({ conversations } as never);
+}
+
+describe('useAIAssistantStripInfo', () => {
+	beforeEach(() => {
+		useBottomStripStore.setState({ left: null, ownerId: null });
+	});
+
+	it('counts only the conversations that are not archived', () => {
+		seed({
+			a: { id: 'a' },
+			b: { id: 'b' },
+			c: { id: 'c', archived: true },
+		});
+
+		renderHook(() => useAIAssistantStripInfo());
+
+		expect(useBottomStripStore.getState().left).toMatchObject([
+			{ kind: StripItemKind.Text, text: '2 conversations' },
+		]);
+	});
+
+	it('says one conversation, not 1 conversations', () => {
+		seed({ a: { id: 'a' } });
+
+		renderHook(() => useAIAssistantStripInfo());
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '1 conversation',
+		});
+	});
+
+	it('shows zero when there are none', () => {
+		seed({});
+
+		renderHook(() => useAIAssistantStripInfo());
+
+		expect(useBottomStripStore.getState().left?.[0]).toMatchObject({
+			text: '0 conversations',
+		});
+	});
+
+	it('clears the strip when the page unmounts', () => {
+		seed({ a: { id: 'a' } });
+
+		const { unmount } = renderHook(() => useAIAssistantStripInfo());
+
+		unmount();
+
+		expect(useBottomStripStore.getState().left).toBeNull();
+	});
+});

frontend/src/pages/AIAssistantPage/stories/AIAssistantPage.stories.tsx

@@ -243,3 +243,11 @@ export const TooltipsInApprovalDiff: Story = {
 	args: { tooltipsOpen: true, agent: 'awaiting-approval', contents: BRIEF },
 	play: openApprovalDiff,
 };
+
+/**
+ * The conversation count in the bottom strip, in place of the build version.
+ * Archived threads are left out of it.
+ */
+export const BottomStrip: Story = {
+	args: { bottomStrip: true },
+};

frontend/src/pages/AIAssistantPage/useAIAssistantStripInfo.ts

@@ -0,0 +1,20 @@
+import { useMemo } from 'react';
+import { useAIAssistantStore } from 'container/AIAssistant/store/useAIAssistantStore';
+import { useBottomStrip } from 'container/BottomStrip/useBottomStrip';
+import { type StripItem, StripItemKind } from 'container/BottomStrip/types';
+import { pluralize } from 'utils/pluralize';
+
+export function useAIAssistantStripInfo(): void {
+	const conversations = useAIAssistantStore((state) => state.conversations);
+
+	const count = Object.values(conversations).filter(
+		(conversation) => !conversation.archived,
+	).length;
+
+	const items = useMemo<StripItem[]>(
+		() => [{ kind: StripItemKind.Text, text: pluralize(count, 'conversation') }],
+		[count],
+	);
+
+	useBottomStrip(items);
+}

frontend/src/pages/AlertList/AlertRules/stories/AlertRules.stories.tsx

@@ -133,3 +133,19 @@ export const ColumnPicker: Story = {
 export const Tooltips: Story = {
 	args: { tooltipsOpen: true },
 };
+
+/**
+ * The rule count in the bottom strip, in place of the build version: the rows on
+ * the page against the total, the same pair the table's own footer prints.
+ */
+export const BottomStrip: Story = {
+	args: { bottomStrip: true },
+};
+
+/** The same count on a second page, where the two numbers come apart. */
+export const BottomStripPaginated: Story = {
+	args: { bottomStrip: true, rules: RULE_MAX },
+	parameters: {
+		signoz: { route: '/alerts?tab=AlertRules&page=2&limit=10' },
+	},
+};

frontend/src/pages/AllErrors/stories/AllErrors.stories.tsx

@@ -125,3 +125,11 @@ export const QuickFiltersSettingsWithBanner: Story = {
 	args: { banner: 'trial-expiry' },
 	play: dirtyQuickFiltersSettings,
 };
+
+/**
+ * The exception count in the bottom strip, in place of the build version: the
+ * rows on the page against the total the count query returns.
+ */
+export const BottomStrip: Story = {
+	args: { bottomStrip: true },
+};

frontend/src/pages/HomePage/stories/HomePage.stories.tsx

@@ -97,3 +97,11 @@ export const NavSettingsMenu: Story = {
 		await screen.findByRole('menu');
 	},
 };
+
+/**
+ * The firing alert count in the bottom strip, in place of the build version. It
+ * counts firing instances, so it does not match the alert rules widget above.
+ */
+export const BottomStrip: Story = {
+	args: { bottomStrip: true },
+};

frontend/src/pages/Services/stories/Services.stories.tsx

@@ -61,3 +61,13 @@ export const Pagination: Story = {
 export const OverTrialLimit: Story = {
 	args: { traffic: 'over-trial-limit', banner: 'trial-expiry' },
 };
+
+/** The service count in the bottom strip, in place of the build version. */
+export const BottomStrip: Story = {
+	args: { bottomStrip: true },
+};
+
+/** The same count on the span metrics table, which is the page's other path. */
+export const BottomStripSpanMetrics: Story = {
+	args: { bottomStrip: true, mode: 'span-metrics' },
+};

frontend/src/storybook/foundations/BottomStrip.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import ROUTES from 'constants/routes';
+import { toast } from '@signozhq/ui/sonner';
 import { screen, userEvent, waitFor } from 'storybook/test';
 
 import type { GlobalMockArgs } from '../globals';
@@ -108,3 +109,24 @@ export const WithoutStripAddCardModal: Story = {
 		});
 	},
 };
+
+/** Raises a toast and waits for it, so the shot is taken with it on screen. */
+const raiseToast: NonNullable<Story['play']> = async () => {
+	toast.success('Service account deleted');
+	await screen.findByText('Service account deleted', undefined, untilLoaded);
+};
+
+/**
+ * A toast with the strip on. Sonner pins itself to the foot of the viewport, so
+ * without an offset it lands on top of Ask Noz and Support.
+ */
+export const WithToast: Story = {
+	args: { noz: true, support: 'pylon' },
+	play: raiseToast,
+};
+
+/** The same toast with the flag off, back at sonner's own inset from the viewport. */
+export const WithoutStripToast: Story = {
+	args: { bottomStrip: false, noz: true, support: 'pylon' },
+	play: raiseToast,
+};

pkg/apiserver/signozapiserver/tracedetail.go

@@ -67,5 +67,23 @@ func (provider *provider) addTraceDetailRoutes(router *mux.Router) error {
 		return err
 	}
 
+	if err := router.Handle("/api/v1/traces/{traceID}/thread", handler.New(
+		provider.authzMiddleware.ViewAccess(provider.traceDetailHandler.GetThread),
+		handler.OpenAPIDef{
+			ID:                  "GetTraceThread",
+			Tags:                []string{"tracedetail"},
+			Summary:             "Get thread view for a trace",
+			Description:         "Returns the spans carrying gen_ai input or output messages in timestamp order, each with the messages normalised into formatted_input and formatted_output. Pass nextCursor as after or prevCursor as before to page, or spanId to open the page around a span.",
+			RequestQuery:        new(spantypes.QueryableThread),
+			Response:            new(spantypes.GettableTraceThread),
+			ResponseContentType: "application/json",
+			SuccessStatusCode:   http.StatusOK,
+			ErrorStatusCodes:    []int{http.StatusBadRequest, http.StatusNotFound},
+			SecuritySchemes:     newSecuritySchemes(types.RoleViewer),
+		},
+	)).Methods(http.MethodGet).GetError(); err != nil {
+		return err
+	}
+
 	return nil
 }

pkg/flagger/registry.go

@@ -9,6 +9,7 @@ var (
 	FeaturePutMetersInZeus        = featuretypes.MustNewName("put_meters_in_zeus")
 	FeatureUseMeterReporter       = featuretypes.MustNewName("use_meter_reporter")
 	FeatureUseJSONBody            = featuretypes.MustNewName("use_json_body")
+	FeatureJSONBodyDualIngestion  = featuretypes.MustNewName("json_body_dual_ingestion")
 	FeatureEnableMetricsReduction = featuretypes.MustNewName("enable_metrics_reduction")
 	FeatureResolveSemconvFamilies = featuretypes.MustNewName("resolve_semconv_families")
 	FeatureUseTraceAttributesJSON = featuretypes.MustNewName("use_trace_attributes_json")
@@ -64,6 +65,14 @@ func MustNewRegistry() featuretypes.Registry {
 			DefaultVariant: featuretypes.MustNewName("disabled"),
 			Variants:       featuretypes.NewBooleanVariants(),
 		},
+		&featuretypes.Feature{
+			Name:           FeatureJSONBodyDualIngestion,
+			Kind:           featuretypes.KindBoolean,
+			Stage:          featuretypes.StageExperimental,
+			Description:    "Controls whether the collector's normalize operator keeps the original log body so it is ingested into both the legacy body and the JSON body columns",
+			DefaultVariant: featuretypes.MustNewName("disabled"),
+			Variants:       featuretypes.NewBooleanVariants(),
+		},
 		&featuretypes.Feature{
 			Name:           FeatureEnableMetricsReduction,
 			Kind:           featuretypes.KindBoolean,
@@ -76,7 +85,7 @@ func MustNewRegistry() featuretypes.Registry {
 			Name:           FeatureResolveSemconvFamilies,
 			Kind:           featuretypes.KindBoolean,
 			Stage:          featuretypes.StageExperimental,
-			Description:    "Controls whether trace queries resolve a semantic-convention name to all the spellings of its family",
+			Description:    "Controls whether trace, log, and metric queries resolve a semantic-convention name to all the spellings of its family",
 			DefaultVariant: featuretypes.MustNewName("disabled"),
 			Variants:       featuretypes.NewBooleanVariants(),
 		},

pkg/modules/inframonitoring/implinframonitoring/helpers.go

@@ -435,6 +435,7 @@ func (m *module) buildFilterClause(ctx context.Context, orgID valuer.UUID, filte
 		whereClauseSelectors[idx].SelectorMatchType = telemetrytypes.FieldSelectorMatchTypeExact
 	}
 
+	whereClauseSelectors = querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, m.fl, whereClauseSelectors)
 	keys, _, err := m.telemetryMetadataStore.GetKeysMulti(ctx, orgID, whereClauseSelectors)
 	if err != nil {
 		return nil, err

pkg/modules/metricsexplorer/implmetricsexplorer/module.go

@@ -936,6 +936,7 @@ func (m *module) buildFilterClause(ctx context.Context, orgID valuer.UUID, filte
 		// whereClauseSelectors[idx].Source = query.Source
 	}
 
+	whereClauseSelectors = querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, m.fl, whereClauseSelectors)
 	keys, _, err := m.telemetryMetadataStore.GetKeysMulti(ctx, orgID, whereClauseSelectors)
 	if err != nil {
 		return nil, err

pkg/modules/tracedetail/impltracedetail/handler.go

@@ -75,3 +75,25 @@ func (h *handler) GetFlamegraph(rw http.ResponseWriter, r *http.Request) {
 
 	render.Success(rw, http.StatusOK, result)
 }
+
+func (h *handler) GetThread(rw http.ResponseWriter, r *http.Request) {
+	req := new(spantypes.QueryableThread)
+	if err := binding.Query.BindQuery(r.URL.Query(), req); err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	query, err := spantypes.NewThreadQuery(req)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	result, err := h.module.GetThread(r.Context(), mux.Vars(r)["traceID"], query)
+	if err != nil {
+		render.Error(rw, err)
+		return
+	}
+
+	render.Success(rw, http.StatusOK, result)
+}

pkg/modules/tracedetail/impltracedetail/module.go

@@ -173,6 +173,49 @@ func (m *module) getWindowedWaterfall(ctx context.Context, traceID, selectedSpan
 	), nil
 }
 
+func (m *module) GetThread(ctx context.Context, traceID string, query *spantypes.ThreadQuery) (*spantypes.GettableTraceThread, error) {
+	summary, err := m.store.GetTraceSummary(ctx, traceID)
+	if err != nil {
+		return nil, err
+	}
+
+	// One extra row per side signals a next/prev page; NewGettableTraceThread trims the response back to query.Limit.
+	page := spantypes.ThreadPage{Limit: query.Limit + 1}
+	switch {
+	case query.SpanID != "":
+		// Window centred on the span: fetch both directions, NewGettableTraceThread splits the limit.
+		anchor, err := m.store.GetThreadCursor(ctx, traceID, summary, query.SpanID)
+		if err != nil {
+			return nil, err
+		}
+		before, err := m.store.GetThreadSpans(ctx, traceID, summary, spantypes.ThreadPage{Cursor: anchor, From: spantypes.ThreadBefore, Limit: page.Limit})
+		if err != nil {
+			return nil, err
+		}
+		// ThreadAt keeps the anchor when it carries messages; otherwise the filter drops it.
+		after, err := m.store.GetThreadSpans(ctx, traceID, summary, spantypes.ThreadPage{Cursor: anchor, From: spantypes.ThreadAt, Limit: page.Limit})
+		if err != nil {
+			return nil, err
+		}
+		return spantypes.NewGettableTraceThread(traceID, query, before, after), nil
+	case query.Before != nil:
+		page.Cursor, page.From = query.Before, spantypes.ThreadBefore
+		before, err := m.store.GetThreadSpans(ctx, traceID, summary, page)
+		if err != nil {
+			return nil, err
+		}
+		return spantypes.NewGettableTraceThread(traceID, query, before, nil), nil
+	default:
+		// nil for the first page.
+		page.Cursor = query.After
+		after, err := m.store.GetThreadSpans(ctx, traceID, summary, page)
+		if err != nil {
+			return nil, err
+		}
+		return spantypes.NewGettableTraceThread(traceID, query, nil, after), nil
+	}
+}
+
 func (m *module) getFullFlamegraph(ctx context.Context, traceID string, summary *spantypes.TraceSummary, selectFields []telemetrytypes.TelemetryFieldKey) (*spantypes.GettableFlamegraphTrace, error) {
 	fullSpans, err := m.store.GetFlamegraphSpans(ctx, traceID, summary.Start, summary.End, nil)
 	if err != nil {

pkg/modules/tracedetail/impltracedetail/store.go

@@ -11,12 +11,23 @@ import (
 	"github.com/SigNoz/signoz/pkg/clickhousesql"
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/telemetrystore"
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
 	"github.com/SigNoz/signoz/pkg/types/spantypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 )
 
 const colServiceName = `resource_string_service$$$$name` // $ gets escaped so $$$$ converts to $$.
 
+var fullSpanColumns = []string{
+	"duration_nano", "span_id", "has_error", "kind",
+	colServiceName, "name",
+	"attributes_string", "attributes_number", "attributes_bool", "resources_string",
+	"events", "status_message", "status_code_string", "kind_string", "parent_span_id",
+	"flags", "is_remote", "trace_state", "status_code",
+	"db_name", "db_operation", "http_method", "http_url", "http_host",
+	"external_http_method", "external_http_url", "response_status_code", "links as references",
+}
+
 func buildFieldExpr(fieldKey telemetrytypes.TelemetryFieldKey) (string, error) {
 	switch fieldKey.FieldContext {
 	case telemetrytypes.FieldContextResource:
@@ -123,16 +134,8 @@ func (s *traceStore) GetTraceSpansByIDs(ctx context.Context, traceID string, sta
 		return []spantypes.StorableSpan{}, nil
 	}
 	sb := sqlbuilder.NewSelectBuilder()
-	sb.Select(
-		"DISTINCT ON (span_id) timestamp",
-		"duration_nano", "span_id", "has_error", "kind",
-		colServiceName, "name",
-		"attributes_string", "attributes_number", "attributes_bool", "resources_string",
-		"events", "status_message", "status_code_string", "kind_string", "parent_span_id",
-		"flags", "is_remote", "trace_state", "status_code",
-		"db_name", "db_operation", "http_method", "http_url", "http_host",
-		"external_http_method", "external_http_url", "response_status_code", "links as references",
-	)
+	sb.Select("DISTINCT ON (span_id) timestamp")
+	sb.SelectMore(fullSpanColumns...)
 	sb.From(fmt.Sprintf("%s.%s", spantypes.TraceDB, spantypes.TraceTable))
 	ids := make([]any, len(spanIDs))
 	for i, id := range spanIDs {
@@ -155,6 +158,81 @@ func (s *traceStore) GetTraceSpansByIDs(ctx context.Context, traceID string, sta
 	return spans, nil
 }
 
+func (s *traceStore) GetThreadSpans(ctx context.Context, traceID string, summary *spantypes.TraceSummary, page spantypes.ThreadPage) ([]spantypes.StorableSpan, error) {
+	sb := sqlbuilder.NewSelectBuilder()
+	sb.Select("DISTINCT ON (span_id) timestamp")
+	sb.SelectMore(fullSpanColumns...)
+	sb.SelectMore("attributes")
+	sb.From(fmt.Sprintf("%s.%s", spantypes.TraceDB, spantypes.TraceTable))
+	sb.Where(
+		sb.E("trace_id", traceID),
+		sb.GE("ts_bucket_start", summary.Start.Unix()-1800),
+		sb.LE("ts_bucket_start", summary.End.Unix()),
+		// Reads only the JSON column; spans with messages only in the legacy maps are skipped.
+		// todo(nitya): pick the column from the attribute evolution metadata.
+		sb.Or(
+			sqlbuilder.Escape(fmt.Sprintf("attributes.%s IS NOT NULL", clickhousesql.Identifier(aiobservabilitytypes.GenAIInputMessages))),
+			sqlbuilder.Escape(fmt.Sprintf("attributes.%s IS NOT NULL", clickhousesql.Identifier(aiobservabilitytypes.GenAIOutputMessages))),
+		),
+	)
+	if cursor := page.Cursor; cursor != nil {
+		// ClickHouse can't use an index for a tuple comparison, so the separate timestamp and
+		// ts_bucket_start bounds are what skip the data on the far side of the cursor.
+		key := "(toUnixTimestamp64Nano(timestamp), span_id)"
+		bucket := int64(cursor.TimeUnixNano / uint64(time.Second))
+		timestamp := fmt.Sprintf("fromUnixTimestamp64Nano(toInt64(%s))", sb.Var(cursor.TimeUnixNano))
+		tuple := sqlbuilder.Tuple(cursor.TimeUnixNano, cursor.SpanID)
+		switch page.From {
+		case spantypes.ThreadBefore:
+			sb.Where(sb.LE("ts_bucket_start", bucket), "timestamp <= "+timestamp, sb.LT(key, tuple))
+		case spantypes.ThreadAt:
+			sb.Where(sb.GE("ts_bucket_start", bucket-1800), "timestamp >= "+timestamp, sb.GE(key, tuple))
+		default:
+			sb.Where(sb.GE("ts_bucket_start", bucket-1800), "timestamp >= "+timestamp, sb.GT(key, tuple))
+		}
+	}
+	// span_id breaks timestamp ties so the order matches the cursor key; otherwise tied spans
+	// can be skipped or repeated across pages.
+	if page.From == spantypes.ThreadBefore {
+		sb.OrderByDesc("timestamp")
+		sb.OrderByDesc("span_id")
+	} else {
+		sb.OrderByAsc("timestamp")
+		sb.OrderByAsc("span_id")
+	}
+	sb.Limit(page.Limit)
+	query, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+
+	var spans []spantypes.StorableSpan
+	if err := s.telemetryStore.ClickhouseDB().Select(ctx, &spans, query, args...); err != nil {
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "error querying thread spans")
+	}
+	return spans, nil
+}
+
+func (s *traceStore) GetThreadCursor(ctx context.Context, traceID string, summary *spantypes.TraceSummary, spanID string) (*spantypes.ThreadCursor, error) {
+	sb := sqlbuilder.NewSelectBuilder()
+	sb.Select("toUnixTimestamp64Nano(timestamp)")
+	sb.From(fmt.Sprintf("%s.%s", spantypes.TraceDB, spantypes.TraceTable))
+	sb.Where(
+		sb.E("trace_id", traceID),
+		sb.GE("ts_bucket_start", summary.Start.Unix()-1800),
+		sb.LE("ts_bucket_start", summary.End.Unix()),
+		sb.E("span_id", spanID),
+	)
+	sb.Limit(1)
+	query, args := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+
+	var timeUnixNano int64
+	if err := s.telemetryStore.ClickhouseDB().QueryRow(ctx, query, args...).Scan(&timeUnixNano); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, errors.NewNotFoundf(spantypes.ErrCodeThreadSpanNotFound, "span %s not found in trace %s", spanID, traceID)
+		}
+		return nil, errors.WrapInternalf(err, errors.CodeInternal, "error querying thread span")
+	}
+	return &spantypes.ThreadCursor{TimeUnixNano: uint64(timeUnixNano), SpanID: spanID}, nil
+}
+
 func (s *traceStore) GetFlamegraphSpans(ctx context.Context, traceID string, start, end time.Time, spanIDs []string) ([]spantypes.StorableSpan, error) {
 	sb := sqlbuilder.NewSelectBuilder()
 	sb.Select(

pkg/modules/tracedetail/tracedetail.go

@@ -13,6 +13,7 @@ type Handler interface {
 	GetWaterfallV4(http.ResponseWriter, *http.Request)
 	GetTraceAggregations(http.ResponseWriter, *http.Request)
 	GetFlamegraph(http.ResponseWriter, *http.Request)
+	GetThread(http.ResponseWriter, *http.Request)
 }
 
 // Module defines the business logic for trace detail operations.
@@ -20,4 +21,5 @@ type Module interface {
 	GetWaterfallV4(ctx context.Context, traceID string, selectedSpanID string, uncollapsedSpans []string) (*spantypes.GettableWaterfallTrace, error)
 	GetTraceAggregations(ctx context.Context, traceID string, req *spantypes.PostableTraceAggregations) (*spantypes.GettableTraceAggregations, error)
 	GetFlamegraph(ctx context.Context, traceID string, selectedSpanID string, selectFields []telemetrytypes.TelemetryFieldKey) (*spantypes.GettableFlamegraphTrace, error)
+	GetThread(ctx context.Context, traceID string, query *spantypes.ThreadQuery) (*spantypes.GettableTraceThread, error)
 }

pkg/prometheus/clickhouseprometheusv2/transpiler_exec.go

@@ -381,6 +381,12 @@ func toMatrix(series []transpiledSeries, startMs, stepMs int64) promql.Matrix {
 // lookback cannot resurrect the previous grid point. Each unit's synthetic
 // samples sit on its own grid: the query grid, or the subquery grid for
 // units inside subqueries.
+//
+// Synthetic series carry no __name__: substituted units all drop it, so
+// nameless matches the replaced expressions' output. A stamped name splits
+// or arms into per-unit series that a later name drop collides into the
+// duplicate-labelset error. hybridQuerier.Select resolves the selector
+// from the matcher, not from series labels.
 func (e *executor) executeHybrid(ctx context.Context, plan *transpilePlan, results [][]transpiledSeries) (promql.Matrix, error) {
 	synthetic := make(map[string][]*series, len(plan.units))
 	staleMarker := math.Float64frombits(promValue.StaleNaN)
@@ -395,9 +401,7 @@ func (e *executor) executeHybrid(ctx context.Context, plan *transpilePlan, resul
 		}
 		list := make([]*series, 0, len(results[i]))
 		for _, cs := range results[i] {
-			builder := labels.NewBuilder(cs.lset)
-			builder.Set(metricNameLabel, unit.name)
-			s := &series{lset: builder.Labels()}
+			s := &series{lset: cs.lset}
 			s.ts = make([]int64, 0, gridLen)
 			s.vs = make([]float64, 0, gridLen)
 			for idx := 0; idx < gridLen; idx++ {
@@ -440,65 +444,17 @@ func (e *executor) executeHybrid(ctx context.Context, plan *transpilePlan, resul
 		return nil, err
 	}
 
-	// Deep-copy before Close returns the result's slices to the engine pool,
-	// and drop the synthetic __name__ that filter comparisons preserve.
+	// Deep-copy before Close returns the result's slices to the engine pool.
 	out := make(promql.Matrix, 0, len(matrix))
 	for _, s := range matrix {
-		lset := s.Metric
-		if name := lset.Get(metricNameLabel); len(name) >= len(syntheticNamePrefix) && name[:len(syntheticNamePrefix)] == syntheticNamePrefix {
-			builder := labels.NewBuilder(lset)
-			builder.Del(metricNameLabel)
-			lset = builder.Labels()
-		}
 		floats := make([]promql.FPoint, len(s.Floats))
 		copy(floats, s.Floats)
-		out = append(out, promql.Series{Metric: lset.Copy(), Floats: floats})
-	}
-	// The strip can leave twins: two units' outputs that only their
-	// synthetic names told apart (e.g. -metric_a or -metric_b, both {}
-	// once real names are dropped). The engine assembles its matrix by
-	// labelset. It merges such temporally-disjoint elements into one
-	// series. Reproduce that, with its duplicate error on same-timestamp
-	// overlap.
-	out, err = mergeMatrixByLabelset(out)
-	if err != nil {
-		return nil, err
+		out = append(out, promql.Series{Metric: s.Metric.Copy(), Floats: floats})
 	}
 	sort.Slice(out, func(i, j int) bool { return labels.Compare(out[i].Metric, out[j].Metric) < 0 })
 	return out, nil
 }
 
-// mergeMatrixByLabelset merges series that share a labelset. It interleaves
-// their points in timestamp order. A timestamp present in both is the
-// engine's duplicate-labelset error.
-func mergeMatrixByLabelset(matrix promql.Matrix) (promql.Matrix, error) {
-	index := make(map[uint64]int, len(matrix))
-	out := matrix[:0]
-	for _, s := range matrix {
-		hash := s.Metric.Hash()
-		idx, ok := index[hash]
-		if ok && labels.Equal(out[idx].Metric, s.Metric) {
-			merged := make([]promql.FPoint, 0, len(out[idx].Floats)+len(s.Floats))
-			a, b := out[idx].Floats, s.Floats
-			for len(a) > 0 && len(b) > 0 {
-				switch {
-				case a[0].T < b[0].T:
-					merged, a = append(merged, a[0]), a[1:]
-				case b[0].T < a[0].T:
-					merged, b = append(merged, b[0]), b[1:]
-				default:
-					return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "vector cannot contain metrics with the same labelset")
-				}
-			}
-			out[idx].Floats = append(append(merged, a...), b...)
-			continue
-		}
-		index[hash] = len(out)
-		out = append(out, s)
-	}
-	return out, nil
-}
-
 func resultToMatrix(res *promql.Result) (promql.Matrix, error) {
 	switch v := res.Value.(type) {
 	case promql.Matrix:

pkg/prometheus/clickhouseprometheusv2/transpiler_test.go

@@ -14,7 +14,6 @@ import (
 	"github.com/SigNoz/signoz/pkg/telemetrystore"
 	"github.com/SigNoz/signoz/pkg/telemetrystore/telemetrystoretest"
 	"github.com/prometheus/prometheus/model/labels"
-	"github.com/prometheus/prometheus/promql"
 	"github.com/prometheus/prometheus/promql/parser"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -679,26 +678,3 @@ func TestMergeSameLabelsetSeries(t *testing.T) {
 	require.Error(t, err, "two values on one evaluation timestamp is the engine's duplicate error")
 	assert.True(t, errors.Ast(err, errors.TypeInvalidInput))
 }
-
-// Hybrid twin case: stripping the synthetic __name__ can leave two engine
-// output series distinguishable only by those names (-metric_a or -metric_b:
-// both {} once real names are dropped). Pinned by conformance cases
-// name_label_dropping.test:137 and operators.test:1016.
-func TestMergeMatrixByLabelset(t *testing.T) {
-	empty := labels.EmptyLabels()
-
-	out, err := mergeMatrixByLabelset(promql.Matrix{
-		{Metric: empty, Floats: []promql.FPoint{{T: 0, F: -1}}},
-		{Metric: empty, Floats: []promql.FPoint{{T: 600_000, F: -4}}},
-	})
-	require.NoError(t, err)
-	require.Len(t, out, 1)
-	assert.Equal(t, []promql.FPoint{{T: 0, F: -1}, {T: 600_000, F: -4}}, out[0].Floats)
-
-	_, err = mergeMatrixByLabelset(promql.Matrix{
-		{Metric: empty, Floats: []promql.FPoint{{T: 0, F: -1}}},
-		{Metric: empty, Floats: []promql.FPoint{{T: 0, F: -3}}},
-	})
-	require.Error(t, err)
-	assert.True(t, errors.Ast(err, errors.TypeInvalidInput))
-}

pkg/querier/consume.go

@@ -566,24 +566,6 @@ func readAsRaw(rows driver.Rows, queryName string) (*qbtypes.RawData, error) {
 	}, nil
 }
 
-// flattenJSONPaths flattens a decoded JSON document into dotted keys, overwriting existing keys in out.
-func flattenJSONPaths(prefix string, m map[string]any, out map[string]any) {
-	for k, v := range m {
-		key := k
-		if prefix != "" {
-			key = prefix + "." + k
-		}
-		switch child := v.(type) {
-		case map[string]any:
-			flattenJSONPaths(key, child, out)
-		case telemetrystoretypes.JSONValue:
-			flattenJSONPaths(key, child, out)
-		default:
-			out[key] = v
-		}
-	}
-}
-
 // mergeSpanAttributeColumns merges (attributes_string, attributes_number, attributes_bool, resources_string) into
 // unified "attributes" and "resource" keys, and parses the stringified `events`
 // and `links` columns into structured slices. Raw DB columns are removed.
@@ -598,7 +580,7 @@ func mergeSpanAttributeColumns(data map[string]any) {
 	resStr, hasRes := data["resources_string"]
 	if hasStr || hasNum || hasBool || attrJSON != nil || hasRes {
 		attributes := make(map[string]any)
-		flattenJSONPaths("", attrJSON, attributes)
+		attrJSON.FlattenInto("", attributes)
 		if m, ok := attrStr.(map[string]string); ok {
 			for k, v := range m {
 				attributes[k] = v

pkg/querier/metric_family_test.go

@@ -0,0 +1,102 @@
+package querier
+
+import (
+	"context"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
+	"github.com/SigNoz/signoz/pkg/types/metrictypes"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes/telemetrytypestest"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The metric metadata of a query on one name of a metric-name family comes
+// from every name of the family: the temporality is Multiple when the names
+// differ, and the reduced flag is set when any name has reduced data.
+func TestResolveMetricMetadataReadsTheFamily(t *testing.T) {
+	testCases := []struct {
+		name                string
+		temporalities       map[string]metrictypes.Temporality
+		reduced             map[string]bool
+		expectedTemporality metrictypes.Temporality
+		expectedReduced     bool
+	}{
+		{
+			name: "SameTemporality_KeepsIt",
+			temporalities: map[string]metrictypes.Temporality{
+				"k8s.pod.cpu.usage":       metrictypes.Cumulative,
+				"k8s.pod.cpu.utilization": metrictypes.Cumulative,
+			},
+			expectedTemporality: metrictypes.Cumulative,
+		},
+		{
+			name: "DifferentTemporalities_ReadAsMultiple",
+			temporalities: map[string]metrictypes.Temporality{
+				"k8s.pod.cpu.usage":       metrictypes.Delta,
+				"k8s.pod.cpu.utilization": metrictypes.Cumulative,
+			},
+			expectedTemporality: metrictypes.Multiple,
+		},
+		{
+			name: "OnlyOldNameKnown_TakesItsTemporality",
+			temporalities: map[string]metrictypes.Temporality{
+				"k8s.pod.cpu.utilization": metrictypes.Delta,
+			},
+			expectedTemporality: metrictypes.Delta,
+		},
+		{
+			name: "OldNameReduced_MarksTheAggregationReduced",
+			temporalities: map[string]metrictypes.Temporality{
+				"k8s.pod.cpu.usage": metrictypes.Cumulative,
+			},
+			reduced:             map[string]bool{"k8s.pod.cpu.utilization": true},
+			expectedTemporality: metrictypes.Cumulative,
+			expectedReduced:     true,
+		},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			metadataStore := telemetrytypestest.NewMockMetadataStore()
+			metadataStore.TemporalityMap = testCase.temporalities
+			metadataStore.TypeMap = map[string]metrictypes.Type{
+				"k8s.pod.cpu.usage":       metrictypes.GaugeType,
+				"k8s.pod.cpu.utilization": metrictypes.GaugeType,
+			}
+			metadataStore.ReducedMap = testCase.reduced
+			q := &querier{
+				logger:        instrumentationtest.New().Logger(),
+				metadataStore: metadataStore,
+				fl: flaggertest.WithBooleanFlags(t, map[string]bool{
+					flagger.FeatureResolveSemconvFamilies.String(): true,
+				}),
+			}
+			queries := []qbtypes.QueryEnvelope{{
+				Type: qbtypes.QueryTypeBuilder,
+				Spec: qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]{
+					Name:   "A",
+					Signal: telemetrytypes.SignalMetrics,
+					Aggregations: []qbtypes.MetricAggregation{{
+						MetricName:       "k8s.pod.cpu.usage",
+						TimeAggregation:  metrictypes.TimeAggregationAvg,
+						SpaceAggregation: metrictypes.SpaceAggregationAvg,
+					}},
+				},
+			}}
+
+			missing, warnings, err := q.resolveMetricMetadata(context.Background(), valuer.UUID{}, queries, 0, 0, qbtypes.RequestTypeTimeSeries)
+			require.NoError(t, err)
+			assert.Empty(t, missing)
+			assert.Empty(t, warnings)
+
+			spec := queries[0].Spec.(qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation])
+			assert.Equal(t, testCase.expectedTemporality, spec.Aggregations[0].Temporality)
+			assert.Equal(t, testCase.expectedReduced, spec.Aggregations[0].Reduced)
+		})
+	}
+}

pkg/querier/querier.go

@@ -369,6 +369,8 @@ func (q *querier) populateQBEvent(event *qbtypes.QBEvent, queries []qbtypes.Quer
 //     resolved: never-seen metrics and dormant metrics (seen but no data in
 //     the query window).
 //   - err: Internal when a metadata fetch fails.
+//
+// Metric metadata resolves through every name of a metric-name family.
 func (q *querier) resolveMetricMetadata(ctx context.Context, orgID valuer.UUID, queries []qbtypes.QueryEnvelope, start, end uint64, requestType qbtypes.RequestType) (missingMetricQueries []string, metricWarnings []string, err error) {
 	metricNames := make([]string, 0)
 	for idx := range queries {
@@ -381,7 +383,7 @@ func (q *querier) resolveMetricMetadata(ctx context.Context, orgID valuer.UUID,
 		}
 		for _, agg := range spec.Aggregations {
 			if agg.MetricName != "" {
-				metricNames = append(metricNames, agg.MetricName)
+				metricNames = append(metricNames, querybuilder.FamilyMetricNames(ctx, orgID, q.fl, agg.MetricName)...)
 			}
 		}
 	}
@@ -409,14 +411,16 @@ func (q *querier) resolveMetricMetadata(ctx context.Context, orgID valuer.UUID,
 
 		presentAggregations := make([]qbtypes.MetricAggregation, 0, len(spec.Aggregations))
 		for i := range spec.Aggregations {
+			familyNames := querybuilder.FamilyMetricNames(ctx, orgID, q.fl, spec.Aggregations[i].MetricName)
 			if spec.Aggregations[i].MetricName != "" && spec.Aggregations[i].Temporality == metrictypes.Unknown {
-				if temp, ok := metricTemporality[spec.Aggregations[i].MetricName]; ok && temp != metrictypes.Unknown {
-					spec.Aggregations[i].Temporality = temp
-				}
+				spec.Aggregations[i].Temporality = familyTemporality(metricTemporality, familyNames)
 			}
 			if spec.Aggregations[i].MetricName != "" && spec.Aggregations[i].Type == metrictypes.UnspecifiedType {
-				if foundMetricType, ok := metricTypes[spec.Aggregations[i].MetricName]; ok && foundMetricType != metrictypes.UnspecifiedType {
-					spec.Aggregations[i].Type = foundMetricType
+				for _, member := range familyNames {
+					if foundMetricType, ok := metricTypes[member]; ok && foundMetricType != metrictypes.UnspecifiedType {
+						spec.Aggregations[i].Type = foundMetricType
+						break
+					}
 				}
 			}
 			if spec.Aggregations[i].Type == metrictypes.UnspecifiedType {
@@ -434,8 +438,11 @@ func (q *querier) resolveMetricMetadata(ctx context.Context, orgID valuer.UUID,
 					return nil, nil, err
 				}
 			}
-			if reducedMetricsSet[spec.Aggregations[i].MetricName] {
-				spec.Aggregations[i].Reduced = true
+			for _, member := range familyNames {
+				if reducedMetricsSet[member] {
+					spec.Aggregations[i].Reduced = true
+					break
+				}
 			}
 			presentAggregations = append(presentAggregations, spec.Aggregations[i])
 		}
@@ -505,6 +512,26 @@ func (q *querier) resolveMetricMetadata(ctx context.Context, orgID valuer.UUID,
 	return missingMetricQueries, warnings, nil
 }
 
+// familyTemporality is the temporality the family names share, or Multiple
+// when they differ.
+func familyTemporality(temporalities map[string]metrictypes.Temporality, names []string) metrictypes.Temporality {
+	found := metrictypes.Unknown
+	for _, name := range names {
+		temporality, ok := temporalities[name]
+		if !ok || temporality == metrictypes.Unknown {
+			continue
+		}
+		if found == metrictypes.Unknown {
+			found = temporality
+			continue
+		}
+		if found != temporality {
+			return metrictypes.Multiple
+		}
+	}
+	return found
+}
+
 func (q *querier) QueryRawStream(ctx context.Context, orgID valuer.UUID, req *qbtypes.QueryRangeRequest, client *qbtypes.RawStream) {
 
 	// Coerce the window to epoch milliseconds up front (End may be 0 for the

pkg/query-service/app/clickhouseReader/reader.go

@@ -52,10 +52,10 @@ import (
 	"github.com/SigNoz/signoz/pkg/query-service/constants"
 
 	chErrors "github.com/SigNoz/signoz/pkg/query-service/errors"
-	"github.com/SigNoz/signoz/pkg/query-service/metrics"
 	"github.com/SigNoz/signoz/pkg/query-service/model"
 	v3 "github.com/SigNoz/signoz/pkg/query-service/model/v3"
 	"github.com/SigNoz/signoz/pkg/query-service/utils"
+	"github.com/SigNoz/signoz/pkg/semconv"
 )
 
 const (
@@ -3202,7 +3202,14 @@ func (r *ClickHouseReader) GetMetricAttributeValues(ctx context.Context, orgID v
 		query = query + fmt.Sprintf(" LIMIT %d;", req.Limit)
 	}
 	names := []string{req.AggregateAttribute}
-	names = append(names, metrics.GetTransitionedMetric(req.AggregateAttribute))
+	current := semconv.Current(semconv.KindMetric, telemetrytypes.FieldKeySelector{
+		Name:         req.AggregateAttribute,
+		Signal:       telemetrytypes.SignalMetrics,
+		FieldContext: telemetrytypes.FieldContextMetric,
+	})
+	if current != req.AggregateAttribute {
+		names = append(names, current)
+	}
 
 	rows, err = r.db.Query(ctx, query, req.FilterAttributeKey, names, req.FilterAttributeKey, fmt.Sprintf("%%%s%%", req.SearchText), common.PastDayRoundOff())
 

pkg/query-service/app/logparsingpipeline/controller.go

@@ -220,7 +220,26 @@ func (ic *LogParsingPipelineController) ValidatePipelines(ctx context.Context,
 	return err
 }
 
-func (ic *LogParsingPipelineController) getNormalizePipeline() pipelinetypes.GettablePipeline {
+// withNormalizePipeline places normalize where the read path dictates. Ahead of user pipelines
+// when queries run on body_v2 (use_json_body), so operators see the body the explorer shows.
+// After them when dual ingestion alone writes body_v2, so operators keep seeing the raw body
+// users still query. Absent when neither flag is on.
+func (ic *LogParsingPipelineController) withNormalizePipeline(ctx context.Context, orgID valuer.UUID, pipelines []pipelinetypes.GettablePipeline) []pipelinetypes.GettablePipeline {
+	evalCtx := featuretypes.NewFlaggerEvaluationContext(orgID)
+	dualIngestion := ic.fl.BooleanOrEmpty(ctx, flagger.FeatureJSONBodyDualIngestion, evalCtx)
+	switch {
+	case ic.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, evalCtx):
+		return append([]pipelinetypes.GettablePipeline{getNormalizePipeline(dualIngestion)}, pipelines...)
+	case dualIngestion:
+		return append(slices.Clone(pipelines), getNormalizePipeline(true))
+	default:
+		return pipelines
+	}
+}
+
+// stashOriginalBody makes normalize carry the pre-normalization body in an internal attribute
+// for the exporter to restore into the legacy body column.
+func getNormalizePipeline(stashOriginalBody bool) pipelinetypes.GettablePipeline {
 	return pipelinetypes.GettablePipeline{
 		StoreablePipeline: pipelinetypes.StoreablePipeline{
 			Name:    "Default Pipeline - PreProcessing Body",
@@ -239,10 +258,11 @@ func (ic *LogParsingPipelineController) getNormalizePipeline() pipelinetypes.Get
 		},
 		Config: []pipelinetypes.PipelineOperator{
 			{
-				ID:      uuid.NewString(),
-				Type:    "normalize",
-				Enabled: true,
-				If:      "body != nil",
+				ID:                    uuid.NewString(),
+				Type:                  "normalize",
+				Enabled:               true,
+				If:                    "body != nil",
+				JSONBodyDualIngestion: stashOriginalBody,
 			},
 		},
 	}
@@ -351,8 +371,11 @@ func (ic *LogParsingPipelineController) PreviewLogsPipelines(
 	}
 
 	// The collector gets the same pipeline prepended over opamp; see RecommendAgentConfig.
+	// Under dual ingestion alone it runs after user operators and only feeds body_v2, which
+	// the explorer does not show yet, so the preview leaves it out. The original-body stash
+	// is left off: the preview has no exporter to restore and strip it.
 	if ic.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(orgID)) {
-		pipelines = append([]pipelinetypes.GettablePipeline{ic.getNormalizePipeline()}, pipelines...)
+		pipelines = append([]pipelinetypes.GettablePipeline{getNormalizePipeline(false)}, pipelines...)
 	}
 
 	result, collectorLogs, err := SimulatePipelinesProcessing(ctx, pipelines, request.Logs)
@@ -373,16 +396,16 @@ func (pc *LogParsingPipelineController) AgentFeatureType() agentConf.AgentFeatur
 
 // Implements agentConf.AgentFeature interface.
 // RecommendAgentConfig generates the collector config to be sent to agents.
-// The normalize pipeline (when use_json_body feature flag is on) is injected here, after
-// rawPipelineData is serialized. So it is only present in the config sent to
+// The normalize pipeline (when use_json_body or json_body_dual_ingestion is on) is placed
+// here, after rawPipelineData is serialized. So it is only present in the config sent to
 // the collector and never persisted to the database as part of the user's pipeline list.
 //
 // NOTE: The configId sent to agents is derived from the pipeline version number
 // (e.g. "LogPipelines:5"), not the YAML content. If server-side logic changes
-// the generated YAML without bumping the version (e.g. toggling the use_json_body
-// flag or updating operator IfExpressions), agents that already applied that version will
-// not re-apply the new config. In such cases, users must save a new pipeline version
-// via the API to force agents to pick up the change.
+// the generated YAML without bumping the version (e.g. toggling the use_json_body or
+// json_body_dual_ingestion flags or updating operator IfExpressions), agents that already
+// applied that version will not re-apply the new config. In such cases, users must save a
+// new pipeline version via the API to force agents to pick up the change.
 func (pc *LogParsingPipelineController) RecommendAgentConfig(
 	orgId valuer.UUID,
 	currentConfYaml []byte,
@@ -408,10 +431,8 @@ func (pc *LogParsingPipelineController) RecommendAgentConfig(
 		return nil, "", err
 	}
 
-	if pc.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(orgId)) {
-		// add default normalize pipeline at the beginning, only for sending to collector
-		enrichedPipelines = append([]pipelinetypes.GettablePipeline{pc.getNormalizePipeline()}, enrichedPipelines...)
-	}
+	// normalize is only for sending to the collector, never persisted
+	enrichedPipelines = pc.withNormalizePipeline(ctx, orgId, enrichedPipelines)
 
 	updatedConf, err := GenerateCollectorConfigWithPipelines(currentConfYaml, enrichedPipelines)
 	if err != nil {

pkg/query-service/metrics/transition.go

@@ -1,14 +0,0 @@
-package metrics
-
-var MetricsUnderTransition = map[string]string{
-	"k8s.pod.cpu.utilization":   "k8s.pod.cpu.usage",
-	"k8s.node.cpu.utilization":  "k8s.node.cpu.usage",
-	"container.cpu.utilization": "container.cpu.usage",
-}
-
-func GetTransitionedMetric(metric string) string {
-	if transitionedMetric, ok := MetricsUnderTransition[metric]; ok {
-		return transitionedMetric
-	}
-	return metric
-}

pkg/query-service/utils/format.go

@@ -10,8 +10,9 @@ import (
 	"log/slog"
 
 	"github.com/SigNoz/signoz/pkg/query-service/constants"
-	"github.com/SigNoz/signoz/pkg/query-service/metrics"
 	v3 "github.com/SigNoz/signoz/pkg/query-service/model/v3"
+	"github.com/SigNoz/signoz/pkg/semconv"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 )
 
 // ValidateAndCastValue validates and casts the value of a key to the corresponding data type of the key
@@ -234,12 +235,12 @@ func ClickHouseFormattedValue(v interface{}) string {
 
 func ClickHouseFormattedMetricNames(v interface{}) string {
 	if name, ok := v.(string); ok {
-		transitionedMetrics := metrics.GetTransitionedMetric(name)
-		if transitionedMetrics != name {
-			return ClickHouseFormattedValue([]interface{}{transitionedMetrics})
-		} else {
-			return ClickHouseFormattedValue([]interface{}{name})
-		}
+		current := semconv.Current(semconv.KindMetric, telemetrytypes.FieldKeySelector{
+			Name:         name,
+			Signal:       telemetrytypes.SignalMetrics,
+			FieldContext: telemetrytypes.FieldContextMetric,
+		})
+		return ClickHouseFormattedValue([]interface{}{current})
 	}
 
 	return ClickHouseFormattedValue(v)

pkg/query-service/utils/format_test.go

@@ -1,6 +1,7 @@
 package utils
 
 import (
+	"github.com/stretchr/testify/assert"
 	"reflect"
 	"testing"
 
@@ -483,3 +484,21 @@ func TestGetEpochNanoSecs(t *testing.T) {
 		})
 	}
 }
+
+// The legacy readers redirect an old metric name to its current name.
+func TestClickHouseFormattedMetricNames(t *testing.T) {
+	testCases := []struct {
+		name     string
+		metric   string
+		expected string
+	}{
+		{name: "OldName_RedirectsToCurrent", metric: "k8s.pod.cpu.utilization", expected: "['k8s.pod.cpu.usage']"},
+		{name: "CurrentName_Unchanged", metric: "k8s.pod.cpu.usage", expected: "['k8s.pod.cpu.usage']"},
+		{name: "OutsideFamily_Unchanged", metric: "http.server.duration", expected: "['http.server.duration']"},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			assert.Equal(t, testCase.expected, ClickHouseFormattedMetricNames(testCase.metric))
+		})
+	}
+}

pkg/querybuilder/family_selectors.go

@@ -4,57 +4,61 @@ import (
 	"context"
 
 	"github.com/SigNoz/signoz/pkg/flagger"
-	"github.com/SigNoz/signoz/pkg/semconv"
 	"github.com/SigNoz/signoz/pkg/types/featuretypes"
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
 	"github.com/SigNoz/signoz/pkg/valuer"
 )
 
-// semconvFamiliesEnabled evaluates the resolve_semconv_families flag for the
+// SemconvFamiliesEnabled evaluates the resolve_semconv_families flag for the
 // org. A nil flagger means off, so a caller without family support stays
 // literal by default.
-func semconvFamiliesEnabled(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger) bool {
+func SemconvFamiliesEnabled(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger) bool {
 	if fl == nil {
 		return false
 	}
 	return fl.BooleanOrEmpty(ctx, flagger.FeatureResolveSemconvFamilies, featuretypes.NewFlaggerEvaluationContext(orgID))
 }
 
-// ExpandKeySelectorsForFamilies adds selectors for the other members of each
-// semantic-convention family that a selector names. The metadata fetched for
-// a query then contains each spelling that MatchingLogicalFields can group.
-// This function is the prefetch of the resolution layer: statement builders
-// call it after they derive the selectors, and the metadata store stays
-// family-blind (autocomplete responses keep the literal spelling that the
-// user typed). It does nothing when the resolve_semconv_families flag is off
-// for the org. Only trace selectors expand today, because that matches the
-// family support. Fuzzy (search-style) selectors never expand.
+// ExpandKeySelectorsForFamilies adds a selector for each other spelling of
+// the family a selector names, so the fetched metadata holds every member.
+// Off, or for a fuzzy selector, it returns the selectors as they are. A call
+// site without the prefetch stays literal and never merges wrong.
 func ExpandKeySelectorsForFamilies(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger, selectors []*telemetrytypes.FieldKeySelector) []*telemetrytypes.FieldKeySelector {
-	if !semconvFamiliesEnabled(ctx, orgID, fl) {
+	if !SemconvFamiliesEnabled(ctx, orgID, fl) {
 		return selectors
 	}
 
+	// The same name under another context, signal, or data type needs its
+	// own siblings. The metric context is not part of the key: metric callers
+	// duplicate the selectors per metric name after this expansion.
+	type identity struct {
+		signal        telemetrytypes.Signal
+		fieldContext  telemetrytypes.FieldContext
+		fieldDataType telemetrytypes.FieldDataType
+		name          string
+	}
 	out := selectors
-	seen := make(map[string]bool, len(selectors))
+	seen := make(map[identity]bool, len(selectors))
 	for _, selector := range selectors {
-		seen[selector.Name] = true
+		seen[identity{selector.Signal, selector.FieldContext, selector.FieldDataType, selector.Name}] = true
 	}
 
 	for _, selector := range selectors {
-		if selector.Signal != telemetrytypes.SignalTraces ||
-			selector.SelectorMatchType == telemetrytypes.FieldSelectorMatchTypeFuzzy {
+		if selector.SelectorMatchType == telemetrytypes.FieldSelectorMatchTypeFuzzy {
 			continue
 		}
-		members := semconv.Members(semconv.KindAttribute, telemetrytypes.FieldKeySelector{
-			Name:         selector.Name,
-			Signal:       selector.Signal,
-			FieldContext: selector.FieldContext,
+		members := familySpellings(telemetrytypes.FieldKeySelector{
+			Name:          selector.Name,
+			Signal:        selector.Signal,
+			FieldContext:  selector.FieldContext,
+			MetricContext: selector.MetricContext,
 		})
 		for _, member := range members {
-			if seen[member] {
+			id := identity{selector.Signal, selector.FieldContext, selector.FieldDataType, member}
+			if seen[id] {
 				continue
 			}
-			seen[member] = true
+			seen[id] = true
 			expanded := *selector
 			expanded.Name = member
 			out = append(out, &expanded)

pkg/querybuilder/logical_expr.go

@@ -20,8 +20,9 @@ import (
 // member reads, current member first. It is present when any member is
 // present, and absent when no member is present. A row without any member
 // reads what the tail of the merge reads: the sentinel for a string family,
-// NULL for the others. A member with a value map reads in the current
-// vocabulary.
+// NULL for the others. When every member reads its sentinel as a value, so
+// does the family, and the keyless contract of the signal survives the
+// merge. A member with a value map reads in the current vocabulary.
 func LogicalRead(ctx context.Context, q qbtypes.QueryInfo, storage qbtypes.Storage, logical *telemetrytypes.LogicalField) (qbtypes.Read, error) {
 	if !logical.IsFamily() {
 		return memberRead(ctx, q, storage, logical, 0)
@@ -35,7 +36,7 @@ func LogicalRead(ctx context.Context, q qbtypes.QueryInfo, storage qbtypes.Stora
 		reads = append(reads, read)
 	}
 
-	merged := qbtypes.Read{WhenAbsent: familyAbsence(logical)}
+	merged := qbtypes.Read{WhenAbsent: familyAbsence(logical, reads)}
 	guards := make([]string, 0, len(reads))
 	for _, read := range reads {
 		guards = append(guards, read.Presence)
@@ -97,10 +98,16 @@ func clickHouseStringArray(values []string) string {
 }
 
 // familyAbsence is what the merged read yields for a row without any
-// member: the sentinel tail of a string family, NULL for the others.
-func familyAbsence(logical *telemetrytypes.LogicalField) qbtypes.Absent {
-	if logical.FieldDataType == telemetrytypes.FieldDataTypeString {
-		return qbtypes.AbsentIsSentinel
+// member: the sentinel tail of a string family, NULL for the others. When
+// every member's sentinel is a value, the tail is one too.
+func familyAbsence(logical *telemetrytypes.LogicalField, reads []qbtypes.Read) qbtypes.Absent {
+	if logical.FieldDataType != telemetrytypes.FieldDataTypeString {
+		return qbtypes.AbsentIsNull
 	}
-	return qbtypes.AbsentIsNull
+	for _, read := range reads {
+		if read.WhenAbsent != qbtypes.AbsentIsValue {
+			return qbtypes.AbsentIsSentinel
+		}
+	}
+	return qbtypes.AbsentIsValue
 }

pkg/querybuilder/logical_fields_test.go

@@ -48,7 +48,7 @@ func TestFamiliesOffByDefault(t *testing.T) {
 		}},
 	}
 
-	fields := matchingLogicalFields(false, telemetrytypes.SignalUnspecified, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
+	fields := matchingLogicalFields(false, telemetrytypes.SignalUnspecified, nil, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
 	require.Len(t, fields, 1)
 	assert.False(t, fields[0].IsFamily())
 	assert.Equal(t, []string{"deployment.environment.name"}, memberNames(fields[0]))
@@ -76,7 +76,7 @@ func TestMatchingLogicalFieldsGroupsFamilyMembers(t *testing.T) {
 	}
 
 	for _, requested := range []string{"deployment.environment.name", "deployment.environment"} {
-		fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, &telemetrytypes.TelemetryFieldKey{Name: requested}, fieldKeys)
+		fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, nil, &telemetrytypes.TelemetryFieldKey{Name: requested}, fieldKeys)
 		require.Len(t, fields, 1, "a family is one logical field, requested via %s", requested)
 		logical := fields[0]
 		assert.Equal(t, requested, logical.Name, "response identity is the requested spelling")
@@ -106,7 +106,7 @@ func TestMatchingLogicalFieldsOrdersMembersByFamilyRank(t *testing.T) {
 		}},
 	}
 
-	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, &telemetrytypes.TelemetryFieldKey{
+	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, nil, &telemetrytypes.TelemetryFieldKey{
 		Name:         "deployment.environment.name",
 		FieldContext: telemetrytypes.FieldContextResource,
 	}, fieldKeys)
@@ -115,26 +115,92 @@ func TestMatchingLogicalFieldsOrdersMembersByFamilyRank(t *testing.T) {
 	assert.Equal(t, []string{"resource.deployment.environment.name", "deployment.environment"}, memberNames(fields[0]))
 }
 
-// Non-trace signals have no family support: the requested spelling stays
-// literal, and a family member name never pulls in its siblings.
-func TestMatchingLogicalFieldsKeepsLogsLiteral(t *testing.T) {
-	logsKey := func(name string) *telemetrytypes.TelemetryFieldKey {
-		return &telemetrytypes.TelemetryFieldKey{
-			Name:          name,
+// Log entries group into families exactly like trace entries.
+func TestMatchingLogicalFieldsGroupsLogEntries(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
 			Signal:        telemetrytypes.SignalLogs,
 			FieldContext:  telemetrytypes.FieldContextResource,
 			FieldDataType: telemetrytypes.FieldDataTypeString,
-		}
-	}
-	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
-		"deployment.environment.name": {logsKey("deployment.environment.name")},
-		"deployment.environment":      {logsKey("deployment.environment")},
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalLogs,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
 	}
 
-	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
+	fields := matchingLogicalFields(true, telemetrytypes.SignalLogs, nil, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
 	require.Len(t, fields, 1)
-	assert.False(t, fields[0].IsFamily())
-	assert.Equal(t, []string{"deployment.environment.name"}, memberNames(fields[0]))
+	assert.True(t, fields[0].IsFamily())
+	assert.Equal(t, []string{"deployment.environment.name", "deployment.environment"}, memberNames(fields[0]))
+}
+
+// Metric entries of a span-metrics metric group across the plain and the
+// resource_ spellings of the family, in member-major order: every spelling
+// of the current name precedes the first spelling of the old one.
+func TestMatchingLogicalFieldsGroupsMetricSpellings(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"resource_deployment.environment.name": {{
+			Name:          "resource_deployment.environment.name",
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"resource_deployment.environment": {{
+			Name:          "resource_deployment.environment",
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	fields := matchingLogicalFields(true, telemetrytypes.SignalMetrics, &telemetrytypes.MetricContext{MetricName: "signoz_calls_total"}, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment"}, fieldKeys)
+	require.Len(t, fields, 1)
+	assert.True(t, fields[0].IsFamily())
+	assert.Equal(t, []string{
+		"deployment.environment.name", "resource_deployment.environment.name",
+		"deployment.environment", "resource_deployment.environment",
+	}, memberNames(fields[0]))
+}
+
+// A non-string entry never joins a family: the merged read has no common
+// ClickHouse type across the storages.
+func TestMatchingLogicalFieldsKeepsNumberEntriesSingle(t *testing.T) {
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeNumber,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextAttribute,
+			FieldDataType: telemetrytypes.FieldDataTypeNumber,
+		}},
+	}
+
+	fields := matchingLogicalFields(true, telemetrytypes.SignalMetrics, nil, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment"}, fieldKeys)
+	require.Len(t, fields, 2)
+	for _, logical := range fields {
+		assert.False(t, logical.IsFamily())
+	}
 }
 
 // A family and a genuine same-name collision stack cleanly: the family stays
@@ -165,7 +231,7 @@ func TestResolveLogicalFieldsKeepsFamilyThroughAmbiguity(t *testing.T) {
 	}
 
 	requested := &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}
-	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, requested, fieldKeys)
+	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, nil, requested, fieldKeys)
 	require.Len(t, fields, 2, "resource family + attribute collision")
 
 	resolved, warning := ResolveLogicalFields(requested, fields)
@@ -229,7 +295,7 @@ func TestMatchingLogicalFieldsNeverMergesAcrossDataTypes(t *testing.T) {
 		}},
 	}
 
-	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
+	fields := matchingLogicalFields(true, telemetrytypes.SignalUnspecified, nil, &telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}, fieldKeys)
 	require.Len(t, fields, 2)
 	for _, logical := range fields {
 		assert.False(t, logical.IsFamily())
@@ -254,11 +320,15 @@ func TestExpandKeySelectorsForFamilies(t *testing.T) {
 		"service.name",
 		"deployment.environment.name",
 		"deployment.environment",
-	}, names, "one sibling selector for the trace family member; logs and non-family names untouched")
+		"deployment.environment",
+	}, names, "each selector identity gets its own sibling, and a non-family name stays untouched")
 
-	sibling := expanded[len(expanded)-1]
-	assert.Equal(t, telemetrytypes.SignalTraces, sibling.Signal)
-	assert.Equal(t, telemetrytypes.FieldSelectorMatchTypeExact, sibling.SelectorMatchType)
+	tracesSibling := expanded[len(expanded)-2]
+	assert.Equal(t, telemetrytypes.SignalTraces, tracesSibling.Signal)
+	assert.Equal(t, telemetrytypes.FieldSelectorMatchTypeExact, tracesSibling.SelectorMatchType)
+	logsSibling := expanded[len(expanded)-1]
+	assert.Equal(t, telemetrytypes.SignalLogs, logsSibling.Signal,
+		"a same-named selector under another signal must not take the sibling")
 }
 
 func TestExpandKeySelectorsForFamiliesDeduplicatesAndSkipsFuzzy(t *testing.T) {

pkg/querybuilder/metric_spellings.go

@@ -0,0 +1,64 @@
+package querybuilder
+
+import (
+	"context"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/semconv"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+)
+
+// The span-metrics processor in signoz-otel-collector writes resource
+// attributes as labels with a resource_ prefix on these metrics only. The
+// signoz_latency histogram is stored as its dotted sub-metrics.
+const spanMetricsResourcePrefix = "resource_"
+
+var spanMetrics = map[string]struct{}{
+	"signoz_calls_total":                 {},
+	"signoz_latency":                     {},
+	"signoz_latency.bucket":              {},
+	"signoz_latency.sum":                 {},
+	"signoz_latency.count":               {},
+	"signoz_latency.min":                 {},
+	"signoz_latency.max":                 {},
+	"signoz_db_latency_sum":              {},
+	"signoz_db_latency_count":            {},
+	"signoz_external_call_latency_sum":   {},
+	"signoz_external_call_latency_count": {},
+}
+
+// MetricLabelSpellings returns the family members of selector.Name, current
+// first, and on a span-metrics metric each member with the resource_ prefix
+// too. A name outside a family, or one the selector leaves ambiguous, is
+// returned as it is.
+func MetricLabelSpellings(selector telemetrytypes.FieldKeySelector) []string {
+	members := semconv.Members(semconv.KindAttribute, selector)
+	if len(members) <= 1 {
+		return []string{selector.Name}
+	}
+	if selector.MetricContext == nil {
+		return members
+	}
+	if _, ok := spanMetrics[selector.MetricContext.MetricName]; !ok {
+		return members
+	}
+	spellings := make([]string, 0, len(members)*2)
+	for _, member := range members {
+		spellings = append(spellings, member, spanMetricsResourcePrefix+member)
+	}
+	return spellings
+}
+
+// FamilyMetricNames returns the metric-name family of metricName when the
+// flag is on for the org, else the name alone.
+func FamilyMetricNames(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger, metricName string) []string {
+	if !SemconvFamiliesEnabled(ctx, orgID, fl) {
+		return []string{metricName}
+	}
+	return semconv.Members(semconv.KindMetric, telemetrytypes.FieldKeySelector{
+		Name:         metricName,
+		Signal:       telemetrytypes.SignalMetrics,
+		FieldContext: telemetrytypes.FieldContextMetric,
+	})
+}

pkg/querybuilder/metric_spellings_test.go

@@ -0,0 +1,100 @@
+package querybuilder
+
+import (
+	"context"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMetricLabelSpellingsReturnsTheFamilyMembers(t *testing.T) {
+	selector := telemetrytypes.FieldKeySelector{
+		Name:          "deployment.environment",
+		Signal:        telemetrytypes.SignalMetrics,
+		MetricContext: &telemetrytypes.MetricContext{MetricName: "k8s.pod.cpu.usage"},
+	}
+
+	assert.Equal(t, []string{"deployment.environment.name", "deployment.environment"}, MetricLabelSpellings(selector))
+}
+
+func TestMetricLabelSpellingsAddsTheResourcePrefixForSpanMetrics(t *testing.T) {
+	testCases := []struct {
+		name     string
+		metric   string
+		expected []string
+	}{
+		{
+			name:   "SpanMetric_ReadsPlainAndResourceSpellings",
+			metric: "signoz_calls_total",
+			expected: []string{
+				"deployment.environment.name", "resource_deployment.environment.name",
+				"deployment.environment", "resource_deployment.environment",
+			},
+		},
+		{
+			name:   "LatencyHistogramSubMetric_ReadsPlainAndResourceSpellings",
+			metric: "signoz_latency.bucket",
+			expected: []string{
+				"deployment.environment.name", "resource_deployment.environment.name",
+				"deployment.environment", "resource_deployment.environment",
+			},
+		},
+		{
+			name:     "OtherSignozMetric_ReadsPlainSpellings",
+			metric:   "signoz_other_metric",
+			expected: []string{"deployment.environment.name", "deployment.environment"},
+		},
+		{
+			name:     "UnderscoreLatencySubMetric_ReadsPlainSpellings",
+			metric:   "signoz_latency_bucket",
+			expected: []string{"deployment.environment.name", "deployment.environment"},
+		},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			selector := telemetrytypes.FieldKeySelector{
+				Name:          "deployment.environment",
+				Signal:        telemetrytypes.SignalMetrics,
+				MetricContext: &telemetrytypes.MetricContext{MetricName: testCase.metric},
+			}
+			assert.Equal(t, testCase.expected, MetricLabelSpellings(selector))
+		})
+	}
+}
+
+// A requested name is never rewritten: a resource_ spelling that is not a
+// family member stays literal, on a span metric too.
+func TestMetricLabelSpellingsKeepsThePrefixedRequestLiteral(t *testing.T) {
+	selector := telemetrytypes.FieldKeySelector{
+		Name:          "resource_deployment.environment",
+		Signal:        telemetrytypes.SignalMetrics,
+		MetricContext: &telemetrytypes.MetricContext{MetricName: "signoz_calls_total"},
+	}
+
+	assert.Equal(t, []string{"resource_deployment.environment"}, MetricLabelSpellings(selector))
+}
+
+func TestMetricLabelSpellingsStaysLiteralOutsideTheVocabulary(t *testing.T) {
+	selector := telemetrytypes.FieldKeySelector{
+		Name:   "http.route",
+		Signal: telemetrytypes.SignalMetrics,
+	}
+
+	assert.Equal(t, []string{"http.route"}, MetricLabelSpellings(selector))
+}
+
+func TestFamilyMetricNames(t *testing.T) {
+	on := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+	assert.Equal(t, []string{"k8s.pod.cpu.usage", "k8s.pod.cpu.utilization"}, FamilyMetricNames(context.Background(), valuer.UUID{}, on, "k8s.pod.cpu.utilization"))
+	assert.Equal(t, []string{"k8s.pod.cpu.usage", "k8s.pod.cpu.utilization"}, FamilyMetricNames(context.Background(), valuer.UUID{}, on, "k8s.pod.cpu.usage"))
+	assert.Equal(t, []string{"http.server.duration"}, FamilyMetricNames(context.Background(), valuer.UUID{}, on, "http.server.duration"))
+
+	off := flaggertest.WithBooleanFlags(t, map[string]bool{})
+	assert.Equal(t, []string{"k8s.pod.cpu.utilization"}, FamilyMetricNames(context.Background(), valuer.UUID{}, off, "k8s.pod.cpu.utilization"))
+}

pkg/querybuilder/resolve.go

@@ -21,7 +21,7 @@ func NewQueryInfo(ctx context.Context, orgID valuer.UUID, fl flagger.Flagger, si
 		EndNs:      endNs,
 		Signal:     signal,
 		Metric:     metric,
-		FamiliesOn: semconvFamiliesEnabled(ctx, orgID, fl),
+		FamiliesOn: SemconvFamiliesEnabled(ctx, orgID, fl),
 	}
 	if fl != nil {
 		evalCtx := featuretypes.NewFlaggerEvaluationContext(orgID)
@@ -61,7 +61,7 @@ func Resolve(
 	traits := storage.Traits()
 
 	lookup := key
-	matches := matchingLogicalFields(q.FamiliesOn, q.Signal, key, fieldKeys)
+	matches := matchingLogicalFields(q.FamiliesOn, q.Signal, q.Metric, key, fieldKeys)
 	if len(matches) == 0 && slices.Contains(traits.OwnContexts, key.FieldContext) {
 		// a column the storage knows under the key's own context is the key
 		// as written, and only a miss corrects to the bare spelling
@@ -71,7 +71,7 @@ func Resolve(
 			}
 		}
 		lookup = telemetrytypes.NewTelemetryFieldKey(key.Name, telemetrytypes.FieldContextUnspecified, key.FieldDataType)
-		matches = matchingLogicalFields(q.FamiliesOn, q.Signal, lookup, fieldKeys)
+		matches = matchingLogicalFields(q.FamiliesOn, q.Signal, q.Metric, lookup, fieldKeys)
 	}
 
 	resolved := qbtypes.Resolved{Key: key, Ambiguous: len(matches) > 1}

pkg/querybuilder/where_clause_visitor.go

@@ -1012,43 +1012,36 @@ func assignIfEmpty(s *string, value string) {
 	}
 }
 
-// familyMemberNames returns the physical spellings to look up for the
-// referenced key: the semantic-convention family members (current-first) when
-// families are on and the query can resolve to traces, else just the requested
-// name. Only the traces storage understands families today. Logs and
-// metrics keep the requested spelling until theirs land.
-func familyMemberNames(familiesOn bool, signal telemetrytypes.Signal, field *telemetrytypes.TelemetryFieldKey) []string {
-	if !familiesOn {
-		return []string{field.Name}
+// familySpellings returns the storage spellings for the selector. Metrics
+// add the span-metrics label layout.
+func familySpellings(selector telemetrytypes.FieldKeySelector) []string {
+	if selector.Signal == telemetrytypes.SignalMetrics {
+		return MetricLabelSpellings(selector)
 	}
-	if signal != telemetrytypes.SignalUnspecified && signal != telemetrytypes.SignalTraces {
-		return []string{field.Name}
-	}
-	return semconv.Members(semconv.KindAttribute, telemetrytypes.FieldKeySelector{
-		Name:         field.Name,
-		Signal:       telemetrytypes.SignalTraces,
-		FieldContext: field.FieldContext,
-	})
+	return semconv.Members(semconv.KindAttribute, selector)
 }
 
-// matchingLogicalFields resolves the referenced key against the metadata map
-// into logical fields, honoring any context/data type the user specified.
-//
-// Physical keys that are members of one semantic-convention family (traces
-// only today) group into one logical field per (signal, context, data type)
-// identity, members ordered current-first. Every other matching key becomes
-// its own single-member logical field. Ambiguity is the length of the
-// returned slice: one family is one element and is never ambiguous with
-// itself, but the slice can hold several logical fields, including several
-// family fields, one per identity, when the family exists under more than
-// one context or data type. Members alias the metadata map entries; nothing
-// is copied or mutated.
-//
-// Family grouping only happens when families are on for the query. Off,
-// every match stays a single-member logical field.
-func matchingLogicalFields(familiesOn bool, signal telemetrytypes.Signal, field *telemetrytypes.TelemetryFieldKey, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.LogicalField {
-	members := familyMemberNames(familiesOn, signal, field)
-	matches := collectMemberMatches(field, members, fieldKeys)
+// matchingLogicalFields resolves the key against the metadata map. Members
+// of one family group into one logical field per (signal, context, data
+// type) identity, current first. Every other match is its own single-member
+// field. The length of the result is the ambiguity: a family is never
+// ambiguous with itself. Members alias the map entries. With families off,
+// only the requested name is looked up. The key's own signal wins over the
+// query's signal.
+func matchingLogicalFields(familiesOn bool, signal telemetrytypes.Signal, metric *telemetrytypes.MetricContext, field *telemetrytypes.TelemetryFieldKey, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []*telemetrytypes.LogicalField {
+	members := []string{field.Name}
+	if familiesOn {
+		if field.Signal != telemetrytypes.SignalUnspecified {
+			signal = field.Signal
+		}
+		members = familySpellings(telemetrytypes.FieldKeySelector{
+			Name:          field.Name,
+			Signal:        signal,
+			FieldContext:  field.FieldContext,
+			MetricContext: metric,
+		})
+	}
+	matches := collectMemberMatches(field, members, metric, fieldKeys)
 	return groupIntoLogicalFields(field.Name, len(members) > 1, matches)
 }
 
@@ -1060,48 +1053,35 @@ type memberMatch struct {
 	rank int
 }
 
-// matchesRequestedIdentity reports whether the entry fits the context and data
-// type that the request specified; unspecified matches any. A context-prefixed
-// lookup already matched the context through the lookup key itself.
-func matchesRequestedIdentity(field, item *telemetrytypes.TelemetryFieldKey, contextMatched bool) bool {
-	if !contextMatched && field.FieldContext != telemetrytypes.FieldContextUnspecified && field.FieldContext != item.FieldContext {
-		return false
-	}
-	if field.FieldDataType != telemetrytypes.FieldDataTypeUnspecified && field.FieldDataType != item.FieldDataType {
-		return false
-	}
-	return true
-}
-
-// inFamilyScope reports whether a match found under a sibling member name is
-// legitimate: the entry must be trace metadata, and the member must be in the
-// family of the requested name for the entry's context. A member lookup can
-// otherwise find a same-named field in a scope where the family does not
-// apply.
-func inFamilyScope(field, item *telemetrytypes.TelemetryFieldKey, memberName string) bool {
-	if item.Signal != telemetrytypes.SignalTraces {
-		return false
-	}
-	return slices.Contains(semconv.Members(semconv.KindAttribute, telemetrytypes.FieldKeySelector{
-		Name:         field.Name,
-		Signal:       telemetrytypes.SignalTraces,
-		FieldContext: item.FieldContext,
-	}), memberName)
-}
-
-// collectMemberMatches finds the metadata entries for every member spelling:
-// first under the member names, then under their context-prefixed spellings
-// (a context can be a legitimate part of a stored name, e.g. `attribute.key`).
-func collectMemberMatches(field *telemetrytypes.TelemetryFieldKey, members []string, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []memberMatch {
+// collectMemberMatches finds the metadata entries for every member spelling,
+// under the member name and under its context-prefixed spelling, because a
+// context can be part of a stored name. An unspecified context or data type
+// matches any.
+func collectMemberMatches(field *telemetrytypes.TelemetryFieldKey, members []string, metric *telemetrytypes.MetricContext, fieldKeys map[string][]*telemetrytypes.TelemetryFieldKey) []memberMatch {
 	matches := make([]memberMatch, 0)
 	collect := func(lookupName string, rank int, memberName string, contextMatched bool) {
 		for _, item := range fieldKeys[lookupName] {
-			if !matchesRequestedIdentity(field, item, contextMatched) {
+			// A context-prefixed lookup matched the context through the key.
+			if !contextMatched && field.FieldContext != telemetrytypes.FieldContextUnspecified && field.FieldContext != item.FieldContext {
 				continue
 			}
-			if memberName != field.Name && !inFamilyScope(field, item, memberName) {
+			if field.FieldDataType != telemetrytypes.FieldDataTypeUnspecified && field.FieldDataType != item.FieldDataType {
 				continue
 			}
+			if memberName != field.Name {
+				// A sibling can match a same-named field where the family does
+				// not apply, so the member must be a spelling of the requested
+				// name for the entry's own signal and context.
+				spellings := familySpellings(telemetrytypes.FieldKeySelector{
+					Name:          field.Name,
+					Signal:        item.Signal,
+					FieldContext:  item.FieldContext,
+					MetricContext: metric,
+				})
+				if !slices.Contains(spellings, memberName) {
+					continue
+				}
+			}
 			matches = append(matches, memberMatch{key: item, rank: rank})
 		}
 	}
@@ -1117,18 +1097,22 @@ func collectMemberMatches(field *telemetrytypes.TelemetryFieldKey, members []str
 	return matches
 }
 
-// groupIntoLogicalFields turns matches into logical fields. Trace entries in
-// family mode group by their (signal, context, data type) identity; every
-// other entry becomes its own single-member field. Members sort by family
-// rank at the end: precedence is a property of the family, not of the order
-// in which the lookups found the members.
+// groupIntoLogicalFields groups a string entry of a family signal under the
+// resource or attribute context by its (signal, context, data type)
+// identity. Every other entry is its own single-member field. Members sort
+// by family rank, not by lookup order.
 func groupIntoLogicalFields(requestedName string, familyMode bool, matches []memberMatch) []*telemetrytypes.LogicalField {
 	fields := make([]*telemetrytypes.LogicalField, 0, len(matches))
 	groups := make(map[string]*telemetrytypes.LogicalField)
 	ranks := make(map[*telemetrytypes.TelemetryFieldKey]int)
 
 	for _, match := range matches {
-		if !familyMode || match.key.Signal != telemetrytypes.SignalTraces {
+		familySignal := match.key.Signal == telemetrytypes.SignalTraces ||
+			match.key.Signal == telemetrytypes.SignalLogs ||
+			match.key.Signal == telemetrytypes.SignalMetrics
+		familyContext := match.key.FieldContext == telemetrytypes.FieldContextResource ||
+			match.key.FieldContext == telemetrytypes.FieldContextAttribute
+		if !familyMode || !familySignal || !familyContext || match.key.FieldDataType != telemetrytypes.FieldDataTypeString {
 			fields = append(fields, telemetrytypes.SingleLogicalField(requestedName, match.key))
 			continue
 		}
@@ -1145,7 +1129,10 @@ func groupIntoLogicalFields(requestedName string, familyMode bool, matches []mem
 			groups[identity] = group
 			fields = append(fields, group)
 		}
-		if groupHasMemberNamed(group, match.key.Name) {
+		alreadyMember := slices.ContainsFunc(group.Members, func(member *telemetrytypes.TelemetryFieldKey) bool {
+			return member.Name == match.key.Name
+		})
+		if alreadyMember {
 			continue
 		}
 		ranks[match.key] = match.rank
@@ -1159,12 +1146,3 @@ func groupIntoLogicalFields(requestedName string, familyMode bool, matches []mem
 	}
 	return fields
 }
-
-func groupHasMemberNamed(group *telemetrytypes.LogicalField, name string) bool {
-	for _, member := range group.Members {
-		if member.Name == name {
-			return true
-		}
-	}
-	return false
-}

pkg/querybuilder/where_clause_visitor_test.go

@@ -589,7 +589,7 @@ func TestVisitKey(t *testing.T) {
 			// and decides not-found handling. Replay that here against the generic
 			// builder behavior (error unless the key is ignored). The test maps carry
 			// no signal, so every logical field is single-member and flattens losslessly.
-			matching := matchingLogicalFields(false, telemetrytypes.SignalUnspecified, key, tt.fieldKeys)
+			matching := matchingLogicalFields(false, telemetrytypes.SignalUnspecified, nil, key, tt.fieldKeys)
 			resolved, warning := ResolveLogicalFields(key, matching)
 			keys := make([]*telemetrytypes.TelemetryFieldKey, 0, len(resolved))
 			for _, logical := range resolved {

pkg/semconv/families_gen.go

@@ -2,21 +2,37 @@
 
 package semconv
 
+import "github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+
 var families = []Family{
 	{
-		Current:        "db.system.name",
-		Old:            []string{"db.system"},
-		Kind:           KindAttribute,
-		Contexts:       nil,
-		Signals:        nil,
-		ApplyToMetrics: nil,
+		current: "container.cpu.usage",
+		kind:    KindMetric,
+		members: []Member{
+			{name: "container.cpu.utilization"},
+		},
 	},
 	{
-		Current:        "deployment.environment.name",
-		Old:            []string{"deployment.environment"},
-		Kind:           KindAttribute,
-		Contexts:       nil,
-		Signals:        nil,
-		ApplyToMetrics: nil,
+		current: "deployment.environment.name",
+		kind:    KindAttribute,
+		members: []Member{
+			{name: "deployment.environment"},
+		},
+		contexts: []telemetrytypes.FieldContext{telemetrytypes.FieldContextAttribute, telemetrytypes.FieldContextResource},
+		signals:  []telemetrytypes.Signal{telemetrytypes.SignalLogs, telemetrytypes.SignalMetrics, telemetrytypes.SignalTraces},
+	},
+	{
+		current: "k8s.node.cpu.usage",
+		kind:    KindMetric,
+		members: []Member{
+			{name: "k8s.node.cpu.utilization"},
+		},
+	},
+	{
+		current: "k8s.pod.cpu.usage",
+		kind:    KindMetric,
+		members: []Member{
+			{name: "k8s.pod.cpu.utilization"},
+		},
 	},
 }

pkg/semconv/semconv.go

@@ -1,6 +1,7 @@
 package semconv
 
 import (
+	"iter"
 	"slices"
 
 	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
@@ -14,16 +15,47 @@ type Kind struct {
 	valuer.String
 }
 
-// Family is one logical telemetry field. Old is ordered from the most recent
-// predecessor to the oldest one and therefore also defines fallback order.
+// Member is one historical spelling with the scope of its rename edges. A
+// nil axis is unconstrained.
+type Member struct {
+	name           string
+	contexts       []telemetrytypes.FieldContext
+	signals        []telemetrytypes.Signal
+	applyToMetrics []string
+}
+
+func (m Member) Name() string {
+	return m.name
+}
+
+// Family is one logical telemetry field. Members run from the most recent
+// predecessor to the oldest, which is the fallback order. The family-level
+// contexts and signals come from the overlay and gate where the family
+// resolves. The member scopes come from the schema edges and gate which
+// members apply.
 type Family struct {
-	Current        string
-	Old            []string
-	Kind           Kind
-	Contexts       []telemetrytypes.FieldContext
-	Signals        []telemetrytypes.Signal
-	ApplyToMetrics []string
-	ValueMap       map[string]string
+	current  string
+	kind     Kind
+	members  []Member
+	contexts []telemetrytypes.FieldContext
+	signals  []telemetrytypes.Signal
+}
+
+func (f Family) Current() string {
+	return f.current
+}
+
+func (f Family) Kind() Kind {
+	return f.kind
+}
+
+// Old returns the historical spellings in fallback order.
+func (f Family) Old() []string {
+	names := make([]string, len(f.members))
+	for i, member := range f.members {
+		names[i] = member.name
+	}
+	return names
 }
 
 var (
@@ -38,90 +70,143 @@ func (Kind) Enum() []any {
 	return []any{KindAttribute, KindMetric}
 }
 
-// Lookup returns the enabled family containing selector.Name for kind. The
-// returned family must not be modified.
-func Lookup(kind Kind, selector telemetrytypes.FieldKeySelector) (Family, bool) {
-	idx, ok := lookupIndex(kind, selector)
-	if !ok {
-		return Family{}, false
-	}
-	return families[idx], true
-}
-
-// Members returns the current name first, followed by historical names in
-// fallback order. A name outside an enabled family is returned unchanged. The
-// returned slice must not be modified.
+// Members returns the current name first, followed by the historical spellings
+// admitted for the selector, in fallback order. A name outside an enabled
+// family is returned unchanged. So is a name the selector leaves ambiguous.
+// The returned slice must not be modified.
 func Members(kind Kind, selector telemetrytypes.FieldKeySelector) []string {
 	idx, ok := lookupIndex(kind, selector)
 	if !ok {
 		return []string{selector.Name}
 	}
-	return familyMembers[idx]
+	return admittedMembers(idx, selector)
+}
+
+func admittedMembers(idx int, selector telemetrytypes.FieldKeySelector) []string {
+	admitted := 0
+	for _, member := range families[idx].members {
+		if memberAdmits(member, selector) {
+			admitted++
+		}
+	}
+	if admitted == len(families[idx].members) {
+		return familyMembers[idx]
+	}
+	names := make([]string, 0, admitted+1)
+	names = append(names, families[idx].current)
+	for _, member := range families[idx].members {
+		if memberAdmits(member, selector) {
+			names = append(names, member.name)
+		}
+	}
+	return names
 }
 
 // Current returns the current name for selector.Name, or the input name when
-// it does not belong to an enabled family.
+// it does not resolve to a family.
 func Current(kind Kind, selector telemetrytypes.FieldKeySelector) string {
 	idx, ok := lookupIndex(kind, selector)
 	if !ok {
 		return selector.Name
 	}
-	return families[idx].Current
+	return families[idx].current
 }
 
-// All returns every enabled family. The returned slice and families must not be
-// modified.
-func All() []Family {
-	return families
+func All() iter.Seq[Family] {
+	return func(yield func(Family) bool) {
+		for _, family := range families {
+			if !yield(family) {
+				return
+			}
+		}
+	}
 }
 
 func buildIndexes() (map[string][]int, [][]string) {
 	index := make(map[string][]int)
 	members := make([][]string, len(families))
+	add := func(name string, i int) {
+		if !slices.Contains(index[name], i) {
+			index[name] = append(index[name], i)
+		}
+	}
 	for i, family := range families {
-		members[i] = make([]string, 0, len(family.Old)+1)
-		members[i] = append(members[i], family.Current)
-		members[i] = append(members[i], family.Old...)
-		index[family.Current] = append(index[family.Current], i)
-		for _, old := range family.Old {
-			index[old] = append(index[old], i)
+		members[i] = make([]string, 0, len(family.members)+1)
+		members[i] = append(members[i], family.current)
+		add(family.current, i)
+		for _, member := range family.members {
+			members[i] = append(members[i], member.name)
+			add(member.name, i)
 		}
 	}
 	return index, members
 }
 
+// lookupIndex returns the one family that admits selector.Name for kind.
+// An axis the selector leaves empty constrains nothing. When more than one
+// family is admitted, the name stays literal.
 func lookupIndex(kind Kind, selector telemetrytypes.FieldKeySelector) (int, bool) {
+	found, foundIdx := 0, 0
 	for _, idx := range memberToFamilies[selector.Name] {
-		if matchesSelector(families[idx], kind, selector) {
-			return idx, true
+		if familyAdmits(families[idx], kind, selector) {
+			found++
+			foundIdx = idx
 		}
 	}
-	return 0, false
+	if found != 1 {
+		return 0, false
+	}
+	return foundIdx, true
 }
 
-func matchesSelector(family Family, kind Kind, selector telemetrytypes.FieldKeySelector) bool {
-	if family.Kind != kind {
+// familyAdmits reports whether the family gate admits the selector and the
+// name is the current name or an admitted member.
+func familyAdmits(family Family, kind Kind, selector telemetrytypes.FieldKeySelector) bool {
+	if family.kind != kind {
 		return false
 	}
-
-	if selector.Signal != telemetrytypes.SignalUnspecified && len(family.Signals) > 0 {
-		if !slices.Contains(family.Signals, selector.Signal) {
-			return false
+	if !axisAdmits(family.signals, selector.Signal, telemetrytypes.SignalUnspecified) {
+		return false
+	}
+	if !axisAdmits(family.contexts, selector.FieldContext, telemetrytypes.FieldContextUnspecified) {
+		return false
+	}
+	if selector.Name == family.current {
+		for _, member := range family.members {
+			if memberAdmits(member, selector) {
+				return true
+			}
+		}
+		return false
+	}
+	for _, member := range family.members {
+		if member.name == selector.Name && memberAdmits(member, selector) {
+			return true
 		}
 	}
+	return false
+}
 
-	if selector.FieldContext != telemetrytypes.FieldContextUnspecified && len(family.Contexts) > 0 {
-		if !slices.Contains(family.Contexts, selector.FieldContext) {
-			return false
-		}
+// memberAdmits reports whether the member applies for the selector. An empty
+// axis on either side admits.
+func memberAdmits(member Member, selector telemetrytypes.FieldKeySelector) bool {
+	if !axisAdmits(member.signals, selector.Signal, telemetrytypes.SignalUnspecified) {
+		return false
 	}
-
-	if selector.Signal == telemetrytypes.SignalMetrics && len(family.ApplyToMetrics) > 0 {
-		if selector.MetricContext == nil {
-			return false
-		}
-		return slices.Contains(family.ApplyToMetrics, selector.MetricContext.MetricName)
+	if !axisAdmits(member.contexts, selector.FieldContext, telemetrytypes.FieldContextUnspecified) {
+		return false
+	}
+	if len(member.applyToMetrics) > 0 &&
+		selector.MetricContext != nil && selector.MetricContext.MetricName != "" &&
+		!slices.Contains(member.applyToMetrics, selector.MetricContext.MetricName) {
+		return false
 	}
-
 	return true
 }
+
+func axisAdmits[T comparable](scope []T, value T, unspecified T) bool {
+	if len(scope) == 0 || value == unspecified {
+		return true
+	}
+	return slices.Contains(scope, value)
+}

pkg/semconv/semconv_test.go

@@ -78,3 +78,116 @@ func TestMembersReturnsInputWhenKindDoesNotMatch(t *testing.T) {
 		"an attribute family must not match a metric-name lookup",
 	)
 }
+
+func TestFamilySignalsGateResolution(t *testing.T) {
+	swapFamilies(t, []Family{{
+		current: "gated.current",
+		kind:    KindAttribute,
+		members: []Member{{name: "gated.old"}},
+		signals: []telemetrytypes.Signal{telemetrytypes.SignalLogs, telemetrytypes.SignalTraces},
+	}})
+	metrics := telemetrytypes.FieldKeySelector{Name: "gated.old", Signal: telemetrytypes.SignalMetrics}
+	logs := telemetrytypes.FieldKeySelector{Name: "gated.old", Signal: telemetrytypes.SignalLogs}
+
+	assert.Equal(t, []string{"gated.old"}, Members(KindAttribute, metrics),
+		"a family gated to traces and logs must stay literal for metrics")
+	assert.Equal(t, []string{"gated.current", "gated.old"}, Members(KindAttribute, logs),
+		"the gate admits the signals it lists")
+}
+
+func TestMetricNameFamilyResolves(t *testing.T) {
+	selector := telemetrytypes.FieldKeySelector{Name: "k8s.pod.cpu.utilization", Signal: telemetrytypes.SignalMetrics}
+
+	assert.Equal(t, []string{"k8s.pod.cpu.usage", "k8s.pod.cpu.utilization"}, Members(KindMetric, selector))
+	assert.Equal(t, "k8s.pod.cpu.usage", Current(KindMetric, selector))
+	assert.Equal(t, []string{"k8s.pod.cpu.utilization"}, Members(KindAttribute, selector),
+		"a metric-name family must not match an attribute lookup")
+}
+
+func TestMembersReturnsSharedSliceForUnscopedFamily(t *testing.T) {
+	selector := telemetrytypes.FieldKeySelector{Name: "deployment.environment", Signal: telemetrytypes.SignalTraces}
+
+	first := Members(KindAttribute, selector)
+	second := Members(KindAttribute, selector)
+	assert.Equal(t, &first[0], &second[0],
+		"a family whose members all admit must return the precomputed slice, not a copy")
+}
+
+func TestAllIteratesEnabledFamilies(t *testing.T) {
+	currents := []string{}
+	for family := range All() {
+		currents = append(currents, family.Current())
+	}
+	assert.Contains(t, currents, "deployment.environment.name")
+	assert.Contains(t, currents, "k8s.pod.cpu.usage")
+}
+
+// swapFamilies replaces the generated table for one test so scoped-member and
+// fan-out behavior can be pinned without enabling such families for real.
+func swapFamilies(t *testing.T, replacement []Family) {
+	t.Helper()
+	prevFamilies, prevIndex, prevMembers := families, memberToFamilies, familyMembers
+	families = replacement
+	memberToFamilies, familyMembers = buildIndexes()
+	t.Cleanup(func() {
+		families, memberToFamilies, familyMembers = prevFamilies, prevIndex, prevMembers
+	})
+}
+
+func TestFanOutResolvesOnlyWithEnoughInformation(t *testing.T) {
+	swapFamilies(t, []Family{
+		{
+			current: "cpu.mode",
+			kind:    KindAttribute,
+			members: []Member{{name: "state", applyToMetrics: []string{"system.cpu.time"}}},
+		},
+		{
+			current: "db.client.connection.state",
+			kind:    KindAttribute,
+			members: []Member{{name: "state", applyToMetrics: []string{"db.client.connections.usage"}}},
+		},
+	})
+
+	ambiguous := telemetrytypes.FieldKeySelector{Name: "state", Signal: telemetrytypes.SignalMetrics}
+	assert.Equal(t, []string{"state"}, Members(KindAttribute, ambiguous),
+		"without a metric name, a fanned-out member admits several families and must stay literal")
+
+	pinned := ambiguous
+	pinned.MetricContext = &telemetrytypes.MetricContext{MetricName: "system.cpu.time"}
+	assert.Equal(t, []string{"cpu.mode", "state"}, Members(KindAttribute, pinned),
+		"the metric name disambiguates the fan-out")
+
+	outside := ambiguous
+	outside.MetricContext = &telemetrytypes.MetricContext{MetricName: "http.server.duration"}
+	assert.Equal(t, []string{"state"}, Members(KindAttribute, outside),
+		"a metric outside every apply_to_metrics list resolves no family")
+}
+
+func TestMemberScopesFilterMembers(t *testing.T) {
+	swapFamilies(t, []Family{{
+		current: "user_agent.original",
+		kind:    KindAttribute,
+		members: []Member{
+			{name: "http.user_agent", contexts: []telemetrytypes.FieldContext{telemetrytypes.FieldContextAttribute}, signals: []telemetrytypes.Signal{telemetrytypes.SignalTraces}},
+			{name: "browser.user_agent", contexts: []telemetrytypes.FieldContext{telemetrytypes.FieldContextResource}},
+		},
+	}})
+
+	resource := telemetrytypes.FieldKeySelector{
+		Name:         "user_agent.original",
+		Signal:       telemetrytypes.SignalTraces,
+		FieldContext: telemetrytypes.FieldContextResource,
+	}
+	assert.Equal(t, []string{"user_agent.original", "browser.user_agent"}, Members(KindAttribute, resource),
+		"a strict resource lookup must not include the span-only member")
+
+	attribute := resource
+	attribute.FieldContext = telemetrytypes.FieldContextAttribute
+	assert.Equal(t, []string{"user_agent.original", "http.user_agent"}, Members(KindAttribute, attribute),
+		"a strict attribute lookup must not include the resource-only member")
+
+	strictResourceOldSpan := resource
+	strictResourceOldSpan.Name = "http.user_agent"
+	assert.Equal(t, []string{"http.user_agent"}, Members(KindAttribute, strictResourceOldSpan),
+		"an old spelling outside its own scope stays literal")
+}

pkg/statementbuilder/logsstatementbuilder/family_test.go

@@ -0,0 +1,256 @@
+package logsstatementbuilder
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/statementbuilder"
+	"github.com/SigNoz/signoz/pkg/telemetryschema/logstelemetryschema"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes/telemetrytypestest"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/stretchr/testify/require"
+)
+
+// A filter on either spelling of an enabled family compiles to one merged
+// condition over the log resource maps. The flag default keeps it literal.
+func TestStatementBuilderResolvesLogFamilies(t *testing.T) {
+	releaseTime := time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC)
+	releaseTimeNano := uint64(releaseTime.UnixNano())
+
+	testCases := []struct {
+		name     string
+		familyOn bool
+		expected string
+	}{
+		{
+			name:     "FamiliesOn",
+			familyOn: true,
+			expected: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_logs.distributed_logs_v2_resource WHERE (COALESCE(NULLIF(simpleJSONExtractString(labels, 'deployment.environment.name'), ''), NULLIF(simpleJSONExtractString(labels, 'deployment.environment'), ''), '') = ? AND (labels LIKE ? OR labels LIKE ?) AND (labels LIKE ? OR labels LIKE ?)) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT count() AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? ORDER BY __result_0 DESC",
+		},
+		{
+			name:     "FamiliesOff",
+			familyOn: false,
+			expected: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_logs.distributed_logs_v2_resource WHERE (simpleJSONExtractString(labels, 'deployment.environment') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT count() AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? ORDER BY __result_0 DESC",
+		},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+				flagger.FeatureResolveSemconvFamilies.String(): testCase.familyOn,
+			})
+			mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+			keys := logstelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
+			for _, name := range []string{"deployment.environment.name", "deployment.environment"} {
+				keys[name] = []*telemetrytypes.TelemetryFieldKey{{
+					Name:          name,
+					Signal:        telemetrytypes.SignalLogs,
+					FieldContext:  telemetrytypes.FieldContextResource,
+					FieldDataType: telemetrytypes.FieldDataTypeString,
+				}}
+			}
+			mockMetadataStore.KeysMap = keys
+			storage := logstelemetryschema.NewStorage()
+			aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, storage, fl, telemetrytypes.SignalLogs)
+			statementBuilder := NewLogQueryStatementBuilder(
+				instrumentationtest.New().ToProviderSettings(),
+				mockMetadataStore, storage, aggExprRewriter,
+				logstelemetryschema.DefaultFullTextColumn, fl, nil,
+				statementbuilder.Config{SkipResourceFingerprint: statementbuilder.SkipResourceFingerprint{Enabled: false, Threshold: 100000}},
+			)
+
+			query := qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+				Signal:       telemetrytypes.SignalLogs,
+				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+				Aggregations: []qbtypes.LogAggregation{{Expression: "count()"}},
+				Filter:       &qbtypes.Filter{Expression: "resource.deployment.environment = 'production'"},
+			}
+			q, err := statementBuilder.Build(context.Background(), valuer.UUID{},
+				releaseTimeNano+uint64(24*time.Hour.Nanoseconds()),
+				releaseTimeNano+uint64(48*time.Hour.Nanoseconds()),
+				qbtypes.RequestTypeScalar, query, nil)
+			require.NoError(t, err)
+			require.Equal(t, testCase.expected, q.Query)
+		})
+	}
+}
+
+// The predicate of a filtered aggregation resolves the family exactly like
+// the main WHERE clause.
+func TestStatementBuilderResolvesLogFamilyFilteredAggregation(t *testing.T) {
+	releaseTime := time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC)
+	releaseTimeNano := uint64(releaseTime.UnixNano())
+
+	testCases := []struct {
+		name     string
+		familyOn bool
+		expected string
+	}{
+		{name: "FamiliesOn", familyOn: true, expected: "SELECT countIf((COALESCE(NULLIF(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL), ''), NULLIF(multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL), ''), '') = ? AND (multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL) IS NOT NULL OR multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL) IS NOT NULL))) AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? ORDER BY __result_0 DESC"},
+		{name: "FamiliesOff", familyOn: false, expected: "SELECT countIf(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL) = ?) AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? ORDER BY __result_0 DESC"},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+				flagger.FeatureResolveSemconvFamilies.String(): testCase.familyOn,
+			})
+			mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+			keys := logstelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
+			for _, name := range []string{"deployment.environment.name", "deployment.environment"} {
+				keys[name] = []*telemetrytypes.TelemetryFieldKey{{
+					Name:          name,
+					Signal:        telemetrytypes.SignalLogs,
+					FieldContext:  telemetrytypes.FieldContextResource,
+					FieldDataType: telemetrytypes.FieldDataTypeString,
+				}}
+			}
+			mockMetadataStore.KeysMap = keys
+			storage := logstelemetryschema.NewStorage()
+			aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, storage, fl, telemetrytypes.SignalLogs)
+			statementBuilder := NewLogQueryStatementBuilder(
+				instrumentationtest.New().ToProviderSettings(),
+				mockMetadataStore, storage, aggExprRewriter,
+				logstelemetryschema.DefaultFullTextColumn, fl, nil,
+				statementbuilder.Config{SkipResourceFingerprint: statementbuilder.SkipResourceFingerprint{Enabled: false, Threshold: 100000}},
+			)
+
+			query := qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+				Signal:       telemetrytypes.SignalLogs,
+				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+				Aggregations: []qbtypes.LogAggregation{{Expression: "countIf(deployment.environment.name = 'production')"}},
+			}
+			q, err := statementBuilder.Build(context.Background(), valuer.UUID{},
+				releaseTimeNano+uint64(24*time.Hour.Nanoseconds()),
+				releaseTimeNano+uint64(48*time.Hour.Nanoseconds()),
+				qbtypes.RequestTypeScalar, query, nil)
+			require.NoError(t, err)
+			require.Equal(t, testCase.expected, q.Query)
+		})
+	}
+}
+
+// The mid-migration state: metadata holds one spelling of the family, and
+// the query names the other. The filter and the group by both read the one
+// stored spelling.
+func TestStatementBuilderResolvesSingleSpellingAcrossNames(t *testing.T) {
+	releaseTime := time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC)
+	releaseTimeNano := uint64(releaseTime.UnixNano())
+
+	testCases := []struct {
+		name     string
+		stored   string
+		queried  string
+		expected string
+	}{
+		{name: "OldDataQueriedByCurrentName", stored: "deployment.environment", queried: "deployment.environment.name", expected: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_logs.distributed_logs_v2_resource WHERE (simpleJSONExtractString(labels, 'deployment.environment') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT toString(multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL)) AS `__GROUP_BY_KEY_0_deployment.environment.name`, count() AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY __result_0 DESC"},
+		{name: "CurrentDataQueriedByOldName", stored: "deployment.environment.name", queried: "deployment.environment", expected: "WITH __resource_filter AS (SELECT fingerprint FROM signoz_logs.distributed_logs_v2_resource WHERE (simpleJSONExtractString(labels, 'deployment.environment.name') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT toString(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL)) AS `__GROUP_BY_KEY_0_deployment.environment`, count() AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_deployment.environment` ORDER BY __result_0 DESC"},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+				flagger.FeatureResolveSemconvFamilies.String(): true,
+			})
+			mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+			keys := logstelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
+			keys[testCase.stored] = []*telemetrytypes.TelemetryFieldKey{{
+				Name:          testCase.stored,
+				Signal:        telemetrytypes.SignalLogs,
+				FieldContext:  telemetrytypes.FieldContextResource,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			}}
+			mockMetadataStore.KeysMap = keys
+			storage := logstelemetryschema.NewStorage()
+			aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, storage, fl, telemetrytypes.SignalLogs)
+			statementBuilder := NewLogQueryStatementBuilder(
+				instrumentationtest.New().ToProviderSettings(),
+				mockMetadataStore, storage, aggExprRewriter,
+				logstelemetryschema.DefaultFullTextColumn, fl, nil,
+				statementbuilder.Config{SkipResourceFingerprint: statementbuilder.SkipResourceFingerprint{Enabled: false, Threshold: 100000}},
+			)
+
+			query := qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+				Signal:       telemetrytypes.SignalLogs,
+				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+				Aggregations: []qbtypes.LogAggregation{{Expression: "count()"}},
+				Filter:       &qbtypes.Filter{Expression: testCase.queried + " = 'production'"},
+				GroupBy: []qbtypes.GroupByKey{
+					{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: testCase.queried}},
+				},
+			}
+			q, err := statementBuilder.Build(context.Background(), valuer.UUID{},
+				releaseTimeNano+uint64(24*time.Hour.Nanoseconds()),
+				releaseTimeNano+uint64(48*time.Hour.Nanoseconds()),
+				qbtypes.RequestTypeScalar, query, nil)
+			require.NoError(t, err)
+			require.Equal(t, testCase.expected, q.Query)
+		})
+	}
+}
+
+// Group by resolves the family exactly like the filter. The merged column
+// reads the spellings current-first with empty falling through, and a row
+// with no member keeps the NULL group of a single key.
+func TestStatementBuilderResolvesLogFamilyGroupBy(t *testing.T) {
+	releaseTime := time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC)
+	releaseTimeNano := uint64(releaseTime.UnixNano())
+
+	testCases := []struct {
+		name     string
+		familyOn bool
+		expected string
+	}{
+		{name: "FamiliesOn", familyOn: true, expected: "SELECT toString(multiIf((multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL) IS NOT NULL OR multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL) IS NOT NULL), COALESCE(NULLIF(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL), ''), NULLIF(multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL), ''), ''), NULL)) AS `__GROUP_BY_KEY_0_deployment.environment.name`, count() AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY __result_0 DESC"},
+		{name: "FamiliesOff", familyOn: false, expected: "SELECT toString(multiIf(resource.`deployment.environment.name` IS NOT NULL, resource.`deployment.environment.name`::String, mapContains(resources_string, 'deployment.environment.name'), resources_string['deployment.environment.name'], NULL)) AS `__GROUP_BY_KEY_0_deployment.environment.name`, count() AS __result_0 FROM signoz_logs.distributed_logs_v2 WHERE timestamp >= ? AND ts_bucket_start >= ? AND timestamp < ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY __result_0 DESC"},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+				flagger.FeatureResolveSemconvFamilies.String(): testCase.familyOn,
+			})
+			mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+			keys := logstelemetryschema.BuildCompleteFieldKeyMap(releaseTime)
+			for _, name := range []string{"deployment.environment.name", "deployment.environment"} {
+				keys[name] = []*telemetrytypes.TelemetryFieldKey{{
+					Name:          name,
+					Signal:        telemetrytypes.SignalLogs,
+					FieldContext:  telemetrytypes.FieldContextResource,
+					FieldDataType: telemetrytypes.FieldDataTypeString,
+				}}
+			}
+			mockMetadataStore.KeysMap = keys
+			storage := logstelemetryschema.NewStorage()
+			aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, storage, fl, telemetrytypes.SignalLogs)
+			statementBuilder := NewLogQueryStatementBuilder(
+				instrumentationtest.New().ToProviderSettings(),
+				mockMetadataStore, storage, aggExprRewriter,
+				logstelemetryschema.DefaultFullTextColumn, fl, nil,
+				statementbuilder.Config{SkipResourceFingerprint: statementbuilder.SkipResourceFingerprint{Enabled: false, Threshold: 100000}},
+			)
+
+			query := qbtypes.QueryBuilderQuery[qbtypes.LogAggregation]{
+				Signal:       telemetrytypes.SignalLogs,
+				StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+				Aggregations: []qbtypes.LogAggregation{{Expression: "count()"}},
+				GroupBy: []qbtypes.GroupByKey{
+					{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}},
+				},
+			}
+			q, err := statementBuilder.Build(context.Background(), valuer.UUID{},
+				releaseTimeNano+uint64(24*time.Hour.Nanoseconds()),
+				releaseTimeNano+uint64(48*time.Hour.Nanoseconds()),
+				qbtypes.RequestTypeScalar, query, nil)
+			require.NoError(t, err)
+			require.Equal(t, testCase.expected, q.Query)
+		})
+	}
+}

pkg/statementbuilder/logsstatementbuilder/statement_builder.go

@@ -125,6 +125,7 @@ func (b *logQueryStatementBuilder) Build(
 	bodyJSONEnabled := b.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(orgID))
 
 	keySelectors, warnings := getKeySelectors(query, bodyJSONEnabled)
+	keySelectors = querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, b.fl, keySelectors)
 	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, keySelectors)
 	if err != nil {
 		return nil, err

pkg/statementbuilder/metricsstatementbuilder/family_test.go

@@ -0,0 +1,175 @@
+package metricsstatementbuilder
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
+	"github.com/SigNoz/signoz/pkg/telemetryschema/metricstelemetryschema"
+	"github.com/SigNoz/signoz/pkg/types/metrictypes"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes/telemetrytypestest"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/stretchr/testify/require"
+)
+
+// The flag merges the label spellings of the family and unions the storage
+// names of the metric-name family, in the filter, the group by column, and
+// every metric_name filter.
+func TestStatementBuilderResolvesFamilies(t *testing.T) {
+	fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = map[string][]*telemetrytypes.TelemetryFieldKey{}
+	for _, name := range []string{"deployment.environment.name", "deployment.environment"} {
+		mockMetadataStore.KeysMap[name] = []*telemetrytypes.TelemetryFieldKey{{
+			Name:          name,
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}}
+	}
+	statementBuilder := NewMetricQueryStatementBuilder(
+		instrumentationtest.New().ToProviderSettings(),
+		mockMetadataStore,
+		metricstelemetryschema.NewStorage(),
+		fl,
+	)
+	query := qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]{
+		Signal:       telemetrytypes.SignalMetrics,
+		StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+		Aggregations: []qbtypes.MetricAggregation{
+			{
+				MetricName:       "k8s.pod.cpu.utilization",
+				Type:             metrictypes.GaugeType,
+				Temporality:      metrictypes.Unspecified,
+				TimeAggregation:  metrictypes.TimeAggregationAvg,
+				SpaceAggregation: metrictypes.SpaceAggregationAvg,
+			},
+		},
+		Filter: &qbtypes.Filter{
+			Expression: "deployment.environment = 'production'",
+		},
+		GroupBy: []qbtypes.GroupByKey{
+			{
+				TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
+					Name: "deployment.environment.name",
+				},
+			},
+		},
+	}
+
+	q, err := statementBuilder.Build(context.Background(), valuer.UUID{}, 1747947419000, 1747983448000, qbtypes.RequestTypeTimeSeries, query, nil)
+	require.NoError(t, err)
+	require.Equal(t, "WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(30)) AS ts, `__GROUP_BY_KEY_0_deployment.environment.name`, avg(value) AS per_series_value FROM signoz_metrics.distributed_samples_v4 AS points INNER JOIN (SELECT fingerprint, COALESCE(NULLIF(JSONExtractString(labels, 'deployment.environment.name'), ''), NULLIF(JSONExtractString(labels, 'deployment.environment'), ''), '') AS `__GROUP_BY_KEY_0_deployment.environment.name` FROM signoz_metrics.time_series_v4_6hrs WHERE metric_name IN (?, ?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND COALESCE(NULLIF(JSONExtractString(labels, 'deployment.environment.name'), ''), NULLIF(JSONExtractString(labels, 'deployment.environment'), ''), '') = ? GROUP BY fingerprint, `__GROUP_BY_KEY_0_deployment.environment.name`) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?, ?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts, `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, `__GROUP_BY_KEY_0_deployment.environment.name`, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts, `__GROUP_BY_KEY_0_deployment.environment.name`) SELECT * FROM __spatial_aggregation_cte ORDER BY `__GROUP_BY_KEY_0_deployment.environment.name`, ts", q.Query)
+	require.Equal(t, []any{"k8s.pod.cpu.usage", "k8s.pod.cpu.utilization", uint64(1747936800000), uint64(1747983420000), "unspecified", "production", "k8s.pod.cpu.usage", "k8s.pod.cpu.utilization", uint64(1747947390000), uint64(1747983420000), 0}, q.Args)
+}
+
+// The mid-migration state: metadata holds only the old label spelling, and
+// the query names the current one. The filter and the group by both read
+// the one stored label.
+func TestStatementBuilderResolvesSingleSpellingAcrossNames(t *testing.T) {
+	fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = map[string][]*telemetrytypes.TelemetryFieldKey{}
+	for _, name := range []string{"deployment.environment"} {
+		mockMetadataStore.KeysMap[name] = []*telemetrytypes.TelemetryFieldKey{{
+			Name:          name,
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}}
+	}
+	statementBuilder := NewMetricQueryStatementBuilder(
+		instrumentationtest.New().ToProviderSettings(),
+		mockMetadataStore,
+		metricstelemetryschema.NewStorage(),
+		fl,
+	)
+	query := qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]{
+		Signal:       telemetrytypes.SignalMetrics,
+		StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+		Aggregations: []qbtypes.MetricAggregation{
+			{
+				MetricName:       "k8s.pod.cpu.utilization",
+				Type:             metrictypes.GaugeType,
+				Temporality:      metrictypes.Unspecified,
+				TimeAggregation:  metrictypes.TimeAggregationAvg,
+				SpaceAggregation: metrictypes.SpaceAggregationAvg,
+			},
+		},
+		Filter: &qbtypes.Filter{
+			Expression: "deployment.environment.name = 'production'",
+		},
+		GroupBy: []qbtypes.GroupByKey{
+			{
+				TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
+					Name: "deployment.environment.name",
+				},
+			},
+		},
+	}
+
+	q, err := statementBuilder.Build(context.Background(), valuer.UUID{}, 1747947419000, 1747983448000, qbtypes.RequestTypeTimeSeries, query, nil)
+	require.NoError(t, err)
+	require.Equal(t, "WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(30)) AS ts, `__GROUP_BY_KEY_0_deployment.environment.name`, avg(value) AS per_series_value FROM signoz_metrics.distributed_samples_v4 AS points INNER JOIN (SELECT fingerprint, JSONExtractString(labels, 'deployment.environment') AS `__GROUP_BY_KEY_0_deployment.environment.name` FROM signoz_metrics.time_series_v4_6hrs WHERE metric_name IN (?, ?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND JSONExtractString(labels, 'deployment.environment') = ? GROUP BY fingerprint, `__GROUP_BY_KEY_0_deployment.environment.name`) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?, ?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts, `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, `__GROUP_BY_KEY_0_deployment.environment.name`, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts, `__GROUP_BY_KEY_0_deployment.environment.name`) SELECT * FROM __spatial_aggregation_cte ORDER BY `__GROUP_BY_KEY_0_deployment.environment.name`, ts", q.Query)
+}
+
+// With the flag at its default, both the labels and the metric name stay
+// literal.
+func TestStatementBuilderKeepsFamiliesLiteralByDefault(t *testing.T) {
+	fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): false,
+	})
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = map[string][]*telemetrytypes.TelemetryFieldKey{}
+	for _, name := range []string{"deployment.environment.name", "deployment.environment"} {
+		mockMetadataStore.KeysMap[name] = []*telemetrytypes.TelemetryFieldKey{{
+			Name:          name,
+			Signal:        telemetrytypes.SignalMetrics,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}}
+	}
+	statementBuilder := NewMetricQueryStatementBuilder(
+		instrumentationtest.New().ToProviderSettings(),
+		mockMetadataStore,
+		metricstelemetryschema.NewStorage(),
+		fl,
+	)
+	query := qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation]{
+		Signal:       telemetrytypes.SignalMetrics,
+		StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+		Aggregations: []qbtypes.MetricAggregation{
+			{
+				MetricName:       "k8s.pod.cpu.utilization",
+				Type:             metrictypes.GaugeType,
+				Temporality:      metrictypes.Unspecified,
+				TimeAggregation:  metrictypes.TimeAggregationAvg,
+				SpaceAggregation: metrictypes.SpaceAggregationAvg,
+			},
+		},
+		Filter: &qbtypes.Filter{
+			Expression: "deployment.environment = 'production'",
+		},
+		GroupBy: []qbtypes.GroupByKey{
+			{
+				TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{
+					Name: "deployment.environment.name",
+				},
+			},
+		},
+	}
+
+	q, err := statementBuilder.Build(context.Background(), valuer.UUID{}, 1747947419000, 1747983448000, qbtypes.RequestTypeTimeSeries, query, nil)
+	require.NoError(t, err)
+	require.Equal(t, "WITH __temporal_aggregation_cte AS (SELECT fingerprint, toStartOfInterval(toDateTime(intDiv(unix_milli, 1000)), toIntervalSecond(30)) AS ts, `__GROUP_BY_KEY_0_deployment.environment.name`, avg(value) AS per_series_value FROM signoz_metrics.distributed_samples_v4 AS points INNER JOIN (SELECT fingerprint, JSONExtractString(labels, 'deployment.environment.name') AS `__GROUP_BY_KEY_0_deployment.environment.name` FROM signoz_metrics.time_series_v4_6hrs WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli <= ? AND LOWER(temporality) LIKE LOWER(?) AND JSONExtractString(labels, 'deployment.environment') = ? GROUP BY fingerprint, `__GROUP_BY_KEY_0_deployment.environment.name`) AS filtered_time_series ON points.fingerprint = filtered_time_series.fingerprint WHERE metric_name IN (?) AND unix_milli >= ? AND unix_milli < ? GROUP BY fingerprint, ts, `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY fingerprint, ts), __spatial_aggregation_cte AS (SELECT ts, `__GROUP_BY_KEY_0_deployment.environment.name`, avg(per_series_value) AS value FROM __temporal_aggregation_cte WHERE isNaN(per_series_value) = ? GROUP BY ts, `__GROUP_BY_KEY_0_deployment.environment.name`) SELECT * FROM __spatial_aggregation_cte ORDER BY `__GROUP_BY_KEY_0_deployment.environment.name`, ts", q.Query)
+	require.Equal(t, []any{"k8s.pod.cpu.utilization", uint64(1747936800000), uint64(1747983420000), "unspecified", "production", "k8s.pod.cpu.utilization", uint64(1747947390000), uint64(1747983420000), 0}, q.Args)
+}

pkg/statementbuilder/metricsstatementbuilder/statement_builder.go

@@ -117,7 +117,9 @@ func (b *StatementBuilder) Build(
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
 	variables map[string]qbtypes.VariableItem,
 ) (*qbtypes.Statement, error) {
-	keySelectors := GetKeySelectors(query)
+	keySelectors := querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, b.flagger, GetKeySelectors(query))
+	metricNames := querybuilder.FamilyMetricNames(ctx, orgID, b.flagger, query.Aggregations[0].MetricName)
+	keySelectors = expandSelectorsForMetricNames(keySelectors, metricNames)
 	keys, _, err := b.metadataStore.GetKeysMulti(ctx, orgID, keySelectors)
 	if err != nil {
 		return nil, err
@@ -125,7 +127,30 @@ func (b *StatementBuilder) Build(
 
 	start, end = querybuilder.AdjustedMetricTimeRange(start, end, uint64(query.StepInterval.Seconds()), query)
 
-	return b.buildPipelineStatement(ctx, orgID, start, end, requestType, query, keys, variables)
+	return b.buildPipelineStatement(ctx, orgID, start, end, requestType, query, keys, metricNames, variables)
+}
+
+// expandSelectorsForMetricNames duplicates the selectors per family metric
+// name. Label-key metadata is filtered by the exact metric_name.
+func expandSelectorsForMetricNames(selectors []*telemetrytypes.FieldKeySelector, metricNames []string) []*telemetrytypes.FieldKeySelector {
+	if len(metricNames) <= 1 {
+		return selectors
+	}
+	out := selectors
+	for _, selector := range selectors {
+		if selector.MetricContext == nil {
+			continue
+		}
+		for _, metricName := range metricNames {
+			if metricName == selector.MetricContext.MetricName {
+				continue
+			}
+			expanded := *selector
+			expanded.MetricContext = &telemetrytypes.MetricContext{MetricName: metricName}
+			out = append(out, &expanded)
+		}
+	}
+	return out
 }
 
 func (b *StatementBuilder) buildPipelineStatement(
@@ -135,6 +160,7 @@ func (b *StatementBuilder) buildPipelineStatement(
 	requestType qbtypes.RequestType,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
+	metricNames []string,
 	variables map[string]qbtypes.VariableItem,
 ) (*qbtypes.Statement, error) {
 	var (
@@ -166,13 +192,13 @@ func (b *StatementBuilder) buildPipelineStatement(
 	var filterWarnings []string
 	var err error
 
-	if timeSeriesCTE, timeSeriesCTEArgs, filterWarnings, err = b.buildTimeSeriesCTE(ctx, orgID, tsStart, tsEnd, cteQuery, keys, variables, tsTable); err != nil {
+	if timeSeriesCTE, timeSeriesCTEArgs, filterWarnings, err = b.buildTimeSeriesCTE(ctx, orgID, tsStart, tsEnd, cteQuery, keys, metricNames, variables, tsTable); err != nil {
 		return nil, err
 	}
 
 	if qbtypes.CanShortCircuitDelta(agg) {
 		// spatial_aggregation_cte directly for certain delta queries
-		if frag, args, err := b.buildTemporalAggDeltaFastPath(start, end, cteQuery, samplesTable, timeSeriesCTE, timeSeriesCTEArgs); err != nil {
+		if frag, args, err := b.buildTemporalAggDeltaFastPath(start, end, cteQuery, metricNames, samplesTable, timeSeriesCTE, timeSeriesCTEArgs); err != nil {
 			return nil, err
 		} else if frag != "" {
 			cteFragments = append(cteFragments, frag)
@@ -180,7 +206,7 @@ func (b *StatementBuilder) buildPipelineStatement(
 		}
 	} else {
 		// temporal_aggregation_cte
-		if frag, args, err := b.buildTemporalAggregationCTE(ctx, start, end, cteQuery, keys, samplesTable, timeSeriesCTE, timeSeriesCTEArgs); err != nil {
+		if frag, args, err := b.buildTemporalAggregationCTE(ctx, start, end, cteQuery, keys, metricNames, samplesTable, timeSeriesCTE, timeSeriesCTEArgs); err != nil {
 			return nil, err
 		} else if frag != "" {
 			cteFragments = append(cteFragments, frag)
@@ -201,16 +227,16 @@ func (b *StatementBuilder) buildPipelineStatement(
 		var tsArgs []any
 		// time series rows are written on hour boundaries
 		tsStart := start - (start % metricstelemetryschema.OneHourInMilliseconds)
-		if tsCTE, tsArgs, err = b.buildReducedTimeSeriesCTE(ctx, orgID, tsStart, end, cteQuery, keys, variables); err != nil {
+		if tsCTE, tsArgs, err = b.buildReducedTimeSeriesCTE(ctx, orgID, tsStart, end, cteQuery, keys, metricNames, variables); err != nil {
 			return nil, err
 		}
 		if qbtypes.CanShortCircuitReduced(agg) {
 			// spatial_aggregation_cte directly, no per-series level
-			if spatialFrag, spatialArgs, ok := b.buildReducedSpatialAggFastPath(start, end, cteQuery, tsCTE, tsArgs); ok {
+			if spatialFrag, spatialArgs, ok := b.buildReducedSpatialAggFastPath(start, end, cteQuery, metricNames, tsCTE, tsArgs); ok {
 				reducedFragments = []string{spatialFrag}
 				reducedArgs = [][]any{spatialArgs}
 			}
-		} else if temporalFrag, temporalArgs, ok := b.buildReducedTemporalAggregationCTE(start, end, cteQuery, tsCTE, tsArgs); ok {
+		} else if temporalFrag, temporalArgs, ok := b.buildReducedTemporalAggregationCTE(start, end, cteQuery, metricNames, tsCTE, tsArgs); ok {
 			spatialFrag, spatialArgs := b.buildReducedSpatialAggregationCTE(cteQuery)
 			reducedFragments = []string{temporalFrag, spatialFrag}
 			reducedArgs = [][]any{temporalArgs, spatialArgs}
@@ -268,6 +294,7 @@ func (b *StatementBuilder) buildReducedTimeSeriesCTE(
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
+	metricNames []string,
 	variables map[string]qbtypes.VariableItem,
 ) (string, []any, error) {
 	sb := sqlbuilder.NewSelectBuilder()
@@ -300,7 +327,7 @@ func (b *StatementBuilder) buildReducedTimeSeriesCTE(
 		sb.SelectMore(sqlbuilder.Escape(fmt.Sprintf("%s AS %s", col, GroupByColumnAlias(i, g.Name))))
 	}
 	sb.Where(
-		sb.In("metric_name", query.Aggregations[0].MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LTE("unix_milli", end),
 	)
@@ -325,6 +352,7 @@ func (b *StatementBuilder) buildReducedTimeSeriesCTE(
 func (b *StatementBuilder) buildReducedSpatialAggFastPath(
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
+	metricNames []string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
 ) (string, []any, bool) {
@@ -345,7 +373,7 @@ func (b *StatementBuilder) buildReducedSpatialAggFastPath(
 	sb.From(fmt.Sprintf("%s.%s AS points FINAL", metricstelemetryschema.DBName, metricstelemetryschema.WhichReducedSamplesTableToUse(agg.Type)))
 	sb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.reduced_fingerprint = filtered_time_series.fingerprint")
 	sb.Where(
-		sb.In("metric_name", agg.MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LT("unix_milli", end),
 	)
@@ -359,6 +387,7 @@ func (b *StatementBuilder) buildReducedSpatialAggFastPath(
 func (b *StatementBuilder) buildReducedTemporalAggregationCTE(
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
+	metricNames []string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
 ) (string, []any, bool) {
@@ -387,7 +416,7 @@ func (b *StatementBuilder) buildReducedTemporalAggregationCTE(
 	sb.From(fmt.Sprintf("%s.%s AS points FINAL", metricstelemetryschema.DBName, metricstelemetryschema.WhichReducedSamplesTableToUse(agg.Type)))
 	sb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.reduced_fingerprint = filtered_time_series.fingerprint")
 	sb.Where(
-		sb.In("metric_name", agg.MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LT("unix_milli", end),
 	)
@@ -428,6 +457,7 @@ func (b *StatementBuilder) buildReducedSpatialAggregationCTE(
 func (b *StatementBuilder) buildTemporalAggDeltaFastPath(
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
+	metricNames []string,
 	samplesTable string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
@@ -469,7 +499,7 @@ func (b *StatementBuilder) buildTemporalAggDeltaFastPath(
 	sb.From(fmt.Sprintf("%s.%s AS points", metricstelemetryschema.DBName, samplesTable))
 	sb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.fingerprint = filtered_time_series.fingerprint")
 	sb.Where(
-		sb.In("metric_name", query.Aggregations[0].MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LT("unix_milli", end),
 	)
@@ -486,6 +516,7 @@ func (b *StatementBuilder) buildTimeSeriesCTE(
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
 	keys map[string][]*telemetrytypes.TelemetryFieldKey,
+	metricNames []string,
 	variables map[string]qbtypes.VariableItem,
 	tsTable string,
 ) (string, []any, []string, error) {
@@ -522,7 +553,7 @@ func (b *StatementBuilder) buildTimeSeriesCTE(
 	}
 
 	sb.Where(
-		sb.In("metric_name", query.Aggregations[0].MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LTE("unix_milli", end),
 	)
@@ -554,22 +585,24 @@ func (b *StatementBuilder) buildTemporalAggregationCTE(
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
 	_ map[string][]*telemetrytypes.TelemetryFieldKey,
+	metricNames []string,
 	samplesTable string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
 ) (string, []any, error) {
 	if query.Aggregations[0].Temporality == metrictypes.Delta {
-		return b.buildTemporalAggDelta(ctx, start, end, query, samplesTable, timeSeriesCTE, timeSeriesCTEArgs)
+		return b.buildTemporalAggDelta(ctx, start, end, query, metricNames, samplesTable, timeSeriesCTE, timeSeriesCTEArgs)
 	} else if query.Aggregations[0].Temporality != metrictypes.Multiple {
-		return b.buildTemporalAggCumulativeOrUnspecified(ctx, start, end, query, samplesTable, timeSeriesCTE, timeSeriesCTEArgs)
+		return b.buildTemporalAggCumulativeOrUnspecified(ctx, start, end, query, metricNames, samplesTable, timeSeriesCTE, timeSeriesCTEArgs)
 	}
-	return b.buildTemporalAggForMultipleTemporalities(ctx, start, end, query, samplesTable, timeSeriesCTE, timeSeriesCTEArgs)
+	return b.buildTemporalAggForMultipleTemporalities(ctx, start, end, query, metricNames, samplesTable, timeSeriesCTE, timeSeriesCTEArgs)
 }
 
 func (b *StatementBuilder) buildTemporalAggDelta(
 	_ context.Context,
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
+	metricNames []string,
 	samplesTable string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
@@ -601,7 +634,7 @@ func (b *StatementBuilder) buildTemporalAggDelta(
 	sb.From(fmt.Sprintf("%s.%s AS points", metricstelemetryschema.DBName, samplesTable))
 	sb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.fingerprint = filtered_time_series.fingerprint")
 	sb.Where(
-		sb.In("metric_name", query.Aggregations[0].MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LT("unix_milli", end),
 	)
@@ -617,6 +650,7 @@ func (b *StatementBuilder) buildTemporalAggCumulativeOrUnspecified(
 	_ context.Context,
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
+	metricNames []string,
 	samplesTable string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
@@ -642,7 +676,7 @@ func (b *StatementBuilder) buildTemporalAggCumulativeOrUnspecified(
 	baseSb.From(fmt.Sprintf("%s.%s AS points", metricstelemetryschema.DBName, samplesTable))
 	baseSb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.fingerprint = filtered_time_series.fingerprint")
 	baseSb.Where(
-		baseSb.In("metric_name", query.Aggregations[0].MetricName),
+		baseSb.In("metric_name", sqlbuilder.List(metricNames)),
 		baseSb.GTE("unix_milli", start),
 		baseSb.LT("unix_milli", end),
 	)
@@ -683,6 +717,7 @@ func (b *StatementBuilder) buildTemporalAggForMultipleTemporalities(
 	_ context.Context,
 	start, end uint64,
 	query qbtypes.QueryBuilderQuery[qbtypes.MetricAggregation],
+	metricNames []string,
 	samplesTable string,
 	timeSeriesCTE string,
 	timeSeriesCTEArgs []any,
@@ -733,7 +768,7 @@ func (b *StatementBuilder) buildTemporalAggForMultipleTemporalities(
 	sb.From(fmt.Sprintf("%s.%s AS points", metricstelemetryschema.DBName, samplesTable))
 	sb.JoinWithOption(sqlbuilder.InnerJoin, timeSeriesCTE, "points.fingerprint = filtered_time_series.fingerprint")
 	sb.Where(
-		sb.In("metric_name", query.Aggregations[0].MetricName),
+		sb.In("metric_name", sqlbuilder.List(metricNames)),
 		sb.GTE("unix_milli", start),
 		sb.LT("unix_milli", end),
 	)

pkg/statementbuilder/tracesstatementbuilder/stmt_builder_test.go

@@ -2062,3 +2062,51 @@ func TestStatementBuilderSemconvFamilies(t *testing.T) {
 		})
 	}
 }
+
+// The mid-migration state: metadata holds only the old spelling, and the
+// query names the current one. The resource-filter condition and the group
+// by column both read the stored spelling, so the filter and the groups
+// agree.
+func TestStatementBuilderSemconvSingleSpelling(t *testing.T) {
+	fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+	storage := tracestelemetryschema.NewStorage()
+	mockMetadataStore := telemetrytypestest.NewMockMetadataStore()
+	mockMetadataStore.KeysMap = map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+	aggExprRewriter := querybuilder.NewAggExprRewriter(instrumentationtest.New().ToProviderSettings(), nil, storage, fl, telemetrytypes.SignalTraces)
+
+	statementBuilder := NewTraceQueryStatementBuilder(
+		instrumentationtest.New().ToProviderSettings(),
+		mockMetadataStore,
+		storage,
+		aggExprRewriter,
+		nil,
+		fl,
+		false,
+		100000,
+	)
+
+	query := qbtypes.QueryBuilderQuery[qbtypes.TraceAggregation]{
+		Signal:       telemetrytypes.SignalTraces,
+		StepInterval: qbtypes.Step{Duration: 30 * time.Second},
+		Aggregations: []qbtypes.TraceAggregation{{Expression: "count()"}},
+		Filter: &qbtypes.Filter{
+			Expression: "deployment.environment.name = 'production'",
+		},
+		GroupBy: []qbtypes.GroupByKey{
+			{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "deployment.environment.name"}},
+		},
+	}
+
+	q, err := statementBuilder.Build(context.Background(), valuer.UUID{}, 1747947419000, 1747983448000, qbtypes.RequestTypeScalar, query, nil)
+	require.NoError(t, err)
+	require.Equal(t, "WITH __resource_filter AS (SELECT fingerprint FROM signoz_traces.distributed_traces_v3_resource WHERE (simpleJSONExtractString(labels, 'deployment.environment') = ? AND labels LIKE ? AND labels LIKE ?) AND seen_at_ts_bucket_start >= ? AND seen_at_ts_bucket_start <= ? GROUP BY fingerprint) SELECT toString(multiIf(resource.`deployment.environment` IS NOT NULL, resource.`deployment.environment`::String, mapContains(resources_string, 'deployment.environment'), resources_string['deployment.environment'], NULL)) AS `__GROUP_BY_KEY_0_deployment.environment.name`, count() AS __result_0 FROM signoz_traces.distributed_signoz_index_v3 WHERE resource_fingerprint GLOBAL IN (SELECT fingerprint FROM __resource_filter) AND timestamp >= ? AND timestamp < ? AND ts_bucket_start >= ? AND ts_bucket_start <= ? GROUP BY `__GROUP_BY_KEY_0_deployment.environment.name` ORDER BY __result_0 DESC", q.Query)
+}

pkg/telemetrymetadata/family_values_test.go

@@ -0,0 +1,150 @@
+package telemetrymetadata
+
+import (
+	"context"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
+	"github.com/SigNoz/signoz/pkg/querybuilder"
+	qbtypes "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/SigNoz/signoz/pkg/types/telemetrytypes"
+	"github.com/SigNoz/signoz/pkg/valuer"
+	"github.com/huandu/go-sqlbuilder"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The flagger provider registration is process-global and keyed by provider
+// name, so each flagger must be used before the next one is created.
+func TestFamilyValueNames(t *testing.T) {
+	selector := &telemetrytypes.FieldValueSelector{
+		FieldKeySelector: &telemetrytypes.FieldKeySelector{Name: "deployment.environment"},
+	}
+
+	off := &telemetryMetaStore{fl: flaggertest.WithBooleanFlags(t, map[string]bool{})}
+	assert.Equal(t,
+		[]string{"deployment.environment"},
+		off.familyValueNames(context.Background(), valuer.UUID{}, telemetrytypes.SignalLogs, selector),
+		"the flag default keeps values literal")
+
+	on := &telemetryMetaStore{fl: flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})}
+	assert.Equal(t,
+		[]string{"deployment.environment.name", "deployment.environment"},
+		on.familyValueNames(context.Background(), valuer.UUID{}, telemetrytypes.SignalLogs, selector),
+		"values for one spelling must cover the whole family")
+	assert.Equal(t,
+		[]string{"deployment.environment.name", "deployment.environment"},
+		on.familyValueNames(context.Background(), valuer.UUID{}, telemetrytypes.SignalMetrics, selector),
+		"metric values cover the family members")
+	spanMetric := &telemetrytypes.FieldValueSelector{
+		FieldKeySelector: &telemetrytypes.FieldKeySelector{
+			Name:          "deployment.environment",
+			MetricContext: &telemetrytypes.MetricContext{MetricName: "signoz_calls_total"},
+		},
+	}
+	assert.Equal(t,
+		[]string{
+			"deployment.environment.name", "resource_deployment.environment.name",
+			"deployment.environment", "resource_deployment.environment",
+		},
+		on.familyValueNames(context.Background(), valuer.UUID{}, telemetrytypes.SignalMetrics, spanMetric),
+		"span-metrics values cover the resource_ spellings too")
+}
+
+// A family condition on the related values table follows the shared guard
+// rule: the operator applies to the current-first merge, a positive operator
+// takes the presence guard, and a negative operator keeps the keyless rows.
+func TestConditionForFamilyMergedSemantics(t *testing.T) {
+	fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+	storage := NewStorage()
+	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{
+		"deployment.environment.name": {{
+			Name:          "deployment.environment.name",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+		"deployment.environment": {{
+			Name:          "deployment.environment",
+			Signal:        telemetrytypes.SignalTraces,
+			FieldContext:  telemetrytypes.FieldContextResource,
+			FieldDataType: telemetrytypes.FieldDataTypeString,
+		}},
+	}
+
+	testCases := []struct {
+		name     string
+		operator qbtypes.FilterOperator
+		expected string
+	}{
+		{
+			name:     "Equal_TakesPresenceGuard",
+			operator: qbtypes.FilterOperatorEqual,
+			expected: "SELECT 1 WHERE (COALESCE(NULLIF(resource_attributes['deployment.environment.name'], ''), NULLIF(resource_attributes['deployment.environment'], ''), '') = ? AND (mapContains(resource_attributes, 'deployment.environment.name') OR mapContains(resource_attributes, 'deployment.environment')))",
+		},
+		{
+			name:     "NotEqual_KeepsKeylessRows",
+			operator: qbtypes.FilterOperatorNotEqual,
+			expected: "SELECT 1 WHERE COALESCE(NULLIF(resource_attributes['deployment.environment.name'], ''), NULLIF(resource_attributes['deployment.environment'], ''), '') <> ?",
+		},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			sb := sqlbuilder.NewSelectBuilder()
+			q := querybuilder.NewQueryInfo(context.Background(), valuer.UUID{}, fl, telemetrytypes.SignalTraces, nil, 0, 0)
+			conds, _, err := querybuilder.Conditions(context.Background(), q, storage,
+				&telemetrytypes.TelemetryFieldKey{Name: "deployment.environment"}, testCase.operator, "production", fieldKeys, false, sb)
+			require.NoError(t, err)
+			sb.Select("1").Where(conds...)
+			sql, _ := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+			assert.Equal(t, testCase.expected, sql)
+		})
+	}
+}
+
+// The related values search applies to the current-first merge that the
+// suggestion shows, also when the request carries no data type.
+func TestContainsConditionsSearchesFamilyAsOneField(t *testing.T) {
+	fl := flaggertest.WithBooleanFlags(t, map[string]bool{
+		flagger.FeatureResolveSemconvFamilies.String(): true,
+	})
+	q := querybuilder.NewQueryInfo(context.Background(), valuer.UUID{}, fl, telemetrytypes.SignalTraces, nil, 0, 0)
+	store := &telemetryMetaStore{storage: NewStorage()}
+	key := &telemetrytypes.TelemetryFieldKey{
+		Name:         "deployment.environment",
+		Signal:       telemetrytypes.SignalTraces,
+		FieldContext: telemetrytypes.FieldContextResource,
+	}
+
+	testCases := []struct {
+		name     string
+		names    []string
+		expected string
+	}{
+		{
+			name:     "FamilySpellings_MergeIntoOneCondition",
+			names:    []string{"deployment.environment.name", "deployment.environment"},
+			expected: "SELECT 1 WHERE (LOWER(COALESCE(NULLIF(resource_attributes['deployment.environment.name'], ''), NULLIF(resource_attributes['deployment.environment'], ''), '')) LIKE LOWER(?) AND (mapContains(resource_attributes, 'deployment.environment.name') OR mapContains(resource_attributes, 'deployment.environment')))",
+		},
+		{
+			name:     "SingleSpelling_StaysLiteral",
+			names:    []string{"deployment.environment"},
+			expected: "SELECT 1 WHERE if(mapContains(resource_attributes, ?), LOWER(resource_attributes['deployment.environment']) LIKE LOWER(?), false)",
+		},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			sb := sqlbuilder.NewSelectBuilder()
+			conds, err := store.containsConditions(context.Background(), q, key, testCase.names, "prod", sb)
+			require.NoError(t, err)
+			sb.Select("1").Where(conds...)
+			sql, _ := sb.BuildWithFlavor(sqlbuilder.ClickHouse)
+			assert.Equal(t, testCase.expected, sql)
+		})
+	}
+}

pkg/telemetrymetadata/metadata.go

@@ -15,6 +15,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/factory"
 	"github.com/SigNoz/signoz/pkg/flagger"
 	"github.com/SigNoz/signoz/pkg/querybuilder"
+	"github.com/SigNoz/signoz/pkg/semconv"
 	"github.com/SigNoz/signoz/pkg/telemetryschema/audittelemetryschema"
 	"github.com/SigNoz/signoz/pkg/telemetryschema/logstelemetryschema"
 	"github.com/SigNoz/signoz/pkg/telemetryschema/metertelemetryschema"
@@ -1292,25 +1293,41 @@ func (t *telemetryMetaStore) getRelatedValues(ctx context.Context, orgID valuer.
 		FieldDataType: fieldValueSelector.FieldDataType,
 	}
 
-	q := querybuilder.NewQueryInfo(ctx, orgID, nil, fieldValueSelector.Signal, nil, 0, 0)
-	selectRead, err := t.storage.Read(ctx, q, key)
-	selectColumn := selectRead.SQL
-
-	if err != nil {
-		// we don't have a explicit column to select from the related metadata table
-		// so we will select either from resource_attributes or attributes table
-		// in that order
-		resourceRead, _ := t.storage.Read(ctx, q, &telemetrytypes.TelemetryFieldKey{
-			Name:          key.Name,
-			FieldContext:  telemetrytypes.FieldContextResource,
-			FieldDataType: telemetrytypes.FieldDataTypeString,
-		})
-		attributeRead, _ := t.storage.Read(ctx, q, &telemetrytypes.TelemetryFieldKey{
-			Name:          key.Name,
-			FieldContext:  telemetrytypes.FieldContextAttribute,
-			FieldDataType: telemetrytypes.FieldDataTypeString,
-		})
-		selectColumn = fmt.Sprintf("if(notEmpty(%s), %s, %s)", resourceRead.SQL, resourceRead.SQL, attributeRead.SQL)
+	q := querybuilder.NewQueryInfo(ctx, orgID, t.fl, fieldValueSelector.Signal, nil, 0, 0)
+	// One column per family spelling, merged current-first, so the
+	// suggestions cover rows that carry only an old spelling.
+	names := t.familyValueNames(ctx, orgID, fieldValueSelector.Signal, fieldValueSelector)
+	memberColumns := make([]string, 0, len(names))
+	for _, name := range names {
+		memberKey := &telemetrytypes.TelemetryFieldKey{
+			Name:          name,
+			Signal:        fieldValueSelector.Signal,
+			FieldContext:  fieldValueSelector.FieldContext,
+			FieldDataType: fieldValueSelector.FieldDataType,
+		}
+		memberRead, err := t.storage.Read(ctx, q, memberKey)
+		memberColumn := memberRead.SQL
+		if err != nil {
+			// we don't have a explicit column to select from the related metadata table
+			// so we will select either from resource_attributes or attributes table
+			// in that order
+			resourceRead, _ := t.storage.Read(ctx, q, &telemetrytypes.TelemetryFieldKey{
+				Name:          name,
+				FieldContext:  telemetrytypes.FieldContextResource,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			})
+			attributeRead, _ := t.storage.Read(ctx, q, &telemetrytypes.TelemetryFieldKey{
+				Name:          name,
+				FieldContext:  telemetrytypes.FieldContextAttribute,
+				FieldDataType: telemetrytypes.FieldDataTypeString,
+			})
+			memberColumn = fmt.Sprintf("if(notEmpty(%s), %s, %s)", resourceRead.SQL, resourceRead.SQL, attributeRead.SQL)
+		}
+		memberColumns = append(memberColumns, memberColumn)
+	}
+	selectColumn := memberColumns[len(memberColumns)-1]
+	for i := len(memberColumns) - 2; i >= 0; i-- {
+		selectColumn = fmt.Sprintf("if(notEmpty(%s), %s, %s)", memberColumns[i], memberColumns[i], selectColumn)
 	}
 
 	sb := sqlbuilder.Select("DISTINCT " + selectColumn).From(t.relatedMetadataDBName + "." + t.relatedMetadataTblName)
@@ -1320,6 +1337,7 @@ func (t *telemetryMetaStore) getRelatedValues(ctx context.Context, orgID valuer.
 		for _, keySelector := range keySelectors {
 			keySelector.Signal = fieldValueSelector.Signal
 		}
+		keySelectors = querybuilder.ExpandKeySelectorsForFamilies(ctx, orgID, t.fl, keySelectors)
 		keys, _, err := t.GetKeysMulti(ctx, orgID, keySelectors)
 		if err != nil {
 			return nil, false, err
@@ -1361,20 +1379,20 @@ func (t *telemetryMetaStore) getRelatedValues(ctx context.Context, orgID valuer.
 
 			// search on attributes
 			key.FieldContext = telemetrytypes.FieldContextAttribute
-			attrConds, err := t.containsConditions(ctx, q, key, fieldValueSelector.Value, sb)
+			attrConds, err := t.containsConditions(ctx, q, key, names, fieldValueSelector.Value, sb)
 			if err == nil {
 				conds = append(conds, attrConds...)
 			}
 
 			// search on resource
 			key.FieldContext = telemetrytypes.FieldContextResource
-			resourceConds, err := t.containsConditions(ctx, q, key, fieldValueSelector.Value, sb)
+			resourceConds, err := t.containsConditions(ctx, q, key, names, fieldValueSelector.Value, sb)
 			if err == nil {
 				conds = append(conds, resourceConds...)
 			}
 			key.FieldContext = origContext
 		} else {
-			keyConds, err := t.containsConditions(ctx, q, key, fieldValueSelector.Value, sb)
+			keyConds, err := t.containsConditions(ctx, q, key, names, fieldValueSelector.Value, sb)
 			if err == nil {
 				conds = append(conds, keyConds...)
 			}
@@ -1432,7 +1450,7 @@ func (t *telemetryMetaStore) GetRelatedValues(ctx context.Context, orgID valuer.
 	return t.getRelatedValues(ctx, orgID, fieldValueSelector)
 }
 
-func (t *telemetryMetaStore) getSpanFieldValues(ctx context.Context, fieldValueSelector *telemetrytypes.FieldValueSelector) (*telemetrytypes.TelemetryFieldValues, bool, error) {
+func (t *telemetryMetaStore) getSpanFieldValues(ctx context.Context, orgID valuer.UUID, fieldValueSelector *telemetrytypes.FieldValueSelector) (*telemetrytypes.TelemetryFieldValues, bool, error) {
 	ctx = ctxtypes.NewContextWithCommentVals(ctx, map[string]string{
 		instrumentationtypes.TelemetrySignal:  telemetrytypes.SignalTraces.StringValue(),
 		instrumentationtypes.CodeNamespace:    "metadata",
@@ -1443,11 +1461,12 @@ func (t *telemetryMetaStore) getSpanFieldValues(ctx context.Context, fieldValueS
 		return values, true, nil
 	}
 	knownBool := isKnownBoolField(fieldValueSelector, tracestelemetryschema.IntrinsicFields, tracestelemetryschema.CalculatedFields)
+	names := t.familyValueNames(ctx, orgID, telemetrytypes.SignalTraces, fieldValueSelector)
 	// unix_milli is the hour of the span start
-	return t.getTagTableValues(ctx, t.tracesDBName+"."+t.tracesFieldsTblName, fieldValueSelector, knownBool)
+	return t.getTagTableValues(ctx, t.tracesDBName+"."+t.tracesFieldsTblName, fieldValueSelector, names, knownBool)
 }
 
-func (t *telemetryMetaStore) getLogFieldValues(ctx context.Context, fieldValueSelector *telemetrytypes.FieldValueSelector) (*telemetrytypes.TelemetryFieldValues, bool, error) {
+func (t *telemetryMetaStore) getLogFieldValues(ctx context.Context, orgID valuer.UUID, fieldValueSelector *telemetrytypes.FieldValueSelector) (*telemetrytypes.TelemetryFieldValues, bool, error) {
 	ctx = ctxtypes.NewContextWithCommentVals(ctx, map[string]string{
 		instrumentationtypes.TelemetrySignal:  telemetrytypes.SignalLogs.StringValue(),
 		instrumentationtypes.CodeNamespace:    "metadata",
@@ -1455,8 +1474,18 @@ func (t *telemetryMetaStore) getLogFieldValues(ctx context.Context, fieldValueSe
 	})
 
 	knownBool := isKnownBoolField(fieldValueSelector, logstelemetryschema.IntrinsicFields)
+	names := t.familyValueNames(ctx, orgID, telemetrytypes.SignalLogs, fieldValueSelector)
 	// unix_milli is the hour the log was ingested, not the log's own timestamp
-	return t.getTagTableValues(ctx, t.logsDBName+"."+t.logsFieldsTblName, fieldValueSelector, knownBool)
+	return t.getTagTableValues(ctx, t.logsDBName+"."+t.logsFieldsTblName, fieldValueSelector, names, knownBool)
+}
+
+// tagKeyCondition matches the requested key, or every spelling of its
+// family when there is more than one.
+func tagKeyCondition(sb *sqlbuilder.SelectBuilder, name string, names []string) string {
+	if len(names) > 1 {
+		return sb.In("tag_key", sqlbuilder.List(names))
+	}
+	return sb.E("tag_key", name)
 }
 
 // tagTableSinceDay restricts rows to the tag table's day partitions from the
@@ -1472,9 +1501,9 @@ func tagTableSinceDay(sb *sqlbuilder.SelectBuilder, startUnixMilli int64) {
 // tagTableHasBoolRows reports whether the tag table holds a bool row for the
 // key. Bool rows carry no value, so one row is enough to know the key takes
 // the values true and false.
-func (t *telemetryMetaStore) tagTableHasBoolRows(ctx context.Context, table string, selector *telemetrytypes.FieldValueSelector) (bool, error) {
+func (t *telemetryMetaStore) tagTableHasBoolRows(ctx context.Context, table string, selector *telemetrytypes.FieldValueSelector, names []string) (bool, error) {
 	sb := sqlbuilder.Select("1").From(table)
-	sb.Where(sb.E("tag_key", selector.Name))
+	sb.Where(tagKeyCondition(sb, selector.Name, names))
 	sb.Where(sb.E("tag_data_type", telemetrytypes.FieldDataTypeBool.TagDataType()))
 	if selector.FieldContext != telemetrytypes.FieldContextUnspecified {
 		sb.Where(sb.E("tag_type", selector.FieldContext.TagType()))
@@ -1494,7 +1523,7 @@ func (t *telemetryMetaStore) tagTableHasBoolRows(ctx context.Context, table stri
 // getTagTableValues returns the string and number values of the key from a
 // tag table, and true and false when the key is a known bool field or the
 // table holds bool rows for it. Bool rows do not count towards the limit.
-func (t *telemetryMetaStore) getTagTableValues(ctx context.Context, table string, fieldValueSelector *telemetrytypes.FieldValueSelector, knownBool bool) (*telemetrytypes.TelemetryFieldValues, bool, error) {
+func (t *telemetryMetaStore) getTagTableValues(ctx context.Context, table string, fieldValueSelector *telemetrytypes.FieldValueSelector, names []string, knownBool bool) (*telemetrytypes.TelemetryFieldValues, bool, error) {
 	limit := fieldValueSelector.Limit
 	if limit == 0 {
 		limit = 50
@@ -1507,7 +1536,7 @@ func (t *telemetryMetaStore) getTagTableValues(ctx context.Context, table string
 			return values, true, nil
 		}
 	} else if fieldValueSelector.FieldDataType == telemetrytypes.FieldDataTypeUnspecified {
-		hasBoolRows, err := t.tagTableHasBoolRows(ctx, table, fieldValueSelector)
+		hasBoolRows, err := t.tagTableHasBoolRows(ctx, table, fieldValueSelector, names)
 		if err != nil {
 			return nil, false, err
 		}
@@ -1519,7 +1548,7 @@ func (t *telemetryMetaStore) getTagTableValues(ctx context.Context, table string
 	sb := sqlbuilder.Select("DISTINCT string_value, number_value").From(table)
 
 	if fieldValueSelector.Name != "" {
-		sb.Where(sb.E("tag_key", fieldValueSelector.Name))
+		sb.Where(tagKeyCondition(sb, fieldValueSelector.Name, names))
 	}
 	sb.Where(sb.NE("tag_data_type", telemetrytypes.FieldDataTypeBool.TagDataType()))
 
@@ -1719,7 +1748,11 @@ func (t *telemetryMetaStore) getMetricFieldValues(ctx context.Context, orgID val
 		From(t.metricsDBName + "." + t.metricsFieldsTblName)
 
 	if fieldValueSelector.Name != "" {
-		sb.Where(sb.E("attr_name", fieldValueSelector.Name))
+		if names := t.familyValueNames(ctx, orgID, telemetrytypes.SignalMetrics, fieldValueSelector); len(names) > 1 {
+			sb.Where(sb.In("attr_name", sqlbuilder.List(names)))
+		} else {
+			sb.Where(sb.E("attr_name", fieldValueSelector.Name))
+		}
 	}
 
 	if fieldValueSelector.FieldContext != telemetrytypes.FieldContextUnspecified {
@@ -1731,7 +1764,11 @@ func (t *telemetryMetaStore) getMetricFieldValues(ctx context.Context, orgID val
 	}
 
 	if fieldValueSelector.MetricContext != nil && fieldValueSelector.MetricContext.MetricName != "" {
-		sb.Where(sb.E("metric_name", fieldValueSelector.MetricContext.MetricName))
+		if metricNames := querybuilder.FamilyMetricNames(ctx, orgID, t.fl, fieldValueSelector.MetricContext.MetricName); len(metricNames) > 1 {
+			sb.Where(sb.In("metric_name", sqlbuilder.List(metricNames)))
+		} else {
+			sb.Where(sb.E("metric_name", fieldValueSelector.MetricContext.MetricName))
+		}
 	}
 	if fieldValueSelector.MetricContext != nil && fieldValueSelector.MetricContext.MetricNamespace != "" {
 		sb.Where(sb.Like("metric_name", clickhousesql.LikePattern(fieldValueSelector.MetricContext.MetricNamespace)+"%"))
@@ -2053,12 +2090,12 @@ func (t *telemetryMetaStore) GetAllValues(ctx context.Context, orgID valuer.UUID
 
 	switch fieldValueSelector.Signal {
 	case telemetrytypes.SignalTraces:
-		values, complete, err = t.getSpanFieldValues(ctx, fieldValueSelector)
+		values, complete, err = t.getSpanFieldValues(ctx, orgID, fieldValueSelector)
 	case telemetrytypes.SignalLogs:
 		if fieldValueSelector.Source == telemetrytypes.SourceAudit {
 			values, complete, err = t.getAuditFieldValues(ctx, fieldValueSelector)
 		} else {
-			values, complete, err = t.getLogFieldValues(ctx, fieldValueSelector)
+			values, complete, err = t.getLogFieldValues(ctx, orgID, fieldValueSelector)
 		}
 	case telemetrytypes.SignalMetrics:
 		if fieldValueSelector.Source == telemetrytypes.SourceMeter {
@@ -2071,13 +2108,13 @@ func (t *telemetryMetaStore) GetAllValues(ctx context.Context, orgID valuer.UUID
 		mapOfRelatedValues := make(map[any]bool)
 		allUnspecifiedValues := &telemetrytypes.TelemetryFieldValues{}
 
-		tracesValues, tracesComplete, err := t.getSpanFieldValues(ctx, fieldValueSelector)
+		tracesValues, tracesComplete, err := t.getSpanFieldValues(ctx, orgID, fieldValueSelector)
 		if err == nil {
 			populateComplete := populateAllUnspecifiedValues(allUnspecifiedValues, mapOfValues, mapOfRelatedValues, tracesValues, limit)
 			complete = complete && tracesComplete && populateComplete
 		}
 
-		logsValues, logsComplete, err := t.getLogFieldValues(ctx, fieldValueSelector)
+		logsValues, logsComplete, err := t.getLogFieldValues(ctx, orgID, fieldValueSelector)
 		if err == nil {
 			populateComplete := populateAllUnspecifiedValues(allUnspecifiedValues, mapOfValues, mapOfRelatedValues, logsValues, limit)
 			complete = complete && logsComplete && populateComplete
@@ -2589,10 +2626,42 @@ func (t *telemetryMetaStore) fetchLastSeenInfoForTable(ctx context.Context, tabl
 	return lastSeenInfo, nil
 }
 
-// containsConditions compiles a contains search on one key of the related
-// values table. The key is its own metadata.
-func (t *telemetryMetaStore) containsConditions(ctx context.Context, q qbtypes.QueryInfo, key *telemetrytypes.TelemetryFieldKey, value string, sb *sqlbuilder.SelectBuilder) ([]string, error) {
-	fieldKeys := map[string][]*telemetrytypes.TelemetryFieldKey{key.Name: {key}}
+// containsConditions compiles a contains search over the key and its family
+// spellings, which stand as their own metadata.
+func (t *telemetryMetaStore) containsConditions(ctx context.Context, q qbtypes.QueryInfo, key *telemetrytypes.TelemetryFieldKey, names []string, value string, sb *sqlbuilder.SelectBuilder) ([]string, error) {
+	// A family forms only over string keys with a signal. The table stores
+	// only string maps, so an unspecified data type is a string here.
+	dataType := key.FieldDataType
+	if dataType == telemetrytypes.FieldDataTypeUnspecified {
+		dataType = telemetrytypes.FieldDataTypeString
+	}
+	fieldKeys := make(map[string][]*telemetrytypes.TelemetryFieldKey, len(names))
+	for _, name := range names {
+		fieldKeys[name] = []*telemetrytypes.TelemetryFieldKey{{
+			Name:          name,
+			Signal:        key.Signal,
+			FieldContext:  key.FieldContext,
+			FieldDataType: dataType,
+		}}
+	}
 	conds, _, err := querybuilder.Conditions(ctx, q, t.storage, key, qbtypes.FilterOperatorContains, value, fieldKeys, false, sb)
 	return conds, err
 }
+
+// familyValueNames returns the spellings whose values merge into the
+// suggestions. With the flag off, the requested name alone.
+func (t *telemetryMetaStore) familyValueNames(ctx context.Context, orgID valuer.UUID, signal telemetrytypes.Signal, fieldValueSelector *telemetrytypes.FieldValueSelector) []string {
+	if !querybuilder.SemconvFamiliesEnabled(ctx, orgID, t.fl) {
+		return []string{fieldValueSelector.Name}
+	}
+	selector := telemetrytypes.FieldKeySelector{
+		Name:          fieldValueSelector.Name,
+		Signal:        signal,
+		FieldContext:  fieldValueSelector.FieldContext,
+		MetricContext: fieldValueSelector.MetricContext,
+	}
+	if signal == telemetrytypes.SignalMetrics {
+		return querybuilder.MetricLabelSpellings(selector)
+	}
+	return semconv.Members(semconv.KindAttribute, selector)
+}

pkg/types/aiobservabilitytypes/genaimessages/captured_test.go

@@ -0,0 +1,41 @@
+package genaimessages
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// testdata/captured/<sdk>/<attribute>.txt holds a real attribute value from the scripts
+// repo's static-telemetry-generator captures; <attribute>.want.json is its reviewed output.
+func TestNormalizeCapturedPayloads(t *testing.T) {
+	inputs, err := filepath.Glob(filepath.Join("testdata", "captured", "*", "*.txt"))
+	require.NoError(t, err)
+	require.NotEmpty(t, inputs)
+
+	for _, input := range inputs {
+		sdk := filepath.Base(filepath.Dir(input))
+		attribute := strings.TrimSuffix(filepath.Base(input), ".txt")
+		t.Run(sdk+"/"+attribute, func(t *testing.T) {
+			raw, err := os.ReadFile(input)
+			require.NoError(t, err)
+			wantJSON, err := os.ReadFile(strings.TrimSuffix(input, ".txt") + ".want.json")
+			require.NoError(t, err)
+
+			var want []aiobservabilitytypes.Message
+			require.NoError(t, json.Unmarshal(wantJSON, &want))
+			got, err := json.Marshal(Normalize(string(raw)))
+			require.NoError(t, err)
+			var gotRoundTrip []aiobservabilitytypes.Message
+			require.NoError(t, json.Unmarshal(got, &gotRoundTrip))
+
+			assert.Equal(t, want, gotRoundTrip)
+		})
+	}
+}

pkg/types/aiobservabilitytypes/genaimessages/envelope.go

@@ -0,0 +1,307 @@
+package genaimessages
+
+import (
+	"encoding/json"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+// convertSemconvMessages handles [{role, parts, finish_reason}] and Gemini contents.
+func convertSemconvMessages(value any) ([]aiobservabilitytypes.Message, bool) {
+	list, ok := value.([]any)
+	if !ok || len(list) == 0 {
+		return nil, false
+	}
+	first, ok := toObject(firstItem(list))
+	if !ok {
+		return nil, false
+	}
+	if ok := first.has("parts"); !ok {
+		return nil, false
+	}
+
+	messages := make([]aiobservabilitytypes.Message, 0, len(list))
+	for _, item := range list {
+		m, ok := toObject(item)
+		if !ok {
+			messages = append(messages, genericMessages(stringOf(item))...)
+			continue
+		}
+		messages = append(messages, semconvMessage(m, "")...)
+	}
+	return messages, true
+}
+
+// convertChatMessageList handles OpenAI, Anthropic, Vercel and LangChain message lists.
+func convertChatMessageList(value any) ([]aiobservabilitytypes.Message, bool) {
+	list, ok := value.([]any)
+	if !ok || len(list) == 0 {
+		return nil, false
+	}
+	if !isChatMessage(firstItem(list)) {
+		return nil, false
+	}
+	messages := make([]aiobservabilitytypes.Message, 0, len(list))
+	for _, item := range list {
+		messages = append(messages, chatMessage(item, "")...)
+	}
+	return messages, true
+}
+
+func isChatMessage(value any) bool {
+	m, ok := toObject(value)
+	if !ok {
+		return false
+	}
+	if ok := m.has("role"); ok {
+		return true
+	}
+	switch typ := m.str("type"); typ {
+	case "message", "reasoning", "human", "ai", "tool", "system":
+		return true
+	case "constructor":
+		ok := m.has("kwargs")
+		return ok
+	default:
+		return isResponsesItemType(typ)
+	}
+}
+
+// convertToolCallList handles a bare tool call list, e.g. Vercel ai.response.toolCalls.
+func convertToolCallList(value any) ([]aiobservabilitytypes.Message, bool) {
+	list, ok := value.([]any)
+	if !ok || len(list) == 0 {
+		return nil, false
+	}
+	msg := aiobservabilitytypes.Message{Role: aiobservabilitytypes.MessageRoleAssistant, Content: make([]aiobservabilitytypes.Part, 0, len(list))}
+	for _, item := range list {
+		call, ok := toObject(item)
+		if !ok || !isToolCall(call) {
+			return nil, false
+		}
+		msg.Content = append(msg.Content, toolCallPart(call))
+	}
+	return []aiobservabilitytypes.Message{msg}, true
+}
+
+// isToolCall rejects tool definitions, which carry no arguments.
+func isToolCall(call object) bool {
+	if has := call.has("toolName"); has {
+		return true
+	}
+	if fn, ok := call.obj("function"); ok {
+		has := fn.has("arguments")
+		return has
+	}
+	if has := call.has("name"); !has {
+		return false
+	}
+	_, has := call.lookup("arguments", "args")
+	return has
+}
+
+// convertChatRequest handles OpenAI, Anthropic, Vercel, Gemini and LangChain request objects.
+func convertChatRequest(value any) ([]aiobservabilitytypes.Message, bool) {
+	m, ok := toObject(value)
+	if !ok {
+		return nil, false
+	}
+	conversation, ok := m.lookup("messages", "input", "contents", "prompt")
+	if !ok {
+		return nil, false
+	}
+
+	messages := []aiobservabilitytypes.Message{}
+	if system := systemMessage(m.first("system", "instructions", "system_instruction", "systemInstruction", "system_prompt")); system != nil {
+		messages = append(messages, *system)
+	} else if config, ok := m.obj("config"); ok {
+		if system := systemMessage(config.first("system_instruction", "systemInstruction")); system != nil {
+			messages = append(messages, *system)
+		}
+	}
+
+	// {messages: "[...]"}: the list arrives JSON-encoded once more from some SDKs
+	if s, isString := conversation.(string); isString {
+		var decoded any
+		if err := json.Unmarshal([]byte(s), &decoded); err == nil {
+			if _, isList := decoded.([]any); isList {
+				conversation = decoded
+			}
+		}
+	}
+	switch c := conversation.(type) {
+	case string:
+		if c != "" {
+			messages = append(messages, textMessage(aiobservabilitytypes.MessageRoleUser, c))
+		}
+	case []any:
+		for _, item := range flattenOnce(c) {
+			if s, isString := item.(string); isString {
+				messages = append(messages, textMessage(aiobservabilitytypes.MessageRoleUser, s))
+				continue
+			}
+			messages = append(messages, semconvMessage(asObject(item), aiobservabilitytypes.MessageRoleUser)...)
+		}
+	case map[string]any:
+		messages = append(messages, semconvMessage(c, aiobservabilitytypes.MessageRoleUser)...)
+	default:
+		return nil, false
+	}
+	return messages, true
+}
+
+// systemMessage returns nil when value is empty or unknown.
+func systemMessage(value any) *aiobservabilitytypes.Message {
+	msg := aiobservabilitytypes.Message{Role: aiobservabilitytypes.MessageRoleSystem, Content: []aiobservabilitytypes.Part{}}
+	switch v := value.(type) {
+	case string:
+		if v == "" {
+			return nil
+		}
+		msg.Content = append(msg.Content, textPart(v))
+	case []any:
+		for _, item := range v {
+			msg.Content = append(msg.Content, contentBlockPart(item))
+		}
+	case map[string]any:
+		parts, ok := object(v).list("parts")
+		if !ok {
+			return nil
+		}
+		for _, p := range parts {
+			msg.Content = append(msg.Content, semconvPart(p))
+		}
+	default:
+		return nil
+	}
+	if len(msg.Content) == 0 {
+		return nil
+	}
+	return &msg
+}
+
+// convertChatResponse handles the OpenAI Chat Completions {choices} response.
+func convertChatResponse(value any) ([]aiobservabilitytypes.Message, bool) {
+	m, ok := toObject(value)
+	if !ok {
+		return nil, false
+	}
+	choices, ok := m.list("choices")
+	if !ok {
+		return nil, false
+	}
+	messages := make([]aiobservabilitytypes.Message, 0, len(choices))
+	for _, c := range choices {
+		choice := asObject(c)
+		var converted []aiobservabilitytypes.Message
+		if message, ok := toObject(choice.first("message", "delta")); ok {
+			converted = chatMessage(message, aiobservabilitytypes.MessageRoleAssistant)
+		} else if text, ok := choice.get("text"); ok {
+			converted = []aiobservabilitytypes.Message{textMessage(aiobservabilitytypes.MessageRoleAssistant, stringOf(text))}
+		} else {
+			converted = []aiobservabilitytypes.Message{{Role: aiobservabilitytypes.MessageRoleAssistant, Content: []aiobservabilitytypes.Part{genericPart(choice)}}}
+		}
+		messages = append(messages, withFinishReason(converted, choice.str("finish_reason"))...)
+	}
+	return messages, true
+}
+
+func convertResponsesAPIResponse(value any) ([]aiobservabilitytypes.Message, bool) {
+	m, ok := toObject(value)
+	if !ok {
+		return nil, false
+	}
+	output, ok := m.list("output")
+	if !ok {
+		return nil, false
+	}
+	messages := make([]aiobservabilitytypes.Message, 0, len(output))
+	for _, item := range output {
+		messages = append(messages, chatMessage(item, aiobservabilitytypes.MessageRoleAssistant)...)
+	}
+	if last := lastMessage(messages); last != nil && last.FinishReason == "" {
+		if details, ok := m.obj("incomplete_details"); ok {
+			last.FinishReason = normalizeFinishReason(details.str("reason"))
+		} else if m.str("status") == "completed" {
+			last.FinishReason = aiobservabilitytypes.FinishReasonStop
+		}
+	}
+	return messages, true
+}
+
+// convertGeminiResponse handles Gemini {candidates} and Google ADK {content} responses.
+func convertGeminiResponse(value any) ([]aiobservabilitytypes.Message, bool) {
+	m, ok := toObject(value)
+	if !ok {
+		return nil, false
+	}
+	if content, ok := m.obj("content"); ok {
+		if hasParts := content.has("parts"); hasParts {
+			return withFinishReason(semconvMessage(content, aiobservabilitytypes.MessageRoleAssistant), finishReasonOf(m)), true
+		}
+	}
+	candidates, ok := m.list("candidates")
+	if !ok {
+		return nil, false
+	}
+	messages := make([]aiobservabilitytypes.Message, 0, len(candidates))
+	for _, c := range candidates {
+		candidate := asObject(c)
+		content, ok := candidate.obj("content")
+		if !ok {
+			generic := []aiobservabilitytypes.Message{{Role: aiobservabilitytypes.MessageRoleAssistant, Content: []aiobservabilitytypes.Part{genericPart(candidate)}}}
+			messages = append(messages, withFinishReason(generic, finishReasonOf(candidate))...)
+			continue
+		}
+		messages = append(messages, withFinishReason(semconvMessage(content, aiobservabilitytypes.MessageRoleAssistant), finishReasonOf(candidate))...)
+	}
+	return messages, true
+}
+
+func convertLegacyCompletion(value any) ([]aiobservabilitytypes.Message, bool) {
+	m, ok := toObject(value)
+	if !ok {
+		return nil, false
+	}
+	completion, ok := m.text("completion")
+	if !ok {
+		return nil, false
+	}
+	msg := aiobservabilitytypes.Message{Role: aiobservabilitytypes.MessageRoleAssistant, Content: []aiobservabilitytypes.Part{}}
+	if reasoning, ok := m.text("reasoning"); ok && reasoning != "" {
+		msg.Content = append(msg.Content, aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: reasoning})
+	}
+	msg.Content = append(msg.Content, textPart(completion))
+	return []aiobservabilitytypes.Message{msg}, true
+}
+
+func convertLangChainGenerations(value any) ([]aiobservabilitytypes.Message, bool) {
+	m, ok := toObject(value)
+	if !ok {
+		return nil, false
+	}
+	generations, ok := m.list("generations")
+	if !ok {
+		return nil, false
+	}
+	messages := []aiobservabilitytypes.Message{}
+	for _, g := range flattenOnce(generations) {
+		gen := asObject(g)
+		var converted []aiobservabilitytypes.Message
+		if message, ok := gen.obj("message"); ok {
+			converted = chatMessage(message, aiobservabilitytypes.MessageRoleAssistant)
+		} else {
+			converted = []aiobservabilitytypes.Message{textMessage(aiobservabilitytypes.MessageRoleAssistant, gen.str("text"))}
+		}
+		messages = append(messages, withFinishReason(converted, asObject(gen.at("generation_info")).str("finish_reason"))...)
+	}
+	return messages, true
+}
+
+// withFinishReason sets reason on the last message that has none.
+func withFinishReason(messages []aiobservabilitytypes.Message, reason string) []aiobservabilitytypes.Message {
+	if last := lastMessage(messages); last != nil && last.FinishReason == "" {
+		last.FinishReason = normalizeFinishReason(reason)
+	}
+	return messages
+}

pkg/types/aiobservabilitytypes/genaimessages/envelope_test.go

@@ -0,0 +1,288 @@
+package genaimessages
+
+import (
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+func TestNormalizeEnvelopeRequests(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "AnthropicRequest_SystemStringBecomesSystemMessage",
+			raw: `{
+				"model": "claude",
+				"system": "Be brief.",
+				"messages": [{"role": "user", "content": "Hi"}],
+				"max_tokens": 100
+			}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleSystem,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Be brief."},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+			},
+		},
+		{
+			name: "GeminiRequest_ConfigSystemInstructionBecomesSystemMessage",
+			raw: `{
+				"model": "gemini-2.0",
+				"config": {"system_instruction": "Be brief."},
+				"contents": [
+					{"role": "user", "parts": [{"text": "Hi"}]},
+					{
+						"role": "user",
+						"parts": [
+							{
+								"function_response": {"name": "get_weather", "response": {"temp": 20}}
+							}
+						]
+					}
+				]
+			}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleSystem,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Be brief."},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, Name: "get_weather", Content: `{"temp":20}`},
+					},
+				},
+			},
+		},
+		{
+			name: "GeminiRequest_SystemInstructionPartsBecomeSystemMessage",
+			raw:  `{"system_instruction": {"parts": [{"text": "Be brief."}]}, "contents": [{"role": "user", "parts": [{"text": "Hi"}]}]}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleSystem,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Be brief."},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+			},
+		},
+		{
+			name: "RequestWithMessagesAsJSONString_MessagesDecoded",
+			raw:  `{"messages":"[{\"role\":\"user\",\"content\":\"Hi\"}]"}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizeEnvelopeChatResponses(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "StreamingChunkDelta_BecomesAssistantText",
+			raw:  `{"choices": [{"delta": {"role": "assistant", "content": "Hel"}, "finish_reason": null}]}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hel"},
+					},
+				},
+			},
+		},
+		{
+			name: "LegacyCompletionChoiceText_BecomesAssistantTextWithLength",
+			raw:  `{"choices": [{"text": "Hello", "finish_reason": "length"}]}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonLength,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hello"},
+					},
+				},
+			},
+		},
+		{
+			name: "FilteredChoiceWithoutMessage_BecomesGenericWithContentFilter",
+			raw:  `{"choices": [{"index": 0, "finish_reason": "content_filter"}]}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonContentFilter,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeGeneric, Content: `{"finish_reason":"content_filter","index":0}`},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizeEnvelopeOpenAIResponses(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "ResponsesAPIResponse_MessageAndReasoningItemsConverted",
+			raw: `{
+				"object": "response",
+				"status": "completed",
+				"output": [
+					{
+						"type": "reasoning",
+						"id": "rs_1",
+						"summary": [{"type": "summary_text", "text": "Thinking about it"}]
+					},
+					{
+						"type": "message",
+						"role": "assistant",
+						"content": [{"type": "output_text", "text": "Paris."}]
+					}
+				]
+			}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeThinking, Content: "Thinking about it"},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Paris."},
+					},
+					FinishReason: aiobservabilitytypes.FinishReasonStop,
+				},
+			},
+		},
+		{
+			name: "ResponsesAPIResponseIncomplete_EncryptedReasoningEmptyAndFinishReasonLength",
+			raw: `{
+				"output": [
+					{"type": "reasoning", "content": [{"type": "reasoning_text", "text": "step 1"}]},
+					{"type": "reasoning", "encrypted_content": "gAAAA"}
+				],
+				"status": "incomplete",
+				"incomplete_details": {"reason": "max_output_tokens"}
+			}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeThinking, Content: "step 1"},
+					},
+				},
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonLength,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeThinking},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizeEnvelopeGemini(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "GeminiResponse_ThoughtAndFunctionCallPartsConverted",
+			raw: `{
+				"candidates": [
+					{
+						"content": {
+							"parts": [
+								{"text": "Let me check", "thought": true},
+								{"function_call": {"name": "get_weather", "args": {"city": "Paris"}}}
+							],
+							"role": "model"
+						},
+						"finishReason": "STOP"
+					}
+				],
+				"usageMetadata": {}
+			}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonStop,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeThinking, Content: "Let me check"},
+						{Type: aiobservabilitytypes.PartTypeToolCall, Name: "get_weather", Arguments: map[string]any{"city": "Paris"}},
+					},
+				},
+			},
+		},
+		{
+			name: "GoogleADKResponse_ContentBecomesAssistantMessageWithStop",
+			raw:  `{"content": {"parts": [{"text": "It is 18°C and clear in Bengaluru."}], "role": "model"}, "finish_reason": "STOP"}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonStop,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "It is 18°C and clear in Bengaluru."},
+					},
+				},
+			},
+		},
+		{
+			name: "GeminiResponseBlockedBySafety_BecomesGenericWithContentFilter",
+			raw:  `{"candidates": [{"finishReason": "SAFETY", "index": 0}]}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonContentFilter,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeGeneric, Content: `{"finishReason":"SAFETY","index":0}`},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizeEnvelopeLangChain(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "LangChainGenerationWithOnlyText_BecomesAssistantTextWithLength",
+			raw:  `{"generations": [[{"text": "Observability is the ability", "generation_info": {"finish_reason": "length"}}]]}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonLength,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Observability is the ability"},
+					},
+				},
+			},
+		},
+	})
+}

pkg/types/aiobservabilitytypes/genaimessages/genaimessages.go

@@ -0,0 +1,71 @@
+package genaimessages
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+// Ordered by specificity: earlier converters never match a later format.
+var converters = []converter{
+	convertSemconvMessages,
+	convertChatMessageList,
+	convertToolCallList,
+	convertChatRequest,
+	convertChatResponse,
+	convertResponsesAPIResponse,
+	convertGeminiResponse,
+	convertLegacyCompletion,
+	convertLangChainGenerations,
+}
+
+// Normalize converts a gen_ai.*.messages value, a JSON string or a decoded value.
+// A string that is not JSON becomes one text part; JSON in no known format becomes
+// one generic part holding the original.
+func Normalize(raw any) []aiobservabilitytypes.Message {
+	var (
+		value    any
+		original string
+	)
+	switch v := raw.(type) {
+	case nil:
+		return []aiobservabilitytypes.Message{}
+	case string:
+		if strings.TrimSpace(v) == "" {
+			return []aiobservabilitytypes.Message{}
+		}
+		original = v
+		if err := json.Unmarshal([]byte(v), &value); err != nil {
+			return []aiobservabilitytypes.Message{{Content: []aiobservabilitytypes.Part{textPart(v)}}}
+		}
+	default:
+		value = v
+		original = stringOf(v)
+	}
+	if value == nil {
+		return []aiobservabilitytypes.Message{}
+	}
+
+	if list, ok := value.([]any); ok {
+		if len(list) == 0 {
+			return []aiobservabilitytypes.Message{}
+		}
+		// [[...]]: some SDKs wrap the conversation in one more list
+		if _, nested := firstItem(list).([]any); nested {
+			value = flattenOnce(list)
+		}
+		// ["{...}", "{...}"]: an array attribute holding one JSON message per element
+		if decoded, ok := decodeJSONStrings(list); ok {
+			value = decoded
+		}
+	}
+	for _, convert := range converters {
+		if messages, ok := convert(value); ok {
+			return messages
+		}
+	}
+	return genericMessages(original)
+}
+
+type converter func(value any) (messages []aiobservabilitytypes.Message, ok bool)

pkg/types/aiobservabilitytypes/genaimessages/genaimessages_test.go

@@ -0,0 +1,146 @@
+package genaimessages
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNormalize(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "ListNestedInAnotherList_Unwrapped",
+			raw:  `[[{"role":"user","content":"Hi"}]]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+			},
+		},
+		{
+			name: "ListOfToolDefinitions_FallsBackToGeneric",
+			raw:  `[{"type":"function","function":{"name":"get_weather","description":"Weather","parameters":{"type":"object"}}}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeGeneric, Content: `[{"type":"function","function":{"name":"get_weather","description":"Weather","parameters":{"type":"object"}}}]`},
+					},
+				},
+			},
+		},
+		{
+			name: "ListOfMessagesAsJSONStrings_EachDecoded",
+			raw:  []any{`{"role":"user","content":"Hi"}`, `{"role":"assistant","content":"Hello"}`},
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hello"},
+					},
+				},
+			},
+		},
+		{
+			name: "TextThatIsNotJSON_ReturnedAsOneTextPart",
+			raw:  "Let the cost of the ball be x dollars.",
+			want: []aiobservabilitytypes.Message{
+				{
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Let the cost of the ball be x dollars."},
+					},
+				},
+			},
+		},
+		{
+			name: "JSONInNoKnownFormat_ReturnedVerbatimAsGeneric",
+			raw:  `{"output": "{\"query\": \"SigNoz\"}", "kwargs": {"name": "search_web"}}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeGeneric, Content: `{"output": "{\"query\": \"SigNoz\"}", "kwargs": {"name": "search_web"}}`},
+					},
+				},
+			},
+		},
+		{
+			name: "AlreadyDecodedValue_ConvertedLikeJSON",
+			raw:  []any{map[string]any{"role": "user", "content": "hi"}},
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "hi"},
+					},
+				},
+			},
+		},
+		{
+			name: "BlankString_ReturnsNoMessages",
+			raw:  " \n\t ",
+			want: []aiobservabilitytypes.Message{},
+		},
+		{
+			name: "JSONNull_ReturnsNoMessages",
+			raw:  `null`,
+			want: []aiobservabilitytypes.Message{},
+		},
+	})
+}
+
+func FuzzNormalize(f *testing.F) {
+	for _, seed := range []string{
+		`[{"role": "user", "parts": [{"type": "text", "content": "Hi"}]}]`,
+		`[{"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_1", "name": "f", "input": {}}]}]`,
+		`[{"role": "tool", "tool_call_id": "call_1", "content": [{"type": "text", "text": "ok"}]}]`,
+		`{"messages": [{"role": "user", "content": "Hi"}], "system": [{"type": "text", "text": "Be brief."}]}`,
+		`{"choices": [{"message": {"role": "assistant", "content": "Hi"}, "finish_reason": "stop"}]}`,
+		`{"output": [{"type": "function_call", "call_id": "c", "name": "f", "arguments": "{}"}, {"type": "reasoning"}]}`,
+		`{"candidates": [{"content": {"parts": [{"functionCall": {"name": "f", "args": {}}}], "role": "model"}}]}`,
+		`{"generations": [[{"text": "Hi", "message": {"lc": 1, "type": "constructor", "id": ["AIMessage"], "kwargs": {}}}]]}`,
+		`[[{"role": "user", "content": "Hi"}]]`,
+		`["{\"role\": \"user\", \"content\": \"Hi\"}"]`,
+		``, `null`, `{}`, `[]`, `[{}]`, `"text"`, `42`,
+	} {
+		f.Add(seed)
+	}
+	f.Fuzz(func(t *testing.T, raw string) {
+		inputs := []any{raw}
+		var decoded any
+		if json.Unmarshal([]byte(raw), &decoded) == nil {
+			inputs = append(inputs, decoded)
+		}
+		for _, input := range inputs {
+			for i, message := range Normalize(input) {
+				if message.Content == nil {
+					t.Fatalf("message %d has nil content for %#v", i, input)
+				}
+			}
+		}
+	})
+}
+
+type normalizeCase struct {
+	name string
+	raw  any
+	want []aiobservabilitytypes.Message
+}
+
+func assertNormalize(t *testing.T, testCases []normalizeCase) {
+	t.Helper()
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			assert.Equal(t, testCase.want, Normalize(testCase.raw))
+		})
+	}
+}

pkg/types/aiobservabilitytypes/genaimessages/message.go

@@ -0,0 +1,254 @@
+package genaimessages
+
+import (
+	"cmp"
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+// chatMessage returns nil for LangGraph tool definitions.
+func chatMessage(value any, defaultRole aiobservabilitytypes.MessageRole) []aiobservabilitytypes.Message {
+	m, ok := toObject(value)
+	if !ok {
+		return genericMessages(stringOf(value))
+	}
+	if inner, role, ok := langChainMessage(m); ok {
+		return chatMessage(inner, role)
+	}
+	if isLangGraphToolDefinition(m) {
+		return nil
+	}
+
+	typ := m.str("type")
+	if isResponsesItemType(typ) {
+		return responsesItemMessages(m, typ)
+	}
+	if typ == "reasoning" {
+		return []aiobservabilitytypes.Message{{Role: aiobservabilitytypes.MessageRoleAssistant, Content: reasoningParts(m)}}
+	}
+
+	role := cmp.Or(normalizeRole(m.str("role")), standardRole(typ), defaultRole)
+	msg := aiobservabilitytypes.Message{
+		Role:         role,
+		Content:      append(messageContentParts(m, role), messageToolCallParts(m)...),
+		FinishReason: normalizeFinishReason(finishReasonOf(m)),
+	}
+	if refusal := m.str("refusal"); refusal != "" {
+		msg.Content = append(msg.Content, textPart(refusal))
+	}
+	return []aiobservabilitytypes.Message{msg}
+}
+
+// langChainMessage unwraps a serialised message: {lc, type: "constructor", id: [..., "HumanMessage"], kwargs}.
+func langChainMessage(m object) (object, aiobservabilitytypes.MessageRole, bool) {
+	kwargs, ok := m.obj("kwargs")
+	if !ok || m.str("type") != "constructor" {
+		return nil, "", false
+	}
+	return kwargs, cmp.Or(langChainRole(m.at("id")), standardRole(kwargs.str("type"))), true
+}
+
+func langChainRole(id any) aiobservabilitytypes.MessageRole {
+	path, ok := id.([]any)
+	if !ok || len(path) == 0 {
+		return ""
+	}
+	switch class := stringOf(lastItem(path)); {
+	case strings.HasPrefix(class, "System"):
+		return aiobservabilitytypes.MessageRoleSystem
+	case strings.HasPrefix(class, "Human"):
+		return aiobservabilitytypes.MessageRoleUser
+	case strings.HasPrefix(class, "AI"):
+		return aiobservabilitytypes.MessageRoleAssistant
+	case strings.HasPrefix(class, "Tool"), strings.HasPrefix(class, "Function"):
+		return aiobservabilitytypes.MessageRoleTool
+	}
+	return ""
+}
+
+// isLangGraphToolDefinition matches {role: "tool", content: {type: "function"}} without tool_call_id.
+func isLangGraphToolDefinition(m object) bool {
+	if normalizeRole(m.str("role")) != aiobservabilitytypes.MessageRoleTool {
+		return false
+	}
+	if has := m.has("tool_call_id"); has {
+		return false
+	}
+	content, ok := m.obj("content")
+	if !ok || content.str("type") != "function" {
+		return false
+	}
+	ok = content.has("function")
+	return ok
+}
+
+// messageContentParts turns a tool message's text into its result.
+func messageContentParts(m object, role aiobservabilitytypes.MessageRole) []aiobservabilitytypes.Part {
+	parts := []aiobservabilitytypes.Part{}
+	switch content := m.at("content").(type) {
+	case nil:
+	case string:
+		if role == aiobservabilitytypes.MessageRoleTool {
+			parts = append(parts, toolMessageResult(m, content))
+		} else if content != "" {
+			parts = append(parts, textPart(content))
+		}
+	case []any:
+		for _, item := range content {
+			part := contentBlockPart(item)
+			if role == aiobservabilitytypes.MessageRoleTool && part.Type == aiobservabilitytypes.PartTypeText {
+				part = toolMessageResult(m, part.Content)
+			}
+			parts = append(parts, part)
+		}
+	case map[string]any:
+		if contentParts, ok := object(content).list("parts"); ok {
+			for _, p := range contentParts {
+				parts = append(parts, semconvPart(p))
+			}
+		} else if role == aiobservabilitytypes.MessageRoleTool {
+			parts = append(parts, toolMessageResult(m, stringOf(content)))
+		} else {
+			parts = append(parts, genericPart(content))
+		}
+	default:
+		parts = append(parts, genericPart(content))
+	}
+	return parts
+}
+
+func messageToolCallParts(m object) []aiobservabilitytypes.Part {
+	calls, _ := m.first("tool_calls", "toolCalls").([]any)
+	if kwargs, ok := m.obj("additional_kwargs"); ok && len(calls) == 0 {
+		calls, _ = kwargs.list("tool_calls")
+	}
+	parts := make([]aiobservabilitytypes.Part, 0, len(calls)+1)
+	for _, call := range calls {
+		parts = append(parts, toolCallPart(call))
+	}
+	if call, ok := m.obj("function_call"); ok {
+		parts = append(parts, aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeToolCall, Name: call.str("name"), Arguments: parseArguments(call.at("arguments"))})
+	}
+	return parts
+}
+
+func toolMessageResult(m object, content string) aiobservabilitytypes.Part {
+	return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: stringOf(m.first("tool_call_id", "toolCallId")), Name: m.str("name"), Content: content}
+}
+
+// semconvMessage falls back to chatMessage when m has no parts. LiteLLM mixes in
+// OpenAI fields: tool_calls beside parts, and tool_call_id on tool messages.
+func semconvMessage(m object, defaultRole aiobservabilitytypes.MessageRole) []aiobservabilitytypes.Message {
+	parts, ok := m.list("parts")
+	if !ok {
+		return chatMessage(m, defaultRole)
+	}
+	role := cmp.Or(normalizeRole(m.str("role")), defaultRole)
+	msg := aiobservabilitytypes.Message{
+		Role:         role,
+		Content:      []aiobservabilitytypes.Part{},
+		FinishReason: normalizeFinishReason(finishReasonOf(m)),
+	}
+	for _, p := range parts {
+		part := semconvPart(p)
+		if role == aiobservabilitytypes.MessageRoleTool && part.Type == aiobservabilitytypes.PartTypeText {
+			part = toolMessageResult(m, part.Content)
+		}
+		msg.Content = append(msg.Content, part)
+	}
+	msg.Content = append(msg.Content, messageToolCallParts(m)...)
+	return []aiobservabilitytypes.Message{msg}
+}
+
+// isResponsesItemType matches role-less Responses API tool and MCP items.
+func isResponsesItemType(typ string) bool {
+	switch typ {
+	case "":
+		return false
+	case "function_call", "function_call_output", "tool_call", "custom_tool_call", "custom_tool_call_output",
+		"mcp_call", "mcp_list_tools", "mcp_approval_request", "mcp_approval_response":
+		return true
+	}
+	return strings.HasSuffix(typ, "_call") || strings.HasSuffix(typ, "_call_output")
+}
+
+// responsesItemMessages turns a built-in tool item into a call, plus its result when the item carries one.
+func responsesItemMessages(m object, typ string) []aiobservabilitytypes.Message {
+	switch typ {
+	case "function_call", "tool_call", "custom_tool_call":
+		return []aiobservabilitytypes.Message{{Role: aiobservabilitytypes.MessageRoleAssistant, Content: []aiobservabilitytypes.Part{{
+			Type:      aiobservabilitytypes.PartTypeToolCall,
+			ID:        stringOf(m.first("call_id", "id")),
+			Name:      m.str("name"),
+			Arguments: parseArguments(m.first("arguments", "args", "input")),
+		}}}}
+	case "function_call_output", "custom_tool_call_output":
+		return []aiobservabilitytypes.Message{{Role: aiobservabilitytypes.MessageRoleTool, Content: []aiobservabilitytypes.Part{{
+			Type:       aiobservabilitytypes.PartTypeToolResult,
+			ToolCallID: stringOf(m.first("call_id", "id")),
+			Content:    stringOf(m.first("output", "result")),
+		}}}}
+	}
+
+	id := stringOf(m.first("call_id", "id"))
+	if strings.HasSuffix(typ, "_output") || typ == "mcp_approval_response" {
+		return []aiobservabilitytypes.Message{{Role: aiobservabilitytypes.MessageRoleTool, Content: []aiobservabilitytypes.Part{{
+			Type:       aiobservabilitytypes.PartTypeToolResult,
+			ToolCallID: id,
+			Name:       strings.TrimSuffix(typ, "_output"),
+			Content:    stringOf(m.first("output", "result", "results")),
+		}}}}
+	}
+
+	args := make(map[string]any, len(m))
+	for k, v := range m {
+		switch k {
+		case "type", "id", "call_id", "status", "name", "server_label", "output", "result", "results":
+		default:
+			args[k] = v
+		}
+	}
+	name := stringOf(m.first("name", "server_label"))
+	if name == "" {
+		name = typ
+	}
+	call := aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeToolCall, ID: id, Name: name}
+	if arguments, ok := m.get("arguments"); ok {
+		call.Arguments = parseArguments(arguments)
+	} else if len(args) > 0 {
+		call.Arguments = args
+	}
+	msg := aiobservabilitytypes.Message{Role: aiobservabilitytypes.MessageRoleAssistant, Content: []aiobservabilitytypes.Part{call}}
+	if result := m.first("output", "result", "results"); result != nil {
+		msg.Content = append(msg.Content, aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: id, Name: name, Content: stringOf(result)})
+	}
+	return []aiobservabilitytypes.Message{msg}
+}
+
+// reasoningParts returns one empty thinking part for encrypted reasoning without a summary.
+func reasoningParts(m object) []aiobservabilitytypes.Part {
+	parts := []aiobservabilitytypes.Part{}
+	if summary, ok := m.list("summary"); ok {
+		for _, s := range summary {
+			parts = append(parts, aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: stringOf(asObject(s).first("text", "content"))})
+		}
+	}
+	if content, ok := m.list("content"); ok {
+		for _, c := range content {
+			parts = append(parts, aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: stringOf(asObject(c).first("text", "content"))})
+		}
+	}
+	if len(parts) == 0 {
+		parts = append(parts, aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking})
+	}
+	return parts
+}
+
+func textMessage(role aiobservabilitytypes.MessageRole, content string) aiobservabilitytypes.Message {
+	return aiobservabilitytypes.Message{Role: role, Content: []aiobservabilitytypes.Part{textPart(content)}}
+}
+
+func genericMessages(content string) []aiobservabilitytypes.Message {
+	return []aiobservabilitytypes.Message{{Content: []aiobservabilitytypes.Part{genericPart(content)}}}
+}

pkg/types/aiobservabilitytypes/genaimessages/message_test.go

@@ -0,0 +1,257 @@
+package genaimessages
+
+import (
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+func TestNormalizeMessageChat(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "AnthropicMessages_ThinkingAndToolUseBlocksConverted",
+			raw: `[
+				{"role": "user", "content": "Hi"},
+				{
+					"role": "assistant",
+					"content": [
+						{"type": "thinking", "thinking": "Let me see"},
+						{"type": "redacted_thinking", "data": "x"},
+						{
+							"type": "tool_use",
+							"id": "toolu_1",
+							"name": "lookup",
+							"input": {"q": "a"}
+						}
+					],
+					"stop_reason": "tool_use"
+				},
+				{
+					"role": "user",
+					"content": [
+						{
+							"type": "tool_result",
+							"tool_use_id": "toolu_1",
+							"content": "found",
+							"is_error": true
+						}
+					]
+				}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+				{
+					Role:         aiobservabilitytypes.MessageRoleAssistant,
+					FinishReason: aiobservabilitytypes.FinishReasonToolCall,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeThinking, Content: "Let me see"},
+						{Type: aiobservabilitytypes.PartTypeThinking},
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "toolu_1", Name: "lookup", Arguments: map[string]any{"q": "a"}},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "toolu_1", Content: "found", IsError: true},
+					},
+				},
+			},
+		},
+		{
+			name: "OpenAIToolMessageTextBlocks_BecomeToolResult",
+			raw: `[
+				{
+					"role": "tool",
+					"tool_call_id": "c1",
+					"content": [{"type": "text", "text": "20C"}, {"type": "text", "text": "clear"}]
+				}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleTool,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "c1", Content: "20C"},
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "c1", Content: "clear"},
+					},
+				},
+			},
+		},
+		{
+			name: "OpenAIRefusal_BecomesAssistantText",
+			raw:  `[{"role": "assistant", "content": null, "refusal": "I can't help with that."}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "I can't help with that."},
+					},
+				},
+			},
+		},
+		{
+			name: "OpenAILegacyFunctionCall_BecomesToolCall",
+			raw:  `[{"role": "assistant", "content": null, "function_call": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, Name: "get_weather", Arguments: map[string]any{"city": "Paris"}},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizeMessageLangChain(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "LangChainTypedMessages_ToolCallsReadFromAdditionalKwargs",
+			raw: `[
+				{"type": "human", "content": "Weather?"},
+				{
+					"type": "ai",
+					"content": "",
+					"additional_kwargs": {
+						"tool_calls": [
+							{
+								"id": "call_1",
+								"type": "function",
+								"function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}
+							}
+						]
+					}
+				},
+				{
+					"type": "tool",
+					"content": "20C",
+					"tool_call_id": "call_1",
+					"name": "get_weather"
+				}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Weather?"},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "call_1", Name: "get_weather", Arguments: map[string]any{"city": "Paris"}},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleTool,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "call_1", Name: "get_weather", Content: "20C"},
+					},
+				},
+			},
+		},
+		{
+			name: "LangGraphToolDefinitionMessage_IsDropped",
+			raw: `[
+				{
+					"role": "tool",
+					"content": {
+						"type": "function",
+						"function": {"name": "get_weather", "parameters": {}}
+					}
+				},
+				{"role": "user", "content": "Hi"}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Hi"},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizeMessageOpenAIResponsesItems(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "BuiltInToolCallItem_BecomesToolCall",
+			raw: `{
+				"object": "response",
+				"status": "completed",
+				"output": [
+					{
+						"type": "web_search_call",
+						"id": "ws_1",
+						"status": "completed",
+						"action": {"type": "search", "query": "SigNoz"}
+					},
+					{
+						"type": "custom_tool_call",
+						"call_id": "c1",
+						"name": "grep",
+						"input": "foo"
+					},
+					{
+						"type": "message",
+						"role": "assistant",
+						"content": [{"type": "output_text", "text": "Found it."}]
+					}
+				]
+			}`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "ws_1", Name: "web_search_call", Arguments: map[string]any{"action": map[string]any{"type": "search", "query": "SigNoz"}}},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "c1", Name: "grep", Arguments: "foo"},
+					},
+				},
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Found it."},
+					},
+					FinishReason: aiobservabilitytypes.FinishReasonStop,
+				},
+			},
+		},
+		{
+			name: "BuiltInToolOutputItem_BecomesToolResult",
+			raw:  `[{"type": "local_shell_call_output", "call_id": "call_2", "output": "ok"}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleTool,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "call_2", Name: "local_shell_call", Content: "ok"},
+					},
+				},
+			},
+		},
+		{
+			name: "MCPCallItemWithOutput_BecomesToolCallAndToolResult",
+			raw:  `[{"type": "mcp_call", "id": "mcp_1", "server_label": "deepwiki", "name": "ask_question", "arguments": "{\"q\": \"What is SigNoz?\"}", "output": "An observability platform."}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "mcp_1", Name: "ask_question", Arguments: map[string]any{"q": "What is SigNoz?"}},
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "mcp_1", Name: "ask_question", Content: "An observability platform."},
+					},
+				},
+			},
+		},
+	})
+}

pkg/types/aiobservabilitytypes/genaimessages/part.go

@@ -0,0 +1,152 @@
+package genaimessages
+
+import (
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+func contentBlockPart(value any) aiobservabilitytypes.Part {
+	p, ok := toObject(value)
+	if !ok {
+		if s, ok := value.(string); ok {
+			return textPart(s)
+		}
+		return genericPart(value)
+	}
+	typ := p.str("type")
+	switch typ {
+	case "text", "input_text", "output_text", "refusal", "summary_text":
+		return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeText, Content: stringOf(p.first("text", "content", "refusal"))}
+	case "thinking", "reasoning":
+		return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: stringOf(p.first("thinking", "text", "content", "reasoning"))}
+	case "redacted_thinking":
+		return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking}
+	case "tool-call", "tool_use", "tool_call", "function_call", "server_tool_use", "mcp_tool_use":
+		return toolCallPart(p)
+	case "tool-result", "tool_result", "function_call_output":
+		return toolResultBlockPart(p, p.first("result", "output", "content"))
+	case "":
+		if text, ok := p.get("text"); ok {
+			return textPart(stringOf(text))
+		}
+	default:
+		if strings.HasSuffix(typ, "_tool_result") {
+			return toolResultBlockPart(p, p.at("content"))
+		}
+	}
+	return genericPart(p)
+}
+
+func semconvPart(value any) aiobservabilitytypes.Part {
+	p, ok := toObject(value)
+	if !ok {
+		if s, ok := value.(string); ok {
+			return textPart(s)
+		}
+		return genericPart(value)
+	}
+	switch p.str("type") {
+	case "text":
+		if p.flag("thought") {
+			return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: stringOf(p.first("content", "text"))}
+		}
+		return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeText, Content: stringOf(p.first("content", "text"))}
+	case "reasoning", "thinking":
+		return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: stringOf(p.first("content", "thinking", "text"))}
+	case "redacted_thinking", "redacted_reasoning":
+		return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking}
+	case "tool_call":
+		return aiobservabilitytypes.Part{
+			Type:      aiobservabilitytypes.PartTypeToolCall,
+			ID:        p.str("id"),
+			Name:      p.str("name"),
+			Arguments: parseArguments(p.first("arguments", "args", "input")),
+		}
+	case "tool_call_response":
+		return aiobservabilitytypes.Part{
+			Type:       aiobservabilitytypes.PartTypeToolResult,
+			ToolCallID: p.str("id"),
+			Name:       p.str("name"),
+			Content:    stringOf(p.first("response", "result", "content", "output")),
+			IsError:    boolOf(p.first("is_error", "isError")),
+		}
+	case "":
+		// Gemini parts carry no type; the field name is the type.
+		if text, ok := p.get("text"); ok {
+			if p.flag("thought") {
+				return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeThinking, Content: stringOf(text)}
+			}
+			return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeText, Content: stringOf(text)}
+		}
+		if call, ok := toObject(p.first("functionCall", "function_call")); ok {
+			return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeToolCall, ID: call.str("id"), Name: call.str("name"), Arguments: parseArguments(call.at("args"))}
+		}
+		if resp, ok := toObject(p.first("functionResponse", "function_response")); ok {
+			return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: resp.str("id"), Name: resp.str("name"), Content: resp.str("response")}
+		}
+	}
+	return genericPart(p)
+}
+
+// toolCallPart reads the OpenAI, flat, Anthropic and Vercel tool call shapes.
+func toolCallPart(value any) aiobservabilitytypes.Part {
+	call, ok := toObject(value)
+	if !ok {
+		return genericPart(value)
+	}
+	part := aiobservabilitytypes.Part{
+		Type: aiobservabilitytypes.PartTypeToolCall,
+		ID:   stringOf(call.first("toolCallId", "call_id", "id")),
+		Name: stringOf(call.first("toolName", "name")),
+	}
+	if fn, ok := call.obj("function"); ok {
+		part.Name = fn.str("name")
+		part.Arguments = parseArguments(fn.at("arguments"))
+		return part
+	}
+	part.Arguments = parseArguments(call.first("arguments", "args", "input"))
+	return part
+}
+
+// toolResultBlockPart unwraps the Vercel {type, value} result wrapper.
+func toolResultBlockPart(p object, result any) aiobservabilitytypes.Part {
+	if nested, ok := toObject(result); ok && len(nested) <= 2 {
+		if v, ok := nested.get("value"); ok {
+			result = v
+		}
+	}
+	return aiobservabilitytypes.Part{
+		Type:       aiobservabilitytypes.PartTypeToolResult,
+		ToolCallID: stringOf(p.first("toolCallId", "tool_use_id", "tool_call_id", "call_id", "id")),
+		Name:       stringOf(p.first("toolName", "name")),
+		Content:    toolResultText(result),
+		IsError:    boolOf(p.first("isError", "is_error")),
+	}
+}
+
+// toolResultText joins a list of text blocks; anything else goes through stringOf.
+func toolResultText(result any) string {
+	list, ok := result.([]any)
+	if !ok || len(list) == 0 {
+		return stringOf(result)
+	}
+	texts := make([]string, 0, len(list))
+	for _, item := range list {
+		block := asObject(item)
+		text, ok := block.text("text")
+		if !ok || (len(block) == 2 && block.str("type") != "text") || len(block) > 2 {
+			return stringOf(result)
+		}
+		texts = append(texts, text)
+	}
+	return strings.Join(texts, "\n")
+}
+
+func textPart(content string) aiobservabilitytypes.Part {
+	return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeText, Content: content}
+}
+
+func genericPart(value any) aiobservabilitytypes.Part {
+	return aiobservabilitytypes.Part{Type: aiobservabilitytypes.PartTypeGeneric, Content: stringOf(value)}
+}

pkg/types/aiobservabilitytypes/genaimessages/part_test.go

@@ -0,0 +1,130 @@
+package genaimessages
+
+import (
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+func TestNormalizePartContent(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "PartWithUnknownType_BecomesGeneric",
+			raw:  `[{"role":"user","parts":[{"type":"image","url":"http://x/y.png"}]}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeGeneric, Content: `{"type":"image","url":"http://x/y.png"}`},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizePartThinking(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "ThoughtReasoningAndHiddenParts_BecomeThinking",
+			raw: `[
+				{
+					"role": "assistant",
+					"parts": [
+						{"type": "text", "content": "Let me think", "thought": true},
+						{"type": "reasoning", "content": "step 1"},
+						{"type": "redacted_reasoning", "data": "xyz"},
+						{"type": "text", "content": "Answer"}
+					]
+				}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeThinking, Content: "Let me think"},
+						{Type: aiobservabilitytypes.PartTypeThinking, Content: "step 1"},
+						{Type: aiobservabilitytypes.PartTypeThinking},
+						{Type: aiobservabilitytypes.PartTypeText, Content: "Answer"},
+					},
+				},
+			},
+		},
+	})
+}
+
+func TestNormalizePartTools(t *testing.T) {
+	assertNormalize(t, []normalizeCase{
+		{
+			name: "AnthropicServerToolUseAndWebSearchResult_BecomeToolCallAndResult",
+			raw: `[
+				{
+					"role": "assistant",
+					"content": [
+						{"type": "server_tool_use", "id": "srvtoolu_1", "name": "web_search", "input": {"query": "SigNoz"}},
+						{"type": "web_search_tool_result", "tool_use_id": "srvtoolu_1", "content": [{"type": "web_search_result", "title": "SigNoz", "url": "https://signoz.io"}]}
+					]
+				}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "srvtoolu_1", Name: "web_search", Arguments: map[string]any{"query": "SigNoz"}},
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "srvtoolu_1", Content: `[{"title":"SigNoz","type":"web_search_result","url":"https://signoz.io"}]`},
+					},
+				},
+			},
+		},
+		{
+			name: "AnthropicToolResultTextBlocks_JoinedIntoOneString",
+			raw: `[
+				{
+					"role": "user",
+					"content": [
+						{
+							"type": "tool_result",
+							"tool_use_id": "t1",
+							"content": [
+								{"type": "text", "text": "line one"},
+								{"type": "text", "text": "line two"}
+							]
+						}
+					]
+				}
+			]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleUser,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "t1", Content: "line one\nline two"},
+					},
+				},
+			},
+		},
+		{
+			name: "VercelToolResultJSONWrapper_ValueUnwrapped",
+			raw:  `[{"role": "tool", "content": [{"type": "tool-result", "toolCallId": "call_1", "toolName": "get_weather", "result": {"type": "json", "value": {"temp_c": 18}}}]}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleTool,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolResult, ToolCallID: "call_1", Name: "get_weather", Content: `{"temp_c":18}`},
+					},
+				},
+			},
+		},
+		{
+			name: "ToolCallWithInvalidJSONArguments_ArgumentsKeptAsString",
+			raw:  `[{"role": "assistant", "tool_calls": [{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{city: Paris"}}]}]`,
+			want: []aiobservabilitytypes.Message{
+				{
+					Role: aiobservabilitytypes.MessageRoleAssistant,
+					Content: []aiobservabilitytypes.Part{
+						{Type: aiobservabilitytypes.PartTypeToolCall, ID: "call_1", Name: "get_weather", Arguments: "{city: Paris"},
+					},
+				},
+			},
+		},
+	})
+}

pkg/types/aiobservabilitytypes/genaimessages/role.go

@@ -0,0 +1,54 @@
+package genaimessages
+
+import (
+	"strings"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+)
+
+var finishReasonKeys = []string{"finish_reason", "finishReason", "stop_reason"}
+
+// normalizeRole keeps an unknown role, lowercased.
+func normalizeRole(role string) aiobservabilitytypes.MessageRole {
+	if known := standardRole(role); known != "" {
+		return known
+	}
+	return aiobservabilitytypes.MessageRole(strings.ToLower(strings.TrimSpace(role)))
+}
+
+// normalizeFinishReason keeps an unknown reason, lowercased.
+func normalizeFinishReason(reason string) aiobservabilitytypes.FinishReason {
+	lowered := strings.ToLower(strings.TrimSpace(reason))
+	switch lowered {
+	case "stop", "end_turn", "stop_sequence", "completed", "complete", "eos", "finished":
+		return aiobservabilitytypes.FinishReasonStop
+	case "tool_call", "tool_calls", "tool_use", "function_call":
+		return aiobservabilitytypes.FinishReasonToolCall
+	case "length", "max_tokens", "max_output_tokens", "max_completion_tokens", "model_length":
+		return aiobservabilitytypes.FinishReasonLength
+	case "content_filter", "content_filtered", "guardrail_intervened", "safety", "refusal", "recitation", "blocklist", "prohibited_content", "spii":
+		return aiobservabilitytypes.FinishReasonContentFilter
+	case "error", "failed", "incomplete":
+		return aiobservabilitytypes.FinishReasonError
+	}
+	return aiobservabilitytypes.FinishReason(lowered)
+}
+
+// standardRole maps vendor role names onto MessageRole; anything else is "".
+func standardRole(role string) aiobservabilitytypes.MessageRole {
+	switch strings.ToLower(strings.TrimSpace(role)) {
+	case "system", "developer":
+		return aiobservabilitytypes.MessageRoleSystem
+	case "user", "human":
+		return aiobservabilitytypes.MessageRoleUser
+	case "assistant", "ai", "model":
+		return aiobservabilitytypes.MessageRoleAssistant
+	case "tool", "function":
+		return aiobservabilitytypes.MessageRoleTool
+	}
+	return ""
+}
+
+func finishReasonOf(m object) string {
+	return stringOf(m.first(finishReasonKeys...))
+}

pkg/types/aiobservabilitytypes/genaimessages/role_test.go

@@ -0,0 +1,53 @@
+package genaimessages
+
+import (
+	"testing"
+
+	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNormalizeRole(t *testing.T) {
+	testCases := []struct {
+		name  string
+		roles []string
+		want  aiobservabilitytypes.MessageRole
+	}{
+		{name: "SystemAndDeveloper_MapToSystem", roles: []string{"system", "developer", " Developer "}, want: aiobservabilitytypes.MessageRoleSystem},
+		{name: "UserAndHuman_MapToUser", roles: []string{"user", "human", "HUMAN"}, want: aiobservabilitytypes.MessageRoleUser},
+		{name: "AssistantAIAndModel_MapToAssistant", roles: []string{"assistant", "ai", "model"}, want: aiobservabilitytypes.MessageRoleAssistant},
+		{name: "ToolAndFunction_MapToTool", roles: []string{"tool", "function"}, want: aiobservabilitytypes.MessageRoleTool},
+		{name: "UnknownRole_KeptLowercased", roles: []string{"Narrator"}, want: "narrator"},
+		{name: "EmptyRole_StaysEmpty", roles: []string{"", "  "}, want: ""},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			for _, role := range testCase.roles {
+				assert.Equal(t, testCase.want, normalizeRole(role), role)
+			}
+		})
+	}
+}
+
+func TestNormalizeFinishReason(t *testing.T) {
+	testCases := []struct {
+		name    string
+		reasons []string
+		want    aiobservabilitytypes.FinishReason
+	}{
+		{name: "EndOfAnswer_MapsToStop", reasons: []string{"stop", "end_turn", "stop_sequence", "completed", "complete", "eos", "finished", "STOP"}, want: aiobservabilitytypes.FinishReasonStop},
+		{name: "ToolCallVariants_MapToToolCall", reasons: []string{"tool_call", "tool_calls", "tool_use", "function_call"}, want: aiobservabilitytypes.FinishReasonToolCall},
+		{name: "TokenLimits_MapToLength", reasons: []string{"length", "max_tokens", "max_output_tokens", "max_completion_tokens", "model_length", "MAX_TOKENS"}, want: aiobservabilitytypes.FinishReasonLength},
+		{name: "SafetyBlocks_MapToContentFilter", reasons: []string{"content_filter", "content_filtered", "guardrail_intervened", "safety", "refusal", "recitation", "blocklist", "prohibited_content", "spii", "SAFETY"}, want: aiobservabilitytypes.FinishReasonContentFilter},
+		{name: "Failures_MapToError", reasons: []string{"error", "failed", "incomplete"}, want: aiobservabilitytypes.FinishReasonError},
+		{name: "UnknownReason_KeptLowercased", reasons: []string{"Weird"}, want: "weird"},
+		{name: "EmptyReason_StaysEmpty", reasons: []string{"", " "}, want: ""},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			for _, reason := range testCase.reasons {
+				assert.Equal(t, testCase.want, normalizeFinishReason(reason), reason)
+			}
+		})
+	}
+}

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost-gateway/gen_ai.input.messages.txt

@@ -0,0 +1 @@
+[{"role":"user","content":"What's the weather in Bengaluru? Use the tool."},{"role":"assistant","content":"","tool_calls":[{"id":"call_yGnJsGOZMnHKTA2x1XM8897b","type":"function","name":"get_current_weather","args":"{\"city\":\"Bengaluru\"}"}]},{"role":"tool","content":"{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}"}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost-gateway/gen_ai.input.messages.want.json

@@ -0,0 +1,33 @@
+[
+	{
+		"role": "user",
+		"content": [
+			{
+				"type": "text",
+				"content": "What's the weather in Bengaluru? Use the tool."
+			}
+		]
+	},
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_yGnJsGOZMnHKTA2x1XM8897b",
+				"name": "get_current_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		]
+	},
+	{
+		"role": "tool",
+		"content": [
+			{
+				"type": "tool_result",
+				"content": "{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}"
+			}
+		]
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost-gateway/gen_ai.output.messages.txt

@@ -0,0 +1 @@
+[{"role":"assistant","content":"","tool_calls":[{"id":"call_yGnJsGOZMnHKTA2x1XM8897b","type":"function","name":"get_current_weather","args":"{\"city\":\"Bengaluru\"}"}]}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost-gateway/gen_ai.output.messages.want.json

@@ -0,0 +1,15 @@
+[
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_yGnJsGOZMnHKTA2x1XM8897b",
+				"name": "get_current_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		]
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost/gen_ai.input.messages.txt

@@ -0,0 +1 @@
+[{"role": "user", "parts": [{"content": "What's the weather in Bengaluru? Use the tool.", "type": "text"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "name": "get_current_weather", "id": "call_iXrmKomEbGycID5aX4BYrQcg", "arguments": {"city": "Bengaluru"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_iXrmKomEbGycID5aX4BYrQcg", "response": "{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}"}]}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost/gen_ai.input.messages.want.json

@@ -0,0 +1,34 @@
+[
+	{
+		"role": "user",
+		"content": [
+			{
+				"type": "text",
+				"content": "What's the weather in Bengaluru? Use the tool."
+			}
+		]
+	},
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_iXrmKomEbGycID5aX4BYrQcg",
+				"name": "get_current_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		]
+	},
+	{
+		"role": "tool",
+		"content": [
+			{
+				"type": "tool_result",
+				"content": "{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}",
+				"toolCallId": "call_iXrmKomEbGycID5aX4BYrQcg"
+			}
+		]
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost/gen_ai.output.messages.txt

@@ -0,0 +1 @@
+[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_current_weather", "id": "call_iXrmKomEbGycID5aX4BYrQcg", "arguments": {"city": "Bengaluru"}}], "finish_reason": "tool_call"}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/bifrost/gen_ai.output.messages.want.json

@@ -0,0 +1,16 @@
+[
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_iXrmKomEbGycID5aX4BYrQcg",
+				"name": "get_current_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		],
+		"finishReason": "tool_call"
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langchain/gen_ai.input.messages.txt

@@ -0,0 +1 @@
+[{"role": "user", "parts": [{"type": "text", "content": "What's the weather in Bengaluru?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_mnRhZ0fYlvrSujkEcdmpppNw", "name": "get_weather", "arguments": {"city": "Bengaluru"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_mnRhZ0fYlvrSujkEcdmpppNw", "response": "{\"city\": \"Bengaluru\", \"temp_c\": 18, \"summary\": \"Clear\"}"}]}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langchain/gen_ai.input.messages.want.json

@@ -0,0 +1,34 @@
+[
+	{
+		"role": "user",
+		"content": [
+			{
+				"type": "text",
+				"content": "What's the weather in Bengaluru?"
+			}
+		]
+	},
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_mnRhZ0fYlvrSujkEcdmpppNw",
+				"name": "get_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		]
+	},
+	{
+		"role": "tool",
+		"content": [
+			{
+				"type": "tool_result",
+				"content": "{\"city\": \"Bengaluru\", \"temp_c\": 18, \"summary\": \"Clear\"}",
+				"toolCallId": "call_mnRhZ0fYlvrSujkEcdmpppNw"
+			}
+		]
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langchain/gen_ai.output.messages.txt

@@ -0,0 +1 @@
+[{"role": "assistant", "parts": [{"type": "tool_call", "id": "call_mnRhZ0fYlvrSujkEcdmpppNw", "name": "get_weather", "arguments": {"city": "Bengaluru"}}], "finish_reason": "tool_call"}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langchain/gen_ai.output.messages.want.json

@@ -0,0 +1,16 @@
+[
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_mnRhZ0fYlvrSujkEcdmpppNw",
+				"name": "get_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		],
+		"finishReason": "tool_call"
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langsmith/gen_ai.completion.txt

@@ -0,0 +1 @@
+{"generations":[[{"text":"","generation_info":{"finish_reason":"tool_calls","logprobs":null},"type":"ChatGeneration","message":{"lc":1,"type":"constructor","id":["langchain","schema","messages","AIMessage"],"kwargs":{"content":"","additional_kwargs":{"refusal":null},"response_metadata":{"token_usage":{"completion_tokens":17,"prompt_tokens":63,"total_tokens":80,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens_details":{"audio_tokens":0,"cached_tokens":0}},"model_provider":"openai","model_name":"gpt-4o-mini-2024-07-18","system_fingerprint":"fp_5feb5fe6c2","id":"chatcmpl-Dm101OqaY01WKntqj29Epz5er05ry","service_tier":"default","finish_reason":"tool_calls","logprobs":null},"type":"ai","id":"lc_run--019e844a-d27a-7c23-b1ed-a542e0f855da-0","tool_calls":[{"name":"get_weather","args":{"city":"Bengaluru"},"id":"call_nbrbkc5fom95q8uMA2bCvH6s","type":"tool_call"}],"usage_metadata":{"input_tokens":63,"output_tokens":17,"total_tokens":80,"input_token_details":{"audio":0,"cache_read":0},"output_token_details":{"audio":0,"reasoning":0}},"invalid_tool_calls":[]}}}]],"llm_output":{"token_usage":{"completion_tokens":17,"prompt_tokens":63,"total_tokens":80,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens_details":{"audio_tokens":0,"cached_tokens":0}},"model_provider":"openai","model_name":"gpt-4o-mini-2024-07-18","system_fingerprint":"fp_5feb5fe6c2","id":"chatcmpl-Dm101OqaY01WKntqj29Epz5er05ry","service_tier":"default"},"run":null,"type":"LLMResult"}

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langsmith/gen_ai.completion.want.json

@@ -0,0 +1,16 @@
+[
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_nbrbkc5fom95q8uMA2bCvH6s",
+				"name": "get_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		],
+		"finishReason": "tool_call"
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langsmith/gen_ai.prompt.txt

@@ -0,0 +1 @@
+{"messages":[[{"lc":1,"type":"constructor","id":["langchain","schema","messages","SystemMessage"],"kwargs":{"content":"You are a weather assistant. Call get_weather once per city.","type":"system"}},{"lc":1,"type":"constructor","id":["langchain","schema","messages","HumanMessage"],"kwargs":{"content":"What's the weather in Bengaluru?","type":"human"}},{"lc":1,"type":"constructor","id":["langchain","schema","messages","AIMessage"],"kwargs":{"content":"","additional_kwargs":{"refusal":null},"response_metadata":{"token_usage":{"completion_tokens":17,"prompt_tokens":63,"total_tokens":80,"completion_tokens_details":{"accepted_prediction_tokens":0,"audio_tokens":0,"reasoning_tokens":0,"rejected_prediction_tokens":0},"prompt_tokens_details":{"audio_tokens":0,"cached_tokens":0}},"model_provider":"openai","model_name":"gpt-4o-mini-2024-07-18","system_fingerprint":"fp_5feb5fe6c2","id":"chatcmpl-Dm101OqaY01WKntqj29Epz5er05ry","service_tier":"default","finish_reason":"tool_calls","logprobs":null},"type":"ai","id":"lc_run--019e844a-d27a-7c23-b1ed-a542e0f855da-0","tool_calls":[{"name":"get_weather","args":{"city":"Bengaluru"},"id":"call_nbrbkc5fom95q8uMA2bCvH6s","type":"tool_call"}],"usage_metadata":{"input_tokens":63,"output_tokens":17,"total_tokens":80,"input_token_details":{"audio":0,"cache_read":0},"output_token_details":{"audio":0,"reasoning":0}},"invalid_tool_calls":[]}},{"lc":1,"type":"constructor","id":["langchain","schema","messages","ToolMessage"],"kwargs":{"content":"{\"city\": \"Bengaluru\", \"temp_c\": 18, \"summary\": \"Clear\"}","type":"tool","tool_call_id":"call_nbrbkc5fom95q8uMA2bCvH6s","status":"success"}}]]}

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/langsmith/gen_ai.prompt.want.json

@@ -0,0 +1,43 @@
+[
+	{
+		"role": "system",
+		"content": [
+			{
+				"type": "text",
+				"content": "You are a weather assistant. Call get_weather once per city."
+			}
+		]
+	},
+	{
+		"role": "user",
+		"content": [
+			{
+				"type": "text",
+				"content": "What's the weather in Bengaluru?"
+			}
+		]
+	},
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_nbrbkc5fom95q8uMA2bCvH6s",
+				"name": "get_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		]
+	},
+	{
+		"role": "tool",
+		"content": [
+			{
+				"type": "tool_result",
+				"content": "{\"city\": \"Bengaluru\", \"temp_c\": 18, \"summary\": \"Clear\"}",
+				"toolCallId": "call_nbrbkc5fom95q8uMA2bCvH6s"
+			}
+		]
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/litellm/gen_ai.input.messages.txt

@@ -0,0 +1 @@
+[{"role": "user", "parts": [{"type": "text", "content": "What's the weather in Bengaluru? Use the tool."}]}, {"role": "assistant", "parts": [], "tool_calls": [{"function": {"arguments": "{\"city\":\"Bengaluru\"}", "name": "get_current_weather"}, "id": "call_GuU9siyYfjnx3DfHKzFbRrvD", "type": "function"}]}, {"role": "tool", "parts": [{"type": "text", "content": "{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}"}], "tool_call_id": "call_GuU9siyYfjnx3DfHKzFbRrvD"}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/litellm/gen_ai.input.messages.want.json

@@ -0,0 +1,34 @@
+[
+	{
+		"role": "user",
+		"content": [
+			{
+				"type": "text",
+				"content": "What's the weather in Bengaluru? Use the tool."
+			}
+		]
+	},
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "tool_call",
+				"id": "call_GuU9siyYfjnx3DfHKzFbRrvD",
+				"name": "get_current_weather",
+				"arguments": {
+					"city": "Bengaluru"
+				}
+			}
+		]
+	},
+	{
+		"role": "tool",
+		"content": [
+			{
+				"type": "tool_result",
+				"content": "{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}",
+				"toolCallId": "call_GuU9siyYfjnx3DfHKzFbRrvD"
+			}
+		]
+	}
+]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/litellm/gen_ai.output.messages.txt

@@ -0,0 +1 @@
+[{"role": "assistant", "parts": [{"type": "text", "content": "The animal in the image is a cartoon duck."}], "finish_reason": "stop"}]

pkg/types/aiobservabilitytypes/genaimessages/testdata/captured/litellm/gen_ai.output.messages.want.json

@@ -0,0 +1,12 @@
+[
+	{
+		"role": "assistant",
+		"content": [
+			{
+				"type": "text",
+				"content": "The animal in the image is a cartoon duck."
+			}
+		],
+		"finishReason": "stop"
+	}
+]