chore(telemetrytypes): introduce LogicalField (#12499)

Possible options

1. The compatibility keys maps (the approach already in the code).

`backward_compat_keys.go` makes an alias key at metadata time. We
rejected this option because of evidence. The alias key resolves, but it
reads the wrong data. It prepares to `attributes_string['<alias>']`, and
that physical key does not hold the data.

2. The flat multi-key.

`GetKeys` returns multiple keys in order, and the downstream code uses
the list. The option fails on semantics. It removes one piece of
information that the downstream must have. The downstream must know the
difference between two cases:

- Two keys are the same field with two spellings so we can merge them
into one expression.
- Two keys are different fields with the same name. The condition
builder must make one condition for each key. The operator connects the
conditions.

Three failures show the problem:

- Negative operators connect with OR across the keys. A row that has
only one spelling then always matches. Example: `env != 'prod'` matches
each row that does not have one of the two keys.
- A row that has both spellings with different values gets no clear
result.
- A value position (group-by, select) needs exactly one expression for
one field. A flat list cannot point to that expression.

The information must live somewhere.

3. Annotations on `TelemetryFieldKey`

Maintain the `SemconvMembers` and `SemconvMaterializedColumns` fields on
the keys. The information is the same as in option 4. But it's awkward
because "these N keys are one family, in this order" lives in N copies,
one copy on each key.

4. introduce `LogicalField`

The information is the same as in option 3, but the structure holds it:

- The slice is the ambiguity.
- The group is the family.
- The member order is the precedence. The code sorts the members one
time, by family rank, at construction.
- The members point to the metadata entries. The code copies nothing and
changes nothing.
- The identity (signal, context, data type) is on the group. A merge
across contexts or data types is not possible. The design does not avoid
that merge; the design cannot express it.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

frontend/src/components/LogDetail/LogHighlights/LogHighlights.module.scss

@@ -0,0 +1,46 @@
+.highlights {
+	display: grid;
+	grid-template-columns: repeat(4, minmax(0, 1fr));
+	gap: 12px 16px;
+	padding: 12px 0;
+
+	// Constrain each KeyValueLabel (the grid items) to its cell.
+	:global(.key-value-label) {
+		width: auto;
+		min-width: 0;
+		overflow: hidden;
+	}
+}
+
+.valueBadge {
+	--badge-font-size: 13px;
+	box-sizing: border-box;
+	max-width: 100%;
+	min-width: 0;
+}
+
+// Truncating text inside a badge
+.badgeText {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.serviceDot {
+	width: 6px;
+	height: 6px;
+	border-radius: 50%;
+	background: var(--accent-forest);
+	flex-shrink: 0;
+	margin-right: 4px;
+}
+
+.traceLink {
+	display: inline-block;
+	max-width: 100%;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	color: var(--accent-primary);
+}

frontend/src/components/LogDetail/LogHighlights/LogHighlights.tsx

@@ -0,0 +1,36 @@
+import KeyValueLabel from 'periscope/components/KeyValueLabel';
+import { ILog } from 'types/api/logs/log';
+
+import { LOG_HIGHLIGHTS } from './config';
+import styles from './LogHighlights.module.scss';
+
+interface LogHighlightsProps {
+	log: ILog;
+}
+
+function LogHighlights({ log }: LogHighlightsProps): JSX.Element | null {
+	const fields = LOG_HIGHLIGHTS.map((field) => ({
+		key: field.key,
+		label: field.label,
+		value: field.render(log),
+	})).filter((field) => field.value != null);
+
+	if (fields.length === 0) {
+		return null;
+	}
+
+	return (
+		<div className={styles.highlights} data-testid="log-details-highlights">
+			{fields.map((field) => (
+				<KeyValueLabel
+					key={field.key}
+					badgeKey={field.label}
+					badgeValue={field.value}
+					direction="column"
+				/>
+			))}
+		</div>
+	);
+}
+
+export default LogHighlights;

frontend/src/components/LogDetail/LogHighlights/TraceIdField.tsx

@@ -0,0 +1,23 @@
+import { Link } from 'react-router-dom';
+
+import styles from './LogHighlights.module.scss';
+
+interface TraceIdFieldProps {
+	traceId: string;
+}
+
+function TraceIdField({ traceId }: TraceIdFieldProps): JSX.Element {
+	return (
+		<Link
+			to={{ pathname: `/trace/${traceId}` }}
+			target="_blank"
+			rel="noreferrer"
+			className={styles.traceLink}
+			title={traceId}
+		>
+			{traceId}
+		</Link>
+	);
+}
+
+export default TraceIdField;

frontend/src/components/LogDetail/LogHighlights/config.tsx

@@ -0,0 +1,102 @@
+import { ReactNode } from 'react';
+import { Badge, BadgeColor } from '@signozhq/ui/badge';
+import { LogType } from 'components/Logs/LogStateIndicator/LogStateIndicator';
+import { getLogIndicatorType } from 'components/Logs/LogStateIndicator/utils';
+import { ILog } from 'types/api/logs/log';
+
+import styles from './LogHighlights.module.scss';
+import TraceIdField from './TraceIdField';
+
+// Severity badge color mirrors the LogStateIndicator bar
+const SEVERITY_COLOR: Record<string, BadgeColor> = {
+	[LogType.TRACE]: 'forest',
+	[LogType.DEBUG]: 'aqua',
+	[LogType.INFO]: 'robin',
+	[LogType.WARN]: 'amber',
+	[LogType.ERROR]: 'cherry',
+	[LogType.FATAL]: 'sakura',
+};
+
+export interface LogHighlightConfig {
+	key: string;
+	label: string;
+	render: (log: ILog) => ReactNode | null;
+}
+
+// Resource/attribute lookup (keys like `service.name` live in resources_string,
+// occasionally attributes_string). Typed loosely as these are string maps.
+const getAttr = (log: ILog, key: string): string =>
+	(log.resources_string as unknown as Record<string, string>)?.[key] ||
+	(log.attributes_string as unknown as Record<string, string>)?.[key] ||
+	'';
+
+const valueBadge = (
+	value: string,
+	options?: { prefix?: ReactNode; color?: BadgeColor },
+): ReactNode => (
+	<Badge color={options?.color ?? 'vanilla'} className={styles.valueBadge}>
+		{options?.prefix}
+		<span className={styles.badgeText} title={value}>
+			{value}
+		</span>
+	</Badge>
+);
+
+export const LOG_HIGHLIGHTS: LogHighlightConfig[] = [
+	{
+		key: 'service',
+		label: 'SERVICE',
+		render: (log): ReactNode | null => {
+			const value = getAttr(log, 'service.name');
+			return value
+				? valueBadge(value, {
+						prefix: <span className={styles.serviceDot} />,
+					})
+				: null;
+		},
+	},
+	{
+		key: 'severity',
+		label: 'SEVERITY',
+		render: (log): ReactNode | null => {
+			if (!log.severity_text) {
+				return null;
+			}
+			return valueBadge(log.severity_text, {
+				color: SEVERITY_COLOR[getLogIndicatorType(log)] ?? 'vanilla',
+			});
+		},
+	},
+	{
+		key: 'namespace',
+		label: 'NAMESPACE',
+		render: (log): ReactNode | null => {
+			const value = getAttr(log, 'service.namespace');
+			return value ? valueBadge(value) : null;
+		},
+	},
+	{
+		key: 'environment',
+		label: 'ENVIRONMENT',
+		render: (log): ReactNode | null => {
+			const value = getAttr(log, 'deployment.environment');
+			return value ? valueBadge(value) : null;
+		},
+	},
+	{
+		key: 'traceId',
+		label: 'TRACE ID',
+		render: (log): ReactNode | null => {
+			const traceId = log.trace_id || log.traceId;
+			return traceId ? <TraceIdField traceId={traceId} /> : null;
+		},
+	},
+	{
+		key: 'spanId',
+		label: 'SPAN ID',
+		render: (log): ReactNode | null => {
+			const spanId = log.span_id || log.spanID;
+			return spanId ? valueBadge(spanId) : null;
+		},
+	},
+];

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

@@ -115,6 +115,45 @@ describe('LogDetail drawer — header (isLogDetailsV2)', () => {
 		expect(screen.queryByText('Open in Explorer')).not.toBeInTheDocument();
 	});
 
+	it('renders Highlights for fields present on the log, omitting absent ones', () => {
+		const logWithMeta = {
+			...mockLog,
+			severity_text: 'ERROR',
+			trace_id: 'trace-abc',
+			resources_string: {
+				'service.name': 'checkout',
+				'deployment.environment': 'production',
+			},
+		} as unknown as ILog;
+
+		renderDrawer({ log: logWithMeta });
+
+		const highlights = screen.getByTestId('log-details-highlights');
+		expect(highlights).toHaveTextContent('SEVERITY');
+		expect(highlights).toHaveTextContent('ERROR');
+		expect(highlights).toHaveTextContent('SERVICE');
+		expect(highlights).toHaveTextContent('checkout');
+		expect(highlights).toHaveTextContent('ENVIRONMENT');
+		expect(highlights).toHaveTextContent('production');
+		expect(highlights).toHaveTextContent('TRACE ID');
+		// Absent fields are omitted (no namespace / span id on this log).
+		expect(highlights).not.toHaveTextContent('NAMESPACE');
+		expect(highlights).not.toHaveTextContent('SPAN ID');
+	});
+
+	it('links the trace id highlight to the trace detail in a new tab', () => {
+		const logWithTrace = {
+			...mockLog,
+			trace_id: 'trace-abc',
+		} as unknown as ILog;
+
+		renderDrawer({ log: logWithTrace });
+
+		const link = screen.getByRole('link', { name: 'trace-abc' });
+		expect(link).toHaveAttribute('target', '_blank');
+		expect(link.getAttribute('href')).toContain('/trace/trace-abc');
+	});
+
 	it('navigates to the next / previous log with the Down / Up arrow keys', async () => {
 		const user = userEvent.setup({ pointerEventsCheck: 0 });
 		const logs = [makeLog('log-0'), makeLog('log-1'), makeLog('log-2')];

frontend/src/components/LogDetail/index.tsx

@@ -55,6 +55,7 @@ import { isLogDetailsV2, RESOURCE_KEYS, VIEW_TYPES, VIEWS } from './constants';
 import { LogDetailInnerProps, LogDetailProps } from './LogDetail.interfaces';
 import LogDetailsHeader from './LogDetailsHeader/LogDetailsHeader';
 import { useLogNavigation } from './LogDetailsHeader/useLogNavigation';
+import LogHighlights from './LogHighlights/LogHighlights';
 
 import './LogDetails.styles.scss';
 
@@ -399,6 +400,8 @@ function LogDetailInner({
 					<div className="log-overflow-shadow">&nbsp;</div>
 				</div>
 
+				{isLogDetailsV2 && <LogHighlights log={log} />}
+
 				<div className="tabs-and-search">
 					<ToggleGroupSimple
 						type="single"

pkg/types/telemetrytypes/logical_field.go

@@ -0,0 +1,78 @@
+package telemetrytypes
+
+import "strings"
+
+// LogicalField is one queryable field. Its Name is the spelling that the
+// request used. Its Members are the physical keys that store the field.
+// LogicalField is the output type of name resolution: resolution changes a
+// referenced name into logical fields, and compilers make SQL from them.
+//
+// A []*LogicalField shows ambiguity. Ambiguity means that possibly different
+// fields have the same name. Each logical field in the slice gets its own
+// condition. The operator tells the compiler how to connect the conditions.
+//
+// One LogicalField with more than one member shows a semantic-convention
+// family. A family is one field that has more than one spelling. The members
+// are in current-first order. The compiler merges the members into one
+// expression, and the current name wins.
+//
+// Members always has one entry or more. A field that is not a family has
+// exactly one member. The members point to the metadata map entries. Do not
+// change the members.
+type LogicalField struct {
+	// Name is the spelling that the request used. Aliases, series labels,
+	// and warnings use this spelling. Because of this, the response shows
+	// the same spelling as the request.
+	Name string
+
+	// Signal, FieldContext, and FieldDataType are the identity that all
+	// members share. Members with a different signal, field context, or
+	// data type are parts of different logical fields.
+	Signal        Signal
+	FieldContext  FieldContext
+	FieldDataType FieldDataType
+
+	// Members are the physical keys that store this field, in current-first
+	// order. Each member has its own physical data (Materialized,
+	// Evolutions, JSONPlan, ...). A per-member accessor does not need data
+	// from the other members.
+	Members []*TelemetryFieldKey
+}
+
+// SingleLogicalField makes a logical field that has one physical key.
+func SingleLogicalField(name string, key *TelemetryFieldKey) *LogicalField {
+	return &LogicalField{
+		Name:          name,
+		Signal:        key.Signal,
+		FieldContext:  key.FieldContext,
+		FieldDataType: key.FieldDataType,
+		Members:       []*TelemetryFieldKey{key},
+	}
+}
+
+// Single returns the only member of a single-member field. A decision that
+// uses only the shared identity can also use Single on a family. This is
+// safe because all members have the same signal, context, and data type.
+func (l *LogicalField) Single() *TelemetryFieldKey {
+	return l.Members[0]
+}
+
+// IsFamily returns true when the field has more than one physical member.
+func (l *LogicalField) IsFamily() bool {
+	return len(l.Members) > 1
+}
+
+// String implements fmt.Stringer. A single-member field prints as its
+// member. Because of this, a message made from the field and a message made
+// from the key are the same. A family prints its shared identity and its
+// member spellings.
+func (l *LogicalField) String() string {
+	if len(l.Members) == 1 {
+		return l.Members[0].String()
+	}
+	names := make([]string, 0, len(l.Members))
+	for _, member := range l.Members {
+		names = append(names, member.Name)
+	}
+	return l.Name + "(" + l.FieldContext.StringValue() + ", " + l.FieldDataType.StringValue() + ", members: " + strings.Join(names, ", ") + ")"
+}

pkg/types/telemetrytypes/logical_field_test.go

@@ -0,0 +1,50 @@
+package telemetrytypes
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSingleLogicalFieldSharesIdentityAndAliasesKey(t *testing.T) {
+	key := &TelemetryFieldKey{
+		Name:          "service.name",
+		Signal:        SignalTraces,
+		FieldContext:  FieldContextResource,
+		FieldDataType: FieldDataTypeString,
+	}
+
+	logical := SingleLogicalField("resource.service.name", key)
+
+	assert.Equal(t, "resource.service.name", logical.Name, "the identity is the spelling that the request used, not the stored spelling")
+	assert.Equal(t, key.Signal, logical.Signal)
+	assert.Equal(t, key.FieldContext, logical.FieldContext)
+	assert.Equal(t, key.FieldDataType, logical.FieldDataType)
+	assert.False(t, logical.IsFamily())
+	assert.Same(t, key, logical.Single(), "the member points to the key; there is no copy")
+}
+
+func TestStringDelegatesForSingleMember(t *testing.T) {
+	key := &TelemetryFieldKey{
+		Name:          "service.name",
+		FieldContext:  FieldContextResource,
+		FieldDataType: FieldDataTypeString,
+	}
+	assert.Equal(t, key.String(), SingleLogicalField(key.Name, key).String(),
+		"a message made from a single-member field must be the same as a message made from the key")
+}
+
+func TestStringListsFamilyMembers(t *testing.T) {
+	logical := &LogicalField{
+		Name:          "deployment.environment.name",
+		Signal:        SignalTraces,
+		FieldContext:  FieldContextResource,
+		FieldDataType: FieldDataTypeString,
+		Members: []*TelemetryFieldKey{
+			{Name: "deployment.environment.name"},
+			{Name: "deployment.environment"},
+		},
+	}
+	assert.True(t, logical.IsFamily())
+	assert.Equal(t, "deployment.environment.name(resource, string, members: deployment.environment.name, deployment.environment)", logical.String())
+}