refactor(charts): trim scatter chart layer comments and dead code

Max/min decades let one outlier decide and never left linear with zeros.
Compare middle-half coverage instead, falling back to symlog.

.claude/rules/pytest.md

@@ -17,4 +17,3 @@ For the Python integration suite under `tests/`. Setup, running, and suite layou
 - **snake_case parametrize ids.** `ids=["fill_gaps", "fill_zero"]`, not camelCase.
 - **Name suite files with the two-digit prefix (`NN_*.py`).** `pyproject.toml` restricts collection to `[0-9][0-9]_*.py` (plus the bootstrap `setup.py` / `run.py`) — a file that doesn't match is silently never collected.
 - **Always run pytest from `tests/`.** `--import-mode=importlib` is what allows same-basename files across suites (`querier/01_logs.py` vs `rawexportdata/01_logs.py`), but it disables pytest's implicit `sys.path` injection — `import fixtures` only resolves via `pythonpath = ["."]` from that rootdir.
-- **After changing any `.py` file, run `make py-fmt` and `make py-lint`** from the repo root and fix what they report.

docs/api/openapi.yml

@@ -3702,6 +3702,13 @@ components:
           nullable: true
           type: number
       type: object
+    DashboardtypesAxisScale:
+      enum:
+      - auto
+      - linear
+      - log
+      - symlog
+      type: string
     DashboardtypesBarChartPanelSpec:
       properties:
         axes:
@@ -4444,6 +4451,7 @@ components:
           signoz/ListPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec'
           signoz/NumberPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec'
           signoz/PieChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec'
+          signoz/ScatterPlotPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec'
           signoz/TablePanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec'
           signoz/TextPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec'
           signoz/TimeSeriesPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec'
@@ -4459,6 +4467,7 @@ components:
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpec'
+      - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec'
       type: object
     DashboardtypesPanelPluginKind:
       enum:
@@ -4472,6 +4481,7 @@ components:
       - signoz/ListPanel
       - signoz/TextPanel
       - signoz/HeatmapPanel
+      - signoz/ScatterPlotPanel
       type: string
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec:
       properties:
@@ -4557,6 +4567,18 @@ components:
       - kind
       - spec
       type: object
+    DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec:
+      properties:
+        kind:
+          enum:
+          - signoz/ScatterPlotPanel
+          type: string
+        spec:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotPanelSpec'
+      required:
+      - kind
+      - spec
+      type: object
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec:
       properties:
         kind:
@@ -4636,6 +4658,16 @@ components:
         visualization:
           $ref: '#/components/schemas/DashboardtypesBasicVisualization'
       type: object
+    DashboardtypesPointDiameter:
+      maximum: 40
+      minimum: 2
+      nullable: true
+      type: integer
+    DashboardtypesPointOpacity:
+      maximum: 1
+      minimum: 0.1
+      nullable: true
+      type: number
     DashboardtypesPostableDashboardV2:
       properties:
         generateName:
@@ -4824,6 +4856,104 @@ components:
       required:
       - queryValue
       type: object
+    DashboardtypesScatterPlotAxes:
+      properties:
+        x:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotAxis'
+        "y":
+          $ref: '#/components/schemas/DashboardtypesScatterPlotAxis'
+      type: object
+    DashboardtypesScatterPlotAxis:
+      properties:
+        label:
+          description: Axis title. Empty draws none.
+          type: string
+        scale:
+          $ref: '#/components/schemas/DashboardtypesAxisScale'
+        softMax:
+          nullable: true
+          type: number
+        softMin:
+          nullable: true
+          type: number
+      type: object
+    DashboardtypesScatterPlotChartAppearance:
+      properties:
+        points:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotPoints'
+      type: object
+    DashboardtypesScatterPlotDimensions:
+      properties:
+        colorBy:
+          description: Group-by label names (e.g. k8s.namespace.name) whose combined
+            values colour dots and drive the legend. Empty colours by every group-by
+            label.
+          items:
+            type: string
+          nullable: true
+          type: array
+        sizeBy:
+          description: Value column key that scales dot size. Empty draws every dot
+            at the default size.
+          type: string
+        x:
+          description: Value column key (queryName, or queryName.expression for a
+            multi-aggregation query) plotted on the x axis. Empty uses the first value
+            column.
+          type: string
+        "y":
+          description: Value column key plotted on the y axis. Empty uses the second
+            value column.
+          type: string
+      type: object
+    DashboardtypesScatterPlotPanelSpec:
+      properties:
+        axes:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotAxes'
+        chartAppearance:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotChartAppearance'
+        dimensions:
+          $ref: '#/components/schemas/DashboardtypesScatterPlotDimensions'
+        formatting:
+          $ref: '#/components/schemas/DashboardtypesTableFormatting'
+        legend:
+          $ref: '#/components/schemas/DashboardtypesLegend'
+        thresholds:
+          items:
+            $ref: '#/components/schemas/DashboardtypesScatterPlotThreshold'
+          nullable: true
+          type: array
+        visualization:
+          $ref: '#/components/schemas/DashboardtypesBasicVisualization'
+      type: object
+    DashboardtypesScatterPlotPoints:
+      properties:
+        maxSize:
+          $ref: '#/components/schemas/DashboardtypesPointDiameter'
+        minSize:
+          $ref: '#/components/schemas/DashboardtypesPointDiameter'
+        opacity:
+          $ref: '#/components/schemas/DashboardtypesPointOpacity'
+        size:
+          $ref: '#/components/schemas/DashboardtypesPointDiameter'
+      type: object
+    DashboardtypesScatterPlotThreshold:
+      properties:
+        axis:
+          $ref: '#/components/schemas/DashboardtypesThresholdAxis'
+        color:
+          type: string
+        label:
+          type: string
+        unit:
+          type: string
+        value:
+          format: double
+          type: number
+      required:
+      - value
+      - color
+      type: object
     DashboardtypesSource:
       enum:
       - user
@@ -4937,6 +5067,11 @@ components:
       - value
       - name
       type: object
+    DashboardtypesThresholdAxis:
+      enum:
+      - x
+      - "y"
+      type: string
     DashboardtypesThresholdFormat:
       enum:
       - text
@@ -16440,12 +16575,12 @@ paths:
   /api/v1/traces/{traceID}/thread:
     get:
       deprecated: false
-      description: Returns the gen_ai spans of a trace, model calls, tool calls and
-        agent spans, in timestamp order. The messages a span carries are decoded into
-        formatted_input and formatted_output, with formatter naming the converter
-        and formatter_warnings what it could not resolve; a span without messages
-        has both empty. Pass nextCursor as after or prevCursor as before to page,
-        or spanId to open the page around a span.
+      description: Returns the spans carrying gen_ai input or output messages, or
+        a tool execution, in timestamp order. Messages already in the OTel GenAI shape
+        are decoded into formatted_input and formatted_output, with formatter naming
+        the converter and formatter_warnings what it could not resolve. Pass nextCursor
+        as after or prevCursor as before to page, or spanId to open the page around
+        a span.
       operationId: GetTraceThread
       parameters:
       - description: Page size, at most 100. 0 means 20.

frontend/__mocks__/uplotMock.ts

@@ -57,6 +57,7 @@ const mockPaths = {
 const mockTzDate = jest.fn(
 	(date: Date, _timezone: string) => new Date(date.getTime()),
 );
+const mockOrient = jest.fn();
 
 // Mock uPlot constructor - this needs to be a proper constructor function
 function MockUPlot(
@@ -70,6 +71,7 @@ function MockUPlot(
 // Add static methods to the constructor
 MockUPlot.tzDate = mockTzDate;
 MockUPlot.paths = mockPaths;
+MockUPlot.orient = mockOrient;
 // Pinned so canvas-space maths in draw hooks is deterministic under jsdom.
 MockUPlot.pxRatio = 1;
 

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

@@ -261,7 +261,7 @@ export const invalidateGetTraceSummary = async (
 };
 
 /**
- * Returns the gen_ai spans of a trace, model calls, tool calls and agent spans, in timestamp order. The messages a span carries are decoded into formatted_input and formatted_output, with formatter naming the converter and formatter_warnings what it could not resolve; a span without messages has both empty. Pass nextCursor as after or prevCursor as before to page, or spanId to open the page around a span.
+ * Returns the spans carrying gen_ai input or output messages, or a tool execution, in timestamp order. Messages already in the OTel GenAI shape are decoded into formatted_input and formatted_output, with formatter naming the converter and formatter_warnings what it could not resolve. 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 = (

frontend/src/lib/uPlotV2/components/Tooltip/ScatterTooltip.module.scss

@@ -0,0 +1,98 @@
+// Sections own the padding so the footer spans edge to edge.
+.container {
+	font-family: 'Inter';
+	font-size: 12px;
+	background: var(--l2-background);
+	-webkit-font-smoothing: antialiased;
+	color: var(--l2-foreground);
+	border-radius: 6px;
+	border: 1px solid var(--l2-border);
+	display: flex;
+	flex-direction: column;
+	min-width: 200px;
+
+	&.pinned {
+		border-color: var(--ring);
+	}
+}
+
+.divider {
+	display: block;
+	width: 100%;
+	height: 1px;
+	background-color: var(--l2-border);
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-2);
+	padding: var(--spacing-3) var(--spacing-4);
+}
+
+// Matches the legend row's marker.
+.marker {
+	width: 10px;
+	height: 10px;
+	border-radius: var(--radius);
+	flex-shrink: 0;
+}
+
+.title {
+	flex: 1;
+	min-width: 0;
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	font-weight: 600;
+	color: var(--text-vanilla-100);
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.status {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-1);
+	font-size: 11px;
+	color: var(--text-vanilla-400);
+	flex-shrink: 0;
+}
+
+.rows {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-1);
+	padding: var(--spacing-3) var(--spacing-4);
+}
+
+.row {
+	display: flex;
+	align-items: baseline;
+	justify-content: space-between;
+	gap: var(--spacing-4);
+	font-family: var(--font-mono);
+	font-size: var(--font-size-xs);
+	font-variant-numeric: tabular-nums;
+	color: var(--text-vanilla-100);
+}
+
+.rowMuted {
+	color: var(--text-vanilla-400);
+}
+
+.rowLabel {
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.rowValue {
+	flex: 0 0 auto;
+	max-width: 60%;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}

frontend/src/lib/uPlotV2/components/Tooltip/ScatterTooltip.tsx

@@ -0,0 +1,107 @@
+import { useMemo } from 'react';
+import cx from 'classnames';
+import { Pin } from '@signozhq/icons';
+
+import { ScatterTooltipProps } from '../types';
+import { buildChannelRows, resolveHoveredPoint } from './scatterTooltipContent';
+
+import Styles from './ScatterTooltip.module.scss';
+
+/** Own component: the shared Tooltip lists one row per series at a shared x. */
+export default function ScatterTooltip({
+	uPlotInstance,
+	dataIndexes,
+	seriesIndex,
+	channels,
+	resolvePointLabels,
+	decimalPrecision,
+	isPinned,
+	dismiss,
+	renderTooltipFooter,
+}: ScatterTooltipProps): JSX.Element | null {
+	const point = useMemo(
+		() => resolveHoveredPoint(uPlotInstance, seriesIndex, dataIndexes),
+		[uPlotInstance, seriesIndex, dataIndexes],
+	);
+
+	const rows = useMemo(
+		() => (point ? buildChannelRows(point, channels, decimalPrecision) : []),
+		[point, channels, decimalPrecision],
+	);
+
+	const labels = useMemo(
+		() =>
+			point
+				? (resolvePointLabels?.(point.seriesIndex, point.dataIndex) ?? [])
+				: [],
+		[point, resolvePointLabels],
+	);
+
+	if (!point) {
+		return null;
+	}
+
+	return (
+		<div
+			className={cx(Styles.container, { [Styles.pinned]: isPinned })}
+			data-pinned={isPinned}
+			data-testid="scatter-tooltip"
+		>
+			<div className={Styles.header}>
+				<span className={Styles.marker} style={{ backgroundColor: point.color }} />
+				<span
+					className={Styles.title}
+					title={point.label}
+					data-testid="scatter-tooltip-title"
+				>
+					{point.label}
+				</span>
+				{isPinned && (
+					<span className={Styles.status} data-testid="scatter-tooltip-status">
+						<Pin size={12} />
+						<span>Pinned</span>
+					</span>
+				)}
+			</div>
+
+			<span className={Styles.divider} />
+
+			<div className={Styles.rows}>
+				{rows.map((row) => (
+					<div
+						key={row.label}
+						className={Styles.row}
+						data-testid="scatter-tooltip-row"
+					>
+						<span className={Styles.rowLabel}>{row.label}</span>
+						<span className={Styles.rowValue}>{row.value}</span>
+					</div>
+				))}
+			</div>
+
+			{labels.length > 0 && (
+				<>
+					<span className={Styles.divider} />
+					<div className={Styles.rows}>
+						{labels.map((label) => (
+							<div
+								key={label.key}
+								className={cx(Styles.row, Styles.rowMuted)}
+								data-testid="scatter-tooltip-label"
+							>
+								<span className={Styles.rowLabel} title={label.key}>
+									{label.key}
+								</span>
+								<span className={Styles.rowValue} title={label.value}>
+									{label.value}
+								</span>
+							</div>
+						))}
+					</div>
+				</>
+			)}
+
+			{renderTooltipFooter?.({ isPinned, dismiss })}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/__tests__/scatterTooltipContent.test.ts

@@ -0,0 +1,94 @@
+import type uPlot from 'uplot';
+
+import {
+	buildChannelRows,
+	resolveHoveredPoint,
+	ScatterHoveredPoint,
+} from '../scatterTooltipContent';
+
+jest.mock('components/Graph/yAxisConfig', () => ({
+	getToolTipValue: jest.fn((value: number | string, unit?: string) =>
+		`${value} ${unit ?? ''}`.trim(),
+	),
+}));
+
+const plot = {
+	data: [
+		null,
+		[
+			[10, 20],
+			[100, 200],
+			[5, null],
+		],
+		[[30], [300]],
+	],
+	series: [
+		{},
+		{ label: 'cart', stroke: '#ff0000' },
+		{ label: 'checkout', stroke: (): string => '#00ff00' },
+	],
+} as unknown as uPlot;
+
+describe('resolveHoveredPoint', () => {
+	it('reads the focused series at its own data index', () => {
+		expect(resolveHoveredPoint(plot, 1, [null, 1, null])).toStrictEqual({
+			seriesIndex: 1,
+			dataIndex: 1,
+			label: 'cart',
+			color: '#ff0000',
+			x: 20,
+			y: 200,
+			size: null,
+		});
+	});
+
+	it('carries the size column when present and resolves function strokes', () => {
+		expect(resolveHoveredPoint(plot, 1, [null, 0, null])?.size).toBe(5);
+		expect(resolveHoveredPoint(plot, 2, [null, null, 0])).toMatchObject({
+			label: 'checkout',
+			color: '#00ff00',
+			size: null,
+		});
+	});
+
+	it('is null without a focused series or an index for it', () => {
+		expect(resolveHoveredPoint(plot, null, [null, 0, null])).toBeNull();
+		expect(resolveHoveredPoint(plot, 0, [0, 0, null])).toBeNull();
+		expect(resolveHoveredPoint(plot, 1, [null, null, null])).toBeNull();
+	});
+});
+
+describe('buildChannelRows', () => {
+	const point: ScatterHoveredPoint = {
+		seriesIndex: 1,
+		dataIndex: 0,
+		label: 'cart',
+		color: '#f00',
+		x: 12,
+		y: 340,
+		size: 7,
+	};
+
+	it('formats x and y with their own units', () => {
+		const rows = buildChannelRows(point, {
+			x: { label: 'Throughput', unit: 'reqps' },
+			y: { label: 'p99', unit: 'ms' },
+		});
+
+		expect(rows).toStrictEqual([
+			{ label: 'Throughput', value: '12 reqps' },
+			{ label: 'p99', value: '340 ms' },
+		]);
+	});
+
+	it('adds the size row only when the channel is mapped and the point has one', () => {
+		const channels = {
+			x: { label: 'x' },
+			y: { label: 'y' },
+			size: { label: 'Errors' },
+		};
+
+		expect(buildChannelRows(point, channels)).toHaveLength(3);
+		expect(buildChannelRows({ ...point, size: null }, channels)).toHaveLength(2);
+	});
+});

frontend/src/lib/uPlotV2/components/Tooltip/scatterTooltipContent.ts

@@ -0,0 +1,89 @@
+import { PrecisionOption } from 'components/Graph/types';
+import { getToolTipValue } from 'components/Graph/yAxisConfig';
+import type uPlot from 'uplot';
+
+import type {
+	ScatterChannel,
+	ScatterChannels,
+	ScatterSeriesData,
+} from '../../plugins/ScatterPlugin/types';
+import { resolveSeriesColor } from './utils';
+
+export interface ScatterHoveredPoint {
+	seriesIndex: number;
+	dataIndex: number;
+	label: string;
+	color: string;
+	x: number;
+	y: number;
+	size: number | null;
+}
+
+export interface ScatterTooltipRow {
+	label: string;
+	value: string;
+}
+
+export function resolveHoveredPoint(
+	u: uPlot,
+	seriesIndex: number | null,
+	dataIndexes: Array<number | null>,
+): ScatterHoveredPoint | null {
+	if (seriesIndex == null || seriesIndex < 1) {
+		return null;
+	}
+	const dataIndex = dataIndexes[seriesIndex];
+	const series = u.series[seriesIndex];
+	const columns = u.data[seriesIndex] as unknown as
+		| ScatterSeriesData
+		| undefined;
+	if (dataIndex == null || !series || !columns) {
+		return null;
+	}
+	const x = columns[0][dataIndex];
+	const y = columns[1][dataIndex];
+	if (x == null || y == null) {
+		return null;
+	}
+	return {
+		seriesIndex,
+		dataIndex,
+		label: String(series.label ?? ''),
+		color: resolveSeriesColor(series.stroke, u, seriesIndex),
+		x,
+		y,
+		size: columns[2]?.[dataIndex] ?? null,
+	};
+}
+
+function formatChannel(
+	value: number,
+	channel: ScatterChannel,
+	decimalPrecision?: PrecisionOption,
+): string {
+	return getToolTipValue(value, channel.unit, decimalPrecision);
+}
+
+export function buildChannelRows(
+	point: ScatterHoveredPoint,
+	channels: ScatterChannels,
+	decimalPrecision?: PrecisionOption,
+): ScatterTooltipRow[] {
+	const rows: ScatterTooltipRow[] = [
+		{
+			label: channels.x.label,
+			value: formatChannel(point.x, channels.x, decimalPrecision),
+		},
+		{
+			label: channels.y.label,
+			value: formatChannel(point.y, channels.y, decimalPrecision),
+		},
+	];
+	if (channels.size && point.size != null) {
+		rows.push({
+			label: channels.size.label,
+			value: formatChannel(point.size, channels.size, decimalPrecision),
+		});
+	}
+	return rows;
+}

frontend/src/lib/uPlotV2/components/types.ts

@@ -6,6 +6,10 @@ import uPlot from 'uplot';
 import { UPlotConfigBuilder } from '../config/UPlotConfigBuilder';
 import { LegendItem } from '../config/types';
 import { HeatmapSeries, HeatmapYAxis } from '../plugins/HeatmapPlugin/types';
+import type {
+	ScatterChannels,
+	ScatterPointLabel,
+} from '../plugins/ScatterPlugin/types';
 import { SyncTooltipFilterMode } from '../plugins/TooltipPlugin/types';
 
 /**
@@ -119,6 +123,16 @@ export interface HeatmapTooltipProps
 	groupColor: string;
 }
 
+export interface ScatterTooltipProps
+	extends BaseTooltipProps, TooltipRenderArgs {
+	channels: ScatterChannels;
+	/** The group values behind a point, e.g. `service.name` → `cart`. */
+	resolvePointLabels?: (
+		seriesIndex: number,
+		dataIndex: number,
+	) => ScatterPointLabel[];
+}
+
 export type TooltipProps =
 	| TimeSeriesTooltipProps
 	| BarTooltipProps

frontend/src/lib/uPlotV2/config/UPlotAxisBuilder.ts

@@ -39,6 +39,16 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		};
 	}
 
+	/** Styled like the grid. */
+	private buildBorderConfig(
+		grid: uPlot.Axis.Grid | undefined,
+	): uPlot.Axis.Border | undefined {
+		if (this.props.showBorder === false || !grid || grid.show === false) {
+			return undefined;
+		}
+		return { show: true, stroke: grid.stroke, width: grid.width };
+	}
+
 	/**
 	 * Build ticks configuration
 	 */
@@ -57,33 +67,43 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		};
 	}
 
-	/**
-	 * Build values formatter for X-axis (time)
-	 */
+	/** Time ticks, or unit-formatted values when a unit/precision is set. */
 	private buildXAxisValuesFormatter(): uPlot.Axis.Values | undefined {
-		const { isTimeAxis } = this.props;
+		const { isTimeAxis, yAxisUnit, decimalPrecision } = this.props;
 
 		if (isTimeAxis) {
 			return uPlotXAxisValuesFormat as uPlot.Axis.Values;
 		}
 
+		if (yAxisUnit !== undefined || decimalPrecision !== undefined) {
+			return this.buildValueAxisFormatter();
+		}
+
 		return undefined;
 	}
 
-	/**
-	 * Build values formatter for Y-axis (values with units)
-	 */
-	private buildYAxisValuesFormatter(): uPlot.Axis.Values {
-		const { yAxisUnit, decimalPrecision } = this.props;
+	/** Blanks splits outside the scale; uPlot's asinh splits always include ±threshold. */
+	private buildValueAxisFormatter(): uPlot.Axis.Values {
+		const { yAxisUnit, decimalPrecision, scaleKey } = this.props;
 
-		return (_, t): string[] =>
-			t.map((v) => {
-				if (v === null || v === undefined || Number.isNaN(v)) {
+		return (u, t): string[] => {
+			const scale = u?.scales?.[scaleKey];
+			const min = scale?.min ?? -Infinity;
+			const max = scale?.max ?? Infinity;
+			return t.map((v) => {
+				if (
+					v === null ||
+					v === undefined ||
+					Number.isNaN(v) ||
+					v < min ||
+					v > max
+				) {
 					return '';
 				}
 				const value = getToolTipValue(v.toString(), yAxisUnit, decimalPrecision);
 				return `${value}`;
 			});
+		};
 	}
 
 	/**
@@ -101,7 +121,7 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		return scaleKey === 'x'
 			? this.buildXAxisValuesFormatter()
 			: scaleKey === 'y'
-				? this.buildYAxisValuesFormatter()
+				? this.buildValueAxisFormatter()
 				: undefined;
 	}
 
@@ -149,10 +169,12 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 			side = 2, // bottom by default
 			space,
 			splits,
+			filter,
 			gap = 5, // default gap is 5
 		} = this.props;
 
 		const grid = this.buildGridConfig();
+		const border = this.buildBorderConfig(grid);
 		const ticks = this.buildTicksConfig();
 		const values = this.buildValuesFormatter();
 		const size = this.buildSizeCalculator();
@@ -177,6 +199,9 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		if (ticks) {
 			axisConfig.ticks = ticks;
 		}
+		if (border) {
+			axisConfig.border = border;
+		}
 		if (values) {
 			axisConfig.values = values;
 		}
@@ -189,6 +214,9 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		if (space !== undefined) {
 			axisConfig.space = space;
 		}
+		if (filter) {
+			axisConfig.filter = filter;
+		}
 		if (size) {
 			axisConfig.size = size;
 		}

frontend/src/lib/uPlotV2/config/UPlotConfigBuilder.ts

@@ -19,6 +19,7 @@ import {
 	ConfigBuilder,
 	ConfigBuilderProps,
 	LegendItem,
+	PlotMode,
 	SelectionPreferencesSource,
 	StackMode,
 } from './types';
@@ -65,6 +66,8 @@ export class UPlotConfigBuilder extends ConfigBuilder<
 
 	private stackMode: StackMode = StackMode.None;
 
+	private mode: PlotMode = PlotMode.Aligned;
+
 	private cursor: Cursor | undefined;
 
 	private hooks: Hooks.Arrays = {};
@@ -160,6 +163,10 @@ export class UPlotConfigBuilder extends ConfigBuilder<
 		return this.stackMode;
 	}
 
+	setMode(mode: PlotMode): void {
+		this.mode = mode;
+	}
+
 	/**
 	 * Add or merge a scale configuration
 	 */
@@ -512,6 +519,10 @@ export class UPlotConfigBuilder extends ConfigBuilder<
 			{} as Record<string, uPlot.Scale>,
 		);
 
+		if (this.mode === PlotMode.Faceted) {
+			config.mode = this.mode as number as uPlot.Mode;
+		}
+
 		config.hooks = this.hooks;
 		config.select = this.select;
 

frontend/src/lib/uPlotV2/config/UPlotScaleBuilder.ts

@@ -40,6 +40,7 @@ export class UPlotScaleBuilder extends ConfigBuilder<
 			range,
 			thresholds,
 			logBase = 10,
+			asinhThreshold,
 			padMinBy = 0,
 			padMaxBy = 0.05,
 		} = this.props;
@@ -99,6 +100,7 @@ export class UPlotScaleBuilder extends ConfigBuilder<
 			time,
 			distr,
 			logBase,
+			asinhThreshold,
 		});
 
 		const { rangeConfig, hardMinOnly, hardMaxOnly, hasFixedRange } =

frontend/src/lib/uPlotV2/config/UPlotSeriesBuilder.ts

@@ -87,6 +87,8 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 			lineConfig.fill = finalFillColor;
 		} else if (this.props.drawStyle === DrawStyle.Histogram) {
 			lineConfig.fill = `${finalFillColor}40`;
+		} else if (this.props.drawStyle === DrawStyle.Scatter) {
+			lineConfig.fill = `${finalFillColor}${toAlphaHex(resolveFillOpacity(fillOpacity))}`;
 		} else if (fillMode && fillMode !== FillMode.None) {
 			const resolvedOpacity = resolveFillOpacity(fillOpacity);
 			if (fillMode === FillMode.Solid) {
@@ -122,7 +124,7 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 			return { paths: pathBuilder };
 		}
 
-		if (drawStyle === DrawStyle.Points) {
+		if (drawStyle === DrawStyle.Points || drawStyle === DrawStyle.Scatter) {
 			return { paths: (): null => null };
 		}
 
@@ -194,6 +196,10 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 		if (drawStyle === DrawStyle.Points) {
 			return true;
 		}
+		// The discs are the series path; uPlot's own points would double-draw them.
+		if (drawStyle === DrawStyle.Scatter) {
+			return false;
+		}
 		return !!showPoints;
 	}
 
@@ -218,7 +224,7 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 	}
 
 	getConfig(): ExtendedSeries {
-		const { scaleKey, label, spanGaps, show = true, metric } = this.props;
+		const { scaleKey, label, spanGaps, show = true, metric, facets } = this.props;
 
 		const resolvedLineColor = this.getLineColor();
 
@@ -246,6 +252,7 @@ export class UPlotSeriesBuilder extends ConfigBuilder<
 			...pathConfig,
 			points: Object.keys(pointsConfig).length > 0 ? pointsConfig : undefined,
 			metric,
+			...(facets && { facets }),
 		};
 	}
 }

frontend/src/lib/uPlotV2/config/__tests__/UPlotAxisBuilder.test.ts

@@ -120,6 +120,41 @@ describe('UPlotAxisBuilder', () => {
 		});
 	});
 
+	it('draws the axis line by default, styled like the grid', () => {
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ isDarkMode: true, grid: { width: 0.5 } }),
+		).getConfig();
+
+		expect(config.border).toStrictEqual({
+			show: true,
+			stroke: config.grid?.stroke,
+			width: 0.5,
+		});
+	});
+
+	it('leaves the axis line off when showBorder is false', () => {
+		expect(
+			new UPlotAxisBuilder(createAxisProps({ showBorder: false })).getConfig(),
+		).not.toHaveProperty('border');
+	});
+
+	it('leaves the axis line off when the grid is hidden', () => {
+		expect(
+			new UPlotAxisBuilder(createAxisProps({ grid: { show: false } })).getConfig(),
+		).not.toHaveProperty('border');
+	});
+
+	it('passes explicit splits and a label filter through to uPlot', () => {
+		const splits = jest.fn();
+		const filter = jest.fn();
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ splits, filter }),
+		).getConfig();
+
+		expect(config.splits).toBe(splits);
+		expect(config.filter).toBe(filter);
+	});
+
 	it('uses provided ticks config when present and falls back to defaults otherwise', () => {
 		const customTicks = { width: 1, show: false };
 		const withTicks = new UPlotAxisBuilder(
@@ -376,3 +411,51 @@ describe('UPlotAxisBuilder', () => {
 		expect(config.values).toBeDefined();
 	});
 });
+
+describe('UPlotAxisBuilder value x axis', () => {
+	it('formats a non-time x axis with its unit', () => {
+		(getToolTipValue as jest.Mock).mockReturnValue('1.2K req/s');
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ scaleKey: 'x', isTimeAxis: false, yAxisUnit: 'reqps' }),
+		).getConfig();
+
+		const values = (config.values as uPlot.Axis.DynamicValues)(
+			{} as uPlot,
+			[1200],
+			0,
+			0,
+			0,
+		);
+
+		expect(values).toStrictEqual(['1.2K req/s']);
+		expect(getToolTipValue).toHaveBeenCalledWith('1200', 'reqps', undefined);
+	});
+
+	it('leaves a non-time x axis to uPlot when nothing says how to format it', () => {
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ scaleKey: 'x', isTimeAxis: false }),
+		).getConfig();
+
+		expect(config.values).toBeUndefined();
+	});
+});
+
+describe('UPlotAxisBuilder out-of-range splits', () => {
+	it('leaves a split the scale cannot place unlabelled', () => {
+		(getToolTipValue as jest.Mock).mockImplementation((v: string) => `${v} ms`);
+		const config = new UPlotAxisBuilder(
+			createAxisProps({ scaleKey: 'y', yAxisUnit: 'ms' }),
+		).getConfig();
+		const u = { scales: { y: { min: 0, max: 1000 } } } as unknown as uPlot;
+
+		const values = (config.values as uPlot.Axis.DynamicValues)(
+			u,
+			[-10, 0, 500, 5000],
+			0,
+			0,
+			0,
+		);
+
+		expect(values).toStrictEqual(['', '0 ms', '500 ms', '']);
+	});
+});

frontend/src/lib/uPlotV2/config/__tests__/UPlotConfigBuilder.test.ts

@@ -5,7 +5,12 @@ import {
 	STEP_INTERVAL_MULTIPLIER,
 } from '../../constants';
 import type { SeriesProps } from '../types';
-import { DrawStyle, SelectionPreferencesSource, StackMode } from '../types';
+import {
+	DrawStyle,
+	PlotMode,
+	SelectionPreferencesSource,
+	StackMode,
+} from '../types';
 import { UPlotConfigBuilder } from '../UPlotConfigBuilder';
 
 // Mock only the real boundary that hits localStorage
@@ -651,3 +656,14 @@ describe('UPlotConfigBuilder stacking', () => {
 		expect(builder.getConfig().bands).toStrictEqual([{ series: [1, 3] }]);
 	});
 });
+
+describe('UPlotConfigBuilder plot mode', () => {
+	it('leaves mode unset for aligned data and emits 2 when faceted', () => {
+		const aligned = new UPlotConfigBuilder({ id: 'aligned' });
+		expect(aligned.getConfig().mode).toBeUndefined();
+
+		const faceted = new UPlotConfigBuilder({ id: 'faceted' });
+		faceted.setMode(PlotMode.Faceted);
+		expect(faceted.getConfig().mode).toBe(2);
+	});
+});

frontend/src/lib/uPlotV2/config/__tests__/UPlotSeriesBuilder.test.ts

@@ -399,3 +399,39 @@ describe('UPlotSeriesBuilder', () => {
 		expect(builder.getConfig().fill).toBeUndefined();
 	});
 });
+
+describe('UPlotSeriesBuilder scatter', () => {
+	it('draws through the given path builder and hides uPlot points', () => {
+		const pathBuilder = jest.fn();
+		const config = new UPlotSeriesBuilder(
+			createBaseProps({
+				drawStyle: DrawStyle.Scatter,
+				pathBuilder,
+				facets: [{ scale: 'x' }, { scale: 'y' }],
+				lineColor: '#ff0000',
+				fillOpacity: 0.5,
+				lineWidth: 1,
+				pointSize: 8,
+			}),
+		).getConfig();
+
+		expect(config.paths).toBe(pathBuilder);
+		expect(config.facets).toStrictEqual([{ scale: 'x' }, { scale: 'y' }]);
+		expect(config.points?.show).toBe(false);
+		expect(config.points?.size).toBe(8);
+		expect(config.stroke).toBe('#ff0000');
+		expect(config.width).toBe(1);
+		expect(config.fill).toBe('#ff000080');
+	});
+
+	it('draws nothing without a path builder', () => {
+		const config = new UPlotSeriesBuilder(
+			createBaseProps({ drawStyle: DrawStyle.Scatter }),
+		).getConfig();
+
+		expect(
+			(config.paths as uPlot.Series.PathBuilder)({} as uPlot, 1, 0, 0),
+		).toBeNull();
+		expect(config.facets).toBeUndefined();
+	});
+});

frontend/src/lib/uPlotV2/config/types.ts

@@ -78,8 +78,12 @@ export interface AxisProps {
 	};
 	/** Explicit tick formatter, replacing the scale's default (time / unit-formatted). */
 	values?: uPlot.Axis.Values;
-	/** Explicit axis splits, overriding the default tick calculation. */
+	/** Explicit tick positions, replacing uPlot's per-distribution default. */
 	splits?: uPlot.Axis.Splits;
+	/** Which splits get a label, replacing uPlot's per-distribution default. */
+	filter?: uPlot.Axis.Filter;
+	/** Draw the axis line along the plot edge, styled like the grid. Default true. */
+	showBorder?: boolean;
 	/** Pixels between the ticks and their labels; also feeds the y axis width calculation. */
 	gap?: number;
 	/** Explicit axis thickness. Left unset, the y axis sizes itself to its widest label. */
@@ -90,7 +94,7 @@ export interface AxisProps {
 	isDarkMode?: boolean;
 	/** Axis is on a log scale — thins the grid lines to keep dense decades readable. */
 	isLogScale?: boolean;
-	/** Unit the y axis ticks are formatted in (`spec.formatting.unit`). */
+	/** Unit the value ticks are formatted in (`spec.formatting.unit`); a non-time x axis reads it too. */
 	yAxisUnit?: string;
 	/**
 	 * X axis carries timestamps, so its ticks format as dates/times. Declared by the caller
@@ -109,6 +113,14 @@ export interface AxisProps {
 export enum DistributionType {
 	Linear = 'linear',
 	Logarithmic = 'logarithmic',
+	/** arcsinh: linear within ±`asinhThreshold`, log beyond; places zero and negatives. */
+	SymmetricLog = 'symlog',
+}
+
+/** uPlot's data layout: one shared x per chart, or per-series x/y columns. */
+export enum PlotMode {
+	Aligned = 1,
+	Faceted = 2,
 }
 
 export interface ScaleProps {
@@ -125,6 +137,8 @@ export interface ScaleProps {
 	auto?: boolean;
 	logBase?: uPlot.Scale.LogBase;
 	distribution?: DistributionType;
+	/** Half-width of a `SymmetricLog` scale's linear band around zero. Default 1. */
+	asinhThreshold?: number;
 }
 
 export enum DisconnectedValuesMode {
@@ -146,6 +160,8 @@ export enum DrawStyle {
 	Points = 'points',
 	Bar = 'bar',
 	Histogram = 'histogram',
+	/** Mode 2; drawn by the caller's `pathBuilder`. */
+	Scatter = 'scatter',
 }
 
 export enum LineInterpolation {
@@ -229,6 +245,8 @@ export interface SeriesProps extends LineConfig, PointsConfig, BarConfig {
 	isDarkMode?: boolean;
 	stepInterval?: number;
 	metric?: { [key: string]: string };
+	/** Mode 2 only: the scales the series' own x and y columns are read against. */
+	facets?: Series.Facet[];
 }
 
 export interface LegendItem {

frontend/src/lib/uPlotV2/plugins/ScatterPlugin/__tests__/geometry.test.ts

@@ -0,0 +1,114 @@
+import type uPlot from 'uplot';
+
+import { Quadtree } from '../../../utils/quadtree';
+import {
+	resolveHit,
+	resolvePointDiameter,
+	resolveSizeDomain,
+} from '../geometry';
+import { ScatterHit, ScatterPointSize } from '../types';
+
+const POINT_SIZE: ScatterPointSize = { fixed: 6, min: 4, max: 20 };
+
+const asData = (columns: unknown[]): uPlot.AlignedData =>
+	columns as unknown as uPlot.AlignedData;
+
+describe('resolveSizeDomain', () => {
+	it('spans the size columns of every series, skipping nulls', () => {
+		const data = asData([
+			null,
+			[
+				[1, 2],
+				[1, 2],
+				[10, null],
+			],
+			[[3], [3], [40]],
+		]);
+
+		expect(resolveSizeDomain(data)).toStrictEqual({ min: 10, max: 40 });
+	});
+
+	it('is null when no series carries sizes', () => {
+		expect(resolveSizeDomain(asData([null, [[1], [1]]]))).toBeNull();
+		expect(resolveSizeDomain(asData([null, [[1], [1], [null]]]))).toBeNull();
+	});
+});
+
+describe('resolvePointDiameter', () => {
+	it('uses the fixed diameter without a size or a domain', () => {
+		expect(resolvePointDiameter(null, { min: 0, max: 10 }, POINT_SIZE)).toBe(6);
+		expect(resolvePointDiameter(5, null, POINT_SIZE)).toBe(6);
+	});
+
+	it('maps the domain ends to min and max', () => {
+		const domain = { min: 0, max: 100 };
+		expect(resolvePointDiameter(0, domain, POINT_SIZE)).toBe(4);
+		expect(resolvePointDiameter(100, domain, POINT_SIZE)).toBe(20);
+	});
+
+	it('scales by area, not diameter', () => {
+		const midArea = (4 ** 2 + 20 ** 2) / 2;
+		expect(
+			resolvePointDiameter(50, { min: 0, max: 100 }, POINT_SIZE),
+		).toBeCloseTo(Math.sqrt(midArea));
+	});
+
+	it('clamps values outside the domain', () => {
+		const domain = { min: 10, max: 20 };
+		expect(resolvePointDiameter(-5, domain, POINT_SIZE)).toBe(4);
+		expect(resolvePointDiameter(500, domain, POINT_SIZE)).toBe(20);
+	});
+
+	it('uses the midpoint when every size is the same', () => {
+		expect(resolvePointDiameter(7, { min: 7, max: 7 }, POINT_SIZE)).toBe(12);
+	});
+});
+
+describe('resolveHit', () => {
+	const hit = (
+		seriesIndex: number,
+		dataIndex: number,
+		x: number,
+		y: number,
+		d: number,
+	): ScatterHit => ({ seriesIndex, dataIndex, x, y, w: d, h: d });
+
+	it('returns the disc under the cursor', () => {
+		const tree = new Quadtree<ScatterHit>(0, 0, 100, 100);
+		tree.add(hit(1, 0, 10, 10, 6));
+		tree.add(hit(2, 3, 50, 50, 6));
+
+		expect(resolveHit(tree, 13, 13, 0)).toMatchObject({
+			seriesIndex: 1,
+			dataIndex: 0,
+		});
+		expect(resolveHit(tree, 52, 52, 0)).toMatchObject({
+			seriesIndex: 2,
+			dataIndex: 3,
+		});
+	});
+
+	it('is null when the cursor is off every disc', () => {
+		const tree = new Quadtree<ScatterHit>(0, 0, 100, 100);
+		tree.add(hit(1, 0, 10, 10, 6));
+
+		expect(resolveHit(tree, 30, 30, 0)).toBeNull();
+	});
+
+	it('tolerance widens each disc', () => {
+		const tree = new Quadtree<ScatterHit>(0, 0, 100, 100);
+		tree.add(hit(1, 0, 10, 10, 6));
+
+		expect(resolveHit(tree, 18, 13, 0)).toBeNull();
+		expect(resolveHit(tree, 18, 13, 3)).not.toBeNull();
+	});
+
+	it('prefers the disc whose centre is nearest when they overlap', () => {
+		const tree = new Quadtree<ScatterHit>(0, 0, 100, 100);
+		tree.add(hit(1, 0, 10, 10, 10));
+		tree.add(hit(1, 1, 14, 10, 10));
+
+		expect(resolveHit(tree, 13, 15, 0)?.dataIndex).toBe(0);
+		expect(resolveHit(tree, 21, 15, 0)?.dataIndex).toBe(1);
+	});
+});

frontend/src/lib/uPlotV2/plugins/ScatterPlugin/__tests__/scatterPlugin.test.ts

@@ -0,0 +1,286 @@
+import uPlot from 'uplot';
+
+import { UPlotConfigBuilder } from '../../../config/UPlotConfigBuilder';
+import {
+	applyScatterPlugin,
+	createScatterPlugin,
+	SCATTER_FACETS,
+} from '../scatterPlugin';
+
+jest.mock('lib/visualization/panels/utils/legendVisibilityUtils', () => ({
+	getStoredSeriesVisibility: jest.fn(),
+}));
+
+/** jsdom has no Path2D; the builder only needs something that takes the calls. */
+class FakePath2D {
+	moveTo = jest.fn();
+	arc = jest.fn();
+}
+
+type OrientCallback = Parameters<typeof uPlot.orient>[2];
+
+interface FakePlotArgs {
+	series: Array<{ xs: number[]; ys: number[]; sizes?: Array<number | null> }>;
+	cursor?: { left: number; top: number };
+	scaleX?: { min: number; max: number };
+	scaleY?: { min: number; max: number };
+}
+
+/**
+ * A 100×100 plot at the canvas origin with identity scales: value 10 draws at
+ * pixel 10 on x, and at 100 − 10 on y (uPlot's y grows downward).
+ */
+function createFakePlot({
+	series,
+	cursor = { left: -1, top: -1 },
+	scaleX = { min: 0, max: 100 },
+	scaleY = { min: 0, max: 100 },
+}: FakePlotArgs): uPlot {
+	const data = [
+		null,
+		...series.map((entry) =>
+			entry.sizes ? [entry.xs, entry.ys, entry.sizes] : [entry.xs, entry.ys],
+		),
+	];
+	return {
+		data,
+		series: [{}, ...series.map((_, index) => ({ label: `s${index + 1}` }))],
+		bbox: { left: 0, top: 0, width: 100, height: 100 },
+		cursor,
+		scales: { x: scaleX, y: scaleY },
+	} as unknown as uPlot;
+}
+
+/** Stands in for `uPlot.orient`: identity x, flipped y, an `arc` that records. */
+function orientWithIdentityScales(
+	u: uPlot,
+	seriesIdx: number,
+	cb: OrientCallback,
+): void {
+	const columns = (u.data as unknown as Array<number[][] | null>)[seriesIdx];
+	if (!columns) {
+		return;
+	}
+	const scaleX = (u.scales as unknown as Record<string, uPlot.Scale>).x;
+	const scaleY = (u.scales as unknown as Record<string, uPlot.Scale>).y;
+	const valToPosX = (value: number): number => value;
+	const valToPosY = (value: number): number => 100 - value;
+	// Real uPlot's `arc` helper forwards to the path; the test counts those calls.
+	const arc = (path: FakePath2D, ...args: number[]): void => {
+		path.arc(...args);
+	};
+	cb(
+		u.series[seriesIdx],
+		columns[0],
+		columns[1],
+		scaleX,
+		scaleY,
+		valToPosX as unknown as uPlot.ValToPos,
+		valToPosY as unknown as uPlot.ValToPos,
+		0,
+		0,
+		100,
+		100,
+		jest.fn() as never,
+		jest.fn() as never,
+		jest.fn() as never,
+		arc as never,
+		jest.fn() as never,
+	);
+}
+
+describe('createScatterPlugin', () => {
+	beforeAll(() => {
+		(globalThis as { Path2D?: unknown }).Path2D = FakePath2D;
+	});
+
+	beforeEach(() => {
+		(uPlot.orient as jest.Mock).mockImplementation(orientWithIdentityScales);
+	});
+
+	afterEach(() => {
+		(uPlot.orient as jest.Mock).mockReset();
+	});
+
+	function drawAll(
+		u: uPlot,
+		plugin: ReturnType<typeof createScatterPlugin>,
+	): void {
+		plugin.hooks.drawClear(u);
+		for (let seriesIdx = 1; seriesIdx < u.series.length; seriesIdx++) {
+			const columns = (u.data as unknown as number[][][])[seriesIdx];
+			plugin.pathBuilder(u, seriesIdx, 0, columns[0].length - 1);
+		}
+	}
+
+	/** Runs the cursor scan the way uPlot does: every data series, in order. */
+	function scan(
+		u: uPlot,
+		plugin: ReturnType<typeof createScatterPlugin>,
+	): Array<number | null> {
+		const dataIdx = plugin.cursor.dataIdx as NonNullable<uPlot.Cursor['dataIdx']>;
+		const indexes: Array<number | null> = [null];
+		for (let seriesIdx = 1; seriesIdx < u.series.length; seriesIdx++) {
+			indexes.push(dataIdx(u, seriesIdx, 0, 0));
+		}
+		return indexes;
+	}
+
+	it('returns one path that strokes and fills the same discs', () => {
+		const plugin = createScatterPlugin();
+		const u = createFakePlot({ series: [{ xs: [10, 20], ys: [10, 20] }] });
+		plugin.hooks.drawClear(u);
+
+		const paths = plugin.pathBuilder(u, 1, 0, 1) as uPlot.Series.Paths;
+
+		expect(paths.stroke).toBeInstanceOf(FakePath2D);
+		expect(paths.fill).toBe(paths.stroke);
+		expect((paths.fill as unknown as FakePath2D).arc).toHaveBeenCalledTimes(2);
+	});
+
+	it('resolves the hovered point to its own series and index', () => {
+		const plugin = createScatterPlugin({
+			pointSize: { fixed: 6, min: 4, max: 20 },
+		});
+		const u = createFakePlot({
+			series: [
+				{ xs: [10, 50], ys: [10, 50] },
+				{ xs: [80], ys: [80] },
+			],
+			// Over the second series' only point: x 80, y drawn at 100 − 80.
+			cursor: { left: 80, top: 20 },
+		});
+		drawAll(u, plugin);
+
+		expect(scan(u, plugin)).toStrictEqual([null, null, 0]);
+		expect(plugin.getHit()).toMatchObject({ seriesIndex: 2, dataIndex: 0 });
+	});
+
+	it('returns null for every series when the cursor is off the plot or off any disc', () => {
+		const plugin = createScatterPlugin();
+		const u = createFakePlot({
+			series: [{ xs: [10], ys: [10] }],
+			cursor: { left: -1, top: -1 },
+		});
+		drawAll(u, plugin);
+
+		expect(scan(u, plugin)).toStrictEqual([null, null]);
+
+		(u.cursor as { left: number; top: number }).left = 50;
+		(u.cursor as { left: number; top: number }).top = 50;
+		expect(scan(u, plugin)).toStrictEqual([null, null]);
+	});
+
+	it('skips points outside the visible scale range', () => {
+		const plugin = createScatterPlugin();
+		const u = createFakePlot({
+			series: [{ xs: [10, 500], ys: [10, 10] }],
+			cursor: { left: 10, top: 90 },
+		});
+		drawAll(u, plugin);
+
+		const paths = plugin.pathBuilder(u, 1, 0, 1) as uPlot.Series.Paths;
+		expect((paths.fill as unknown as FakePath2D).arc).toHaveBeenCalledTimes(1);
+		expect(scan(u, plugin)).toStrictEqual([null, 0]);
+	});
+
+	it('rings the hit disc, in CSS pixels, with a gap around it', () => {
+		const plugin = createScatterPlugin({
+			pointSize: { fixed: 8, min: 4, max: 20 },
+		});
+		const u = createFakePlot({
+			series: [{ xs: [10], ys: [10] }],
+			cursor: { left: 10, top: 90 },
+		});
+		drawAll(u, plugin);
+		scan(u, plugin);
+
+		const bbox = plugin.cursor.points?.bbox;
+		// The 8px disc spans 6..14; the ring sits 3px out and is 2px wide.
+		expect(bbox?.(u, 1)).toStrictEqual({
+			left: 1,
+			top: 81,
+			width: 18,
+			height: 18,
+		});
+		expect(bbox?.(u, 2)).toMatchObject({ width: 0, height: 0 });
+	});
+
+	it('snaps the ring to whole pixels without moving its centre', () => {
+		const plugin = createScatterPlugin({
+			pointSize: { fixed: 7, min: 4, max: 20 },
+		});
+		const u = createFakePlot({
+			series: [{ xs: [10], ys: [10] }],
+			cursor: { left: 10, top: 90 },
+		});
+		drawAll(u, plugin);
+		scan(u, plugin);
+
+		// The 7px disc starts at 6.5, so the ring's edge would land on 1.5.
+		const ring = plugin.cursor.points?.bbox?.(u, 1);
+		expect(ring).toMatchObject({ left: 1, width: 18 });
+		expect((ring?.left ?? 0) + (ring?.width ?? 0) / 2).toBe(10);
+	});
+
+	it('draws the hover marker as an outline in the series colour', () => {
+		const plugin = createScatterPlugin();
+		const u = {
+			series: [{}, { stroke: (): string => '#E5484D' }, { stroke: '#30A46C' }],
+		} as unknown as uPlot;
+		const points = plugin.cursor.points as {
+			fill: (u: uPlot, seriesIdx: number) => string;
+			stroke: (u: uPlot, seriesIdx: number) => string;
+			width: (u: uPlot, seriesIdx: number, size: number) => number;
+		};
+
+		expect(points.fill(u, 1)).toBe('transparent');
+		expect(points.stroke(u, 1)).toBe('#E5484D');
+		expect(points.stroke(u, 2)).toBe('#30A46C');
+		expect(points.width(u, 1, 0)).toBe(2);
+	});
+
+	it('drawClear drops cached paths on data series only', () => {
+		const plugin = createScatterPlugin();
+		const u = createFakePlot({ series: [{ xs: [1], ys: [1] }] });
+		const [xSeries, dataSeries] = u.series as Array<{ _paths?: unknown }>;
+		xSeries._paths = 'x';
+		dataSeries._paths = 'cached';
+
+		plugin.hooks.drawClear(u);
+
+		expect(xSeries._paths).toBe('x');
+		expect(dataSeries._paths).toBeNull();
+	});
+
+	it('focus distance is zero, so the hit series wins focus', () => {
+		const plugin = createScatterPlugin();
+		expect(plugin.cursor.focus?.dist?.({} as uPlot, 1, 0, 0, 0)).toBe(0);
+	});
+});
+
+describe('applyScatterPlugin', () => {
+	it('switches the builder to faceted mode and disables drag selection', () => {
+		const builder = new UPlotConfigBuilder({ id: 'scatter' });
+		const plugin = createScatterPlugin();
+
+		applyScatterPlugin(builder, plugin);
+		const config = builder.getConfig();
+
+		expect(config.mode).toBe(2);
+		expect(config.cursor?.drag).toMatchObject({
+			x: false,
+			y: false,
+			setScale: false,
+		});
+		expect(config.hooks?.drawClear).toHaveLength(1);
+		expect(config.hooks?.destroy).toHaveLength(1);
+	});
+
+	it('facets read x and y against the shared scales', () => {
+		expect(SCATTER_FACETS).toStrictEqual([
+			{ scale: 'x', auto: true },
+			{ scale: 'y', auto: true },
+		]);
+	});
+});

frontend/src/lib/uPlotV2/plugins/ScatterPlugin/geometry.ts

@@ -0,0 +1,86 @@
+import type uPlot from 'uplot';
+
+import type { Quadtree } from '../../utils/quadtree';
+import type { ScatterHit, ScatterPointSize, ScatterSeriesData } from './types';
+
+export interface SizeDomain {
+	min: number;
+	max: number;
+}
+
+/** Size extent across all series, so equal values draw equal discs. */
+export function resolveSizeDomain(data: uPlot.AlignedData): SizeDomain | null {
+	let min = Infinity;
+	let max = -Infinity;
+	for (let seriesIndex = 1; seriesIndex < data.length; seriesIndex++) {
+		const sizes = (data[seriesIndex] as unknown as ScatterSeriesData)[2];
+		if (!sizes) {
+			continue;
+		}
+		for (const size of sizes) {
+			if (size == null || !Number.isFinite(size)) {
+				continue;
+			}
+			min = Math.min(min, size);
+			max = Math.max(max, size);
+		}
+	}
+	return min <= max ? { min, max } : null;
+}
+
+/** Area, not diameter, scales with the value. */
+export function resolvePointDiameter(
+	size: number | null | undefined,
+	domain: SizeDomain | null,
+	pointSize: ScatterPointSize,
+): number {
+	if (size == null || domain == null || !Number.isFinite(size)) {
+		return pointSize.fixed;
+	}
+	if (domain.max === domain.min) {
+		return (pointSize.min + pointSize.max) / 2;
+	}
+	const t = Math.min(
+		1,
+		Math.max(0, (size - domain.min) / (domain.max - domain.min)),
+	);
+	const minArea = pointSize.min ** 2;
+	const maxArea = pointSize.max ** 2;
+	return Math.sqrt(minArea + (maxArea - minArea) * t);
+}
+
+/** Disc whose centre is closest, within `tolerance` px; `null` if none. */
+export function resolveHit(
+	tree: Quadtree<ScatterHit>,
+	cx: number,
+	cy: number,
+	tolerance: number,
+): ScatterHit | null {
+	let best: ScatterHit | null = null;
+	let bestDistance = Infinity;
+
+	tree.get(
+		cx - tolerance,
+		cy - tolerance,
+		tolerance * 2,
+		tolerance * 2,
+		(hit) => {
+			const left = hit.x - tolerance;
+			const top = hit.y - tolerance;
+			const right = hit.x + hit.w + tolerance;
+			const bottom = hit.y + hit.h + tolerance;
+			if (cx < left || cx > right || cy < top || cy > bottom) {
+				return;
+			}
+			const dx = cx - (hit.x + hit.w / 2);
+			const dy = cy - (hit.y + hit.h / 2);
+			const distance = dx * dx + dy * dy;
+			if (distance < bestDistance) {
+				best = hit;
+				bestDistance = distance;
+			}
+		},
+	);
+
+	return best;
+}

frontend/src/lib/uPlotV2/plugins/ScatterPlugin/scatterPlugin.ts

@@ -0,0 +1,225 @@
+import uPlot, { Series } from 'uplot';
+
+import { DEFAULT_FOCUS_PROXIMITY_VALUE } from '../../constants';
+import { PlotMode } from '../../config/types';
+import type { UPlotConfigBuilder } from '../../config/UPlotConfigBuilder';
+import { Quadtree } from '../../utils/quadtree';
+import {
+	resolveHit,
+	resolvePointDiameter,
+	resolveSizeDomain,
+	SizeDomain,
+} from './geometry';
+import {
+	DEFAULT_HOVER_TOLERANCE_PX,
+	DEFAULT_SCATTER_POINT_SIZE,
+	ScatterHit,
+	ScatterPluginOptions,
+	ScatterSeriesData,
+} from './types';
+
+export const SCATTER_FACETS: Series.Facet[] = [
+	{ scale: 'x', auto: true },
+	{ scale: 'y', auto: true },
+];
+
+const HIDDEN_BBOX: uPlot.BBox = { left: -10, top: -10, width: 0, height: 0 };
+
+const TWO_PI = 2 * Math.PI;
+
+/** CSS pixels between a hovered disc and the outline ring drawn around it. */
+const HOVER_RING_GAP_PX = 3;
+const HOVER_RING_WIDTH_PX = 2;
+
+/** uPlot ceils a cursor point's left/top but not its size; snap so the ring stays centred. */
+function snapToPixel(start: number, length: number): [number, number] {
+	const snapped = Math.floor(start);
+	return [snapped, length + (start - snapped) * 2];
+}
+
+export function getSeriesStroke(u: uPlot, seriesIdx: number): string {
+	const { stroke } = u.series[seriesIdx];
+	const color = typeof stroke === 'function' ? stroke(u, seriesIdx) : stroke;
+	return typeof color === 'string' ? color : '';
+}
+
+/** uPlot caches built paths on the series; the field is internal to it. */
+type SeriesWithPaths = Series & { _paths?: Series.Paths | null };
+
+export interface ScatterPlugin {
+	pathBuilder: Series.PathBuilder;
+	/** Hover by disc rather than by nearest x: mode 2 has no shared x to scan. */
+	cursor: uPlot.Cursor;
+	hooks: {
+		drawClear: (u: uPlot) => void;
+		destroy: (u: uPlot) => void;
+	};
+	getHit: () => ScatterHit | null;
+}
+
+export function createScatterPlugin({
+	pointSize = DEFAULT_SCATTER_POINT_SIZE,
+	hoverTolerance = DEFAULT_HOVER_TOLERANCE_PX,
+}: ScatterPluginOptions = {}): ScatterPlugin {
+	let tree: Quadtree<ScatterHit> | null = null;
+	let hit: ScatterHit | null = null;
+
+	// Spans every series; cached per dataset.
+	let cachedData: uPlot.AlignedData | null = null;
+	let cachedDomain: SizeDomain | null = null;
+
+	function getSizeDomain(u: uPlot): SizeDomain | null {
+		if (cachedData !== u.data) {
+			cachedDomain = resolveSizeDomain(u.data);
+			cachedData = u.data;
+		}
+		return cachedDomain;
+	}
+
+	const pathBuilder: Series.PathBuilder = (u, seriesIdx, idx0, idx1) => {
+		const path = new Path2D();
+		const sizes = (u.data[seriesIdx] as unknown as ScatterSeriesData)[2];
+		const domain = getSizeDomain(u);
+		const { pxRatio } = uPlot;
+
+		uPlot.orient(
+			u,
+			seriesIdx,
+			(
+				_series,
+				dataX,
+				dataY,
+				scaleX,
+				scaleY,
+				valToPosX,
+				valToPosY,
+				xOff,
+				yOff,
+				xDim,
+				yDim,
+				_moveTo,
+				_lineTo,
+				_rect,
+				arc,
+			) => {
+				const xMin = scaleX.min ?? -Infinity;
+				const xMax = scaleX.max ?? Infinity;
+				const yMin = scaleY.min ?? -Infinity;
+				const yMax = scaleY.max ?? Infinity;
+
+				for (let i = idx0; i <= idx1; i++) {
+					const x = dataX[i];
+					const y = dataY[i];
+					if (
+						x == null ||
+						y == null ||
+						x < xMin ||
+						x > xMax ||
+						y < yMin ||
+						y > yMax
+					) {
+						continue;
+					}
+
+					const diameter =
+						resolvePointDiameter(sizes?.[i], domain, pointSize) * pxRatio;
+					const radius = diameter / 2;
+					const cx = valToPosX(x, scaleX, xDim, xOff);
+					const cy = valToPosY(y, scaleY, yDim, yOff);
+
+					path.moveTo(cx + radius, cy);
+					arc(path, cx, cy, radius, 0, TWO_PI);
+
+					tree?.add({
+						x: cx - radius - u.bbox.left,
+						y: cy - radius - u.bbox.top,
+						w: diameter,
+						h: diameter,
+						seriesIndex: seriesIdx,
+						dataIndex: i,
+					});
+				}
+			},
+		);
+
+		return { stroke: path, fill: path, clip: null };
+	};
+
+	const cursor: uPlot.Cursor = {
+		// Selection would set the dashboard time range; neither axis is time here.
+		drag: { x: false, y: false, setScale: false },
+		dataIdx: (u, seriesIdx): number | null => {
+			// uPlot asks series 1..n in order on every cursor move; resolve once.
+			if (seriesIdx === 1) {
+				const { left = -1, top = -1 } = u.cursor;
+				const { pxRatio } = uPlot;
+				hit =
+					tree && left >= 0 && top >= 0
+						? resolveHit(
+								tree,
+								left * pxRatio,
+								top * pxRatio,
+								hoverTolerance * pxRatio,
+							)
+						: null;
+			}
+			return hit?.seriesIndex === seriesIdx ? hit.dataIndex : null;
+		},
+		points: {
+			bbox: (_u, seriesIdx): uPlot.BBox => {
+				if (hit?.seriesIndex !== seriesIdx) {
+					return HIDDEN_BBOX;
+				}
+				const { pxRatio } = uPlot;
+				const inset = HOVER_RING_GAP_PX + HOVER_RING_WIDTH_PX;
+				const [left, width] = snapToPixel(
+					hit.x / pxRatio - inset,
+					hit.w / pxRatio + inset * 2,
+				);
+				const [top, height] = snapToPixel(
+					hit.y / pxRatio - inset,
+					hit.h / pxRatio + inset * 2,
+				);
+				return { left, top, width, height };
+			},
+			fill: (): string => 'transparent',
+			stroke: getSeriesStroke,
+			width: (): number => HOVER_RING_WIDTH_PX,
+		},
+		// uPlot only measures series that returned a data index, i.e. the hit one.
+		focus: { prox: DEFAULT_FOCUS_PROXIMITY_VALUE, dist: (): number => 0 },
+	};
+
+	return {
+		pathBuilder,
+		cursor,
+		hooks: {
+			drawClear: (u: uPlot): void => {
+				tree = new Quadtree<ScatterHit>(0, 0, u.bbox.width, u.bbox.height);
+				// The tree holds only what the path builder drew, so force a rebuild.
+				u.series.forEach((series, index) => {
+					if (index > 0) {
+						(series as SeriesWithPaths)._paths = null;
+					}
+				});
+			},
+			destroy: (): void => {
+				tree = null;
+				hit = null;
+				cachedData = null;
+				cachedDomain = null;
+			},
+		},
+		getHit: (): ScatterHit | null => hit,
+	};
+}
+
+export function applyScatterPlugin(
+	builder: UPlotConfigBuilder,
+	plugin: ScatterPlugin,
+): void {
+	builder.setMode(PlotMode.Faceted);
+	builder.setCursor(plugin.cursor);
+	builder.addHook('drawClear', plugin.hooks.drawClear);
+	builder.addHook('destroy', plugin.hooks.destroy);
+}

frontend/src/lib/uPlotV2/plugins/ScatterPlugin/types.ts

@@ -0,0 +1,54 @@
+import type { QuadtreeRect } from '../../utils/quadtree';
+
+/** Diameters in CSS pixels. `min`/`max` bound the area scale when a size column is mapped. */
+export interface ScatterPointSize {
+	fixed: number;
+	min: number;
+	max: number;
+}
+
+export const DEFAULT_SCATTER_POINT_SIZE: ScatterPointSize = {
+	fixed: 6,
+	min: 4,
+	max: 24,
+};
+
+/** CSS pixels around a point's disc that still register as a hover. */
+export const DEFAULT_HOVER_TOLERANCE_PX = 3;
+
+export interface ScatterPluginOptions {
+	pointSize?: ScatterPointSize;
+	hoverTolerance?: number;
+}
+
+/** Parallel columns; a `null` size draws at `fixed`. */
+export type ScatterSeriesData = [
+	xs: number[],
+	ys: number[],
+	sizes?: Array<number | null>,
+];
+
+/** Mode-2 data: series 0 is uPlot's x placeholder and carries nothing. */
+export type ScatterChartData = [null, ...ScatterSeriesData[]];
+
+/** A drawn point's disc, in canvas pixels relative to the plot area. */
+export interface ScatterHit extends QuadtreeRect {
+	seriesIndex: number;
+	dataIndex: number;
+}
+
+export interface ScatterChannel {
+	label: string;
+	unit?: string;
+}
+
+export interface ScatterChannels {
+	x: ScatterChannel;
+	y: ScatterChannel;
+	size?: ScatterChannel;
+}
+
+export interface ScatterPointLabel {
+	key: string;
+	value: string;
+}

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/__tests__/buildClickData.test.ts

@@ -0,0 +1,52 @@
+import type uPlot from 'uplot';
+
+import { buildClickData } from '../utils';
+
+jest.mock('lib/uPlotLib/plugins/onClickPlugin', () => ({
+	getFocusedSeriesAtPosition: jest.fn(() => ({ seriesIndex: 1 })),
+}));
+
+const event = {
+	offsetX: 10,
+	offsetY: 20,
+	clientX: 110,
+	clientY: 220,
+} as MouseEvent;
+
+describe('buildClickData', () => {
+	it('skips the x-index lookups on a faceted plot, which has no shared x series', () => {
+		const posToIdx = jest.fn(() => {
+			throw new Error('faceted data[0] is null');
+		});
+		const plot = {
+			data: [null],
+			posToVal: (pos: number): number => pos * 2,
+			posToIdx,
+		} as unknown as uPlot;
+
+		expect(buildClickData(event, plot)).toStrictEqual({
+			xValue: 20,
+			yValue: 40,
+			focusedSeries: null,
+			clickedDataTimestamp: 20,
+			mouseX: 10,
+			mouseY: 20,
+			absoluteMouseX: 110,
+			absoluteMouseY: 220,
+		});
+		expect(posToIdx).not.toHaveBeenCalled();
+	});
+
+	it('resolves the focused series and clicked timestamp on an aligned plot', () => {
+		const plot = {
+			data: [[100, 200, 300]],
+			posToVal: (pos: number): number => pos,
+			posToIdx: (): number => 1,
+		} as unknown as uPlot;
+
+		expect(buildClickData(event, plot)).toMatchObject({
+			focusedSeries: { seriesIndex: 1 },
+			clickedDataTimestamp: 200,
+		});
+	});
+});

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/utils.ts

@@ -174,6 +174,24 @@ export function createLayoutObserver(
 export function buildClickData(event: MouseEvent, plot: uPlot): ChartClickData {
 	const xValue = plot.posToVal(event.offsetX, 'x');
 	const yValue = plot.posToVal(event.offsetY, 'y');
+	const pointer = {
+		mouseX: event.offsetX,
+		mouseY: event.offsetY,
+		absoluteMouseX: event.clientX,
+		absoluteMouseY: event.clientY,
+	};
+
+	// Faceted (scatter): no shared x, so `posToIdx` would throw.
+	if (plot.data[0] == null) {
+		return {
+			xValue,
+			yValue,
+			focusedSeries: null,
+			clickedDataTimestamp: xValue,
+			...pointer,
+		};
+	}
+
 	const focusedSeries = getFocusedSeriesAtPosition(event, plot);
 
 	const dataIndex = plot.posToIdx(event.offsetX);
@@ -193,9 +211,6 @@ export function buildClickData(event: MouseEvent, plot: uPlot): ChartClickData {
 		yValue,
 		focusedSeries,
 		clickedDataTimestamp,
-		mouseX: event.offsetX,
-		mouseY: event.offsetY,
-		absoluteMouseX: event.clientX,
-		absoluteMouseY: event.clientY,
+		...pointer,
 	};
 }

frontend/src/lib/uPlotV2/utils/__tests__/logGridSplits.test.ts

@@ -0,0 +1,59 @@
+import type uPlot from 'uplot';
+
+import { logScaleSplits, spacedLogLabels } from '../logGridSplits';
+
+describe('logScaleSplits', () => {
+	const splitsFor = (min: number, max: number): number[] =>
+		(
+			logScaleSplits as (
+				u: uPlot,
+				axisIdx: number,
+				min: number,
+				max: number,
+			) => number[]
+		)({} as uPlot, 0, min, max);
+
+	it('splits at 1, 2 and 5 × 10ⁿ inside an unsnapped range', () => {
+		expect(splitsFor(10.6, 990)).toStrictEqual([20, 50, 100, 200, 500]);
+	});
+
+	it('includes the ends when they fall on a split', () => {
+		expect(splitsFor(0.1, 10)).toStrictEqual([0.1, 0.2, 0.5, 1, 2, 5, 10]);
+	});
+
+	it('is empty for a range a log scale cannot hold', () => {
+		expect(splitsFor(0, 10)).toStrictEqual([]);
+		expect(splitsFor(5, 5)).toStrictEqual([]);
+	});
+});
+
+describe('spacedLogLabels', () => {
+	// 100px per decade.
+	const plot = {
+		axes: [{ scale: 'x' }],
+		valToPos: (value: number): number => Math.log10(value) * 100,
+	} as unknown as uPlot;
+	const label = (splits: number[], space: number): (number | null)[] =>
+		spacedLogLabels(plot, splits, 0, space, 0) as (number | null)[];
+
+	it('always labels the powers of ten', () => {
+		expect(label([10, 20, 50, 100], 200)).toStrictEqual([10, null, null, 100]);
+	});
+
+	it('adds a 2 or 5 that clears the labels already kept', () => {
+		// 20 is 30px from 10; 50 is 70px from 10 and 30px from 100.
+		expect(label([10, 20, 50, 100], 25)).toStrictEqual([10, 20, 50, 100]);
+		expect(label([10, 20, 50, 100], 40)).toStrictEqual([10, null, null, 100]);
+	});
+
+	it('labels both ends of a range spanning under a decade', () => {
+		// 100 sits at 200px; 20 (130px) and 500 (270px) clear it, 50 and 200 do not.
+		expect(label([20, 50, 100, 200, 500], 60)).toStrictEqual([
+			20,
+			null,
+			100,
+			null,
+			500,
+		]);
+	});
+});

frontend/src/lib/uPlotV2/utils/__tests__/quadtree.test.ts

@@ -0,0 +1,62 @@
+import { Quadtree, QuadtreeRect } from '../quadtree';
+
+interface Item extends QuadtreeRect {
+	id: number;
+}
+
+function collect(
+	tree: Quadtree<Item>,
+	x: number,
+	y: number,
+	w: number,
+	h: number,
+): Set<number> {
+	const ids = new Set<number>();
+	tree.get(x, y, w, h, (item) => ids.add(item.id));
+	return ids;
+}
+
+describe('Quadtree', () => {
+	it('returns items in the queried region and not those far from it', () => {
+		const tree = new Quadtree<Item>(0, 0, 100, 100);
+		tree.add({ id: 1, x: 10, y: 10, w: 5, h: 5 });
+		tree.add({ id: 2, x: 80, y: 80, w: 5, h: 5 });
+
+		// Below the split threshold every item is visited; callers refine the hit.
+		expect(collect(tree, 9, 9, 8, 8)).toStrictEqual(new Set([1, 2]));
+	});
+
+	it('splits past the object limit and still finds every item', () => {
+		const tree = new Quadtree<Item>(0, 0, 100, 100);
+		const total = 50;
+		for (let id = 0; id < total; id++) {
+			tree.add({ id, x: (id % 10) * 10, y: Math.floor(id / 10) * 10, w: 4, h: 4 });
+		}
+
+		expect(collect(tree, 0, 0, 100, 100).size).toBe(total);
+	});
+
+	it('after a split, a query in one quadrant skips items confined to another', () => {
+		const tree = new Quadtree<Item>(0, 0, 100, 100);
+		for (let id = 0; id < 20; id++) {
+			// All in the north-west quadrant.
+			tree.add({ id, x: 1 + id, y: 1, w: 2, h: 2 });
+		}
+		tree.add({ id: 99, x: 90, y: 90, w: 2, h: 2 });
+
+		const northWest = collect(tree, 0, 0, 10, 10);
+		expect(northWest.has(99)).toBe(false);
+		expect(collect(tree, 85, 85, 10, 10).has(99)).toBe(true);
+	});
+
+	it('reports an item straddling the midline from either side', () => {
+		const tree = new Quadtree<Item>(0, 0, 100, 100);
+		for (let id = 0; id < 20; id++) {
+			tree.add({ id, x: 1, y: 1 + id, w: 2, h: 2 });
+		}
+		tree.add({ id: 99, x: 48, y: 48, w: 4, h: 4 });
+
+		expect(collect(tree, 40, 40, 5, 5).has(99)).toBe(true);
+		expect(collect(tree, 55, 55, 5, 5).has(99)).toBe(true);
+	});
+});

frontend/src/lib/uPlotV2/utils/__tests__/scale.test.ts

@@ -195,3 +195,22 @@ describe('scale utils', () => {
 		});
 	});
 });
+
+describe('symmetric log scale', () => {
+	it('maps to uPlot arcsinh with the given linear threshold', () => {
+		expect(
+			scaleUtils.getDistributionConfig({
+				time: false,
+				distr: DistributionType.SymmetricLog,
+				asinhThreshold: 0.01,
+			}),
+		).toStrictEqual({ distr: 4, log: 10, asinh: 0.01 });
+
+		expect(
+			scaleUtils.getDistributionConfig({
+				time: false,
+				distr: DistributionType.SymmetricLog,
+			}).asinh,
+		).toBe(scaleUtils.DEFAULT_ASINH_THRESHOLD);
+	});
+});

frontend/src/lib/uPlotV2/utils/logGridSplits.ts

@@ -0,0 +1,61 @@
+import type uPlot from 'uplot';
+
+const DECADE_TOLERANCE = 1e-9;
+
+function isDecade(value: number): boolean {
+	if (value === 0) {
+		return true;
+	}
+	const exponent = Math.log10(Math.abs(value));
+	return Math.abs(exponent - Math.round(exponent)) < DECADE_TOLERANCE;
+}
+
+const LOG_SPLIT_MULTIPLES = [1, 2, 5];
+
+/** 1, 2, 5 × 10ⁿ in range; uPlot's log splits step from an unsnapped min (10.79, 21.58…). */
+export const logScaleSplits: uPlot.Axis.Splits = (_u, _axisIdx, min, max) => {
+	if (!(min > 0) || !(max > min)) {
+		return [];
+	}
+	const splits: number[] = [];
+	for (
+		let exponent = Math.floor(Math.log10(min));
+		exponent <= Math.ceil(Math.log10(max));
+		exponent++
+	) {
+		LOG_SPLIT_MULTIPLES.forEach((multiple) => {
+			// Rounded through toPrecision so 0.1 × 3 noise can't fall outside [min, max].
+			const split = Number((multiple * 10 ** exponent).toPrecision(12));
+			if (split >= min && split <= max) {
+				splits.push(split);
+			}
+		});
+	}
+	return splits;
+};
+
+/** Labels every decade, plus any 2 or 5 at least `space` px clear. */
+export const spacedLogLabels: uPlot.Axis.Filter = (
+	u,
+	splits,
+	axisIdx,
+	space,
+) => {
+	const scaleKey = u.axes[axisIdx]?.scale ?? 'x';
+	const positions = splits.map((split) =>
+		split == null ? null : u.valToPos(split, scaleKey),
+	);
+	const kept = splits.map((split) => split != null && isDecade(split));
+	const isClear = (index: number): boolean =>
+		kept.every(
+			(isKept, other) =>
+				!isKept ||
+				Math.abs((positions[other] ?? 0) - (positions[index] ?? 0)) >= space,
+		);
+	splits.forEach((split, index) => {
+		if (split != null && !kept[index] && isClear(index)) {
+			kept[index] = true;
+		}
+	});
+	return splits.map((split, index) => (kept[index] ? split : null));
+};

frontend/src/lib/uPlotV2/utils/quadtree.ts

@@ -0,0 +1,100 @@
+export interface QuadtreeRect {
+	x: number;
+	y: number;
+	w: number;
+	h: number;
+}
+
+const MAX_OBJECTS = 10;
+const MAX_LEVELS = 4;
+
+/** Rect index for cursor hit-testing; items straddling quadrants are stored in each, so `get` may repeat them. */
+export class Quadtree<T extends QuadtreeRect = QuadtreeRect> {
+	private items: T[] = [];
+	private quadrants: Quadtree<T>[] | null = null;
+
+	constructor(
+		private readonly x: number,
+		private readonly y: number,
+		private readonly w: number,
+		private readonly h: number,
+		private readonly level = 0,
+	) {}
+
+	add(item: T): void {
+		if (this.quadrants) {
+			this.forEachQuadrant(item, (quadrant) => quadrant.add(item));
+			return;
+		}
+
+		this.items.push(item);
+
+		if (this.items.length > MAX_OBJECTS && this.level < MAX_LEVELS) {
+			this.split();
+			const items = this.items;
+			this.items = [];
+			for (const existing of items) {
+				this.forEachQuadrant(existing, (quadrant) => quadrant.add(existing));
+			}
+		}
+	}
+
+	/** Visits every item whose quadrant overlaps the rectangle; callers refine the test. */
+	get(
+		x: number,
+		y: number,
+		w: number,
+		h: number,
+		visit: (item: T) => void,
+	): void {
+		for (const item of this.items) {
+			visit(item);
+		}
+		if (this.quadrants) {
+			this.forEachQuadrant({ x, y, w, h }, (quadrant) =>
+				quadrant.get(x, y, w, h, visit),
+			);
+		}
+	}
+
+	private split(): void {
+		const w = this.w / 2;
+		const h = this.h / 2;
+		const level = this.level + 1;
+		// North-east, north-west, south-west, south-east.
+		this.quadrants = [
+			new Quadtree<T>(this.x + w, this.y, w, h, level),
+			new Quadtree<T>(this.x, this.y, w, h, level),
+			new Quadtree<T>(this.x, this.y + h, w, h, level),
+			new Quadtree<T>(this.x + w, this.y + h, w, h, level),
+		];
+	}
+
+	private forEachQuadrant(
+		rect: QuadtreeRect,
+		visit: (quadrant: Quadtree<T>) => void,
+	): void {
+		if (!this.quadrants) {
+			return;
+		}
+		const midX = this.x + this.w / 2;
+		const midY = this.y + this.h / 2;
+		const startsNorth = rect.y < midY;
+		const startsWest = rect.x < midX;
+		const endsEast = rect.x + rect.w > midX;
+		const endsSouth = rect.y + rect.h > midY;
+
+		if (startsNorth && endsEast) {
+			visit(this.quadrants[0]);
+		}
+		if (startsWest && startsNorth) {
+			visit(this.quadrants[1]);
+		}
+		if (startsWest && endsSouth) {
+			visit(this.quadrants[2]);
+		}
+		if (endsEast && endsSouth) {
+			visit(this.quadrants[3]);
+		}
+	}
+}

frontend/src/lib/uPlotV2/utils/scale.ts

@@ -58,18 +58,23 @@ function normalizeLogLimit(
 	return logBase ** exp;
 }
 
+export const DEFAULT_ASINH_THRESHOLD = 1;
+
 /**
- * Returns uPlot scale distribution options for the Y axis.
- * Time (X) scale gets no distr/log; Y scale gets distr 1 (linear) or 3 (log) and log base 2 or 10.
+ * Returns uPlot scale distribution options for a value axis.
+ * Time scales get no distr/log; value scales get distr 1 (linear), 3 (log) or
+ * 4 (arcsinh, uPlot's symmetric log) and log base 2 or 10.
  */
 export function getDistributionConfig({
 	time,
 	distr,
 	logBase,
+	asinhThreshold,
 }: {
 	time: ScaleProps['time'];
 	distr?: DistributionType;
 	logBase?: number;
+	asinhThreshold?: number;
 }): Partial<Scale> {
 	if (time) {
 		return {};
@@ -77,6 +82,14 @@ export function getDistributionConfig({
 
 	const resolvedLogBase = (logBase ?? 10) === 2 ? 2 : 10;
 
+	if (distr === DistributionType.SymmetricLog) {
+		return {
+			distr: 4,
+			log: resolvedLogBase,
+			asinh: asinhThreshold ?? DEFAULT_ASINH_THRESHOLD,
+		};
+	}
+
 	return {
 		distr: distr === DistributionType.Logarithmic ? 3 : 1,
 		log: resolvedLogBase,

frontend/src/lib/visualization/charts/ChartWrapper/ChartWrapper.tsx

@@ -37,6 +37,7 @@ export default function ChartWrapper({
 	syncKey,
 	syncFilterMode,
 	onDestroy = noop,
+	plotRef,
 	children,
 	layoutChildren,
 	yAxisUnit,
@@ -123,6 +124,7 @@ export default function ChartWrapper({
 						height={chartHeight}
 						plotRef={(plot): void => {
 							plotInstanceRef.current = plot;
+							plotRef?.(plot);
 						}}
 						onDestroy={(plot: uPlot): void => {
 							plotInstanceRef.current = null;

frontend/src/lib/visualization/charts/ChartWrapper/__tests__/ChartWrapper.test.tsx

@@ -0,0 +1,45 @@
+import { render } from 'tests/test-utils';
+import type uPlot from 'uplot';
+
+import { LegendPosition } from 'lib/uPlotV2/components/types';
+import { UPlotConfigBuilder } from 'lib/uPlotV2/config/UPlotConfigBuilder';
+
+import ChartWrapper from '../ChartWrapper';
+
+const FAKE_PLOT = { id: 'plot' } as unknown as uPlot;
+
+jest.mock('lib/uPlotV2/components/UPlotChart/UPlotChart', () => ({
+	__esModule: true,
+	default: ({ plotRef }: { plotRef?: (plot: uPlot | null) => void }): null => {
+		plotRef?.(FAKE_PLOT);
+		return null;
+	},
+}));
+
+window.ResizeObserver =
+	window.ResizeObserver ||
+	jest.fn().mockImplementation(() => ({
+		disconnect: jest.fn(),
+		observe: jest.fn(),
+		unobserve: jest.fn(),
+	}));
+
+describe('ChartWrapper', () => {
+	it('hands the plot instance to the caller', () => {
+		const plotRef = jest.fn();
+		render(
+			<ChartWrapper
+				config={new UPlotConfigBuilder({ id: 'chart' })}
+				data={[[1], [2]]}
+				width={400}
+				height={300}
+				legendConfig={{ position: LegendPosition.BOTTOM }}
+				showLegend={false}
+				showTooltip={false}
+				plotRef={plotRef}
+			/>,
+		);
+
+		expect(plotRef).toHaveBeenCalledWith(FAKE_PLOT);
+	});
+});

frontend/src/lib/visualization/charts/Scatter/Scatter.stories.tsx

@@ -0,0 +1,244 @@
+import { useMemo } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useIsDarkMode } from 'hooks/useDarkMode';
+import { LegendPosition } from 'lib/uPlotV2/components/types';
+import type { Threshold } from 'lib/uPlotV2/hooks/types';
+import type { ScatterPointLabel } from 'lib/uPlotV2/plugins/ScatterPlugin/types';
+
+import Scatter from './Scatter';
+import {
+	buildScatterConfig,
+	prepareScatterChartData,
+	ScatterAxisScale,
+	ScatterSeries,
+} from './utils';
+
+const SERVICES = [
+	'frontend',
+	'cart',
+	'checkout',
+	'payment',
+	'shipping',
+	'currency',
+	'email',
+	'recommendation',
+	'ads',
+	'product-catalog',
+];
+
+type Shape = 'spread' | 'single' | 'sameX';
+
+interface ScatterStoryProps {
+	groups: number;
+	pointsPerGroup: number;
+	/** Adds an error-count size column. */
+	sized: boolean;
+	xScale: ScatterAxisScale;
+	yScale: ScatterAxisScale;
+	/** Zeroes a share of y values, which forces the symmetric log. */
+	withZeros: boolean;
+	shape: Shape;
+	thresholds: boolean;
+	pointSize: number;
+	/** 0–1. */
+	fillOpacity: number;
+	width: number;
+	height: number;
+}
+
+/** Deterministic, so a story renders the same points on every run. */
+function createRng(seed: number): () => number {
+	let state = seed >>> 0;
+	return (): number => {
+		state = (state * 1664525 + 1013904223) >>> 0;
+		return state / 2 ** 32;
+	};
+}
+
+function buildSeries({
+	groups,
+	pointsPerGroup,
+	sized,
+	withZeros,
+	shape,
+}: ScatterStoryProps): ScatterSeries[] {
+	const rng = createRng(42);
+	return Array.from({ length: groups }, (_, groupIndex) => {
+		const label = SERVICES[groupIndex % SERVICES.length];
+		// Each service sits in its own throughput/latency band, so groups are telling
+		// apart rather than one cloud.
+		const baseThroughput = 20 * 2 ** (groupIndex % 5);
+		const baseLatency = 40 + 60 * (groupIndex % 4);
+
+		const count = shape === 'single' ? 1 : pointsPerGroup;
+		const xs: number[] = [];
+		const ys: number[] = [];
+		const sizes: Array<number | null> = [];
+
+		for (let i = 0; i < count; i++) {
+			const throughput =
+				shape === 'sameX' ? baseThroughput : baseThroughput * (0.5 + rng() * 1.5);
+			// Latency grows with load, plus noise; the odd outlier keeps the axis honest.
+			const outlier = rng() < 0.03 ? 4 + rng() * 6 : 1;
+			let latency =
+				baseLatency *
+				(0.8 + (throughput / baseThroughput) * 0.4 + rng() * 0.3) *
+				outlier;
+			if (withZeros && rng() < 0.2) {
+				latency = 0;
+			}
+			xs.push(Number(throughput.toFixed(2)));
+			ys.push(Number(latency.toFixed(2)));
+			sizes.push(rng() < 0.1 ? null : Math.round(rng() * rng() * 500));
+		}
+
+		return sized ? { label, xs, ys, sizes } : { label, xs, ys };
+	});
+}
+
+const THRESHOLDS: Threshold[] = [
+	{
+		thresholdValue: 300,
+		thresholdUnit: 'ms',
+		thresholdColor: '#E5484D',
+		thresholdLabel: 'p99 SLO',
+	},
+];
+
+function ScatterStory(props: ScatterStoryProps): JSX.Element {
+	const {
+		xScale,
+		yScale,
+		sized,
+		thresholds,
+		pointSize,
+		fillOpacity,
+		width,
+		height,
+	} = props;
+	const isDarkMode = useIsDarkMode();
+
+	const series = useMemo(() => buildSeries(props), [props]);
+
+	const config = useMemo(
+		() =>
+			buildScatterConfig({
+				id: 'scatter-story',
+				series,
+				isDarkMode,
+				x: { unit: 'reqps', scale: xScale },
+				y: { unit: 'ms', scale: yScale },
+				pointSize: { fixed: pointSize, min: 4, max: pointSize * 4 },
+				fillOpacity,
+				thresholds: thresholds ? THRESHOLDS : undefined,
+			}),
+		[series, isDarkMode, xScale, yScale, pointSize, fillOpacity, thresholds],
+	);
+
+	const data = useMemo(() => prepareScatterChartData(series), [series]);
+
+	const resolvePointLabels = (
+		seriesIndex: number,
+		dataIndex: number,
+	): ScatterPointLabel[] => [
+		{ key: 'service.name', value: series[seriesIndex - 1]?.label ?? '' },
+		{
+			key: 'k8s.pod.name',
+			value: `pod-${dataIndex.toString().padStart(3, '0')}`,
+		},
+	];
+
+	return (
+		<div style={{ width, padding: 16 }}>
+			<Scatter
+				config={config}
+				data={data}
+				width={width}
+				height={height}
+				legendConfig={{ position: LegendPosition.BOTTOM }}
+				channels={{
+					x: { label: 'Throughput', unit: 'reqps' },
+					y: { label: 'p99 latency', unit: 'ms' },
+					...(sized && { size: { label: 'Errors', unit: 'short' } }),
+				}}
+				resolvePointLabels={resolvePointLabels}
+				canPinTooltip
+			/>
+		</div>
+	);
+}
+
+const meta = {
+	title: 'Charts/Scatter',
+	component: ScatterStory,
+	parameters: { layout: 'padded' },
+	args: {
+		groups: 1,
+		pointsPerGroup: 10,
+		sized: false,
+		xScale: ScatterAxisScale.Linear,
+		yScale: ScatterAxisScale.Linear,
+		withZeros: false,
+		shape: 'spread',
+		thresholds: false,
+		pointSize: 6,
+		fillOpacity: 0.7,
+		width: 800,
+		height: 420,
+	},
+	argTypes: {
+		shape: { control: 'radio', options: ['spread', 'single', 'sameX'] },
+		xScale: { control: 'radio', options: Object.values(ScatterAxisScale) },
+		yScale: { control: 'radio', options: Object.values(ScatterAxisScale) },
+		fillOpacity: { control: { type: 'range', min: 0, max: 1, step: 0.05 } },
+		pointSize: { control: { type: 'range', min: 2, max: 16, step: 1 } },
+	},
+} satisfies Meta<ScatterStoryProps>;
+
+export default meta;
+
+type Story = StoryObj<ScatterStoryProps>;
+
+/** One service, ten points: axes formatted with units, hover picks the right point. */
+export const Basic: Story = {};
+
+/** Five services, one legend entry each; toggling a row hides its points. */
+export const Grouped: Story = {
+	args: { groups: 5, pointsPerGroup: 40 },
+};
+
+/** Error count as disc area, between the configured min and max diameters. */
+export const Sized: Story = {
+	args: { groups: 5, pointsPerGroup: 40, sized: true, pointSize: 5 },
+};
+
+/** Log x; a fifth of the latencies are 0, so y falls back to the symmetric log. */
+export const LogAxes: Story = {
+	args: {
+		groups: 5,
+		pointsPerGroup: 60,
+		xScale: ScatterAxisScale.Log,
+		yScale: ScatterAxisScale.Log,
+		withZeros: true,
+	},
+};
+
+/** A single point still gets a padded range rather than an empty plot. */
+export const SinglePoint: Story = {
+	args: { shape: 'single' },
+};
+
+/** Fifty points sharing one x collide on nothing: no shared x array to align. */
+export const SameX: Story = {
+	args: { groups: 3, pointsPerGroup: 50, shape: 'sameX' },
+};
+
+/** Horizontal line with label on the y axis; the scale stretches to include it. */
+export const Thresholds: Story = {
+	args: { groups: 3, pointsPerGroup: 40, thresholds: true },
+};
+
+/** Perf harness: raise `pointsPerGroup` and read the draw time under the chart. */
+export const Dense: Story = {
+	args: { groups: 5, pointsPerGroup: 1000, pointSize: 4, fillOpacity: 0.5 },
+};

frontend/src/lib/visualization/charts/Scatter/Scatter.tsx

@@ -0,0 +1,98 @@
+import { useCallback, useRef } from 'react';
+import ChartWrapper from 'lib/visualization/charts/ChartWrapper/ChartWrapper';
+import ScatterTooltip from 'lib/uPlotV2/components/Tooltip/ScatterTooltip';
+import {
+	ScatterTooltipProps,
+	TooltipRenderArgs,
+} from 'lib/uPlotV2/components/types';
+import { getSeriesStroke } from 'lib/uPlotV2/plugins/ScatterPlugin/scatterPlugin';
+import type { ChartClickData } from 'lib/uPlotV2/plugins/TooltipPlugin/types';
+import { ScatterChartProps } from 'lib/visualization/charts/types';
+import uPlot from 'uplot';
+
+import { getCursorHit } from './utils';
+
+// Faceted uPlot can't mount without series; empty aligned data shows no-data instead.
+const EMPTY_ALIGNED_DATA: uPlot.AlignedData = [[]];
+
+export default function Scatter(props: ScatterChartProps): JSX.Element {
+	const {
+		children,
+		customTooltip,
+		channels,
+		resolvePointLabels,
+		pinnedTooltipElement,
+		onPointClick,
+		plotRef,
+		...rest
+	} = props;
+
+	const plotInstanceRef = useRef<uPlot | null>(null);
+
+	const handlePlotRef = useCallback(
+		(plot: uPlot | null): void => {
+			plotInstanceRef.current = plot;
+			plotRef?.(plot);
+		},
+		[plotRef],
+	);
+
+	// Faceted plots have no shared x; take the hit from the cursor.
+	const handleClick = useCallback(
+		(click: ChartClickData): void => {
+			const plot = plotInstanceRef.current;
+			const hit = plot ? getCursorHit(plot) : null;
+			if (!plot || !hit || !onPointClick) {
+				return;
+			}
+			onPointClick({
+				...hit,
+				color: getSeriesStroke(plot, hit.seriesIndex),
+				coordinates: { x: click.absoluteMouseX, y: click.absoluteMouseY },
+			});
+		},
+		[onPointClick],
+	);
+
+	const renderTooltip = useCallback(
+		(args: TooltipRenderArgs): React.ReactNode => {
+			if (customTooltip) {
+				return customTooltip(args);
+			}
+			const tooltipProps: ScatterTooltipProps = {
+				...args,
+				id: rest.config.getId(),
+				channels,
+				resolvePointLabels,
+				decimalPrecision: rest.decimalPrecision,
+				canPinTooltip: rest.canPinTooltip,
+				renderTooltipFooter: rest.renderTooltipFooter,
+			};
+			return <ScatterTooltip {...tooltipProps} />;
+		},
+		[
+			customTooltip,
+			channels,
+			resolvePointLabels,
+			rest.config,
+			rest.decimalPrecision,
+			rest.canPinTooltip,
+			rest.renderTooltipFooter,
+		],
+	);
+
+	const hasSeries = rest.data.length > 1;
+
+	return (
+		<ChartWrapper
+			{...rest}
+			data={hasSeries ? rest.data : EMPTY_ALIGNED_DATA}
+			plotRef={handlePlotRef}
+			onClick={onPointClick ? handleClick : rest.onClick}
+			customTooltip={renderTooltip}
+			pinnedTooltipElement={pinnedTooltipElement}
+		>
+			{children}
+		</ChartWrapper>
+	);
+}

frontend/src/lib/visualization/charts/Scatter/__tests__/scatterRange.test.ts

@@ -0,0 +1,97 @@
+import { DistributionType } from 'lib/uPlotV2/config/types';
+import uPlot from 'uplot';
+
+import { createScatterRange, type ScatterRangeOptions } from '../scatterRange';
+
+/** A 220px-tall, 420px-wide plot at a device pixel ratio of 1. */
+const plot = { bbox: { width: 420, height: 220 } } as unknown as uPlot;
+
+function rangeOf(
+	options: Partial<ScatterRangeOptions>,
+	dataMin: number | null,
+	dataMax: number | null,
+): [number, number] {
+	const range = createScatterRange({
+		dimension: 'y',
+		marginPx: 10,
+		distribution: DistributionType.Linear,
+		...options,
+	}) as (u: uPlot, min: number | null, max: number | null) => [number, number];
+	return range(plot, dataMin, dataMax);
+}
+
+describe('createScatterRange', () => {
+	beforeAll(() => {
+		Object.defineProperty(uPlot, 'pxRatio', { value: 1, configurable: true });
+	});
+
+	it('widens a linear range so the data sits marginPx inside each edge', () => {
+		// 200px of data inside 220px: 10px at each end is 1/20 of the span.
+		expect(rangeOf({}, 0, 100)).toStrictEqual([-5, 105]);
+	});
+
+	it('measures the margin along its own axis', () => {
+		// 400px of data inside 420px.
+		expect(rangeOf({ dimension: 'x' }, 0, 100)).toStrictEqual([-2.5, 102.5]);
+	});
+
+	it('pads a log range in decades, without snapping to the next power of ten', () => {
+		const [min, max] = rangeOf(
+			{ distribution: DistributionType.Logarithmic },
+			1,
+			10,
+		);
+		expect(Math.log10(min)).toBeCloseTo(-0.05);
+		expect(Math.log10(max)).toBeCloseTo(1.05);
+	});
+
+	it('pads a symmetric log range in its asinh space', () => {
+		const [min, max] = rangeOf(
+			{ distribution: DistributionType.SymmetricLog, asinhThreshold: 2 },
+			0,
+			20,
+		);
+		const span = Math.asinh(10);
+		expect(Math.asinh(min / 2)).toBeCloseTo(-span / 20);
+		expect(Math.asinh(max / 2)).toBeCloseTo(span + span / 20);
+	});
+
+	it('stretches to the soft limits before padding', () => {
+		expect(rangeOf({ softMin: 0, softMax: 200 }, 50, 100)).toStrictEqual([
+			-10, 210,
+		]);
+	});
+
+	it('ignores a soft min at or below zero on a log scale', () => {
+		const [min] = rangeOf(
+			{ distribution: DistributionType.Logarithmic, softMin: 0 },
+			10,
+			100,
+		);
+		expect(min).toBeGreaterThan(0);
+	});
+
+	it('spreads a single value around itself', () => {
+		const [min, max] = rangeOf({}, 5, 5);
+		expect(min).toBeLessThan(5);
+		expect(max).toBeGreaterThan(5);
+		expect(5 - min).toBeCloseTo(max - 5);
+	});
+
+	it('falls back to a unit range with no data', () => {
+		expect(rangeOf({}, null, null)).toStrictEqual([0, 1]);
+		expect(
+			rangeOf({ distribution: DistributionType.Logarithmic }, null, null),
+		).toStrictEqual([1, 10]);
+	});
+
+	it('skips the margin on a plot too small to hold it', () => {
+		const tiny = { bbox: { width: 15, height: 15 } } as unknown as uPlot;
+		const range = createScatterRange({
+			dimension: 'y',
+			marginPx: 10,
+			distribution: DistributionType.Linear,
+		}) as (u: uPlot, min: number, max: number) => [number, number];
+		expect(range(tiny, 0, 100)).toStrictEqual([0, 100]);
+	});
+});

frontend/src/lib/visualization/charts/Scatter/__tests__/utils.test.ts

@@ -0,0 +1,243 @@
+import type uPlot from 'uplot';
+import { DistributionType } from 'lib/uPlotV2/config/types';
+
+import {
+	buildScatterConfig,
+	getCursorHit,
+	prepareScatterChartData,
+	resolveAxisDistribution,
+	ScatterAxisScale,
+	ScatterSeries,
+} from '../utils';
+
+jest.mock('lib/visualization/panels/utils/legendVisibilityUtils', () => ({
+	getStoredSeriesVisibility: jest.fn(),
+}));
+
+const SERIES: ScatterSeries[] = [
+	{ label: 'cart', xs: [10, 20], ys: [100, 200], sizes: [1, null] },
+	{ label: 'checkout', xs: [30], ys: [0] },
+];
+
+describe('prepareScatterChartData', () => {
+	it('lays series out as facets behind an empty x slot', () => {
+		expect(prepareScatterChartData(SERIES)).toStrictEqual([
+			null,
+			[
+				[10, 20],
+				[100, 200],
+				[1, null],
+			],
+			[[30], [0]],
+		]);
+	});
+});
+
+describe('getCursorHit', () => {
+	const plotWith = (idxs: Array<number | null>): uPlot =>
+		({ cursor: { idxs } }) as unknown as uPlot;
+
+	it('reads the series the scatter plugin answered for', () => {
+		expect(getCursorHit(plotWith([null, null, 4, null]))).toStrictEqual({
+			seriesIndex: 2,
+			dataIndex: 4,
+		});
+	});
+
+	it('takes a data index of 0 as a hit', () => {
+		expect(getCursorHit(plotWith([0, 0]))).toStrictEqual({
+			seriesIndex: 1,
+			dataIndex: 0,
+		});
+	});
+
+	it('is null off every dot', () => {
+		expect(getCursorHit(plotWith([null, null]))).toBeNull();
+		expect(getCursorHit({ cursor: {} } as unknown as uPlot)).toBeNull();
+	});
+});
+
+describe('resolveAxisDistribution', () => {
+	it('is linear when asked, whatever the values', () => {
+		expect(
+			resolveAxisDistribution([1, 1e6], ScatterAxisScale.Linear),
+		).toStrictEqual({ distribution: DistributionType.Linear });
+	});
+
+	it('is a plain log when every value is positive', () => {
+		expect(resolveAxisDistribution([1, 100], ScatterAxisScale.Log)).toStrictEqual(
+			{ distribution: DistributionType.Logarithmic },
+		);
+	});
+
+	it('falls back from log to a symmetric log around the smallest magnitude when zero is present', () => {
+		expect(
+			resolveAxisDistribution([0, 0.05, 300], ScatterAxisScale.Log),
+		).toStrictEqual({
+			distribution: DistributionType.SymmetricLog,
+			asinhThreshold: 0.01,
+		});
+	});
+
+	it('keeps an explicit log axis for a soft min it cannot place', () => {
+		expect(
+			resolveAxisDistribution([1, 100], ScatterAxisScale.Log, [-10]),
+		).toStrictEqual({ distribution: DistributionType.Logarithmic });
+	});
+
+	it('is a symmetric log when asked, even with only positive values', () => {
+		expect(
+			resolveAxisDistribution([2, 300], ScatterAxisScale.SymLog),
+		).toStrictEqual({
+			distribution: DistributionType.SymmetricLog,
+			asinhThreshold: 1,
+		});
+	});
+
+	it('uses a unit threshold when nothing is positive', () => {
+		expect(
+			resolveAxisDistribution([0, -5], ScatterAxisScale.SymLog),
+		).toStrictEqual({
+			distribution: DistributionType.SymmetricLog,
+			asinhThreshold: 1,
+		});
+	});
+
+	describe('auto', () => {
+		const SKEWED = [1, 2, 3, 5, 8, 10, 20, 50, 1000];
+
+		it.each([
+			['skewed positive values', SKEWED, DistributionType.Logarithmic],
+			[
+				'values spread evenly across decades',
+				[1, 250, 500, 750, 1000],
+				DistributionType.Linear,
+			],
+			[
+				'a single outlier among clustered values',
+				[0.001, 40, 45, 50, 55, 60],
+				DistributionType.Linear,
+			],
+			[
+				'skewed values spanning under two decades',
+				[10, 10, 10, 11, 50],
+				DistributionType.Linear,
+			],
+			['no finite values', [Number.NaN], DistributionType.Linear],
+		])('picks a scale for %s', (_, values, distribution) => {
+			expect(resolveAxisDistribution(values, ScatterAxisScale.Auto)).toStrictEqual(
+				{ distribution },
+			);
+		});
+
+		it('picks symlog for skewed values that include zero', () => {
+			expect(
+				resolveAxisDistribution(
+					[0, 0, 1, 2, 5, 10, 50, 100, 10_000],
+					ScatterAxisScale.Auto,
+				),
+			).toStrictEqual({
+				distribution: DistributionType.SymmetricLog,
+				asinhThreshold: 1,
+			});
+		});
+
+		it('picks symlog when a soft limit reaches zero or below', () => {
+			expect(
+				resolveAxisDistribution(SKEWED, ScatterAxisScale.Auto, [0]),
+			).toStrictEqual({
+				distribution: DistributionType.SymmetricLog,
+				asinhThreshold: 1,
+			});
+		});
+
+		it('counts a soft limit towards the decades it spans', () => {
+			expect(
+				resolveAxisDistribution([5, 50], ScatterAxisScale.Auto, [null, 5000]),
+			).toStrictEqual({ distribution: DistributionType.Logarithmic });
+		});
+
+		it('is the default', () => {
+			expect(resolveAxisDistribution(SKEWED)).toStrictEqual({
+				distribution: DistributionType.Logarithmic,
+			});
+		});
+	});
+});
+
+describe('buildScatterConfig', () => {
+	const build = (
+		overrides: Partial<Parameters<typeof buildScatterConfig>[0]> = {},
+	): ReturnType<typeof buildScatterConfig> =>
+		buildScatterConfig({
+			id: 'scatter',
+			series: SERIES,
+			isDarkMode: true,
+			x: { unit: 'reqps' },
+			y: { unit: 'ms', scale: ScatterAxisScale.Log },
+			...overrides,
+		});
+
+	it('draws a line along both plot edges', () => {
+		const [xAxis, yAxis] = build().getConfig().axes ?? [];
+
+		expect(xAxis?.border?.show).toBe(true);
+		expect(yAxis?.border?.show).toBe(true);
+	});
+
+	it('titles each axis with its label, and leaves an unlabelled one bare', () => {
+		const config = build({
+			x: { unit: 'reqps', label: 'Throughput' },
+			y: { unit: 'ms', label: '' },
+		}).getConfig();
+		const [xAxis, yAxis] = config.axes ?? [];
+
+		expect(xAxis?.label).toBe('Throughput');
+		expect(yAxis?.label).toBeUndefined();
+	});
+
+	it('emits a faceted plot with two value scales', () => {
+		const config = build().getConfig();
+
+		expect(config.mode).toBe(2);
+		expect(config.scales?.x).toMatchObject({ time: false, distr: 1 });
+		// The y column has a 0, so log becomes the symmetric variant.
+		expect(config.scales?.y).toMatchObject({ time: false, distr: 4 });
+	});
+
+	it('draws one faceted series per group with the plugin path builder', () => {
+		const config = build().getConfig();
+		const [, cart, checkout] = config.series ?? [];
+
+		expect(config.series).toHaveLength(3);
+		expect(cart).toMatchObject({
+			label: 'cart',
+			facets: [
+				{ scale: 'x', auto: true },
+				{ scale: 'y', auto: true },
+			],
+		});
+		expect(typeof cart?.paths).toBe('function');
+		expect(cart?.paths).toBe(checkout?.paths);
+		expect(cart?.points?.show).toBe(false);
+	});
+
+	it('formats both axes with their units', () => {
+		const config = build().getConfig();
+		const [xAxis, yAxis] = config.axes ?? [];
+
+		expect(xAxis).toMatchObject({ scale: 'x', side: 2, space: 90 });
+		expect(yAxis).toMatchObject({ scale: 'y', side: 3 });
+		expect(typeof xAxis?.values).toBe('function');
+		expect(typeof yAxis?.values).toBe('function');
+	});
+
+	it('registers a y threshold draw hook when thresholds are given', () => {
+		const config = build({
+			thresholds: [{ thresholdValue: 300, thresholdUnit: 'ms' }],
+		}).getConfig();
+
+		expect(config.hooks?.draw).toHaveLength(1);
+		expect(build().getConfig().hooks?.draw).toBeUndefined();
+	});
+});

frontend/src/lib/visualization/charts/Scatter/scatterRange.ts

@@ -0,0 +1,101 @@
+import { DistributionType } from 'lib/uPlotV2/config/types';
+import { DEFAULT_ASINH_THRESHOLD } from 'lib/uPlotV2/utils/scale';
+import uPlot from 'uplot';
+
+import type { AxisDistribution } from './utils';
+
+interface ScaleTransform {
+	forward: (value: number) => number;
+	inverse: (position: number) => number;
+}
+
+export function getScaleTransform({
+	distribution,
+	asinhThreshold = DEFAULT_ASINH_THRESHOLD,
+}: AxisDistribution): ScaleTransform {
+	switch (distribution) {
+		case DistributionType.Logarithmic:
+			return {
+				forward: (value): number => Math.log10(value),
+				inverse: (position): number => 10 ** position,
+			};
+		case DistributionType.SymmetricLog:
+			return {
+				forward: (value): number => Math.asinh(value / asinhThreshold),
+				inverse: (position): number => Math.sinh(position) * asinhThreshold,
+			};
+		default:
+			return {
+				forward: (value): number => value,
+				inverse: (position): number => position,
+			};
+	}
+}
+
+/** In transformed units. */
+const SINGLE_VALUE_HALF_SPAN = 0.5;
+
+/** The data's extent stretched to the soft limits; null with neither. */
+function resolveExtent(
+	dataMin: number | null,
+	dataMax: number | null,
+	softMin: number | null | undefined,
+	softMax: number | null | undefined,
+): [number, number] | null {
+	const lows = [dataMin, softMin].filter(
+		(value): value is number => value != null && Number.isFinite(value),
+	);
+	const highs = [dataMax, softMax].filter(
+		(value): value is number => value != null && Number.isFinite(value),
+	);
+	return lows.length > 0 && highs.length > 0
+		? [Math.min(...lows), Math.max(...highs)]
+		: null;
+}
+
+export interface ScatterRangeOptions extends AxisDistribution {
+	dimension: 'x' | 'y';
+	/** CSS pixels kept clear at each end so the largest dot draws whole. */
+	marginPx: number;
+	softMin?: number | null;
+	softMax?: number | null;
+}
+
+/** Data extent padded by `marginPx` so edge dots draw whole; log stays unsnapped (snapping after the margin can add an empty decade). */
+export function createScatterRange({
+	dimension,
+	marginPx,
+	softMin,
+	softMax,
+	...distribution
+}: ScatterRangeOptions): uPlot.Scale.Range {
+	const transform = getScaleTransform(distribution);
+	const isLog = distribution.distribution === DistributionType.Logarithmic;
+
+	// A log scale cannot place a soft limit at or below zero.
+	const usableSoftMin = isLog && (softMin ?? 0) <= 0 ? null : softMin;
+
+	return (u, dataMin, dataMax): uPlot.Range.MinMax => {
+		const extent = resolveExtent(dataMin, dataMax, usableSoftMin, softMax);
+		if (!extent) {
+			return isLog ? [1, 10] : [0, 1];
+		}
+
+		let start = transform.forward(extent[0]);
+		let end = transform.forward(extent[1]);
+		if (start === end) {
+			start -= SINGLE_VALUE_HALF_SPAN;
+			end += SINGLE_VALUE_HALF_SPAN;
+		}
+
+		const plotPx =
+			(dimension === 'x' ? u.bbox.width : u.bbox.height) / uPlot.pxRatio;
+		if (plotPx > 2 * marginPx) {
+			const pad = ((end - start) * marginPx) / (plotPx - 2 * marginPx);
+			start -= pad;
+			end += pad;
+		}
+
+		return [transform.inverse(start), transform.inverse(end)];
+	};
+}

frontend/src/lib/visualization/charts/Scatter/utils.ts

@@ -0,0 +1,366 @@
+import { PrecisionOption } from 'components/Graph/types';
+import {
+	type AxisProps,
+	DistributionType,
+	DrawStyle,
+	SelectionPreferencesSource,
+} from 'lib/uPlotV2/config/types';
+import { UPlotConfigBuilder } from 'lib/uPlotV2/config/UPlotConfigBuilder';
+import { Threshold } from 'lib/uPlotV2/hooks/types';
+import {
+	applyScatterPlugin,
+	createScatterPlugin,
+	SCATTER_FACETS,
+} from 'lib/uPlotV2/plugins/ScatterPlugin/scatterPlugin';
+import {
+	DEFAULT_SCATTER_POINT_SIZE,
+	ScatterChartData,
+	ScatterPointSize,
+	ScatterSeriesData,
+} from 'lib/uPlotV2/plugins/ScatterPlugin/types';
+import {
+	logScaleSplits,
+	spacedLogLabels,
+} from 'lib/uPlotV2/utils/logGridSplits';
+import { adjustSoftLimitsWithThresholds } from 'lib/uPlotV2/utils/scale';
+import uPlot from 'uplot';
+
+import { createScatterRange, getScaleTransform } from './scatterRange';
+
+const POINT_STROKE_WIDTH = 1;
+
+/** Unit-suffixed x labels are wider than uPlot's 50px default assumes. */
+const X_AXIS_TICK_SPACE_PX = 90;
+const X_AXIS_END_LABEL_PADDING_PX = 40;
+
+export interface ScatterSeries {
+	label: string;
+	xs: number[];
+	ys: number[];
+	/** Optional third channel, in the caller's units. */
+	sizes?: Array<number | null>;
+}
+
+export enum ScatterAxisScale {
+	/** Log or symlog when it spreads the points out more than linear does. */
+	Auto = 'auto',
+	Linear = 'linear',
+	Log = 'log',
+	/** Log-like, but places zero and negatives. */
+	SymLog = 'symlog',
+}
+
+export interface ScatterAxisOptions {
+	label?: string;
+	unit?: string;
+	softMin?: number | null;
+	softMax?: number | null;
+	scale?: ScatterAxisScale;
+}
+
+export interface BuildScatterConfigArgs {
+	id: string;
+	series: ScatterSeries[];
+	isDarkMode: boolean;
+	x: ScatterAxisOptions;
+	y: ScatterAxisOptions;
+	pointSize?: ScatterPointSize;
+	/** 0–1. */
+	fillOpacity?: number;
+	colorMapping?: Record<string, string>;
+	/** Drawn on the y axis. */
+	thresholds?: Threshold[];
+	decimalPrecision?: PrecisionOption;
+	selectionPreferencesSource?: SelectionPreferencesSource;
+	shouldSaveSelectionPreference?: boolean;
+}
+
+/** The plugin's `dataIdx` answers only for the hit series. */
+export function getCursorHit(
+	plot: uPlot,
+): { seriesIndex: number; dataIndex: number } | null {
+	const idxs = plot.cursor.idxs ?? [];
+	for (let seriesIndex = 1; seriesIndex < idxs.length; seriesIndex++) {
+		const dataIndex = idxs[seriesIndex];
+		if (dataIndex != null) {
+			return { seriesIndex, dataIndex };
+		}
+	}
+	return null;
+}
+
+/** `[null, [xs, ys, sizes?], …]`: uPlot's faceted layout, series 0 empty. */
+export function prepareScatterChartData(
+	series: ScatterSeries[],
+): uPlot.AlignedData {
+	const data: ScatterChartData = [
+		null,
+		...series.map(
+			(entry): ScatterSeriesData =>
+				entry.sizes ? [entry.xs, entry.ys, entry.sizes] : [entry.xs, entry.ys],
+		),
+	];
+	return data as unknown as uPlot.AlignedData;
+}
+
+export interface AxisDistribution {
+	distribution: DistributionType;
+	asinhThreshold?: number;
+}
+
+const LINEAR_DISTRIBUTION: AxisDistribution = {
+	distribution: DistributionType.Linear,
+};
+
+/** Orders of magnitude `auto` needs before it considers leaving linear. */
+export const AUTO_MIN_DECADES = 2;
+
+/** How many times more axis the middle half of the points must cover for `auto` to leave linear. */
+export const AUTO_SPREAD_GAIN = 2;
+
+function getMagnitudeRange(values: number[]): {
+	minMagnitude: number;
+	maxMagnitude: number;
+	hasNonPositive: boolean;
+} {
+	let minMagnitude = Infinity;
+	let maxMagnitude = -Infinity;
+	let hasNonPositive = false;
+	for (const value of values) {
+		if (!Number.isFinite(value)) {
+			continue;
+		}
+		if (value <= 0) {
+			hasNonPositive = true;
+		}
+		if (value !== 0) {
+			minMagnitude = Math.min(minMagnitude, Math.abs(value));
+			maxMagnitude = Math.max(maxMagnitude, Math.abs(value));
+		}
+	}
+	return { minMagnitude, maxMagnitude, hasNonPositive };
+}
+
+/** The linear band ends at the smallest non-zero magnitude so small values still spread. */
+function symmetricLogDistribution(minMagnitude: number): AxisDistribution {
+	const asinhThreshold = Number.isFinite(minMagnitude)
+		? 10 ** Math.floor(Math.log10(minMagnitude))
+		: 1;
+	return { distribution: DistributionType.SymmetricLog, asinhThreshold };
+}
+
+function quantile(sorted: number[], q: number): number {
+	const position = (sorted.length - 1) * q;
+	const lower = Math.floor(position);
+	const upper = Math.ceil(position);
+	return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+
+/** Share of the axis the middle half of the points covers. */
+function middleHalfSpread(
+	sorted: number[],
+	[min, max]: [number, number],
+	distribution: AxisDistribution,
+): number {
+	const { forward } = getScaleTransform(distribution);
+	const span = forward(max) - forward(min);
+	return span > 0
+		? (forward(quantile(sorted, 0.75)) - forward(quantile(sorted, 0.25))) / span
+		: 0;
+}
+
+/**
+ * Log (symlog with zero or negatives) when it spreads the points out clearly
+ * more than linear does; min/max alone would let one outlier decide.
+ */
+function resolveAutoDistribution(
+	values: number[],
+	softLimits: number[],
+): AxisDistribution {
+	const sorted = values
+		.filter((value) => Number.isFinite(value))
+		.sort((a, b) => a - b);
+	if (sorted.length < 2) {
+		return LINEAR_DISTRIBUTION;
+	}
+	const { minMagnitude, maxMagnitude, hasNonPositive } = getMagnitudeRange([
+		...sorted,
+		...softLimits,
+	]);
+	if (!(Math.log10(maxMagnitude / minMagnitude) >= AUTO_MIN_DECADES)) {
+		return LINEAR_DISTRIBUTION;
+	}
+	const candidate = hasNonPositive
+		? symmetricLogDistribution(minMagnitude)
+		: { distribution: DistributionType.Logarithmic };
+	const extent: [number, number] = [
+		Math.min(sorted[0], ...softLimits),
+		Math.max(sorted[sorted.length - 1], ...softLimits),
+	];
+	const candidateSpread = middleHalfSpread(sorted, extent, candidate);
+	const linearSpread = middleHalfSpread(sorted, extent, LINEAR_DISTRIBUTION);
+	return candidateSpread > 0 &&
+		candidateSpread >= AUTO_SPREAD_GAIN * linearSpread
+		? candidate
+		: LINEAR_DISTRIBUTION;
+}
+
+/** `log` falls back to symlog rather than drop zero or negatives; callers filter first to drop them. */
+export function resolveAxisDistribution(
+	values: number[],
+	scale: ScatterAxisScale = ScatterAxisScale.Auto,
+	/** Soft limits and thresholds the axis must reach; only `auto` weighs them. */
+	softLimits: Array<number | null | undefined> = [],
+): AxisDistribution {
+	switch (scale) {
+		case ScatterAxisScale.Linear:
+			return LINEAR_DISTRIBUTION;
+		case ScatterAxisScale.SymLog:
+			return symmetricLogDistribution(getMagnitudeRange(values).minMagnitude);
+		case ScatterAxisScale.Log: {
+			const { minMagnitude, hasNonPositive } = getMagnitudeRange(values);
+			return hasNonPositive
+				? symmetricLogDistribution(minMagnitude)
+				: { distribution: DistributionType.Logarithmic };
+		}
+		case ScatterAxisScale.Auto:
+		default:
+			return resolveAutoDistribution(
+				values,
+				softLimits.filter(
+					(limit): limit is number => limit != null && Number.isFinite(limit),
+				),
+			);
+	}
+}
+
+/** The scatter range is unsnapped, so a log axis places and labels its own ticks. */
+function getLogAxisTicks({
+	distribution,
+}: AxisDistribution): Pick<AxisProps, 'splits' | 'filter'> {
+	return distribution === DistributionType.Logarithmic
+		? { splits: logScaleSplits, filter: spacedLogLabels }
+		: {};
+}
+
+export function buildScatterConfig({
+	id,
+	series,
+	isDarkMode,
+	x,
+	y,
+	pointSize = DEFAULT_SCATTER_POINT_SIZE,
+	fillOpacity,
+	colorMapping = {},
+	thresholds,
+	decimalPrecision,
+	selectionPreferencesSource,
+	shouldSaveSelectionPreference,
+}: BuildScatterConfigArgs): UPlotConfigBuilder {
+	const builder = new UPlotConfigBuilder({
+		id,
+		selectionPreferencesSource,
+		shouldSaveSelectionPreference,
+	});
+
+	const plugin = createScatterPlugin({ pointSize });
+	applyScatterPlugin(builder, plugin);
+	// The last x label is centred on the plot's right edge; room for its unit.
+	builder.setPadding([16, X_AXIS_END_LABEL_PADDING_PX, 8, 8]);
+
+	const ySoftLimits = adjustSoftLimitsWithThresholds(
+		y.softMin ?? null,
+		y.softMax ?? null,
+		thresholds,
+		y.unit,
+	);
+	const xDistribution = resolveAxisDistribution(
+		series.flatMap((entry) => entry.xs),
+		x.scale,
+		[x.softMin, x.softMax],
+	);
+	const yDistribution = resolveAxisDistribution(
+		series.flatMap((entry) => entry.ys),
+		y.scale,
+		[ySoftLimits.softMin, ySoftLimits.softMax],
+	);
+
+	const yThresholds =
+		thresholds && thresholds.length > 0
+			? { scaleKey: 'y', thresholds, yAxisUnit: y.unit }
+			: undefined;
+
+	// The largest disc drawn, plus its outline, kept clear of each plot edge.
+	const largestDiameter = series.some((entry) => entry.sizes)
+		? pointSize.max
+		: pointSize.fixed;
+	const marginPx = largestDiameter / 2 + POINT_STROKE_WIDTH;
+
+	builder.addScale({
+		scaleKey: 'x',
+		time: false,
+		range: createScatterRange({
+			dimension: 'x',
+			marginPx,
+			softMin: x.softMin,
+			softMax: x.softMax,
+			...xDistribution,
+		}),
+		...xDistribution,
+	});
+	builder.addScale({
+		scaleKey: 'y',
+		time: false,
+		range: createScatterRange({
+			dimension: 'y',
+			marginPx,
+			...ySoftLimits,
+			...yDistribution,
+		}),
+		...yDistribution,
+	});
+
+	builder.addAxis({
+		scaleKey: 'x',
+		side: 2,
+		label: x.label || undefined,
+		isDarkMode,
+		isTimeAxis: false,
+		yAxisUnit: x.unit ?? '',
+		decimalPrecision,
+		isLogScale: xDistribution.distribution !== DistributionType.Linear,
+		...getLogAxisTicks(xDistribution),
+		space: X_AXIS_TICK_SPACE_PX,
+	});
+	builder.addAxis({
+		scaleKey: 'y',
+		side: 3,
+		label: y.label || undefined,
+		isDarkMode,
+		yAxisUnit: y.unit ?? '',
+		decimalPrecision,
+		isLogScale: yDistribution.distribution !== DistributionType.Linear,
+		...getLogAxisTicks(yDistribution),
+	});
+
+	series.forEach((entry) => {
+		builder.addSeries({
+			scaleKey: 'y',
+			label: entry.label,
+			colorMapping,
+			drawStyle: DrawStyle.Scatter,
+			pathBuilder: plugin.pathBuilder,
+			facets: SCATTER_FACETS,
+			lineWidth: POINT_STROKE_WIDTH,
+			pointSize: pointSize.fixed,
+			fillOpacity,
+			isDarkMode,
+		});
+	});
+
+	if (yThresholds) {
+		builder.addThresholds(yThresholds);
+	}
+
+	return builder;
+}

frontend/src/lib/visualization/charts/types.ts

@@ -16,6 +16,10 @@ import type {
 	HeatmapColorOptions,
 	HeatmapSeries,
 } from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import type {
+	ScatterChannels,
+	ScatterPointLabel,
+} from 'lib/uPlotV2/plugins/ScatterPlugin/types';
 import {
 	DashboardCursorSync,
 	SyncTooltipFilterMode,
@@ -88,6 +92,26 @@ export interface HistogramChartProps extends ChartWrapperProps {
 	isQueriesMerged?: boolean;
 }
 
+/** The dot a click landed on; `seriesIndex` is uPlot's, so the first series is 1. */
+export interface ScatterPointClick {
+	seriesIndex: number;
+	dataIndex: number;
+	color: string;
+	/** Viewport coordinates of the click. */
+	coordinates: { x: number; y: number };
+}
+
+/** `data` is mode-2 (`prepareScatterChartData`); `config` comes from `buildScatterConfig`. */
+export interface ScatterChartProps extends ChartWrapperProps {
+	channels: ScatterChannels;
+	resolvePointLabels?: (
+		seriesIndex: number,
+		dataIndex: number,
+	) => ScatterPointLabel[];
+	/** Fires for a click on a dot; a click on empty plot space fires nothing. */
+	onPointClick?: (click: ScatterPointClick) => void;
+}
+
 /**
  * Data arrives as the query response carries it — bucket bounds plus one series per
  * group — and the chart pivots and sums it, so no caller has to get the transpose

pkg/apiserver/signozapiserver/tracedetail.go

@@ -90,7 +90,7 @@ func (provider *provider) addTraceDetailRoutes(router *mux.Router) error {
 			ID:                  "GetTraceThread",
 			Tags:                []string{"tracedetail"},
 			Summary:             "Get thread view for a trace",
-			Description:         "Returns the gen_ai spans of a trace, model calls, tool calls and agent spans, in timestamp order. The messages a span carries are decoded into formatted_input and formatted_output, with formatter naming the converter and formatter_warnings what it could not resolve; a span without messages has both empty. Pass nextCursor as after or prevCursor as before to page, or spanId to open the page around a span.",
+			Description:         "Returns the spans carrying gen_ai input or output messages, or a tool execution, in timestamp order. Messages already in the OTel GenAI shape are decoded into formatted_input and formatted_output, with formatter naming the converter and formatter_warnings what it could not resolve. Pass nextCursor as after or prevCursor as before to page, or spanId to open the page around a span.",
 			RequestQuery:        new(spantypes.GetTraceThreadParams),
 			Response:            new(spantypes.GettableTraceThread),
 			ResponseContentType: "application/json",

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,

pkg/modules/tracedetail/impltracedetail/store.go

@@ -297,11 +297,11 @@ func (s *traceStore) GetThreadSpans(ctx context.Context, orgID valuer.UUID, trac
 		sb.SelectMore("attributes")
 	}
 	sb.From(fmt.Sprintf("%s.%s", spantypes.TraceDB, spantypes.TraceTable))
-	keys, err := s.genAIFieldKeys(ctx, orgID, aiobservabilitytypes.GenAISpanGateKeys)
+	keys, err := s.genAIFieldKeys(ctx, orgID, aiobservabilitytypes.GenAIThreadKeys)
 	if err != nil {
 		return nil, err
 	}
-	isThreadSpan, err := s.anyExistsCondition(ctx, q, aiobservabilitytypes.GenAISpanGateKeys, keys, sb)
+	isThreadSpan, err := s.anyExistsCondition(ctx, q, aiobservabilitytypes.GenAIThreadKeys, keys, sb)
 	if err != nil {
 		return nil, err
 	}

pkg/modules/tracedetail/impltracedetail/store_test.go

@@ -220,14 +220,14 @@ func TestGetThreadSpans(t *testing.T) {
 			name:        "FlagOff_ReadsAndFiltersLegacyMaps",
 			jsonRelease: &jsonInsideTrace,
 			selectSQL:   selectSQL,
-			whereSQL:    "(mapContains(attributes_string, 'gen_ai.request.model') OR mapContains(attributes_string, 'gen_ai.tool.name') OR mapContains(attributes_string, 'gen_ai.agent.name'))",
+			whereSQL:    "(mapContains(attributes_string, 'gen_ai.input.messages') OR mapContains(attributes_string, 'gen_ai.output.messages') OR mapContains(attributes_string, 'gen_ai.tool.name'))",
 		},
 		{
 			name:        "FlagOn_ReleasedDuringTrace_ReadsJSONFiltersJSONThenMaps",
 			jsonOn:      true,
 			jsonRelease: &jsonInsideTrace,
 			selectSQL:   selectSQL + ", attributes",
-			whereSQL:    "(multiIf(attributes.`gen_ai.request.model` IS NOT NULL, attributes.`gen_ai.request.model`::String, mapContains(attributes_string, 'gen_ai.request.model'), attributes_string['gen_ai.request.model'], NULL) IS NOT NULL OR multiIf(attributes.`gen_ai.tool.name` IS NOT NULL, attributes.`gen_ai.tool.name`::String, mapContains(attributes_string, 'gen_ai.tool.name'), attributes_string['gen_ai.tool.name'], NULL) IS NOT NULL OR multiIf(attributes.`gen_ai.agent.name` IS NOT NULL, attributes.`gen_ai.agent.name`::String, mapContains(attributes_string, 'gen_ai.agent.name'), attributes_string['gen_ai.agent.name'], NULL) IS NOT NULL)",
+			whereSQL:    "(multiIf(attributes.`gen_ai.input.messages` IS NOT NULL, attributes.`gen_ai.input.messages`::String, mapContains(attributes_string, 'gen_ai.input.messages'), attributes_string['gen_ai.input.messages'], NULL) IS NOT NULL OR multiIf(attributes.`gen_ai.output.messages` IS NOT NULL, attributes.`gen_ai.output.messages`::String, mapContains(attributes_string, 'gen_ai.output.messages'), attributes_string['gen_ai.output.messages'], NULL) IS NOT NULL OR multiIf(attributes.`gen_ai.tool.name` IS NOT NULL, attributes.`gen_ai.tool.name`::String, mapContains(attributes_string, 'gen_ai.tool.name'), attributes_string['gen_ai.tool.name'], NULL) IS NOT NULL)",
 		},
 	}
 

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

@@ -2,7 +2,6 @@ package logparsingpipeline
 
 import (
 	"encoding/json"
-	"slices"
 	"strings"
 	"sync"
 
@@ -25,13 +24,10 @@ var (
 )
 
 const (
-	memoryLimiterProcessor        = "memory_limiter"
-	memoryLimiterProcessorPrefix  = "memory_limiter/"
-	batchProcessor                = "batch"
-	batchProcessorPrefix          = "batch/"
-	normalizerProcessor           = "signozlogsnormalizer"
-	normalizerProcessorPrefix     = "signozlogsnormalizer/"
-	normalizerBeforeUserPipelines = "before"
+	memoryLimiterProcessor       = "memory_limiter"
+	memoryLimiterProcessorPrefix = "memory_limiter/"
+	batchProcessor               = "batch"
+	batchProcessorPrefix         = "batch/"
 )
 
 // check if the processors already exist
@@ -94,14 +90,9 @@ func getOtelPipelineFromConfig(config map[string]interface{}) (*otelPipeline, er
 //  2. signoz user-pipeline processors (in the order given by signozPipelineProcessorNames)
 //  3. custom processors (non-signoz, non-memory_limiter, non-batch processors from the current config)
 //  4. batch processors (any processor named "batch" or "batch/<id>") and anything after them
-//
-// If a signozlogsnormalizer processor is present, the order above is skipped: the first one
-// runs right after user-pipeline processors, or right before them when its config sets
-// `opamp.position: before`, and the other processors keep their places.
 func buildCollectorPipelineProcessorsList(
 	currentCollectorProcessors []string,
 	signozPipelineProcessorNames []string,
-	processorConfigs map[string]interface{},
 ) ([]string, error) {
 	lockLogsPipelineSpec.Lock()
 	defer lockLogsPipelineSpec.Unlock()
@@ -112,23 +103,6 @@ func buildCollectorPipelineProcessorsList(
 		userPipelineSet[p] = struct{}{}
 	}
 
-	if normalizerIdx := slices.IndexFunc(currentCollectorProcessors, isNormalizerProcessor); normalizerIdx >= 0 {
-		normalizerFirst := opampPosition(processorConfigs, currentCollectorProcessors[normalizerIdx]) == normalizerBeforeUserPipelines
-		result := make([]string, 0, len(currentCollectorProcessors)+len(signozPipelineProcessorNames))
-		for idx, p := range currentCollectorProcessors {
-			if idx == normalizerIdx && !normalizerFirst {
-				result = append(result, signozPipelineProcessorNames...)
-			}
-			if _, inUserPipelines := userPipelineSet[p]; !inUserPipelines && !hasSignozPipelineProcessorPrefix(p) {
-				result = append(result, p)
-			}
-			if idx == normalizerIdx && normalizerFirst {
-				result = append(result, signozPipelineProcessorNames...)
-			}
-		}
-		return result, nil
-	}
-
 	var memoryLimiters []string
 	var customProcessors []string
 	batchIdx := -1
@@ -161,51 +135,13 @@ func buildCollectorPipelineProcessorsList(
 	return result, nil
 }
 
-func isNormalizerProcessor(name string) bool {
-	return name == normalizerProcessor || strings.HasPrefix(name, normalizerProcessorPrefix)
-}
-
-// collectorNormalizesFirst reports whether the logs pipeline of the collector config runs
-// signozlogsnormalizer ahead of user pipelines, judged by the first one as in buildCollectorPipelineProcessorsList.
-// Malformed configs report false; generateCollectorConfigWithPipelines surfaces their errors.
-func collectorNormalizesFirst(collectorConf map[string]interface{}) bool {
-	p, err := getOtelPipelineFromConfig(collectorConf)
-	if err != nil || p.Pipelines.Logs == nil {
-		return false
-	}
-	normalizerIdx := slices.IndexFunc(p.Pipelines.Logs.Processors, isNormalizerProcessor)
-	if normalizerIdx < 0 {
-		return false
-	}
-	processorConfigs, _ := collectorConf["processors"].(map[string]interface{})
-	return opampPosition(processorConfigs, p.Pipelines.Logs.Processors[normalizerIdx]) == normalizerBeforeUserPipelines
-}
-
-func opampPosition(processorConfigs map[string]interface{}, name string) string {
-	config, _ := processorConfigs[name].(map[string]interface{})
-	opamp, _ := config["opamp"].(map[string]interface{})
-	position, _ := opamp["position"].(string)
-	return position
-}
-
-func unmarshalCollectorConfig(config []byte) (map[string]interface{}, error) {
+func GenerateCollectorConfigWithPipelines(config []byte, pipelines []pipelinetypes.GettablePipeline) ([]byte, error) {
 	var collectorConf map[string]interface{}
-	if err := yaml.Unmarshal(config, &collectorConf); err != nil {
+	err := yaml.Unmarshal([]byte(config), &collectorConf)
+	if err != nil {
 		return nil, errors.WrapInvalidInputf(err, CodeCollectorConfigUnmarshalFailed, "could not unmarshal collector config")
 	}
-	return collectorConf, nil
-}
 
-func GenerateCollectorConfigWithPipelines(config []byte, pipelines []pipelinetypes.GettablePipeline) ([]byte, error) {
-	collectorConf, err := unmarshalCollectorConfig(config)
-	if err != nil {
-		return nil, err
-	}
-	return generateCollectorConfigWithPipelines(collectorConf, pipelines)
-}
-
-// generateCollectorConfigWithPipelines modifies collectorConf in place.
-func generateCollectorConfigWithPipelines(collectorConf map[string]any, pipelines []pipelinetypes.GettablePipeline) ([]byte, error) {
 	signozPipelineProcessors, signozPipelineProcNames, err := PreparePipelineProcessor(pipelines)
 	if err != nil {
 		return nil, err
@@ -244,11 +180,11 @@ func generateCollectorConfigWithPipelines(collectorConf map[string]any, pipeline
 		return nil, errors.NewInternalf(CodeCollectorConfigLogsPipelineNotFound, "logs pipeline doesn't exist")
 	}
 
-	updatedProcessorList, _ := buildCollectorPipelineProcessorsList(p.Pipelines.Logs.Processors, signozPipelineProcNames, collectorConf["processors"].(map[string]any))
+	updatedProcessorList, _ := buildCollectorPipelineProcessorsList(p.Pipelines.Logs.Processors, signozPipelineProcNames)
 	p.Pipelines.Logs.Processors = updatedProcessorList
 
 	// add the new processor to the data ( no checks required as the keys will exists)
-	collectorConf["service"].(map[string]any)["pipelines"].(map[string]any)["logs"] = p.Pipelines.Logs
+	collectorConf["service"].(map[string]interface{})["pipelines"].(map[string]interface{})["logs"] = p.Pipelines.Logs
 
 	updatedConf, err := yaml.Marshal(collectorConf)
 	if err != nil {

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

@@ -5,14 +5,11 @@ import (
 	"fmt"
 	"testing"
 
-	"github.com/SigNoz/signoz/pkg/flagger/flaggertest"
 	"github.com/SigNoz/signoz/pkg/query-service/constants"
 	"github.com/SigNoz/signoz/pkg/query-service/model"
 	v3 "github.com/SigNoz/signoz/pkg/query-service/model/v3"
 	"github.com/SigNoz/signoz/pkg/types/pipelinetypes"
-	"github.com/SigNoz/signoz/pkg/valuer"
 	. "github.com/smartystreets/goconvey/convey"
-	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"gopkg.in/yaml.v3"
 )
@@ -209,74 +206,13 @@ var BuildLogsPipelineTestData = []struct {
 func TestBuildLogsPipeline(t *testing.T) {
 	for _, test := range BuildLogsPipelineTestData {
 		Convey(test.Name, t, func() {
-			v, err := buildCollectorPipelineProcessorsList(test.fromCollector, test.userPipelines, nil)
+			v, err := buildCollectorPipelineProcessorsList(test.fromCollector, test.userPipelines)
 			So(err, ShouldBeNil)
 			So(v, ShouldResemble, test.finalOutput)
 		})
 	}
 }
 
-func TestBuildLogsPipelineWithNormalizer(t *testing.T) {
-	a := constants.LogsPPLPfx + "a"
-	b := constants.LogsPPLPfx + "b"
-	before := map[string]any{"opamp": map[string]any{"position": "before"}}
-	after := map[string]any{"opamp": map[string]any{"position": "after"}}
-
-	testCases := []struct {
-		name          string
-		fromCollector []string
-		userPipelines []string
-		configs       map[string]any
-		expected      []string
-	}{
-		{
-			name:          "ExistingAndStaleUserProcessorsReplaced",
-			fromCollector: []string{"memory_limiter", a, constants.LogsPPLPfx + "stale", constants.OldLogsPPLPfx + "old", "signozlogsnormalizer", "custom", "batch"},
-			userPipelines: []string{a, b},
-			expected:      []string{"memory_limiter", a, b, "signozlogsnormalizer", "custom", "batch"},
-		},
-		{
-			name:          "NamedNormalizerAfter_CustomProcessorsKeepPlace",
-			fromCollector: []string{"memory_limiter", "custom_a", "signozlogsnormalizer/x", a, "custom_b", "batch"},
-			userPipelines: []string{a},
-			configs:       map[string]any{"signozlogsnormalizer/x": after},
-			expected:      []string{"memory_limiter", "custom_a", a, "signozlogsnormalizer/x", "custom_b", "batch"},
-		},
-		{
-			name:          "FirstNormalizerAfter_SecondIgnored",
-			fromCollector: []string{"memory_limiter", "signozlogsnormalizer/first", "signozlogsnormalizer/second", "batch"},
-			userPipelines: []string{a},
-			configs:       map[string]any{"signozlogsnormalizer/first": after, "signozlogsnormalizer/second": before},
-			expected:      []string{"memory_limiter", a, "signozlogsnormalizer/first", "signozlogsnormalizer/second", "batch"},
-		},
-		{
-			name:          "FirstNormalizerBefore_SecondIgnored",
-			fromCollector: []string{"memory_limiter", "signozlogsnormalizer/first", "signozlogsnormalizer/second", "batch"},
-			userPipelines: []string{a},
-			configs:       map[string]any{"signozlogsnormalizer/first": before, "signozlogsnormalizer/second": after},
-			expected:      []string{"memory_limiter", "signozlogsnormalizer/first", a, "signozlogsnormalizer/second", "batch"},
-		},
-		{
-			name:          "NormalizerAfterBatch",
-			fromCollector: []string{"memory_limiter", "batch", "signozlogsnormalizer"},
-			userPipelines: []string{a},
-			expected:      []string{"memory_limiter", "batch", a, "signozlogsnormalizer"},
-		},
-		{
-			name:          "NoUserPipelines_StaleRemoved",
-			fromCollector: []string{"memory_limiter", a, "signozlogsnormalizer", "batch"},
-			expected:      []string{"memory_limiter", "signozlogsnormalizer", "batch"},
-		},
-	}
-	for _, testCase := range testCases {
-		t.Run(testCase.name, func(t *testing.T) {
-			processors, err := buildCollectorPipelineProcessorsList(testCase.fromCollector, testCase.userPipelines, testCase.configs)
-			require.NoError(t, err)
-			assert.Equal(t, testCase.expected, processors)
-		})
-	}
-}
-
 func TestPipelineAliasCollisionsDontResultInDuplicateCollectorProcessors(t *testing.T) {
 	require := require.New(t)
 
@@ -501,61 +437,3 @@ func TestPipeCharInAliasDoesntBreakCollectorConfig(t *testing.T) {
 		}, result[0].Attributes_string,
 	)
 }
-
-func TestRecommendAgentConfigWithNormalizerProcessorAndJSONBody(t *testing.T) {
-	userPipeline := makeTestAddAttributePipeline()
-	controller := &LogParsingPipelineController{
-		fl: flaggertest.WithUseJSONBody(t, true),
-		GetIntegrationPipelines: func(context.Context, string) ([]pipelinetypes.GettablePipeline, error) {
-			return []pipelinetypes.GettablePipeline{userPipeline}, nil
-		},
-	}
-	normalizeOperator := CollectorConfProcessorName(getNormalizePipeline())
-	user := CollectorConfProcessorName(userPipeline)
-
-	testCases := []struct {
-		name       string
-		processors string
-		logs       string
-		expected   []any
-	}{
-		{
-			name:     "NoNormalizer_OperatorPrepended",
-			logs:     "[memory_limiter, batch]",
-			expected: []any{"memory_limiter", normalizeOperator, user, "batch"},
-		},
-		{
-			name:     "NormalizerDefault_OperatorKept",
-			logs:     "[memory_limiter, signozlogsnormalizer, batch]",
-			expected: []any{"memory_limiter", normalizeOperator, user, "signozlogsnormalizer", "batch"},
-		},
-		{
-			name:       "NormalizerBefore_OperatorDropped",
-			processors: "signozlogsnormalizer:\n    opamp:\n      position: before\n",
-			logs:       "[memory_limiter, signozlogsnormalizer, batch]",
-			expected:   []any{"memory_limiter", "signozlogsnormalizer", user, "batch"},
-		},
-		{
-			name:       "NormalizerAfter_OperatorKept",
-			processors: "signozlogsnormalizer:\n    opamp:\n      position: after\n",
-			logs:       "[memory_limiter, signozlogsnormalizer, batch]",
-			expected:   []any{"memory_limiter", normalizeOperator, user, "signozlogsnormalizer", "batch"},
-		},
-	}
-	for _, testCase := range testCases {
-		t.Run(testCase.name, func(t *testing.T) {
-			conf := fmt.Sprintf(
-				"processors:\n  memory_limiter: {}\n  batch: {}\n  %s\nservice:\n  pipelines:\n    logs:\n      receivers: [otlp]\n      processors: %s\n      exporters: [clickhouselogsexporter]\n",
-				testCase.processors, testCase.logs,
-			)
-
-			recommended, _, err := controller.RecommendAgentConfig(valuer.GenerateUUID(), []byte(conf), nil)
-			require.NoError(t, err)
-
-			var recommendedConf map[string]any
-			require.NoError(t, yaml.Unmarshal(recommended, &recommendedConf))
-			logs := recommendedConf["service"].(map[string]any)["pipelines"].(map[string]any)["logs"].(map[string]any)
-			assert.Equal(t, testCase.expected, logs["processors"])
-		})
-	}
-}

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

@@ -220,17 +220,26 @@ func (ic *LogParsingPipelineController) ValidatePipelines(ctx context.Context,
 	return err
 }
 
-// withNormalizePipeline places normalize ahead of user pipelines when queries run on body_v2
-// (use_json_body), so operators see the body the explorer shows. Absent when the flag is off
-// or collectorNormalizesFirst.
-func (ic *LogParsingPipelineController) withNormalizePipeline(ctx context.Context, orgID valuer.UUID, pipelines []pipelinetypes.GettablePipeline, collectorNormalizesFirst bool) []pipelinetypes.GettablePipeline {
-	if collectorNormalizesFirst || !ic.fl.BooleanOrEmpty(ctx, flagger.FeatureUseJSONBody, featuretypes.NewFlaggerEvaluationContext(orgID)) {
+// 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
 	}
-	return append([]pipelinetypes.GettablePipeline{getNormalizePipeline()}, pipelines...)
 }
 
-func getNormalizePipeline() pipelinetypes.GettablePipeline {
+// 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",
@@ -249,10 +258,11 @@ func getNormalizePipeline() pipelinetypes.GettablePipeline {
 		},
 		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,
 			},
 		},
 	}
@@ -361,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{getNormalizePipeline()}, pipelines...)
+		pipelines = append([]pipelinetypes.GettablePipeline{getNormalizePipeline(false)}, pipelines...)
 	}
 
 	result, collectorLogs, err := SimulatePipelinesProcessing(ctx, pipelines, request.Logs)
@@ -383,14 +396,14 @@ 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 is on) is placed
+// 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
+// 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(
@@ -418,15 +431,10 @@ func (pc *LogParsingPipelineController) RecommendAgentConfig(
 		return nil, "", err
 	}
 
-	collectorConf, err := unmarshalCollectorConfig(currentConfYaml)
-	if err != nil {
-		return nil, "", err
-	}
-
 	// normalize is only for sending to the collector, never persisted
-	enrichedPipelines = pc.withNormalizePipeline(ctx, orgId, enrichedPipelines, collectorNormalizesFirst(collectorConf))
+	enrichedPipelines = pc.withNormalizePipeline(ctx, orgId, enrichedPipelines)
 
-	updatedConf, err := generateCollectorConfigWithPipelines(collectorConf, enrichedPipelines)
+	updatedConf, err := GenerateCollectorConfigWithPipelines(currentConfYaml, enrichedPipelines)
 	if err != nil {
 		return nil, "", err
 	}

pkg/types/aiobservabilitytypes/keys.go

@@ -17,14 +17,8 @@ const (
 	GenAIUsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens"
 	GenAIUsageReasoningOutputTokens    = "gen_ai.usage.reasoning.output_tokens"
 
-	GenAIInputMessages         = "gen_ai.input.messages"
-	GenAIOutputMessages        = "gen_ai.output.messages"
-	GenAISystemInstructions    = "gen_ai.system_instructions"
-	GenAIResponseFinishReasons = "gen_ai.response.finish_reasons"
-
-	GenAIToolCallID        = "gen_ai.tool.call.id"
-	GenAIToolCallArguments = "gen_ai.tool.call.arguments"
-	GenAIToolCallResult    = "gen_ai.tool.call.result"
+	GenAIInputMessages  = "gen_ai.input.messages"
+	GenAIOutputMessages = "gen_ai.output.messages"
 )
 
 // Per-span costs the SigNoz LLM pricing processor attaches; SigNoz semconv
@@ -38,10 +32,12 @@ const (
 )
 
 // GenAISpanGateKeys mark a span as gen_ai: an LLM call, a tool call, or an
-// agent span. A trace belongs to the AI explorer when any span carries one,
-// and the thread of a trace is these spans.
+// agent span. A trace belongs to the AI explorer when any span carries one.
 var GenAISpanGateKeys = []string{GenAIRequestModel, GenAIToolName, GenAIAgentName}
 
+// GenAIThreadKeys mark a span as a thread row: a model call with its messages, or a tool execution.
+var GenAIThreadKeys = []string{GenAIInputMessages, GenAIOutputMessages, GenAIToolName}
+
 // GenAISpanFilterExpression renders the gate as a query-builder filter
 // expression: each gate key ORed on EXISTS.
 func GenAISpanFilterExpression() string {

pkg/types/aiobservabilitytypes/message.go

@@ -1,6 +1,5 @@
 // The message types mirror the OpenTelemetry GenAI message schemas, one type per schema definition:
-// https://github.com/open-telemetry/semantic-conventions-genai/blob/06ec68e722c45a7218e23ea1bc1339fe4e21ecae/model/gen-ai/gen-ai-input-messages.json
-// https://github.com/open-telemetry/semantic-conventions-genai/blob/06ec68e722c45a7218e23ea1bc1339fe4e21ecae/model/gen-ai/gen-ai-output-messages.json
+// open-telemetry/semantic-conventions-genai@06ec68e, model/gen-ai/gen-ai-{input,output}-messages.json.
 // Keys the schema does not name are dropped; the raw attribute on the span still has them.
 
 package aiobservabilitytypes

pkg/types/aiobservabilitytypes/message_format.go

@@ -4,32 +4,23 @@ import (
 	"encoding/json"
 	"fmt"
 	"regexp"
-	"sort"
-	"strconv"
 	"strings"
 
 	"github.com/SigNoz/signoz/pkg/valuer"
 )
 
 const (
-	FormatterSemconv       = "semconv"
-	FormatterTool          = "tool"
-	FormatterOpenInference = "openinference"
-	FormatterOpenAIChat    = "openai.chat"
-	FormatterText          = "text"
-	FormatterGeneric       = "generic"
+	FormatterSemconv    = "semconv"
+	FormatterOpenAIChat = "openai.chat"
+	FormatterText       = "text"
+	FormatterGeneric    = "generic"
 )
 
 var dataURL = regexp.MustCompile(`^data:([^;,]+);base64,(.+)$`)
 
-// Provider spellings of the finish reasons; the enum values themselves pass through. tool_calls and
-// function_call are OpenAI's, end_turn, stop_sequence, max_tokens and tool_use Anthropic's, tool-calls the
-// Vercel AI SDK's:
-// https://github.com/openai/openai-openapi/blob/aeb6a041dc56c011ca9f12127ec898f911100aa0/openapi.yaml#L44782
-// https://platform.claude.com/docs/en/api/messages
-// https://github.com/vercel/ai/blob/a5e92fe3c692f8e152fe1eb9ef50a4e734ad0ffb/packages/provider/src/language-model/v2/language-model-v2-finish-reason.ts
+// Provider spellings of the finish reasons; the enum values themselves pass through.
 var finishReasonAliases = map[string]FinishReason{
-	"tool_calls": FinishReasonToolCall, "function_call": FinishReasonToolCall, "tool-calls": FinishReasonToolCall, "tool_use": FinishReasonToolCall,
+	"tool_calls": FinishReasonToolCall, "function_call": FinishReasonToolCall,
 	"end_turn": FinishReasonStop, "stop_sequence": FinishReasonStop,
 	"max_tokens": FinishReasonLength,
 }
@@ -43,97 +34,36 @@ type FormattedMessages struct {
 	Warnings  []string
 }
 
-// FormatMessages builds the OTel GenAI view of a span's messages from the formats SDKs write. attributes
-// is the span's JSON attribute document, nested by key segment, so an object value is whole. Each
-// message value is a JSON string or a structured value. OpenInference's flattened messages come first,
-// then a tool call and its result, then the message attributes. gen_ai.system_instructions leads the
-// input and gen_ai.response.finish_reasons overrides the finish reasons the converter found, whichever
-// converter ran.
-func FormatMessages(attributes map[string]any) FormattedMessages {
-	f := &formatting{attributes: attributes, out: FormattedMessages{Input: InputMessages{}, Output: OutputMessages{}, Warnings: []string{}}}
-	switch {
-	case f.openInference():
-	case attribute(f.attributes, GenAIToolCallArguments) != nil || attribute(f.attributes, GenAIToolCallResult) != nil:
-		f.tool()
-	case attribute(f.attributes, GenAIInputMessages) != nil || attribute(f.attributes, GenAIOutputMessages) != nil:
-		f.messages()
-	}
-	f.prependSystemInstructions()
-	f.fillFinishReasons()
-	return f.out
-}
-
-type formatting struct {
-	attributes map[string]any
-	out        FormattedMessages
-}
-
-func (f *formatting) warn(format string, args ...any) {
-	f.out.Warnings = append(f.out.Warnings, fmt.Sprintf(format, args...))
-}
-
-// messages converts gen_ai.input.messages and gen_ai.output.messages, each by its own shape.
-func (f *formatting) messages() {
+// FormatMessages builds the OTel GenAI view of gen_ai.input.messages and gen_ai.output.messages from the
+// formats SDKs write. Each value is a JSON string or a structured value; nil means absent.
+func FormatMessages(input, output any) FormattedMessages {
+	f := &formatting{out: FormattedMessages{Input: InputMessages{}, Output: OutputMessages{}, Warnings: []string{}}}
 	var inputLabel, outputLabel string
-	if input := attribute(f.attributes, GenAIInputMessages); input != nil {
+	if input != nil {
 		var msgs OutputMessages
 		msgs, inputLabel = f.side(decode(input), RoleUser)
-		f.out.Input = inputMessages(msgs)
+		for _, m := range msgs {
+			f.out.Input = append(f.out.Input, ChatMessage{Role: m.Role, Parts: m.Parts, Name: m.Name})
+		}
 	}
-	if output := attribute(f.attributes, GenAIOutputMessages); output != nil {
+	if output != nil {
 		f.out.Output, outputLabel = f.side(decode(output), RoleAssistant)
 	}
-	f.label(inputLabel, outputLabel)
-}
-
-// label names the formatter after the input side, or the output side when the input has none, and
-// warns when the two sides came from different converters.
-func (f *formatting) label(inputLabel, outputLabel string) {
 	f.out.Formatter = inputLabel
 	if inputLabel == "" {
 		f.out.Formatter = outputLabel
 	} else if outputLabel != "" && outputLabel != inputLabel {
 		f.warn("output formatted as %s, input as %s", outputLabel, inputLabel)
 	}
+	return f.out
 }
 
-// prependSystemInstructions adds gen_ai.system_instructions, a list of parts, as a leading system message,
-// unless the input already starts with a system message of the same text: the OpenInference strands
-// processor keeps the attribute and inserts it as message 0 as well. A span without messages, such as
-// create_agent, stays without them.
-// https://github.com/open-telemetry/semantic-conventions-genai/blob/06ec68e722c45a7218e23ea1bc1339fe4e21ecae/model/gen-ai/gen-ai-system-instructions.json
-// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L152
-// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L293
-func (f *formatting) prependSystemInstructions() {
-	raw := attribute(f.attributes, GenAISystemInstructions)
-	if raw == nil || (len(f.out.Input) == 0 && len(f.out.Output) == 0) {
-		return
-	}
-	parts := systemParts(decode(raw))
-	if len(parts) == 0 || (len(f.out.Input) > 0 && f.out.Input[0].Role == RoleSystem && textOf(f.out.Input[0].Parts) == textOf(parts)) {
-		return
-	}
-	f.out.Input = append(InputMessages{{Role: RoleSystem, Parts: parts}}, f.out.Input...)
+type formatting struct {
+	out FormattedMessages
 }
 
-// fillFinishReasons applies gen_ai.response.finish_reasons, one entry per output message, over
-// whatever the converter found in the payload.
-// https://github.com/open-telemetry/semantic-conventions-genai/blob/06ec68e722c45a7218e23ea1bc1339fe4e21ecae/model/gen-ai/registry.yaml#L210
-func (f *formatting) fillFinishReasons() {
-	raw := attribute(f.attributes, GenAIResponseFinishReasons)
-	if raw == nil || len(f.out.Output) == 0 {
-		return
-	}
-	reasons := stringList(decode(raw))
-	if len(reasons) != len(f.out.Output) {
-		f.warn("gen_ai.response.finish_reasons has %d entries for %d output messages", len(reasons), len(f.out.Output))
-		return
-	}
-	for i, reason := range reasons {
-		if fr := finishReason(reason); fr != nil {
-			f.out.Output[i].FinishReason = fr
-		}
-	}
+func (f *formatting) warn(format string, args ...any) {
+	f.out.Warnings = append(f.out.Warnings, fmt.Sprintf(format, args...))
 }
 
 // side converts one attribute value by its shape; role is what a bare string on this side is
@@ -167,53 +97,6 @@ func (f *formatting) side(value any, role Role) (OutputMessages, string) {
 	return OutputMessages{genericMessage(value)}, FormatterGeneric
 }
 
-// attribute walks the document along the dotted key; a nested object comes back whole. Not handled: a
-// scalar at a prefix of the path, such as gen_ai.input beside gen_ai.input.messages, which ends the
-// walk early.
-func attribute(doc map[string]any, key string) any {
-	var current any = doc
-	for segment := range strings.SplitSeq(key, ".") {
-		object, ok := current.(map[string]any)
-		if !ok {
-			return nil
-		}
-		current = object[segment]
-	}
-	return current
-}
-
-// indexed reads a flattened list, "<key>.<N>.*" keys stored as an object keyed by N, in numeric order.
-// A list value is returned as is.
-func indexed(doc map[string]any, key string) []map[string]any {
-	var items []any
-	switch v := attribute(doc, key).(type) {
-	case []any:
-		items = v
-	case map[string]any:
-		indexes := make([]int, 0, len(v))
-		byIndex := make(map[int]any, len(v))
-		for k, item := range v {
-			n, err := strconv.Atoi(k)
-			if err != nil {
-				continue
-			}
-			indexes = append(indexes, n)
-			byIndex[n] = item
-		}
-		sort.Ints(indexes)
-		for _, n := range indexes {
-			items = append(items, byIndex[n])
-		}
-	}
-	out := make([]map[string]any, 0, len(items))
-	for _, item := range items {
-		if m, ok := item.(map[string]any); ok {
-			out = append(out, m)
-		}
-	}
-	return out
-}
-
 func firstObject(list []any) (map[string]any, bool) {
 	if len(list) == 0 {
 		return nil, false
@@ -226,31 +109,6 @@ func genericMessage(value any) OutputMessage {
 	return OutputMessage{Parts: Parts{part(GenericPart{"type": FormatterGeneric, "content": stringOf(value)})}}
 }
 
-func inputMessages(msgs OutputMessages) InputMessages {
-	out := make(InputMessages, 0, len(msgs))
-	for _, m := range msgs {
-		out = append(out, ChatMessage{Role: m.Role, Parts: m.Parts, Name: m.Name})
-	}
-	return out
-}
-
-// foldAssistant merges runs of assistant messages into one and drops messages without parts, for
-// SDKs that write one message per output item.
-func foldAssistant(msgs OutputMessages) OutputMessages {
-	out := make(OutputMessages, 0, len(msgs))
-	for _, msg := range msgs {
-		if len(out) > 0 && msg.Role == RoleAssistant && out[len(out)-1].Role == RoleAssistant {
-			out[len(out)-1].Parts = append(out[len(out)-1].Parts, msg.Parts...)
-			continue
-		}
-		if len(msg.Parts) == 0 {
-			continue
-		}
-		out = append(out, msg)
-	}
-	return out
-}
-
 // decode parses a JSON-encoded attribute value, twice when an SDK encoded the string again.
 // Anything that is not JSON is returned as is.
 func decode(value any) any {
@@ -297,23 +155,6 @@ func finishReason(value string) *FinishReason {
 	return &fr
 }
 
-// stringList reads a list of strings, or a bare string as a list of one.
-func stringList(value any) []string {
-	switch v := value.(type) {
-	case []any:
-		out := make([]string, 0, len(v))
-		for _, item := range v {
-			out = append(out, stringOf(item))
-		}
-		return out
-	case string:
-		if v != "" {
-			return []string{v}
-		}
-	}
-	return nil
-}
-
 func optionalString(value any) *string {
 	s := stringOf(value)
 	if s == "" {
@@ -330,37 +171,8 @@ func textPart(content string) TextPart {
 	return TextPart{Type: PartTypeText, Content: content}
 }
 
-// textOf joins the text parts, for comparing a system message with gen_ai.system_instructions.
-func textOf(parts Parts) string {
-	var texts []string
-	for _, p := range parts {
-		if t, ok := p.Value.(TextPart); ok {
-			texts = append(texts, t.Content)
-		}
-	}
-	return strings.Join(texts, "\n")
-}
-
-// systemParts reads a system prompt given outside the history, a list of parts or a bare string.
-func systemParts(value any) Parts {
-	switch v := value.(type) {
-	case []any:
-		parts := make(Parts, 0, len(v))
-		for _, item := range v {
-			parts = append(parts, contentPart(item))
-		}
-		return parts
-	case string:
-		if v != "" {
-			return Parts{part(textPart(v))}
-		}
-	}
-	return nil
-}
-
-// contentPart converts one OpenAI content block, which semconv parts may also carry; a text part
-// in the semconv spelling has content where OpenAI has text. A block of any other type is kept
-// as sent.
+// contentPart converts one OpenAI content block, which semconv parts may also carry; a block of
+// any other type is kept as sent.
 func contentPart(item any) Part {
 	p, ok := item.(map[string]any)
 	if !ok {
@@ -371,9 +183,6 @@ func contentPart(item any) Part {
 	}
 	switch stringOf(p["type"]) {
 	case "text":
-		if p["text"] == nil {
-			return part(textPart(stringOf(p["content"])))
-		}
 		return part(textPart(stringOf(p["text"])))
 	case "refusal":
 		return part(textPart(stringOf(p["refusal"])))

pkg/types/aiobservabilitytypes/message_format_openai_chat_test.go

@@ -170,8 +170,7 @@ func TestFormat_OpenAIChat(t *testing.T) {
 			]`,
 		},
 		{
-			// ChatCompletionRequestMessageContentPartFile {file: {file_id}}, as OpenInference records the request in input.value:
-			// https://github.com/openai/openai-openapi/blob/aeb6a041dc56c011ca9f12127ec898f911100aa0/openapi.yaml#L42650
+			// openinference capture, input.value of the ChatCompletion span
 			name:      "FileByID_FilePart",
 			input:     `{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": [{"type": "text", "text": "Summarise this document in one sentence."}, {"type": "file", "file": {"file_id": "file-6F2ksmvXxt4VdoqmHRw6kL"}}]}], "max_tokens": 60}`,
 			output:    `{"id":"chatcmpl-DktFileCapture0001","object":"chat.completion","model":"gpt-4o-mini-2024-07-18","choices":[{"index":0,"finish_reason":"stop","logprobs":null,"message":{"role":"assistant","content":"The document is a short PDF about dragons.","refusal":null,"annotations":[]}}]}`,
@@ -194,8 +193,7 @@ func TestFormat_OpenAIChat(t *testing.T) {
 			]`,
 		},
 		{
-			// ChatCompletionRequestMessageContentPartFile {file: {filename, file_data}}, file_data a data URL:
-			// https://github.com/openai/openai-openapi/blob/aeb6a041dc56c011ca9f12127ec898f911100aa0/openapi.yaml#L42650
+			// openinference capture, input.value of the ChatCompletion span
 			name:      "FileInline_BlobPart",
 			input:     `{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": [{"type": "text", "text": "Summarise this document in one sentence."}, {"type": "file", "file": {"filename": "draconomicon.pdf", "file_data": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbXS9Db3VudCAwPj5lbmRvYmoKdHJhaWxlcjw8L1Jvb3QgMSAwIFI+PgolJUVPRgo="}}]}], "max_tokens": 60}`,
 			formatter: FormatterOpenAIChat,

pkg/types/aiobservabilitytypes/message_format_openinference.go

@@ -1,137 +0,0 @@
-package aiobservabilitytypes
-
-import "github.com/SigNoz/signoz/pkg/valuer"
-
-// Format: the flattened llm.input_messages.N.message.* and llm.output_messages.N.message.* keys, the
-// provider-neutral copy of the conversation the OpenInference instrumentations write on LLM spans. A side
-// without them falls back to the raw provider payload the mapper moved onto gen_ai.*.messages; pipecat
-// streams the reply into output.value alone.
-// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/semantic_conventions.md#L77
-// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/tool_calling.md#L37
-// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/multimodal_attributes.md#L35
-// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/llm_spans.md#L181
-// Handled: message.content, the ordered message.contents items (text, image, audio, video, reasoning),
-// message.tool_calls, the legacy message.function_call_*, tool results, llm.finish_reason. A tool_use
-// content item repeats a call from message.tool_calls and is skipped.
-// Dropped: reasoning id, signature, data and encrypted_content; audio transcripts.
-
-const (
-	openInferenceInputMessages  = "llm.input_messages"
-	openInferenceOutputMessages = "llm.output_messages"
-	openInferenceFinishReason   = "llm.finish_reason"
-)
-
-func (f *formatting) openInference() bool {
-	input := indexed(f.attributes, openInferenceInputMessages)
-	output := indexed(f.attributes, openInferenceOutputMessages)
-	if len(input) == 0 && len(output) == 0 {
-		return false
-	}
-	inputLabel, outputLabel := FormatterOpenInference, FormatterOpenInference
-	if len(input) > 0 {
-		f.out.Input = inputMessages(openInferenceMessages(input))
-	} else if raw := attribute(f.attributes, GenAIInputMessages); raw != nil {
-		var msgs OutputMessages
-		msgs, inputLabel = f.side(decode(raw), RoleUser)
-		f.out.Input = inputMessages(msgs)
-	}
-	if len(output) > 0 {
-		f.out.Output = openInferenceMessages(output)
-		if fr := finishReason(stringOf(attribute(f.attributes, openInferenceFinishReason))); fr != nil {
-			for i := range f.out.Output {
-				f.out.Output[i].FinishReason = fr
-			}
-		}
-	} else if raw := attribute(f.attributes, GenAIOutputMessages); raw != nil {
-		f.out.Output, outputLabel = f.side(decode(raw), RoleAssistant)
-	}
-	f.label(inputLabel, outputLabel)
-	return true
-}
-
-// openInferenceMessages converts the message buckets and folds runs of assistant messages: the Responses
-// path writes one message per output item, an empty one for a reasoning item without a summary.
-func openInferenceMessages(buckets []map[string]any) OutputMessages {
-	msgs := make(OutputMessages, 0, len(buckets))
-	for _, bucket := range buckets {
-		message, _ := bucket["message"].(map[string]any)
-		msgs = append(msgs, openInferenceMessage(message))
-	}
-	return foldAssistant(msgs)
-}
-
-// openInferenceMessage converts one message.* object. A message without a role is a tool response when
-// it has a tool_call_id, an assistant turn when it has tool calls, else a user turn, as the
-// collector-contrib normalizer decides it:
-// https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/fc79b95297776dec6c47490cd6f6026b942bf6fb/processor/genainormalizerprocessor/internal/openinference/messages.go#L473
-func openInferenceMessage(m map[string]any) OutputMessage {
-	msg := OutputMessage{Role: role(stringOf(m["role"])), Parts: Parts{}, Name: optionalString(m["name"])}
-	id := stringOf(m["tool_call_id"])
-	calls := indexed(m, "tool_calls")
-	if msg.Role.IsZero() {
-		switch {
-		case id != "":
-			msg.Role = RoleTool
-		case len(calls) > 0:
-			msg.Role = RoleAssistant
-		default:
-			msg.Role = RoleUser
-		}
-	}
-	if msg.Role == RoleTool && id != "" {
-		msg.Parts = Parts{part(ToolCallResponsePart{Type: PartTypeToolCallResponse, ID: &id, Response: decode(m["content"])})}
-		return msg
-	}
-	if content := stringOf(m["content"]); content != "" {
-		msg.Parts = append(msg.Parts, part(textPart(content)))
-	}
-	msg.Parts = append(msg.Parts, openInferenceContents(m)...)
-	for _, call := range calls {
-		if c, ok := call["tool_call"].(map[string]any); ok {
-			msg.Parts = append(msg.Parts, openInferenceToolCall(c))
-		}
-	}
-	if name := stringOf(m["function_call_name"]); name != "" {
-		msg.Parts = append(msg.Parts, part(ToolCallRequestPart{Type: PartTypeToolCall, Name: name, Arguments: decode(m["function_call_arguments_json"])}))
-	}
-	return msg
-}
-
-// openInferenceContents converts the ordered message.contents items. A text item may come without
-// message_content.type, as the collector-contrib normalizer reads it:
-// https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/fc79b95297776dec6c47490cd6f6026b942bf6fb/processor/genainormalizerprocessor/internal/openinference/messages.go#L285
-func openInferenceContents(m map[string]any) Parts {
-	items := indexed(m, "contents")
-	parts := make(Parts, 0, len(items))
-	for _, item := range items {
-		content, _ := item["message_content"].(map[string]any)
-		typ := stringOf(content["type"])
-		if typ == "" && content["text"] != nil {
-			typ = "text"
-		}
-		switch typ {
-		case "text":
-			parts = append(parts, part(textPart(stringOf(content["text"]))))
-		case "reasoning":
-			parts = append(parts, part(ReasoningPart{Type: PartTypeReasoning, Content: stringOf(content["text"])}))
-		case "image", "audio", "video":
-			if url := stringOf(attribute(content, typ+"."+typ+".url")); url != "" {
-				parts = append(parts, part(mediaPart(url, Modality{valuer.NewString(typ)})))
-			}
-		case "tool_use":
-		default:
-			parts = append(parts, part(GenericPart(content)))
-		}
-	}
-	return parts
-}
-
-// openInferenceToolCall reads a tool_call.* object, {id, function: {name, arguments}}.
-func openInferenceToolCall(call map[string]any) Part {
-	fn, _ := call["function"].(map[string]any)
-	p := ToolCallRequestPart{Type: PartTypeToolCall, Name: stringOf(fn["name"]), ID: optionalString(call["id"])}
-	if args, ok := fn["arguments"]; ok {
-		p.Arguments = decode(args)
-	}
-	return part(p)
-}

pkg/types/aiobservabilitytypes/message_format_openinference_test.go

@@ -1,341 +0,0 @@
-package aiobservabilitytypes
-
-import "testing"
-
-// Captured cases are the llm.input_messages.N.* and llm.output_messages.N.* keys as the collector
-// stored them for the SigNoz/scripts static-telemetry-generator captures.
-func TestFormat_OpenInference(t *testing.T) {
-	runFormatCases(t, []formatCase{
-		{
-			// openinference capture, ChatCompletion span: the flattened keys win over the raw request the
-			// mapper moved onto gen_ai.input.messages
-			name: "FlattenedMessages_RawRequestIgnored",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":     "system",
-				"llm.input_messages.0.message.content":  "You are concise.",
-				"llm.input_messages.1.message.role":     "user",
-				"llm.input_messages.1.message.content":  "Say hello in five words.",
-				"llm.output_messages.0.message.role":    "assistant",
-				"llm.output_messages.0.message.content": "Hello! How are you today?",
-				"llm.finish_reason":                     "stop",
-				GenAIInputMessages:                      `{"messages": [{"role": "system", "content": "You are concise."}, {"role": "user", "content": "Say hello in five words."}], "model": "gpt-4o-mini", "max_tokens": 50, "temperature": 0.2}`,
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "You are concise."}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "Say hello in five words."}]}
-			]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "Hello! How are you today?"}], "finish_reason": "stop"}]`,
-		},
-		{
-			// openinference capture, ChatCompletion span: message.tool_calls and llm.finish_reason
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/tool_calling.md#L37
-			name: "ToolCalls_ToolCallParts_FinishReasonFromLLMKey",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                       "user",
-				"llm.input_messages.0.message.content":                                    "What is the weather in Bengaluru in celsius?",
-				"llm.output_messages.0.message.role":                                      "assistant",
-				"llm.output_messages.0.message.tool_calls.0.tool_call.id":                 "call_MdYKTRrkshuBG9W5oBXYZaRc",
-				"llm.output_messages.0.message.tool_calls.0.tool_call.function.name":      "get_current_weather",
-				"llm.output_messages.0.message.tool_calls.0.tool_call.function.arguments": `{"city":"Bengaluru","unit":"c"}`,
-				"llm.finish_reason": "tool_calls",
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[{"role": "user", "parts": [{"type": "text", "content": "What is the weather in Bengaluru in celsius?"}]}]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_current_weather", "id": "call_MdYKTRrkshuBG9W5oBXYZaRc", "arguments": {"city": "Bengaluru", "unit": "c"}}], "finish_reason": "tool_call"}]`,
-		},
-		{
-			// openinference capture, the follow-up ChatCompletion span: tool role messages carry the result
-			// in message.content with their tool_call_id
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/llm_spans.md#L50
-			name: "ToolRoleMessages_ToolCallResponseParts",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                      "user",
-				"llm.input_messages.0.message.content":                                   "What's the weather in Paris and in London? Use the tool for each.",
-				"llm.input_messages.1.message.role":                                      "assistant",
-				"llm.input_messages.1.message.tool_calls.0.tool_call.id":                 "call_SW4hst7nzysgvWSAz4OdyK9D",
-				"llm.input_messages.1.message.tool_calls.0.tool_call.function.name":      "get_current_weather",
-				"llm.input_messages.1.message.tool_calls.0.tool_call.function.arguments": `{"city": "Paris"}`,
-				"llm.input_messages.1.message.tool_calls.1.tool_call.id":                 "call_si8wiETYGpooMB7gMXSgMQpk",
-				"llm.input_messages.1.message.tool_calls.1.tool_call.function.name":      "get_current_weather",
-				"llm.input_messages.1.message.tool_calls.1.tool_call.function.arguments": `{"city": "London"}`,
-				"llm.input_messages.2.message.role":                                      "tool",
-				"llm.input_messages.2.message.tool_call_id":                              "call_SW4hst7nzysgvWSAz4OdyK9D",
-				"llm.input_messages.2.message.content":                                   `{"city": "Paris", "temp_c": 18, "summary": "Clear"}`,
-				"llm.input_messages.3.message.role":                                      "tool",
-				"llm.input_messages.3.message.tool_call_id":                              "call_si8wiETYGpooMB7gMXSgMQpk",
-				"llm.input_messages.3.message.content":                                   `{"city": "London", "temp_c": 18, "summary": "Clear"}`,
-				"llm.output_messages.0.message.role":                                     "assistant",
-				"llm.output_messages.0.message.content":                                  "The current weather is as follows:\n\n- **Paris**: 18°C, Clear\n- **London**: 18°C, Clear",
-				"llm.finish_reason":                                                      "stop",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[
-			  {"role": "user", "parts": [{"type": "text", "content": "What's the weather in Paris and in London? Use the tool for each."}]},
-			  {"role": "assistant", "parts": [
-			    {"type": "tool_call", "name": "get_current_weather", "id": "call_SW4hst7nzysgvWSAz4OdyK9D", "arguments": {"city": "Paris"}},
-			    {"type": "tool_call", "name": "get_current_weather", "id": "call_si8wiETYGpooMB7gMXSgMQpk", "arguments": {"city": "London"}}
-			  ]},
-			  {"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_SW4hst7nzysgvWSAz4OdyK9D", "response": {"city": "Paris", "temp_c": 18, "summary": "Clear"}}]},
-			  {"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_si8wiETYGpooMB7gMXSgMQpk", "response": {"city": "London", "temp_c": 18, "summary": "Clear"}}]}
-			]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "The current weather is as follows:\n\n- **Paris**: 18°C, Clear\n- **London**: 18°C, Clear"}], "finish_reason": "stop"}]`,
-		},
-		{
-			// openinference capture, vision call; base64 trimmed. An image as a data URL:
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/multimodal_attributes.md#L47
-			name: "ContentsTextAndImage_TextAndBlobParts",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                       "user",
-				"llm.input_messages.0.message.contents.0.message_content.type":            "text",
-				"llm.input_messages.0.message.contents.0.message_content.text":            "What animal is in this image? One sentence.",
-				"llm.input_messages.0.message.contents.1.message_content.type":            "image",
-				"llm.input_messages.0.message.contents.1.message_content.image.image.url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD",
-				"llm.output_messages.0.message.role":                                      "assistant",
-				"llm.output_messages.0.message.content":                                   "The animal in the image is a duck.",
-				"llm.finish_reason":                                                       "stop",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[{"role": "user", "parts": [
-			  {"type": "text", "content": "What animal is in this image? One sentence."},
-			  {"type": "blob", "modality": "image", "mime_type": "image/jpeg", "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD"}
-			]}]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "The animal in the image is a duck."}], "finish_reason": "stop"}]`,
-		},
-		{
-			// openinference-openai-agents capture, Response span: one output message per item, an empty one
-			// for a reasoning item without a summary
-			name: "ResponsesOutputItems_AssistantMessagesFolded_EmptyDropped",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                  "system",
-				"llm.input_messages.0.message.content":                               "You solve problems step by step and give a final answer.",
-				"llm.input_messages.1.message.role":                                  "user",
-				"llm.input_messages.1.message.content":                               "A bat and a ball cost $1.10. How much is the ball?",
-				"llm.output_messages.0.message.role":                                 "assistant",
-				"llm.output_messages.1.message.role":                                 "assistant",
-				"llm.output_messages.1.message.contents.0.message_content.type":      "text",
-				"llm.output_messages.1.message.contents.0.message_content.text":      "Final Answer: The ball costs $0.05.",
-				"llm.output_messages.2.message.role":                                 "assistant",
-				"llm.output_messages.2.message.tool_calls.0.tool_call.id":            "call_1",
-				"llm.output_messages.2.message.tool_calls.0.tool_call.function.name": "done",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "You solve problems step by step and give a final answer."}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "A bat and a ball cost $1.10. How much is the ball?"}]}
-			]`,
-			wantOutput: `[{"role": "assistant", "parts": [
-			  {"type": "text", "content": "Final Answer: The ball costs $0.05."},
-			  {"type": "tool_call", "name": "done", "id": "call_1"}
-			]}]`,
-		},
-		{
-			// openinference capture, the ChatCompletion span of a failed call
-			name: "InputOnly_NoOutput",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":    "user",
-				"llm.input_messages.0.message.content": "this should fail",
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[{"role": "user", "parts": [{"type": "text", "content": "this should fail"}]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// the strands processor keeps the SDK's gen_ai.system_instructions on the span and inserts the same
-			// prompt as message 0
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L152
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L293
-			name: "StrandsSystemInstructionsRepeated_OneSystemMessage",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":     "system",
-				"llm.input_messages.0.message.content":  "You are concise.",
-				"llm.input_messages.1.message.role":     "user",
-				"llm.input_messages.1.message.content":  "hi",
-				"llm.output_messages.0.message.role":    "assistant",
-				"llm.output_messages.0.message.content": "Hello.",
-				GenAISystemInstructions:                 `[{"type": "text", "content": "You are concise."}]`,
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "You are concise."}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "hi"}]}
-			]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "Hello."}]}]`,
-		},
-		{
-			// pipecat writes the request as llm.input_messages and the streamed reply as output.value alone,
-			// which the mapper copies onto gen_ai.output.messages
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-pipecat/src/openinference/instrumentation/pipecat/_attributes.py#L430
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-pipecat/src/openinference/instrumentation/pipecat/_observer.py#L628
-			name: "OutputKeysAbsent_RawOutputFormatted_Warns",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":    "user",
-				"llm.input_messages.0.message.content": "hi",
-				GenAIOutputMessages:                    "Hello there.",
-			},
-			formatter:  FormatterOpenInference,
-			warnings:   []string{"bare assistant text, role assumed", "output formatted as text, input as openinference"},
-			wantInput:  `[{"role": "user", "parts": [{"type": "text", "content": "hi"}]}]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "Hello there."}]}]`,
-		},
-		{
-			// message.role left unset by some instrumentors: tool_call_id, tool_calls or neither decide it,
-			// as the collector-contrib normalizer does
-			// https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/fc79b95297776dec6c47490cd6f6026b942bf6fb/processor/genainormalizerprocessor/internal/openinference/messages.go#L473
-			name: "MissingRole_InferredFromToolFields",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.content":                                   "Weather in Oslo?",
-				"llm.input_messages.1.message.tool_calls.0.tool_call.id":                 "call_9",
-				"llm.input_messages.1.message.tool_calls.0.tool_call.function.name":      "get_weather",
-				"llm.input_messages.1.message.tool_calls.0.tool_call.function.arguments": `{"city":"Oslo"}`,
-				"llm.input_messages.2.message.tool_call_id":                              "call_9",
-				"llm.input_messages.2.message.content":                                   "4C, cloudy",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[
-			  {"role": "user", "parts": [{"type": "text", "content": "Weather in Oslo?"}]},
-			  {"role": "assistant", "parts": [{"type": "tool_call", "name": "get_weather", "id": "call_9", "arguments": {"city": "Oslo"}}]},
-			  {"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_9", "response": "4C, cloudy"}]}
-			]`,
-			wantOutput: `[]`,
-		},
-		{
-			// message_content.type left unset on text items by some instrumentors, as the collector-contrib
-			// normalizer reads them
-			// https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/fc79b95297776dec6c47490cd6f6026b942bf6fb/processor/genainormalizerprocessor/internal/openinference/messages.go#L285
-			name: "UntypedContentWithText_TextPart",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                            "user",
-				"llm.input_messages.0.message.contents.0.message_content.text": "Summarise this.",
-				"llm.input_messages.0.message.contents.1.message_content.text": "Second block.",
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[{"role": "user", "parts": [{"type": "text", "content": "Summarise this."}, {"type": "text", "content": "Second block."}]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// an image given by URL
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/multimodal_attributes.md#L42
-			name: "ImageURL_UriPart",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                       "user",
-				"llm.input_messages.0.message.contents.0.message_content.type":            "image",
-				"llm.input_messages.0.message.contents.0.message_content.image.image.url": "https://example.com/duck.jpg",
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[{"role": "user", "parts": [{"type": "uri", "modality": "image", "uri": "https://example.com/duck.jpg"}]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// audio by URL with its transcript, or as the data URI built from a Chat Completions input_audio
-			// block; the transcript has no part to go to
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/multimodal_attributes.md#L55
-			name: "Audio_UriAndBlobParts_TranscriptDropped",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                              "user",
-				"llm.input_messages.0.message.contents.0.message_content.type":                   "audio",
-				"llm.input_messages.0.message.contents.0.message_content.audio.audio.url":        "https://example.com/hello.mp3",
-				"llm.input_messages.0.message.contents.0.message_content.audio.audio.transcript": "Hello, how are you?",
-				"llm.input_messages.0.message.contents.1.message_content.type":                   "audio",
-				"llm.input_messages.0.message.contents.1.message_content.audio.audio.url":        "data:audio/wav;base64,UklGRg==",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[{"role": "user", "parts": [
-			  {"type": "uri", "modality": "audio", "uri": "https://example.com/hello.mp3"},
-			  {"type": "blob", "modality": "audio", "mime_type": "audio/wav", "content": "UklGRg=="}
-			]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// reasoning items; id, signature, data and encrypted_content have no field on the reasoning part
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/llm_spans.md#L181
-			name: "Reasoning_ReasoningParts_ProviderKeysDropped",
-			attributes: map[string]any{
-				"llm.output_messages.0.message.role":                                         "assistant",
-				"llm.output_messages.0.message.contents.0.message_content.type":              "reasoning",
-				"llm.output_messages.0.message.contents.0.message_content.text":              "The ball must cost less than a dollar.",
-				"llm.output_messages.0.message.contents.0.message_content.signature":         "EuYBCkQYAiJA",
-				"llm.output_messages.0.message.contents.1.message_content.type":              "reasoning",
-				"llm.output_messages.0.message.contents.1.message_content.data":              "EmwKAhgBEgy3",
-				"llm.output_messages.0.message.contents.2.message_content.type":              "reasoning",
-				"llm.output_messages.0.message.contents.2.message_content.id":                "rs_abc123",
-				"llm.output_messages.0.message.contents.2.message_content.encrypted_content": "gAAAAA==",
-				"llm.output_messages.0.message.contents.3.message_content.type":              "text",
-				"llm.output_messages.0.message.contents.3.message_content.text":              "The ball costs 5 cents.",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [
-			  {"type": "reasoning", "content": "The ball must cost less than a dollar."},
-			  {"type": "reasoning", "content": ""},
-			  {"type": "reasoning", "content": ""},
-			  {"type": "text", "content": "The ball costs 5 cents."}
-			]}]`,
-		},
-		{
-			// a tool call repeated as an ordered tool_use content item; message.tool_calls stays the one
-			// source. llm.finish_reason is Anthropic's stop_reason as the instrumentation passes it through
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/tool_calling.md#L63
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-anthropic/src/openinference/instrumentation/anthropic/_wrappers.py#L938
-			name: "ToolUseBesideToolCalls_OneToolCallPart",
-			attributes: map[string]any{
-				"llm.output_messages.0.message.role":                                      "assistant",
-				"llm.output_messages.0.message.contents.0.message_content.type":           "text",
-				"llm.output_messages.0.message.contents.0.message_content.text":           "Let me check.",
-				"llm.output_messages.0.message.contents.1.message_content.type":           "tool_use",
-				"llm.output_messages.0.message.contents.1.tool_call.id":                   "toolu_01",
-				"llm.output_messages.0.message.contents.1.tool_call.function.name":        "get_weather",
-				"llm.output_messages.0.message.contents.1.tool_call.function.arguments":   `{"city": "Paris"}`,
-				"llm.output_messages.0.message.tool_calls.0.tool_call.id":                 "toolu_01",
-				"llm.output_messages.0.message.tool_calls.0.tool_call.function.name":      "get_weather",
-				"llm.output_messages.0.message.tool_calls.0.tool_call.function.arguments": `{"city": "Paris"}`,
-				"llm.finish_reason": "tool_use",
-			},
-			formatter: FormatterOpenInference,
-			wantInput: `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [
-			  {"type": "text", "content": "Let me check."},
-			  {"type": "tool_call", "name": "get_weather", "id": "toolu_01", "arguments": {"city": "Paris"}}
-			], "finish_reason": "tool_call"}]`,
-		},
-		{
-			// a content type the spec does not name is kept as sent
-			name: "UnknownContentType_GenericPart",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":                                            "user",
-				"llm.input_messages.0.message.contents.0.message_content.type":                 "document",
-				"llm.input_messages.0.message.contents.0.message_content.document.document.id": "file_1",
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[{"role": "user", "parts": [{"type": "document", "document": {"document": {"id": "file_1"}}}]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// the legacy function_call keys
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/semantic_conventions.md#L111
-			name: "LegacyFunctionCall_ToolCallPart",
-			attributes: map[string]any{
-				"llm.output_messages.0.message.role":                         "assistant",
-				"llm.output_messages.0.message.function_call_name":           "multiply",
-				"llm.output_messages.0.message.function_call_arguments_json": `{"x": 2}`,
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "multiply", "arguments": {"x": 2}}]}]`,
-		},
-		{
-			// a tool result with message.name naming the function
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/llm_spans.md#L50
-			name: "ToolResultWithName_NameKept",
-			attributes: map[string]any{
-				"llm.input_messages.0.message.role":         "tool",
-				"llm.input_messages.0.message.name":         "multiply",
-				"llm.input_messages.0.message.tool_call_id": "call_62136355",
-				"llm.input_messages.0.message.content":      "2001",
-			},
-			formatter:  FormatterOpenInference,
-			wantInput:  `[{"role": "tool", "name": "multiply", "parts": [{"type": "tool_call_response", "id": "call_62136355", "response": "2001"}]}]`,
-			wantOutput: `[]`,
-		},
-	})
-}

pkg/types/aiobservabilitytypes/message_format_semconv.go

@@ -6,20 +6,15 @@ import (
 )
 
 // Format: the OTel shape itself, [{role, parts}].
-// Written by: litellm, langchain, openllmetry, portkey, traceloop LLM spans, pydantic-ai.
-// Decoding is the genai types. Repairs: "text" used for "content" on text parts; OpenAI content blocks
-// left inside parts; tool call arguments as a JSON string and "result" for "response", as pydantic-ai
-// writes them:
-// https://github.com/pydantic/pydantic-ai/blob/9ac853bb84ffed7ba0edccb026c5b4f3228c1de7/pydantic_ai_slim/pydantic_ai/messages.py#L3130
-// https://github.com/pydantic/pydantic-ai/blob/9ac853bb84ffed7ba0edccb026c5b4f3228c1de7/pydantic_ai_slim/pydantic_ai/messages.py#L1724
-// The choice finish_reason as the provider spells it, as litellm copies it:
-// https://github.com/BerriAI/litellm/blob/9d72bae336ec0d14c41651adcb0d2e1149721f46/litellm/integrations/opentelemetry.py#L2822
-// Not yet: "thinking" for "reasoning".
+// Written by: litellm, langchain, openllmetry, portkey, traceloop LLM spans.
+// Decoding is the genai types. Repairs: "text" used for "content" on text parts; OpenAI content
+// blocks left inside parts.
+// Not yet: "thinking" for "reasoning"; "result" or "output" for "response" on tool call responses.
 
 // semconv decodes messages that already follow the schema through the genai types. A part of a
 // type the schema does not name is a provider content block, which contentPart converts.
 func (f *formatting) semconv(list []any) OutputMessages {
-	data, err := json.Marshal(semconvRepairs(list))
+	data, err := json.Marshal(semconvTextKey(list))
 	if err != nil {
 		f.warn("messages could not be encoded: %s", err)
 		return OutputMessages{genericMessage(list)}
@@ -33,9 +28,6 @@ func (f *formatting) semconv(list []any) OutputMessages {
 		if msgs[i].Parts == nil {
 			msgs[i].Parts = Parts{}
 		}
-		if msgs[i].FinishReason != nil {
-			msgs[i].FinishReason = finishReason(msgs[i].FinishReason.StringValue())
-		}
 		for j, p := range msgs[i].Parts {
 			if block, ok := p.Value.(GenericPart); ok {
 				msgs[i].Parts[j] = contentPart(map[string]any(block))
@@ -45,9 +37,9 @@ func (f *formatting) semconv(list []any) OutputMessages {
 	return msgs
 }
 
-// semconvRepairs copies the parts whose keys SDKs misspell into the schema's spelling. The input
-// is left untouched, it is also the span's raw attribute.
-func semconvRepairs(list []any) []any {
+// semconvTextKey copies the text and reasoning parts some SDKs write with "text" in place of the
+// schema's "content". The input is left untouched, it is also the span's raw attribute.
+func semconvTextKey(list []any) []any {
 	out := make([]any, 0, len(list))
 	for _, item := range list {
 		m, ok := item.(map[string]any)
@@ -58,8 +50,13 @@ func semconvRepairs(list []any) []any {
 		}
 		fixedParts := make([]any, 0, len(parts))
 		for _, p := range parts {
-			if part, ok := p.(map[string]any); ok {
-				p = semconvRepairPart(part)
+			part, ok := p.(map[string]any)
+			typ := stringOf(part["type"])
+			if ok && (typ == "text" || typ == "reasoning") && part["content"] == nil && part["text"] != nil {
+				fixed := maps.Clone(part)
+				fixed["content"] = fixed["text"]
+				delete(fixed, "text")
+				p = fixed
 			}
 			fixedParts = append(fixedParts, p)
 		}
@@ -69,24 +66,3 @@ func semconvRepairs(list []any) []any {
 	}
 	return out
 }
-
-func semconvRepairPart(part map[string]any) map[string]any {
-	fixed := maps.Clone(part)
-	switch stringOf(part["type"]) {
-	case "text", "reasoning":
-		if part["content"] == nil && part["text"] != nil {
-			fixed["content"] = fixed["text"]
-			delete(fixed, "text")
-		}
-	case "tool_call":
-		if args, ok := part["arguments"].(string); ok {
-			fixed["arguments"] = decode(args)
-		}
-	case "tool_call_response":
-		if _, ok := part["response"]; !ok && part["result"] != nil {
-			fixed["response"] = part["result"]
-			delete(fixed, "result")
-		}
-	}
-	return fixed
-}

pkg/types/aiobservabilitytypes/message_format_semconv_test.go

@@ -161,36 +161,3 @@ func TestFormat_Semconv(t *testing.T) {
 		},
 	})
 }
-
-func TestFormat_Semconv_Repairs(t *testing.T) {
-	runFormatCases(t, []formatCase{
-		{
-			// pydantic-ai keeps string tool call arguments as sent, writes the tool result under result, and the
-			// instructions as a gen_ai.system_instructions text part:
-			// https://github.com/pydantic/pydantic-ai/blob/9ac853bb84ffed7ba0edccb026c5b4f3228c1de7/pydantic_ai_slim/pydantic_ai/messages.py#L3130
-			// https://github.com/pydantic/pydantic-ai/blob/9ac853bb84ffed7ba0edccb026c5b4f3228c1de7/pydantic_ai_slim/pydantic_ai/messages.py#L1724
-			// https://github.com/pydantic/pydantic-ai/blob/9ac853bb84ffed7ba0edccb026c5b4f3228c1de7/pydantic_ai_slim/pydantic_ai/models/instrumented.py#L292
-			name:       "PydanticAI_ArgumentsDecoded_ResultBecomesResponse_InstructionsLead",
-			input:      `[{"role":"user","parts":[{"type":"text","content":"Weather in Paris?"}]},{"role":"assistant","parts":[{"type":"tool_call","id":"call_stub1","name":"get_weather","arguments":"{\"city\": \"Paris\"}"}],"finish_reason":"tool_call"},{"role":"user","parts":[{"type":"tool_call_response","id":"call_stub1","name":"get_weather","result":{"city":"Paris","temp_c":18}}]}]`,
-			output:     `[{"role":"assistant","parts":[{"type":"text","content":"Paris is clear at 18C."}],"finish_reason":"stop"}]`,
-			attributes: map[string]any{GenAISystemInstructions: `[{"type":"text","content":"Use the tool."}]`},
-			formatter:  FormatterSemconv,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "Use the tool."}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]},
-			  {"role": "assistant", "parts": [{"type": "tool_call", "name": "get_weather", "id": "call_stub1", "arguments": {"city": "Paris"}}]},
-			  {"role": "user", "parts": [{"type": "tool_call_response", "id": "call_stub1", "response": {"city": "Paris", "temp_c": 18}}]}
-			]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "Paris is clear at 18C."}], "finish_reason": "stop"}]`,
-		},
-		{
-			// litellm copies the choice finish_reason into the semconv message as OpenAI spells it:
-			// https://github.com/BerriAI/litellm/blob/9d72bae336ec0d14c41651adcb0d2e1149721f46/litellm/integrations/opentelemetry.py#L2822
-			name:       "LiteLLMFinishReasonSpelling_Normalised",
-			output:     `[{"role": "assistant", "parts": [], "finish_reason": "tool_calls"}]`,
-			formatter:  FormatterSemconv,
-			wantInput:  `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [], "finish_reason": "tool_call"}]`,
-		},
-	})
-}

pkg/types/aiobservabilitytypes/message_format_test.go

@@ -2,8 +2,6 @@ package aiobservabilitytypes
 
 import (
 	"encoding/json"
-	"maps"
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -14,7 +12,6 @@ type formatCase struct {
 	name       string
 	input      any
 	output     any
-	attributes map[string]any // flat dotted keys beside the two message attributes
 	formatter  string
 	warnings   []string
 	wantInput  string
@@ -25,9 +22,7 @@ func runFormatCases(t *testing.T, testCases []formatCase) {
 	t.Helper()
 	for _, testCase := range testCases {
 		t.Run(testCase.name, func(t *testing.T) {
-			attributes := map[string]any{GenAIInputMessages: testCase.input, GenAIOutputMessages: testCase.output}
-			maps.Copy(attributes, testCase.attributes)
-			formatted := FormatMessages(document(attributes))
+			formatted := FormatMessages(testCase.input, testCase.output)
 			assert.Equal(t, testCase.formatter, formatted.Formatter)
 			assert.Equal(t, append([]string{}, testCase.warnings...), formatted.Warnings)
 
@@ -41,25 +36,6 @@ func runFormatCases(t *testing.T, testCases []formatCase) {
 	}
 }
 
-// document nests flat dotted keys the way the JSON column stores them.
-func document(flat map[string]any) map[string]any {
-	doc := map[string]any{}
-	for key, value := range flat {
-		segments := strings.Split(key, ".")
-		current := doc
-		for _, segment := range segments[:len(segments)-1] {
-			child, ok := current[segment].(map[string]any)
-			if !ok {
-				child = map[string]any{}
-				current[segment] = child
-			}
-			current = child
-		}
-		current[segments[len(segments)-1]] = value
-	}
-	return doc
-}
-
 func TestFormat(t *testing.T) {
 	runFormatCases(t, []formatCase{
 		{
@@ -117,121 +93,9 @@ So, the ball costs 5 cents.`,
 			wantOutput: `[]`,
 		},
 		{
-			name:       "NoMessageAttributes_EmptyListsNoFormatter",
-			attributes: map[string]any{GenAIRequestModel: "gpt-4o", GenAIToolName: "get_weather"},
+			name:       "NoAttributes_EmptyListsNoFormatter",
 			wantInput:  `[]`,
 			wantOutput: `[]`,
 		},
 	})
 }
-
-func TestIndexed(t *testing.T) {
-	testCases := []struct {
-		name string
-		doc  map[string]any
-		want []map[string]any
-	}{
-		{
-			name: "NumericKeys_SortedNumerically",
-			doc:  document(map[string]any{"llm.input_messages.10.message.role": "user", "llm.input_messages.2.message.role": "system", "llm.input_messages.x.message.role": "skipped"}),
-			want: []map[string]any{{"message": map[string]any{"role": "system"}}, {"message": map[string]any{"role": "user"}}},
-		},
-		{
-			name: "StructuredList_KeptInOrder",
-			doc:  map[string]any{"llm": map[string]any{"input_messages": []any{map[string]any{"message": "b"}, map[string]any{"message": "a"}, "not an object"}}},
-			want: []map[string]any{{"message": "b"}, {"message": "a"}},
-		},
-		{name: "Absent_Empty", doc: map[string]any{}, want: []map[string]any{}},
-	}
-	for _, testCase := range testCases {
-		t.Run(testCase.name, func(t *testing.T) {
-			assert.Equal(t, testCase.want, indexed(testCase.doc, openInferenceInputMessages))
-		})
-	}
-}
-
-func TestFormat_SystemInstructions(t *testing.T) {
-	input := `[{"role":"user","parts":[{"type":"text","content":"hi"}]}]`
-	runFormatCases(t, []formatCase{
-		{
-			// the langchain instrumentation moves system messages out of the history into gen_ai.system_instructions,
-			// a JSON list of parts:
-			// https://github.com/traceloop/openllmetry/blob/93429cfb9767e6b51db6cb35f6b70f758117669a/packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py#L304
-			name:       "ListOfParts_LeadsInput",
-			input:      input,
-			attributes: map[string]any{GenAISystemInstructions: `[{"type": "text", "content": "You are concise."}]`},
-			formatter:  FormatterSemconv,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "You are concise."}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "hi"}]}
-			]`,
-			wantOutput: `[]`,
-		},
-		{
-			// the OpenInference strands processor keeps gen_ai.system_instructions on the span and inserts the
-			// same prompt as message 0
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L152
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/python/instrumentation/openinference-instrumentation-strands-agents/src/openinference/instrumentation/strands_agents/processor.py#L293
-			name:       "SameTextLeadsInput_Skipped",
-			input:      `[{"role":"system","parts":[{"type":"text","content":"You are concise."}]},{"role":"user","parts":[{"type":"text","content":"hi"}]}]`,
-			attributes: map[string]any{GenAISystemInstructions: `[{"type": "text", "content": "You are concise."}]`},
-			formatter:  FormatterSemconv,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "You are concise."}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "hi"}]}
-			]`,
-			wantOutput: `[]`,
-		},
-		{
-			name:       "BareString_TextPart",
-			input:      input,
-			attributes: map[string]any{GenAISystemInstructions: "be brief"},
-			formatter:  FormatterSemconv,
-			wantInput: `[
-			  {"role": "system", "parts": [{"type": "text", "content": "be brief"}]},
-			  {"role": "user", "parts": [{"type": "text", "content": "hi"}]}
-			]`,
-			wantOutput: `[]`,
-		},
-		{
-			// a create_agent span carries instructions alone
-			name:       "NoMessages_Nothing",
-			attributes: map[string]any{GenAISystemInstructions: "be brief"},
-			wantInput:  `[]`,
-			wantOutput: `[]`,
-		},
-	})
-}
-
-func TestFormat_FinishReasons(t *testing.T) {
-	output := `[{"role":"assistant","parts":[{"type":"text","content":"a"}],"finish_reason":"stop"},{"role":"assistant","parts":[{"type":"text","content":"b"}]}]`
-	runFormatCases(t, []formatCase{
-		{
-			name:       "List_OverridesMessages",
-			output:     output,
-			attributes: map[string]any{GenAIResponseFinishReasons: []any{"tool_calls", "length"}},
-			formatter:  FormatterSemconv,
-			wantInput:  `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "a"}], "finish_reason": "tool_call"}, {"role": "assistant", "parts": [{"type": "text", "content": "b"}], "finish_reason": "length"}]`,
-		},
-		{
-			name:       "LengthMismatch_LeavesMessages_Warns",
-			output:     output,
-			attributes: map[string]any{GenAIResponseFinishReasons: []any{"stop"}},
-			formatter:  FormatterSemconv,
-			warnings:   []string{"gen_ai.response.finish_reasons has 1 entries for 2 output messages"},
-			wantInput:  `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "a"}], "finish_reason": "stop"}, {"role": "assistant", "parts": [{"type": "text", "content": "b"}]}]`,
-		},
-		{
-			// llm.finish_reason copied by the mapper as a bare string, in the Vercel AI SDK spelling:
-			// https://github.com/vercel/ai/blob/a5e92fe3c692f8e152fe1eb9ef50a4e734ad0ffb/packages/provider/src/language-model/v2/language-model-v2-finish-reason.ts
-			name:       "BareString_SingleChoice",
-			output:     `{"choices":[{"finish_reason":"stop","message":{"role":"assistant","content":"hi"}}]}`,
-			attributes: map[string]any{GenAIResponseFinishReasons: "tool-calls"},
-			formatter:  FormatterOpenAIChat,
-			wantInput:  `[]`,
-			wantOutput: `[{"role": "assistant", "parts": [{"type": "text", "content": "hi"}], "finish_reason": "tool_call"}]`,
-		},
-	})
-}

pkg/types/aiobservabilitytypes/message_format_tool.go

@@ -1,72 +0,0 @@
-package aiobservabilitytypes
-
-// Format: gen_ai.tool.call.arguments and gen_ai.tool.call.result on an execute_tool span, each an
-// object or its JSON string:
-// https://github.com/open-telemetry/semantic-conventions-genai/blob/06ec68e722c45a7218e23ea1bc1339fe4e21ecae/model/gen-ai/registry.yaml#L545
-// Written by: opentelemetry-instrumentation-langchain, traceloop @tool, OpenInference TOOL spans and
-// Vercel ai.toolCall.* through the span mapper.
-// Envelopes unwrapped: LangChain's on_tool_start and on_tool_end payloads, {input_str, tags, metadata,
-// inputs, kwargs} and {output, kwargs}:
-// https://github.com/traceloop/openllmetry/blob/93429cfb9767e6b51db6cb35f6b70f758117669a/packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/callback_handler.py#L837
-// The traceloop decorator's {args, kwargs}:
-// https://github.com/traceloop/openllmetry/blob/93429cfb9767e6b51db6cb35f6b70f758117669a/packages/traceloop-sdk/traceloop/sdk/decorators/base.py#L169
-
-// tool renders the call as an assistant tool_call and the result as a tool tool_call_response, both
-// carrying gen_ai.tool.call.id so the pair can be matched.
-func (f *formatting) tool() {
-	id := optionalString(attribute(f.attributes, GenAIToolCallID))
-	if raw := attribute(f.attributes, GenAIToolCallArguments); raw != nil {
-		call := ToolCallRequestPart{Type: PartTypeToolCall, Name: stringOf(attribute(f.attributes, GenAIToolName)), ID: id, Arguments: toolArguments(decode(raw))}
-		f.out.Input = InputMessages{{Role: RoleAssistant, Parts: Parts{part(call)}}}
-	}
-	if raw := attribute(f.attributes, GenAIToolCallResult); raw != nil {
-		result := ToolCallResponsePart{Type: PartTypeToolCallResponse, ID: id, Response: toolResult(decode(raw))}
-		f.out.Output = OutputMessages{{Role: RoleTool, Parts: Parts{part(result)}}}
-	}
-	f.out.Formatter = FormatterTool
-}
-
-func toolArguments(value any) any {
-	m, ok := value.(map[string]any)
-	if !ok {
-		return value
-	}
-	if _, isLangChain := m["input_str"]; isLangChain && hasKeys(m, "inputs", "kwargs") {
-		if inputs := m["inputs"]; inputs != nil {
-			return inputs
-		}
-		return decode(m["input_str"])
-	}
-	if len(m) == 2 && hasKeys(m, "args", "kwargs") {
-		args, _ := m["args"].([]any)
-		kwargs, _ := m["kwargs"].(map[string]any)
-		switch {
-		case len(args) == 0:
-			return m["kwargs"]
-		case len(kwargs) == 0:
-			return args
-		}
-	}
-	return value
-}
-
-// toolResult unwraps the LangChain envelope; the traceloop decorator encodes a tool returning
-// nothing as the literal null.
-func toolResult(value any) any {
-	if m, ok := value.(map[string]any); ok && len(m) == 2 && hasKeys(m, "output", "kwargs") {
-		return decode(m["output"])
-	}
-	if value == "null" {
-		return nil
-	}
-	return value
-}
-
-func hasKeys(m map[string]any, keys ...string) bool {
-	for _, key := range keys {
-		if _, ok := m[key]; !ok {
-			return false
-		}
-	}
-	return true
-}

pkg/types/aiobservabilitytypes/message_format_tool_test.go

@@ -1,112 +0,0 @@
-package aiobservabilitytypes
-
-import "testing"
-
-// Captured cases are the tool span attributes as the collector stored them for the SigNoz/scripts
-// static-telemetry-generator captures, after the span mapper filled the gen_ai.tool.call.* keys.
-func TestFormat_Tool(t *testing.T) {
-	runFormatCases(t, []formatCase{
-		{
-			// gen_ai.tool.call.arguments and gen_ai.tool.call.result written by the langchain instrumentation itself,
-			// wrapped in its on_tool_start and on_tool_end payloads:
-			// https://github.com/traceloop/openllmetry/blob/93429cfb9767e6b51db6cb35f6b70f758117669a/packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/callback_handler.py#L837
-			name: "LangChainEnvelopes_InputsAndOutputUnwrapped",
-			attributes: map[string]any{
-				GenAIToolName:          "get_weather",
-				GenAIToolCallArguments: `{"input_str": "{'city': 'Bengaluru'}", "tags": [], "metadata": {}, "inputs": {"city": "Bengaluru"}, "kwargs": {"color": "green", "name": null, "tool_call_id": null}}`,
-				GenAIToolCallResult:    `{"output": "{\"city\": \"Bengaluru\", \"temp_c\": 18, \"summary\": \"Clear\"}", "kwargs": {"tags": [], "color": "green", "name": "get_weather"}}`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_weather", "arguments": {"city": "Bengaluru"}}]}]`,
-			wantOutput: `[{"role": "tool", "parts": [{"type": "tool_call_response", "response": {"city": "Bengaluru", "temp_c": 18, "summary": "Clear"}}]}]`,
-		},
-		{
-			// traceloop.entity.input and traceloop.entity.output from the @tool decorator, renamed by the mapper;
-			// the tool returned a JSON string, which json.dumps encoded again:
-			// https://github.com/traceloop/openllmetry/blob/93429cfb9767e6b51db6cb35f6b70f758117669a/packages/traceloop-sdk/traceloop/sdk/decorators/base.py#L169
-			name: "TraceloopDecorator_KwargsUnwrapped_ResultDecodedTwice",
-			attributes: map[string]any{
-				GenAIToolName:          "get_weather",
-				GenAIToolCallArguments: `{"args": [], "kwargs": {"city": "Bengaluru"}}`,
-				GenAIToolCallResult:    `"{\"city\": \"Bengaluru\", \"temp_c\": 28, \"summary\": \"Partly cloudy\"}"`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_weather", "arguments": {"city": "Bengaluru"}}]}]`,
-			wantOutput: `[{"role": "tool", "parts": [{"type": "tool_call_response", "response": {"city": "Bengaluru", "temp_c": 28, "summary": "Partly cloudy"}}]}]`,
-		},
-		{
-			// traceloop.entity.output of a @tool returning None, json.dumps(None), renamed by the mapper:
-			// https://github.com/traceloop/openllmetry/blob/93429cfb9767e6b51db6cb35f6b70f758117669a/packages/traceloop-sdk/traceloop/sdk/decorators/base.py#L185
-			name: "TraceloopDecorator_PositionalArgsOnly_ListKept",
-			attributes: map[string]any{
-				GenAIToolName:          "lookup",
-				GenAIToolCallArguments: `{"args": ["OpenAI", "What's the weather in Paris?"], "kwargs": {}}`,
-				GenAIToolCallResult:    `null`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "lookup", "arguments": ["OpenAI", "What's the weather in Paris?"]}]}]`,
-			wantOutput: `[{"role": "tool", "parts": [{"type": "tool_call_response", "response": null}]}]`,
-		},
-		{
-			name: "TraceloopDecorator_BothArgsAndKwargs_EnvelopeKept",
-			attributes: map[string]any{
-				GenAIToolName:          "lookup",
-				GenAIToolCallArguments: `{"args": ["Paris"], "kwargs": {"unit": "c"}}`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "lookup", "arguments": {"args": ["Paris"], "kwargs": {"unit": "c"}}}]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// input.value and output.value of an OpenInference TOOL span, renamed by the mapper:
-			// https://github.com/Arize-ai/openinference/blob/12f2cc035edfb00b60b656d977f07abfb7a69900/spec/traces.md
-			name: "OpenInferenceToolSpan_PlainJSONAndText",
-			attributes: map[string]any{
-				GenAIToolName:          "get_weather",
-				GenAIToolCallArguments: `{"city":"Bangalore"}`,
-				GenAIToolCallResult:    `27C, partly cloudy, light breeze from the south.`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_weather", "arguments": {"city": "Bangalore"}}]}]`,
-			wantOutput: `[{"role": "tool", "parts": [{"type": "tool_call_response", "response": "27C, partly cloudy, light breeze from the south."}]}]`,
-		},
-		{
-			// ai.toolCall.{id,name,args,result} of a Vercel ai.toolCall span, renamed by the mapper:
-			// https://ai-sdk.dev/docs/ai-sdk-core/telemetry
-			name: "VercelToolCall_IDOnBothParts",
-			attributes: map[string]any{
-				GenAIToolName:          "get_current_weather",
-				GenAIToolCallID:        "call_l0ycKcmt1uPCdGWR4SkwoLBv",
-				GenAIToolCallArguments: `{"city":"Bengaluru","unit":"c"}`,
-				GenAIToolCallResult:    `{"city":"Bengaluru","unit":"c","temperature":27,"condition":"partly cloudy"}`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_current_weather", "id": "call_l0ycKcmt1uPCdGWR4SkwoLBv", "arguments": {"city": "Bengaluru", "unit": "c"}}]}]`,
-			wantOutput: `[{"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_l0ycKcmt1uPCdGWR4SkwoLBv", "response": {"city": "Bengaluru", "unit": "c", "temperature": 27, "condition": "partly cloudy"}}]}]`,
-		},
-		{
-			// the object form the OTel registry asks for, whole in the JSON column
-			name: "StructuredArguments_ObjectKept",
-			attributes: map[string]any{
-				GenAIToolName:          "get_weather",
-				GenAIToolCallID:        "call_1",
-				GenAIToolCallArguments: map[string]any{"city": "Paris", "days": []any{1.0, 2.0}},
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "get_weather", "id": "call_1", "arguments": {"city": "Paris", "days": [1, 2]}}]}]`,
-			wantOutput: `[]`,
-		},
-		{
-			// the mapper groups never fill both; the tool call wins when an SDK does
-			name: "MessagesBesideToolCall_ToolCallFormatted",
-			attributes: map[string]any{
-				GenAIInputMessages:     `[{"role": "user", "parts": [{"type": "text", "content": "hi"}]}]`,
-				GenAIToolName:          "lookup",
-				GenAIToolCallArguments: `{"city": "Paris"}`,
-			},
-			formatter:  FormatterTool,
-			wantInput:  `[{"role": "assistant", "parts": [{"type": "tool_call", "name": "lookup", "arguments": {"city": "Paris"}}]}]`,
-			wantOutput: `[]`,
-		},
-	})
-}

pkg/types/dashboardtypes/perses_dashboard_data.go

@@ -123,10 +123,22 @@ func (d *DashboardSpec) validatePanels() error {
 				return err
 			}
 		}
+		// validatePanelQueryCount left exactly one query for a spec that reads it.
+		if spec, ok := panel.Spec.Plugin.Spec.(queryBoundPanelSpec); ok {
+			if err := spec.validateAgainstQuery(panel.Spec.Queries[0], path+".spec.plugin.spec"); err != nil {
+				return err
+			}
+		}
 	}
 	return nil
 }
 
+// queryBoundPanelSpec is a panel spec with fields that depend on the panel's
+// query. It is checked after the query itself validates.
+type queryBoundPanelSpec interface {
+	validateAgainstQuery(query Query, path string) error
+}
+
 func validatePanelQueryCount(queries []Query, panelKind PanelPluginKind, path string) error {
 	if queries == nil {
 		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "%s.spec.queries: is required and must not be null; use [] for a panel that renders without a query", path)

pkg/types/dashboardtypes/perses_dashboard_test.go

@@ -1870,6 +1870,319 @@ func TestInvalidateAreaChartPanelSpecValues(t *testing.T) {
 	}
 }
 
+func TestScatterPlotPanelDefaults(t *testing.T) {
+	data := []byte(`{
+		"variables": [],
+		"panels": {
+			"p1": {
+				"kind": "Panel",
+				"spec": {
+					"links": [],
+					"plugin": {
+						"kind": "signoz/ScatterPlotPanel",
+						"spec": {}
+					},
+					"queries": [{"kind": "scalar", "spec": {"plugin": {"kind": "signoz/ClickHouseSQL", "spec": {"name": "A", "query": "SELECT 1"}}}}]
+				}
+			}
+		},
+		"links": [],
+		"layouts": []
+	}`)
+	d, err := unmarshalDashboard(data)
+	require.NoError(t, err, "unmarshal and validate failed")
+
+	require.IsType(t, &ScatterPlotPanelSpec{}, d.Panels["p1"].Spec.Plugin.Spec)
+	spec := d.Panels["p1"].Spec.Plugin.Spec.(*ScatterPlotPanelSpec)
+
+	assert.Empty(t, spec.Dimensions.X, "an omitted x stays empty so the renderer picks the first value column")
+	assert.Empty(t, spec.Dimensions.Y, "an omitted y stays empty so the renderer picks the second value column")
+	assert.Empty(t, spec.Dimensions.ColorBy, "an omitted colorBy stays empty so the renderer colours by every group-by label")
+	assert.Equal(t, "auto", spec.Axes.X.Scale.ValueOrDefault(), "expected x scale default auto")
+	assert.Equal(t, "auto", spec.Axes.Y.Scale.ValueOrDefault(), "expected y scale default auto")
+	assert.Nil(t, spec.Axes.X.SoftMin, "expected x softMin unset")
+	assert.Equal(t, "2", spec.Formatting.DecimalPrecision.ValueOrDefault(), "expected DecimalPrecision default 2")
+	assert.Equal(t, "global_time", spec.Visualization.TimePreference.ValueOrDefault(), "expected TimePreference default global_time")
+	assert.Equal(t, "bottom", spec.Legend.Position.ValueOrDefault(), "expected LegendPosition default bottom")
+
+	output, err := json.Marshal(d)
+	require.NoError(t, err, "marshal dashboard failed")
+	assert.Contains(t, string(output), `"axes":{"x":{"softMin":null,"softMax":null,"scale":"auto","label":""},"y":{"softMin":null,"softMax":null,"scale":"auto","label":""}}`, "expected default axes in stored/response JSON")
+	assert.Contains(t, string(output), `"dimensions":{"x":"","y":"","sizeBy":"","colorBy":null}`, "expected empty dimensions in stored/response JSON")
+	assert.Contains(t, string(output), `"chartAppearance":{"points":{"size":null,"minSize":null,"maxSize":null,"opacity":null}}`, "omitted point settings stay null so the renderer applies its defaults")
+}
+
+func TestValidateScatterPlotDashboard(t *testing.T) {
+	data, err := os.ReadFile("testdata/perses_scatter_plot_panel.json")
+	require.NoError(t, err, "reading example file")
+
+	spec, err := unmarshalDashboard(data)
+	require.NoError(t, err, "unmarshal and validate failed")
+
+	require.IsType(t, &ScatterPlotPanelSpec{}, spec.Panels["p1"].Spec.Plugin.Spec)
+	panelSpec := spec.Panels["p1"].Spec.Plugin.Spec.(*ScatterPlotPanelSpec)
+	softMin, softMax := 0.0, 1000.0
+	size, minSize, maxSize, opacity := PointDiameter(8), PointDiameter(4), PointDiameter(24), PointOpacity(0.1)
+	assert.Equal(t, &ScatterPlotPanelSpec{
+		Visualization: BasicVisualization{TimePreference: TimePreferenceLast1Hr},
+		Dimensions:    ScatterPlotDimensions{X: "A.count()", Y: "A.p99(duration_nano)", SizeBy: "A.countIf(has_error = true)", ColorBy: []string{"k8s.namespace.name", "k8s.pod.name"}},
+		Formatting:    TableFormatting{ColumnUnits: map[string]string{"A.p99(duration_nano)": "ns"}, DecimalPrecision: PrecisionOption1},
+		Axes: ScatterPlotAxes{
+			X: ScatterPlotAxis{SoftMin: &softMin, Scale: AxisScaleLog, Label: "Throughput"},
+			Y: ScatterPlotAxis{SoftMax: &softMax, Scale: AxisScaleSymlog, Label: "p99 latency"},
+		},
+		ChartAppearance: ScatterPlotChartAppearance{Points: ScatterPlotPoints{Size: &size, MinSize: &minSize, MaxSize: &maxSize, Opacity: &opacity}},
+		Legend:          Legend{Position: LegendPositionRight, Mode: LegendModeList, CustomColors: map[string]string{"checkout": "#1f77b4"}},
+		Thresholds: []ScatterPlotThreshold{
+			{ThresholdWithLabel: ThresholdWithLabel{Value: 300, Unit: "ms", Color: "#f00", Label: "p99 SLO"}, Axis: ThresholdAxisY},
+			{ThresholdWithLabel: ThresholdWithLabel{Value: 50, Color: "#0f0"}, Axis: ThresholdAxisX},
+		},
+	}, panelSpec)
+
+	dashboard := &DashboardV2{Spec: *spec}
+	request, err := dashboard.GetPanelQuery(1, 2, "p1")
+	require.NoError(t, err, "building the panel's query failed")
+	assert.Equal(t, qb.RequestTypeScalar, request.RequestType)
+	require.NotNil(t, request.FormatOptions)
+	assert.True(t, request.FormatOptions.FormatTableResultForUI, "scatter rows are joined the way a table's are")
+
+	require.Len(t, request.CompositeQuery.Queries, 1)
+	query, ok := request.CompositeQuery.Queries[0].Spec.(qb.QueryBuilderQuery[qb.TraceAggregation])
+	require.True(t, ok, "expected a traces builder query")
+	assert.Len(t, query.Aggregations, 3)
+	assert.Len(t, query.GroupBy, 2)
+
+	require.NoError(t, request.Validate(), "the request built from the panel is not a valid scalar request")
+
+	// the panel read back out of storage draws the same scatter plot
+	stored, err := json.Marshal(spec)
+	require.NoError(t, err, "marshal dashboard failed")
+	reread, err := unmarshalDashboard(stored)
+	require.NoError(t, err, "the stored dashboard does not validate")
+	assert.Equal(t, panelSpec, reread.Panels["p1"].Spec.Plugin.Spec)
+	rereadRequest, err := (&DashboardV2{Spec: *reread}).GetPanelQuery(1, 2, "p1")
+	require.NoError(t, err, "building the stored panel's query failed")
+	assert.Equal(t, request, rereadRequest)
+}
+
+func TestInvalidateScatterPlotPanelSpecValues(t *testing.T) {
+	tests := []struct {
+		scenario               string
+		panelKind              string
+		panelSpec              string
+		expectedErrorSubstring string
+	}{
+		{
+			scenario:               "unknown axis scale",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"axes": {"x": {"scale": "sqrt"}}}`,
+			expectedErrorSubstring: "invalid axis scale \"sqrt\": must be `auto`, `linear`, `log`, or `symlog`",
+		},
+		{
+			scenario:               "non-string axis scale",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"axes": {"y": {"scale": true}}}`,
+			expectedErrorSubstring: "cannot unmarshal bool",
+		},
+		{
+			scenario:               "isLogScale on a scatter plot axis",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"axes": {"x": {"isLogScale": true}}}`,
+			expectedErrorSubstring: "unknown field",
+		},
+		{
+			scenario:               "single-axis axes shape on a scatter plot panel",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"axes": {"softMin": 0}}`,
+			expectedErrorSubstring: "unknown field",
+		},
+		{
+			scenario:               "unknown threshold axis",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"thresholds": [{"value": 1, "color": "#f00", "axis": "z"}]}`,
+			expectedErrorSubstring: "invalid threshold axis \"z\": must be `x` or `y`",
+		},
+		{
+			scenario:               "unknown dimension",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"dimensions": {"z": "A"}}`,
+			expectedErrorSubstring: "unknown field",
+		},
+		{
+			scenario:               "point size below the minimum",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"points": {"size": 1}}}`,
+			expectedErrorSubstring: "invalid point diameter 1: must be a whole number between 2 and 40",
+		},
+		{
+			scenario:               "max point size above the maximum",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"points": {"maxSize": 41}}}`,
+			expectedErrorSubstring: "invalid point diameter 41",
+		},
+		{
+			scenario:               "fractional point size",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"points": {"minSize": 4.5}}}`,
+			expectedErrorSubstring: "cannot unmarshal number 4.5",
+		},
+		{
+			scenario:               "min point size above max",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"points": {"minSize": 20, "maxSize": 10}}}`,
+			expectedErrorSubstring: "minSize 20 must not exceed maxSize 10",
+		},
+		{
+			scenario:               "point opacity below the floor",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"points": {"opacity": 0.05}}}`,
+			expectedErrorSubstring: "invalid point opacity 0.05: must be between 0.1 and 1",
+		},
+		{
+			scenario:               "point opacity as a percentage",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"points": {"opacity": 70}}}`,
+			expectedErrorSubstring: "invalid point opacity 70",
+		},
+		{
+			scenario:               "area fill fields on a scatter plot",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"chartAppearance": {"fillOpacity": 0.5}}`,
+			expectedErrorSubstring: "unknown field",
+		},
+		{
+			scenario:               "a single colour key as a string",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"dimensions": {"colorBy": "service.name"}}`,
+			expectedErrorSubstring: "cannot unmarshal string",
+		},
+		{
+			scenario:               "panel-wide unit on a scatter plot panel",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"formatting": {"unit": "ms"}}`,
+			expectedErrorSubstring: "unknown field",
+		},
+		{
+			scenario:               "threshold without a color",
+			panelKind:              "signoz/ScatterPlotPanel",
+			panelSpec:              `{"thresholds": [{"value": 300}]}`,
+			expectedErrorSubstring: "Color' Error:Field validation for 'Color' failed on the 'required' tag",
+		},
+		{
+			scenario:               "scale on a time series panel",
+			panelKind:              "signoz/TimeSeriesPanel",
+			panelSpec:              `{"axes": {"scale": "log"}}`,
+			expectedErrorSubstring: "unknown field",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.scenario, func(t *testing.T) {
+			data := []byte(`{
+				"variables": [],
+				"panels": {
+					"p1": {
+						"kind": "Panel",
+						"spec": {
+							"links": [],
+							"plugin": {"kind": "` + test.panelKind + `", "spec": ` + test.panelSpec + `},
+							"queries": [{"kind": "scalar", "spec": {"plugin": {"kind": "signoz/ClickHouseSQL", "spec": {"name": "A", "query": "SELECT 1"}}}}]
+						}
+					}
+				},
+				"links": [],
+				"layouts": []
+			}`)
+			_, err := unmarshalDashboard(data)
+			require.Error(t, err, "expected the spec to be rejected")
+			assert.Contains(t, err.Error(), test.expectedErrorSubstring, "unexpected error message: %s", err.Error())
+		})
+	}
+}
+
+func TestScatterPlotDimensionsBindToQuery(t *testing.T) {
+	tests := []struct {
+		scenario               string
+		queryPlugin            string
+		dimensions             string
+		expectedErrorSubstring string
+	}{
+		{
+			scenario:    "a single-aggregation query is one value column keyed by its name",
+			queryPlugin: `{"kind": "signoz/BuilderQuery", "spec": {"name": "A", "signal": "traces", "aggregations": [{"expression": "count()"}], "groupBy": [{"name": "service.name"}]}}`,
+			dimensions:  `{"x": "A", "colorBy": ["service.name"]}`,
+		},
+		{
+			scenario:               "a multi-aggregation query keys each value column by name and expression",
+			queryPlugin:            `{"kind": "signoz/BuilderQuery", "spec": {"name": "A", "signal": "traces", "aggregations": [{"expression": "count()"}, {"expression": "p99(duration_nano)"}]}}`,
+			dimensions:             `{"x": "A"}`,
+			expectedErrorSubstring: "dimensions.x: \"A\" is not a value column of the panel's query; value columns: `A.count()`, `A.p99(duration_nano)`",
+		},
+		{
+			scenario:               "a value column of a query the panel does not have",
+			queryPlugin:            `{"kind": "signoz/BuilderQuery", "spec": {"name": "A", "signal": "logs", "aggregations": [{"expression": "count()"}]}}`,
+			dimensions:             `{"y": "B"}`,
+			expectedErrorSubstring: "dimensions.y: \"B\" is not a value column of the panel's query; value columns: `A`",
+		},
+		{
+			scenario:               "a colour key the query does not group by",
+			queryPlugin:            `{"kind": "signoz/BuilderQuery", "spec": {"name": "A", "signal": "traces", "aggregations": [{"expression": "count()"}], "groupBy": [{"name": "service.name"}]}}`,
+			dimensions:             `{"colorBy": ["service.name", "k8s.pod.name"]}`,
+			expectedErrorSubstring: "dimensions.colorBy: \"k8s.pod.name\" is not a group-by key of the panel's query; group-by keys: `service.name`",
+		},
+		{
+			scenario: "a formula is a value column and carries the labels of the disabled queries it reads",
+			queryPlugin: `{"kind": "signoz/CompositeQuery", "spec": {"queries": [
+				{"type": "builder_query", "spec": {"name": "A", "signal": "traces", "disabled": true, "aggregations": [{"expression": "count()"}], "groupBy": [{"name": "service.name"}]}},
+				{"type": "builder_query", "spec": {"name": "B", "signal": "traces", "disabled": true, "aggregations": [{"expression": "countIf(has_error = true)"}], "groupBy": [{"name": "service.name"}]}},
+				{"type": "builder_formula", "spec": {"name": "F1", "expression": "B / A"}}
+			]}}`,
+			dimensions: `{"x": "F1", "colorBy": ["service.name"]}`,
+		},
+		{
+			scenario: "a disabled query yields no value column",
+			queryPlugin: `{"kind": "signoz/CompositeQuery", "spec": {"queries": [
+				{"type": "builder_query", "spec": {"name": "A", "signal": "logs", "disabled": true, "aggregations": [{"expression": "count()"}]}},
+				{"type": "builder_formula", "spec": {"name": "F1", "expression": "A * 2"}}
+			]}}`,
+			dimensions:             `{"sizeBy": "A"}`,
+			expectedErrorSubstring: "dimensions.sizeBy: \"A\" is not a value column of the panel's query; value columns: `F1`",
+		},
+		{
+			scenario:    "clickhouse columns are only known at run time, so the bindings go unchecked",
+			queryPlugin: `{"kind": "signoz/ClickHouseSQL", "spec": {"name": "A", "query": "SELECT 1"}}`,
+			dimensions:  `{"x": "throughput", "colorBy": ["pod"]}`,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.scenario, func(t *testing.T) {
+			data := []byte(`{
+				"variables": [],
+				"panels": {
+					"p1": {
+						"kind": "Panel",
+						"spec": {
+							"links": [],
+							"plugin": {"kind": "signoz/ScatterPlotPanel", "spec": {"dimensions": ` + test.dimensions + `}},
+							"queries": [{"kind": "scalar", "spec": {"plugin": ` + test.queryPlugin + `}}]
+						}
+					}
+				},
+				"links": [],
+				"layouts": []
+			}`)
+			_, err := unmarshalDashboard(data)
+			if test.expectedErrorSubstring == "" {
+				require.NoError(t, err)
+				return
+			}
+			require.Error(t, err, "expected the binding to be rejected")
+			assert.Contains(t, err.Error(), test.expectedErrorSubstring, "unexpected error message: %s", err.Error())
+		})
+	}
+}
+
 func TestNumberPanelDefaults(t *testing.T) {
 	data := []byte(`{
 		"variables": [],
@@ -2228,7 +2541,7 @@ func TestPanelTypeQueryTypeCompatibility(t *testing.T) {
 		switch panelKind {
 		case "signoz/ListPanel":
 			return "raw"
-		case "signoz/TablePanel", "signoz/NumberPanel", "signoz/PieChartPanel", "signoz/HistogramPanel":
+		case "signoz/TablePanel", "signoz/NumberPanel", "signoz/PieChartPanel", "signoz/HistogramPanel", "signoz/ScatterPlotPanel":
 			return "scalar"
 		default:
 			return "time_series"
@@ -2272,14 +2585,17 @@ func TestPanelTypeQueryTypeCompatibility(t *testing.T) {
 		{"List+Builder", mkQuery("signoz/ListPanel", "signoz/BuilderQuery", `{"name":"A","signal":"logs"}`), false},
 		{"TimeSeries+AIBuilder", mkQuery("signoz/TimeSeriesPanel", "signoz/AIBuilderQuery", `{"name":"A","aggregations":[{"expression":"count()"}]}`), false},
 		{"List+AIBuilder", mkQuery("signoz/ListPanel", "signoz/AIBuilderQuery", `{"name":"A"}`), false},
+		{"ScatterPlot+ClickHouse", mkQuery("signoz/ScatterPlotPanel", "signoz/ClickHouseSQL", `{"name":"A","query":"SELECT 1"}`), false},
 		// Top-level: rejected
 		{"Table+PromQL", mkQuery("signoz/TablePanel", "signoz/PromQLQuery", `{"name":"A","query":"up"}`), true},
+		{"ScatterPlot+PromQL", mkQuery("signoz/ScatterPlotPanel", "signoz/PromQLQuery", `{"name":"A","query":"up"}`), true},
 		{"List+ClickHouse", mkQuery("signoz/ListPanel", "signoz/ClickHouseSQL", `{"name":"A","query":"SELECT 1"}`), true},
 		{"List+PromQL", mkQuery("signoz/ListPanel", "signoz/PromQLQuery", `{"name":"A","query":"up"}`), true},
 		{"List+Composite", mkQuery("signoz/ListPanel", "signoz/CompositeQuery", `{"queries":[]}`), true},
 		{"List+Formula", mkQuery("signoz/ListPanel", "signoz/Formula", `{"name":"F1","expression":"A+B"}`), true},
 		// Composite sub-queries
 		{"Table+Composite(promql)", mkComposite("signoz/TablePanel", "promql", `{"name":"A","query":"up"}`), true},
+		{"ScatterPlot+Composite(promql)", mkComposite("signoz/ScatterPlotPanel", "promql", `{"name":"A","query":"up"}`), true},
 		{"Table+Composite(clickhouse)", mkComposite("signoz/TablePanel", "clickhouse_sql", `{"name":"A","query":"SELECT 1"}`), false},
 		{"Table+Composite(builder_ai)", mkComposite("signoz/TablePanel", "builder_ai_query", `{"name":"A","aggregations":[{"expression":"count()"}]}`), false},
 	}

pkg/types/dashboardtypes/perses_plugin_wrappers.go

@@ -28,16 +28,17 @@ type PanelPlugin struct {
 // (and strips the duplicate parent properties) after reflection.
 func (PanelPlugin) PrepareJSONSchema(s *jsonschema.Schema) error {
 	return markDiscriminator(s, "kind", map[string]string{
-		string(PanelKindTimeSeries): schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec"),
-		string(PanelKindBarChart):   schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec"),
-		string(PanelKindAreaChart):  schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec"),
-		string(PanelKindNumber):     schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec"),
-		string(PanelKindPieChart):   schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec"),
-		string(PanelKindTable):      schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec"),
-		string(PanelKindHistogram):  schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec"),
-		string(PanelKindList):       schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec"),
-		string(PanelKindText):       schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec"),
-		string(PanelKindHeatmap):    schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpec"),
+		string(PanelKindTimeSeries):  schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec"),
+		string(PanelKindBarChart):    schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec"),
+		string(PanelKindAreaChart):   schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesAreaChartPanelSpec"),
+		string(PanelKindNumber):      schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec"),
+		string(PanelKindPieChart):    schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec"),
+		string(PanelKindTable):       schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec"),
+		string(PanelKindHistogram):   schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec"),
+		string(PanelKindList):        schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec"),
+		string(PanelKindText):        schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec"),
+		string(PanelKindHeatmap):     schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHeatmapPanelSpec"),
+		string(PanelKindScatterPlot): schemaRef("DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesScatterPlotPanelSpec"),
 	})
 }
 
@@ -71,6 +72,7 @@ func (PanelPlugin) JSONSchemaOneOf() []any {
 		PanelPluginVariant[ListPanelSpec]{Kind: string(PanelKindList)},
 		PanelPluginVariant[TextPanelSpec]{Kind: string(PanelKindText)},
 		PanelPluginVariant[HeatmapPanelSpec]{Kind: string(PanelKindHeatmap)},
+		PanelPluginVariant[ScatterPlotPanelSpec]{Kind: string(PanelKindScatterPlot)},
 	}
 }
 
@@ -234,16 +236,17 @@ func (v VariablePluginVariant[S]) PrepareJSONSchema(s *jsonschema.Schema) error
 
 var (
 	panelPluginSpecs = map[PanelPluginKind]func() any{
-		PanelKindTimeSeries: func() any { return new(TimeSeriesPanelSpec) },
-		PanelKindBarChart:   func() any { return new(BarChartPanelSpec) },
-		PanelKindAreaChart:  func() any { return new(AreaChartPanelSpec) },
-		PanelKindNumber:     func() any { return new(NumberPanelSpec) },
-		PanelKindPieChart:   func() any { return new(PieChartPanelSpec) },
-		PanelKindTable:      func() any { return new(TablePanelSpec) },
-		PanelKindHistogram:  func() any { return new(HistogramPanelSpec) },
-		PanelKindList:       func() any { return new(ListPanelSpec) },
-		PanelKindText:       func() any { return new(TextPanelSpec) },
-		PanelKindHeatmap:    func() any { return new(HeatmapPanelSpec) },
+		PanelKindTimeSeries:  func() any { return new(TimeSeriesPanelSpec) },
+		PanelKindBarChart:    func() any { return new(BarChartPanelSpec) },
+		PanelKindAreaChart:   func() any { return new(AreaChartPanelSpec) },
+		PanelKindNumber:      func() any { return new(NumberPanelSpec) },
+		PanelKindPieChart:    func() any { return new(PieChartPanelSpec) },
+		PanelKindTable:       func() any { return new(TablePanelSpec) },
+		PanelKindHistogram:   func() any { return new(HistogramPanelSpec) },
+		PanelKindList:        func() any { return new(ListPanelSpec) },
+		PanelKindText:        func() any { return new(TextPanelSpec) },
+		PanelKindHeatmap:     func() any { return new(HeatmapPanelSpec) },
+		PanelKindScatterPlot: func() any { return new(ScatterPlotPanelSpec) },
 	}
 	queryPluginSpecs = map[QueryPluginKind]func() any{
 		QueryKindBuilder:       func() any { return new(BuilderQuerySpec) },
@@ -260,16 +263,17 @@ var (
 		VariableKindCustom:  func() any { return new(CustomVariableSpec) },
 	}
 	allowedQueryKinds = map[PanelPluginKind][]QueryPluginKind{
-		PanelKindTimeSeries: {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
-		PanelKindBarChart:   {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
-		PanelKindAreaChart:  {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
-		PanelKindNumber:     {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
-		PanelKindHistogram:  {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
-		PanelKindPieChart:   {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindClickHouseSQL},
-		PanelKindTable:      {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindClickHouseSQL},
-		PanelKindList:       {QueryKindBuilder, QueryKindAIBuilder},
-		PanelKindText:       {},
-		PanelKindHeatmap:    {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindTimeSeries:  {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindBarChart:    {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindAreaChart:   {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindNumber:      {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindHistogram:   {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindPieChart:    {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindClickHouseSQL},
+		PanelKindTable:       {QueryKindBuilder, QueryKindAIBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindClickHouseSQL},
+		PanelKindList:        {QueryKindBuilder, QueryKindAIBuilder},
+		PanelKindText:        {},
+		PanelKindHeatmap:     {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindPromQL, QueryKindClickHouseSQL},
+		PanelKindScatterPlot: {QueryKindBuilder, QueryKindComposite, QueryKindFormula, QueryKindTraceOperator, QueryKindClickHouseSQL},
 	}
 )
 

pkg/types/dashboardtypes/perses_public_dashboard.go

@@ -221,7 +221,7 @@ func (d *DashboardV2) GetPanelQuery(startTime, endTime uint64, panelKey string)
 		CompositeQuery: composite,
 		FormatOptions: &qb.FormatOptions{
 			FillGaps:               fillGaps,
-			FormatTableResultForUI: panel.Spec.Plugin.Kind == PanelKindTable,
+			FormatTableResultForUI: panel.Spec.Plugin.Kind == PanelKindTable || panel.Spec.Plugin.Kind == PanelKindScatterPlot,
 		},
 	}, nil
 }

pkg/types/dashboardtypes/perses_public_dashboard_panel_query_test.go

@@ -251,34 +251,38 @@ func TestDashboardV2GetPanelQuery(t *testing.T) {
 		assert.Equal(t, telemetrytypes.SignalTraces, spec.Signal)
 	})
 
-	t.Run("sets FormatTableResultForUI only for table panels", func(t *testing.T) {
-		dashboard := &DashboardV2{
-			Spec: DashboardSpec{
-				Panels: map[string]*Panel{
-					"panel-1": {
-						Spec: PanelSpec{
-							Plugin: PanelPlugin{Kind: PanelKindTable},
-							Queries: []Query{
-								{
-									Kind: qb.RequestTypeScalar,
-									Spec: QuerySpec{
-										Plugin: QueryPlugin{
-											Kind: QueryKindBuilder,
-											Spec: &BuilderQuerySpec{Spec: qb.QueryBuilderQuery[qb.MetricAggregation]{Name: "A"}},
+	t.Run("sets FormatTableResultForUI for panels that join scalar rows", func(t *testing.T) {
+		for _, kind := range []PanelPluginKind{PanelKindTable, PanelKindScatterPlot} {
+			t.Run(string(kind), func(t *testing.T) {
+				dashboard := &DashboardV2{
+					Spec: DashboardSpec{
+						Panels: map[string]*Panel{
+							"panel-1": {
+								Spec: PanelSpec{
+									Plugin: PanelPlugin{Kind: kind},
+									Queries: []Query{
+										{
+											Kind: qb.RequestTypeScalar,
+											Spec: QuerySpec{
+												Plugin: QueryPlugin{
+													Kind: QueryKindBuilder,
+													Spec: &BuilderQuerySpec{Spec: qb.QueryBuilderQuery[qb.MetricAggregation]{Name: "A"}},
+												},
+											},
 										},
 									},
 								},
 							},
 						},
 					},
-				},
-			},
-		}
+				}
 
-		req, err := dashboard.GetPanelQuery(1, 2, "panel-1")
-		require.NoError(t, err)
-		require.NotNil(t, req.FormatOptions)
-		assert.True(t, req.FormatOptions.FormatTableResultForUI)
+				req, err := dashboard.GetPanelQuery(1, 2, "panel-1")
+				require.NoError(t, err)
+				require.NotNil(t, req.FormatOptions)
+				assert.True(t, req.FormatOptions.FormatTableResultForUI)
+			})
+		}
 	})
 
 	t.Run("sets FillGaps from the panel visualization", func(t *testing.T) {

pkg/types/dashboardtypes/perses_signoz_plugins.go

@@ -2,6 +2,8 @@ package dashboardtypes
 
 import (
 	"encoding/json"
+	"maps"
+	"slices"
 	"strconv"
 
 	"github.com/SigNoz/signoz/pkg/errors"
@@ -187,20 +189,21 @@ func (AIBuilderQuerySpec) PrepareJSONSchema(s *jsonschema.Schema) error {
 type PanelPluginKind string
 
 const (
-	PanelKindTimeSeries PanelPluginKind = "signoz/TimeSeriesPanel"
-	PanelKindBarChart   PanelPluginKind = "signoz/BarChartPanel"
-	PanelKindAreaChart  PanelPluginKind = "signoz/AreaChartPanel"
-	PanelKindNumber     PanelPluginKind = "signoz/NumberPanel"
-	PanelKindPieChart   PanelPluginKind = "signoz/PieChartPanel"
-	PanelKindTable      PanelPluginKind = "signoz/TablePanel"
-	PanelKindHistogram  PanelPluginKind = "signoz/HistogramPanel"
-	PanelKindList       PanelPluginKind = "signoz/ListPanel"
-	PanelKindText       PanelPluginKind = "signoz/TextPanel"
-	PanelKindHeatmap    PanelPluginKind = "signoz/HeatmapPanel"
+	PanelKindTimeSeries  PanelPluginKind = "signoz/TimeSeriesPanel"
+	PanelKindBarChart    PanelPluginKind = "signoz/BarChartPanel"
+	PanelKindAreaChart   PanelPluginKind = "signoz/AreaChartPanel"
+	PanelKindNumber      PanelPluginKind = "signoz/NumberPanel"
+	PanelKindPieChart    PanelPluginKind = "signoz/PieChartPanel"
+	PanelKindTable       PanelPluginKind = "signoz/TablePanel"
+	PanelKindHistogram   PanelPluginKind = "signoz/HistogramPanel"
+	PanelKindList        PanelPluginKind = "signoz/ListPanel"
+	PanelKindText        PanelPluginKind = "signoz/TextPanel"
+	PanelKindHeatmap     PanelPluginKind = "signoz/HeatmapPanel"
+	PanelKindScatterPlot PanelPluginKind = "signoz/ScatterPlotPanel"
 )
 
 func (PanelPluginKind) Enum() []any {
-	return []any{PanelKindTimeSeries, PanelKindBarChart, PanelKindAreaChart, PanelKindNumber, PanelKindPieChart, PanelKindTable, PanelKindHistogram, PanelKindList, PanelKindText, PanelKindHeatmap}
+	return []any{PanelKindTimeSeries, PanelKindBarChart, PanelKindAreaChart, PanelKindNumber, PanelKindPieChart, PanelKindTable, PanelKindHistogram, PanelKindList, PanelKindText, PanelKindHeatmap, PanelKindScatterPlot}
 }
 
 func (k PanelPluginKind) rendersWithoutQuery() bool {
@@ -350,6 +353,95 @@ type TextPanelSpec struct {
 	HeaderOptions HeaderOptions    `json:"headerOptions"`
 }
 
+type ScatterPlotPanelSpec struct {
+	Visualization   BasicVisualization         `json:"visualization"`
+	Dimensions      ScatterPlotDimensions      `json:"dimensions"`
+	Formatting      TableFormatting            `json:"formatting"`
+	Axes            ScatterPlotAxes            `json:"axes"`
+	ChartAppearance ScatterPlotChartAppearance `json:"chartAppearance"`
+	Legend          Legend                     `json:"legend"`
+	Thresholds      []ScatterPlotThreshold     `json:"thresholds" validate:"dive"`
+}
+
+func (s *ScatterPlotPanelSpec) validateAgainstQuery(query Query, path string) error {
+	composite, err := query.Spec.Plugin.buildV5CompositeQueryFromPlugin()
+	if err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "%s.dimensions: %s", path, err.Error())
+	}
+	keys, known := composite.CollectResultColumnKeys()
+	if !known {
+		return nil
+	}
+	for _, binding := range []struct{ field, key string }{{"x", s.Dimensions.X}, {"y", s.Dimensions.Y}, {"sizeBy", s.Dimensions.SizeBy}} {
+		// Empty is unset: the renderer picks a column or a fixed size.
+		if binding.key == "" {
+			continue
+		}
+		if _, ok := keys.Aggregations[binding.key]; !ok {
+			return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "%s.dimensions.%s: %q is not a value column of the panel's query; value columns: %s", path, binding.field, binding.key, allowedValuesForKind(slices.Sorted(maps.Keys(keys.Aggregations))))
+		}
+	}
+	for _, label := range s.Dimensions.ColorBy {
+		if _, ok := keys.Groups[label]; !ok {
+			return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "%s.dimensions.colorBy: %q is not a group-by key of the panel's query; group-by keys: %s", path, label, allowedValuesForKind(slices.Sorted(maps.Keys(keys.Groups))))
+		}
+	}
+	return nil
+}
+
+// ScatterPlotDimensions binds result columns to what a dot encodes. Value columns
+// use the Table column key, so formatting.columnUnits carries over between the
+// two kinds.
+type ScatterPlotDimensions struct {
+	X       string   `json:"x" description:"Value column key (queryName, or queryName.expression for a multi-aggregation query) plotted on the x axis. Empty uses the first value column."`
+	Y       string   `json:"y" description:"Value column key plotted on the y axis. Empty uses the second value column."`
+	SizeBy  string   `json:"sizeBy" description:"Value column key that scales dot size. Empty draws every dot at the default size."`
+	ColorBy []string `json:"colorBy" description:"Group-by label names (e.g. k8s.namespace.name) whose combined values colour dots and drive the legend. Empty colours by every group-by label."`
+}
+
+type ScatterPlotAxes struct {
+	X ScatterPlotAxis `json:"x"`
+	Y ScatterPlotAxis `json:"y"`
+}
+
+type ScatterPlotAxis struct {
+	SoftMin *float64  `json:"softMin"`
+	SoftMax *float64  `json:"softMax"`
+	Scale   AxisScale `json:"scale"`
+	Label   string    `json:"label" description:"Axis title. Empty draws none."`
+}
+
+type ScatterPlotChartAppearance struct {
+	Points ScatterPlotPoints `json:"points"`
+}
+
+// ScatterPlotPoints keeps the fixed size and the size range side by side so
+// binding or unbinding dimensions.sizeBy restores the other's last setting. Nil
+// fields resolve to the renderer default.
+type ScatterPlotPoints struct {
+	Size    *PointDiameter `json:"size" description:"Diameter of every dot when dimensions.sizeBy is unset."`
+	MinSize *PointDiameter `json:"minSize" description:"Diameter of the smallest dot when dimensions.sizeBy is set."`
+	MaxSize *PointDiameter `json:"maxSize" description:"Diameter of the largest dot when dimensions.sizeBy is set."`
+	Opacity *PointOpacity  `json:"opacity"`
+}
+
+func (p *ScatterPlotPoints) UnmarshalJSON(data []byte) error {
+	type alias ScatterPlotPoints
+	var tmp alias
+	if err := json.Unmarshal(data, &tmp); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid points")
+	}
+	*p = ScatterPlotPoints(tmp)
+	return p.validate()
+}
+
+func (p ScatterPlotPoints) validate() error {
+	if p.MinSize != nil && p.MaxSize != nil && *p.MinSize > *p.MaxSize {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid points: minSize %d must not exceed maxSize %d", *p.MinSize, *p.MaxSize)
+	}
+	return nil
+}
+
 type TextPresentation struct {
 	TextAlign     TextAlign     `json:"textAlign"`
 	VerticalAlign VerticalAlign `json:"verticalAlign"`
@@ -431,6 +523,11 @@ type ComparisonThreshold struct {
 	Format   ThresholdFormat    `json:"format"`
 }
 
+type ScatterPlotThreshold struct {
+	ThresholdWithLabel
+	Axis ThresholdAxis `json:"axis"`
+}
+
 type TableThreshold struct {
 	ComparisonThreshold
 	ColumnName string `json:"columnName" validate:"required" required:"true"`
@@ -716,6 +813,86 @@ func (ls *LineStyle) UnmarshalJSON(data []byte) error {
 	}
 }
 
+// AxisScale `auto` leaves the choice to the renderer; `symlog` is log-like but
+// defined at and below zero.
+type AxisScale struct{ valuer.String }
+
+var (
+	AxisScaleAuto   = AxisScale{valuer.NewString("auto")} // default
+	AxisScaleLinear = AxisScale{valuer.NewString("linear")}
+	AxisScaleLog    = AxisScale{valuer.NewString("log")}
+	AxisScaleSymlog = AxisScale{valuer.NewString("symlog")}
+)
+
+func (AxisScale) Enum() []any {
+	return []any{AxisScaleAuto, AxisScaleLinear, AxisScaleLog, AxisScaleSymlog}
+}
+
+func (as AxisScale) ValueOrDefault() string {
+	if as.IsZero() {
+		return AxisScaleAuto.StringValue()
+	}
+	return as.StringValue()
+}
+
+func (as AxisScale) MarshalJSON() ([]byte, error) {
+	return json.Marshal(as.ValueOrDefault())
+}
+
+func (as *AxisScale) UnmarshalJSON(data []byte) error {
+	var v string
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid axis scale: must be a string, one of `auto`, `linear`, `log`, or `symlog`")
+	}
+	val := AxisScale{valuer.NewString(v)}
+	switch val {
+	case AxisScaleAuto, AxisScaleLinear, AxisScaleLog, AxisScaleSymlog:
+		*as = val
+		return nil
+	default:
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid axis scale %q: must be `auto`, `linear`, `log`, or `symlog`", v)
+	}
+}
+
+// ThresholdAxis is the axis a scatter plot threshold line marks: `y` draws it
+// horizontally, `x` vertically.
+type ThresholdAxis struct{ valuer.String }
+
+var (
+	ThresholdAxisX = ThresholdAxis{valuer.NewString("x")}
+	ThresholdAxisY = ThresholdAxis{valuer.NewString("y")} // default
+)
+
+func (ThresholdAxis) Enum() []any {
+	return []any{ThresholdAxisX, ThresholdAxisY}
+}
+
+func (ta ThresholdAxis) ValueOrDefault() string {
+	if ta.IsZero() {
+		return ThresholdAxisY.StringValue()
+	}
+	return ta.StringValue()
+}
+
+func (ta ThresholdAxis) MarshalJSON() ([]byte, error) {
+	return json.Marshal(ta.ValueOrDefault())
+}
+
+func (ta *ThresholdAxis) UnmarshalJSON(data []byte) error {
+	var v string
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid threshold axis: must be a string, one of `x` or `y`")
+	}
+	val := ThresholdAxis{valuer.NewString(v)}
+	switch val {
+	case ThresholdAxisX, ThresholdAxisY:
+		*ta = val
+		return nil
+	default:
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid threshold axis %q: must be `x` or `y`", v)
+	}
+}
+
 type FillMode struct{ valuer.String }
 
 var (
@@ -854,6 +1031,53 @@ func (o *FillOpacity) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+const (
+	minPointDiameter = 2
+	maxPointDiameter = 40
+)
+
+// PointDiameter is a scatter dot's diameter in whole CSS pixels.
+type PointDiameter int
+
+func (PointDiameter) PrepareJSONSchema(s *jsonschema.Schema) error {
+	s.WithMinimum(minPointDiameter).WithMaximum(maxPointDiameter)
+	return nil
+}
+
+func (d *PointDiameter) UnmarshalJSON(data []byte) error {
+	var v int
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid point diameter: must be a whole number between %d and %d", minPointDiameter, maxPointDiameter)
+	}
+	if v < minPointDiameter || v > maxPointDiameter {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid point diameter %d: must be a whole number between %d and %d", v, minPointDiameter, maxPointDiameter)
+	}
+	*d = PointDiameter(v)
+	return nil
+}
+
+const minPointOpacity = 0.1
+
+// PointOpacity is a scatter dot's fill alpha. The floor keeps a dot visible.
+type PointOpacity float64
+
+func (PointOpacity) PrepareJSONSchema(s *jsonschema.Schema) error {
+	s.WithMinimum(minPointOpacity).WithMaximum(1)
+	return nil
+}
+
+func (o *PointOpacity) UnmarshalJSON(data []byte) error {
+	var v float64
+	if err := json.Unmarshal(data, &v); err != nil {
+		return errors.WrapInvalidInputf(err, ErrCodeDashboardInvalidInput, "invalid point opacity: must be a number between %v and 1", minPointOpacity)
+	}
+	if v < minPointOpacity || v > 1 {
+		return errors.NewInvalidInputf(ErrCodeDashboardInvalidInput, "invalid point opacity %v: must be between %v and 1", v, minPointOpacity)
+	}
+	*o = PointOpacity(v)
+	return nil
+}
+
 type SpanGaps struct {
 	FillOnlyBelow bool   `json:"fillOnlyBelow" description:"Controls whether lines connect across null values. When false (default), all gaps are connected. When true, only gaps smaller than fillLessThan are connected."`
 	FillLessThan  string `json:"fillLessThan" description:"The maximum gap size to connect when fillOnlyBelow is true. Gaps larger than this duration are left disconnected."`

pkg/types/dashboardtypes/testdata/perses_scatter_plot_panel.json

@@ -0,0 +1,134 @@
+{
+  "display": {
+    "name": "service health",
+    "description": "throughput against tail latency per pod"
+  },
+  "variables": [],
+  "panels": {
+    "p1": {
+      "kind": "Panel",
+      "spec": {
+        "display": {
+          "name": "throughput vs p99",
+          "description": ""
+        },
+        "plugin": {
+          "kind": "signoz/ScatterPlotPanel",
+          "spec": {
+            "visualization": {
+              "timePreference": "last_1_hr"
+            },
+            "dimensions": {
+              "x": "A.count()",
+              "y": "A.p99(duration_nano)",
+              "sizeBy": "A.countIf(has_error = true)",
+              "colorBy": ["k8s.namespace.name", "k8s.pod.name"]
+            },
+            "formatting": {
+              "columnUnits": {
+                "A.p99(duration_nano)": "ns"
+              },
+              "decimalPrecision": "1"
+            },
+            "axes": {
+              "x": {
+                "softMin": 0,
+                "softMax": null,
+                "scale": "log",
+                "label": "Throughput"
+              },
+              "y": {
+                "softMin": null,
+                "softMax": 1000,
+                "scale": "symlog",
+                "label": "p99 latency"
+              }
+            },
+            "chartAppearance": {
+              "points": {
+                "size": 8,
+                "minSize": 4,
+                "maxSize": 24,
+                "opacity": 0.1
+              }
+            },
+            "legend": {
+              "position": "right",
+              "mode": "list",
+              "customColors": {
+                "checkout": "#1f77b4"
+              }
+            },
+            "thresholds": [
+              {
+                "value": 300,
+                "unit": "ms",
+                "color": "#f00",
+                "label": "p99 SLO",
+                "axis": "y"
+              },
+              {
+                "value": 50,
+                "color": "#0f0",
+                "axis": "x"
+              }
+            ]
+          }
+        },
+        "links": [],
+        "queries": [
+          {
+            "kind": "scalar",
+            "spec": {
+              "plugin": {
+                "kind": "signoz/BuilderQuery",
+                "spec": {
+                  "name": "A",
+                  "signal": "traces",
+                  "aggregations": [
+                    {
+                      "expression": "count()"
+                    },
+                    {
+                      "expression": "p99(duration_nano)"
+                    },
+                    {
+                      "expression": "countIf(has_error = true)"
+                    }
+                  ],
+                  "groupBy": [
+                    {
+                      "name": "k8s.namespace.name"
+                    },
+                    {
+                      "name": "k8s.pod.name"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "links": [],
+  "layouts": [
+    {
+      "kind": "Grid",
+      "spec": {
+        "items": [
+          {
+            "x": 0,
+            "y": 0,
+            "width": 12,
+            "height": 8,
+            "content": {
+              "$ref": "#/spec/panels/p1"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

pkg/types/pipelinetypes/pipeline.go

@@ -122,6 +122,9 @@ type PipelineOperator struct {
 	EnablePaths        bool   `json:"enable_paths,omitempty" yaml:"enable_paths,omitempty"`
 	PathPrefix         string `json:"path_prefix,omitempty" yaml:"path_prefix,omitempty"`
 
+	// normalize fields, set by the server only
+	JSONBodyDualIngestion bool `json:"-" yaml:"json_body_dual_ingestion,omitempty"`
+
 	// Used in Severity Parsing and JSON Flattening mapping
 	Mapping map[string][]string `json:"mapping,omitempty" yaml:"mapping,omitempty"`
 	// severity parser fields

pkg/types/querybuildertypes/querybuildertypesv5/req.go

@@ -266,6 +266,43 @@ type CompositeQuery struct {
 	Queries []QueryEnvelope `json:"queries"`
 }
 
+// ResultColumnKeys is what a scalar query yields per row, keyed the way the
+// UI keys columns: an aggregation column is the query name, or
+// queryName.expression when the query has several aggregations; a group
+// column is a group-by key name.
+type ResultColumnKeys struct {
+	Aggregations map[string]struct{}
+	Groups       map[string]struct{}
+}
+
+// CollectResultColumnKeys reports false when a query's columns are only known
+// at run time, as for ClickHouse SQL and PromQL. A disabled query yields no
+// aggregation column but keeps its group columns, since a formula over it
+// still carries them.
+func (c *CompositeQuery) CollectResultColumnKeys() (ResultColumnKeys, bool) {
+	keys := ResultColumnKeys{Aggregations: map[string]struct{}{}, Groups: map[string]struct{}{}}
+	for _, envelope := range c.Queries {
+		if envelope.GetType() == QueryTypeClickHouseSQL || envelope.GetType() == QueryTypePromQL {
+			return ResultColumnKeys{}, false
+		}
+		for _, key := range envelope.GetGroupBy() {
+			keys.Groups[key.Name] = struct{}{}
+		}
+		if envelope.IsDisabled() {
+			continue
+		}
+		expressions := envelope.GetAggregationExpressions()
+		if len(expressions) <= 1 {
+			keys.Aggregations[envelope.GetQueryName()] = struct{}{}
+			continue
+		}
+		for _, expression := range expressions {
+			keys.Aggregations[envelope.GetQueryName()+"."+expression] = struct{}{}
+		}
+	}
+	return keys, true
+}
+
 // PrepareJSONSchema adds description to the CompositeQuery schema.
 func (c *CompositeQuery) PrepareJSONSchema(schema *jsonschema.Schema) error {
 	schema.WithDescription("Composite query containing one or more query envelopes. Each query envelope specifies its type and corresponding spec.")

pkg/types/querybuildertypes/querybuildertypesv5/req_getters.go

@@ -225,6 +225,34 @@ func (q *QueryEnvelope) GetGroupBy() []GroupByKey {
 	return nil
 }
 
+// GetAggregationExpressions returns one entry per aggregation. A metric
+// aggregation has no expression, so it contributes an empty entry.
+func (q *QueryEnvelope) GetAggregationExpressions() []string {
+	switch spec := q.Spec.(type) {
+	case QueryBuilderTraceOperator:
+		expressions := make([]string, len(spec.Aggregations))
+		for i, aggregation := range spec.Aggregations {
+			expressions[i] = aggregation.Expression
+		}
+		return expressions
+	case QueryBuilderQuery[TraceAggregation]:
+		expressions := make([]string, len(spec.Aggregations))
+		for i, aggregation := range spec.Aggregations {
+			expressions[i] = aggregation.Expression
+		}
+		return expressions
+	case QueryBuilderQuery[LogAggregation]:
+		expressions := make([]string, len(spec.Aggregations))
+		for i, aggregation := range spec.Aggregations {
+			expressions[i] = aggregation.Expression
+		}
+		return expressions
+	case QueryBuilderQuery[MetricAggregation]:
+		return make([]string, len(spec.Aggregations))
+	}
+	return nil
+}
+
 // GetFilter returns the filter.
 func (q *QueryEnvelope) GetFilter() *Filter {
 	switch spec := q.Spec.(type) {

pkg/types/querybuildertypes/querybuildertypesv5/req_test.go

@@ -1903,3 +1903,63 @@ func TestQueryRangeRequest_StepIntervalForQuery(t *testing.T) {
 		})
 	}
 }
+
+func TestCompositeQueryCollectResultColumnKeys(t *testing.T) {
+	testCases := []struct {
+		scenario      string
+		composite     CompositeQuery
+		expectedKeys  ResultColumnKeys
+		expectedKnown bool
+	}{
+		{
+			scenario: "a single aggregation is keyed by the query name",
+			composite: CompositeQuery{Queries: []QueryEnvelope{{Type: QueryTypeBuilder, Spec: QueryBuilderQuery[TraceAggregation]{
+				Name:         "A",
+				Aggregations: []TraceAggregation{{Expression: "count()"}},
+				GroupBy:      []GroupByKey{{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "service.name"}}},
+			}}}},
+			expectedKeys:  ResultColumnKeys{Aggregations: map[string]struct{}{"A": {}}, Groups: map[string]struct{}{"service.name": {}}},
+			expectedKnown: true,
+		},
+		{
+			scenario: "several aggregations are keyed by query name and expression",
+			composite: CompositeQuery{Queries: []QueryEnvelope{{Type: QueryTypeBuilder, Spec: QueryBuilderQuery[LogAggregation]{
+				Name:         "A",
+				Aggregations: []LogAggregation{{Expression: "count()"}, {Expression: "p99(duration_nano)"}},
+			}}}},
+			expectedKeys:  ResultColumnKeys{Aggregations: map[string]struct{}{"A.count()": {}, "A.p99(duration_nano)": {}}, Groups: map[string]struct{}{}},
+			expectedKnown: true,
+		},
+		{
+			scenario: "a disabled query yields no aggregation but keeps its groups for the formula over it",
+			composite: CompositeQuery{Queries: []QueryEnvelope{
+				{Type: QueryTypeBuilder, Spec: QueryBuilderQuery[MetricAggregation]{
+					Name:         "A",
+					Disabled:     true,
+					Aggregations: []MetricAggregation{{MetricName: "http.server.request.count"}},
+					GroupBy:      []GroupByKey{{TelemetryFieldKey: telemetrytypes.TelemetryFieldKey{Name: "service.name"}}},
+				}},
+				{Type: QueryTypeFormula, Spec: QueryBuilderFormula{Name: "F1", Expression: "A * 2"}},
+			}},
+			expectedKeys:  ResultColumnKeys{Aggregations: map[string]struct{}{"F1": {}}, Groups: map[string]struct{}{"service.name": {}}},
+			expectedKnown: true,
+		},
+		{
+			scenario: "clickhouse columns are only known at run time",
+			composite: CompositeQuery{Queries: []QueryEnvelope{{Type: QueryTypeClickHouseSQL, Spec: ClickHouseQuery{
+				Name:  "A",
+				Query: "SELECT 1",
+			}}}},
+			expectedKeys:  ResultColumnKeys{},
+			expectedKnown: false,
+		},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.scenario, func(t *testing.T) {
+			keys, known := testCase.composite.CollectResultColumnKeys()
+			assert.Equal(t, testCase.expectedKnown, known)
+			assert.Equal(t, testCase.expectedKeys, keys)
+		})
+	}
+}

pkg/types/spantypes/thread.go

@@ -4,6 +4,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"maps"
+	"strings"
 
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/types/aiobservabilitytypes"
@@ -179,9 +180,7 @@ func newThreadSpan(traceID string, storable *StorableSpan) *ThreadSpan {
 	maps.Copy(resources, storable.ResourcesString)
 	timeUnixNano := uint64(storable.StartTime.UnixNano())
 	attributes := threadAttributes(storable)
-	// Spans from before the JSON rollout have no document and are not decoded: the legacy maps
-	// hold an object split into one key per field.
-	formatted := aiobservabilitytypes.FormatMessages(storable.AttributesJSON)
+	formatted := aiobservabilitytypes.FormatMessages(rawAttribute(storable, aiobservabilitytypes.GenAIInputMessages), rawAttribute(storable, aiobservabilitytypes.GenAIOutputMessages))
 	return &ThreadSpan{
 		SpanID:            storable.SpanID,
 		TraceID:           traceID,
@@ -215,3 +214,20 @@ func threadAttributes(storable *StorableSpan) map[string]any {
 	storable.AttributesJSON.FlattenInto("", attributes)
 	return attributes
 }
+
+// rawAttribute reads one attribute for decoding from the JSON document, where an object value is
+// still whole. The legacy maps hold objects split into one key per field, so spans from before
+// the JSON rollout are not decoded. Not handled: a list of JSON strings, which formats as generic,
+// and a scalar at a prefix of the path, such as gen_ai.input beside gen_ai.input.messages, which
+// ends the walk early.
+func rawAttribute(storable *StorableSpan, key string) any {
+	var current any = map[string]any(storable.AttributesJSON)
+	for segment := range strings.SplitSeq(key, ".") {
+		object, ok := current.(map[string]any)
+		if !ok {
+			return nil
+		}
+		current = object[segment]
+	}
+	return current
+}

pkg/types/spantypes/thread_test.go

@@ -73,3 +73,35 @@ func TestThreadAttributes(t *testing.T) {
 		})
 	}
 }
+
+func TestRawAttribute(t *testing.T) {
+	arguments := map[string]any{"city": "Paris", "days": []any{1.0, 2.0}}
+	testCases := []struct {
+		name     string
+		storable StorableSpan
+		key      string
+		want     any
+	}{
+		{
+			name:     "JSONColumn_ObjectReturnedWhole",
+			storable: StorableSpan{AttributesJSON: telemetrystoretypes.JSONValue{"gen_ai": map[string]any{"tool": map[string]any{"call": map[string]any{"arguments": arguments}}}}},
+			key:      "gen_ai.tool.call.arguments",
+			want:     arguments,
+		},
+		{
+			name:     "JSONColumn_MissingPath_Nil",
+			storable: StorableSpan{AttributesJSON: telemetrystoretypes.JSONValue{"gen_ai": map[string]any{"tool": map[string]any{"name": "get_weather"}}}},
+			key:      "gen_ai.tool.call.arguments",
+		},
+		{
+			name:     "LegacyMapsOnly_Nil",
+			storable: StorableSpan{AttributesString: map[string]string{"gen_ai.output.messages": "sunny", "gen_ai.tool.call.arguments.city": "Paris"}},
+			key:      "gen_ai.output.messages",
+		},
+	}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			assert.Equal(t, testCase.want, rawAttribute(&testCase.storable, testCase.key))
+		})
+	}
+}

tests/integration/tests/alertmanager/09_googlechat.py

@@ -22,6 +22,7 @@ from fixtures.notification_channel import (
     wait_for_alertmanager_sync,
 )
 
+
 METRICS_DATA = "ruler/test_scenarios/threshold_above_at_least_once/alert_data.jsonl"
 METRICS_RULE = "ruler/test_scenarios/threshold_above_at_least_once/rule.json"
 LOGS_DATA = "ruler/test_scenarios/threshold_below_at_least_once/alert_data.jsonl"

tests/integration/tests/alertmanager/11_incidentio.py

@@ -23,6 +23,7 @@ from fixtures.notification_channel import (
     wait_for_alertmanager_sync,
 )
 
+
 METRICS_DATA = "ruler/test_scenarios/threshold_above_at_least_once/alert_data.jsonl"
 METRICS_RULE = "ruler/test_scenarios/threshold_above_at_least_once/rule.json"
 LOGS_DATA = "ruler/test_scenarios/threshold_below_at_least_once/alert_data.jsonl"

tests/integration/tests/alertmanager/13_jira.py

@@ -24,6 +24,7 @@ from fixtures.notification_channel import (
     wait_for_alertmanager_sync,
 )
 
+
 METRICS_DATA = "ruler/test_scenarios/threshold_above_at_least_once/alert_data.jsonl"
 METRICS_RULE = "ruler/test_scenarios/threshold_above_at_least_once/rule.json"
 LOGS_DATA = "ruler/test_scenarios/threshold_below_at_least_once/alert_data.jsonl"

tests/integration/tests/alertmanager/14_jira_test_channel.py

@@ -30,6 +30,7 @@ from fixtures.notification_channel import (
     wait_for_alertmanager_sync,
 )
 
+
 # channel test (POST /api/v1/channels/test) drives the notifier once, synchronously,
 # with a hardcoded firing test alert and no retry. The search stub decides which
 # branch runs (create / update / reopen), so the whole issue lifecycle is

tests/integration/tests/alertmanager/15_jsmops.py

@@ -25,6 +25,7 @@ from fixtures.notification_channel import (
     wait_for_alertmanager_sync,
 )
 
+
 METRICS_DATA = "ruler/test_scenarios/threshold_above_at_least_once/alert_data.jsonl"
 METRICS_RULE = "ruler/test_scenarios/threshold_above_at_least_once/rule.json"
 LOGS_DATA = "ruler/test_scenarios/threshold_below_at_least_once/alert_data.jsonl"

tests/integration/tests/alertmanager/16_jsmops_test_channel.py

@@ -24,6 +24,7 @@ from fixtures.notification_channel import (
     wait_for_alertmanager_sync,
 )
 
+
 # channel test (POST /api/v1/channels/test) drives the notifier once, synchronously,
 # with a hardcoded firing test alert and no retry: create alert on the JSM Ops
 # gateway, then append a timeline note. Default-template events + retry are in

tests/integration/tests/tracedetail/02_thread.py

@@ -11,7 +11,7 @@ from fixtures.auth import USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD
 from fixtures.traces import ATTRIBUTE_JSON_ROLLOUT_TIME, TraceIdGenerator, Traces, TracesKind
 
 
-def test_thread_returns_gen_ai_spans_in_order(
+def test_thread_returns_message_spans_in_order(
     signoz: types.SigNoz,
     create_user_admin: None,  # pylint: disable=unused-argument
     get_token: Callable[[str, str], str],
@@ -21,56 +21,24 @@ def test_thread_returns_gen_ai_spans_in_order(
     seed_attribute_evolution("traces", ATTRIBUTE_JSON_ROLLOUT_TIME)
     now = datetime.now(tz=UTC).replace(microsecond=0)
     trace_id = TraceIdGenerator.trace_id()
-    root_id, first_llm_id, tool_id, agent_id, second_llm_id, third_llm_id, flattened_llm_id = (TraceIdGenerator.span_id() for _ in range(7))
+    root_id, first_llm_id, tool_id, agent_id, second_llm_id, third_llm_id = (TraceIdGenerator.span_id() for _ in range(6))
     resources = {"service.name": "tracedetail-thread"}
     first_input = json.dumps([{"role": "user", "parts": [{"type": "text", "content": "weather in Bangalore?"}]}])
-    first_output = json.dumps([{"role": "assistant", "parts": [{"type": "tool_call", "id": "call_1", "name": "get_weather", "arguments": {"city": "Bangalore"}}]}])
-    first_instructions = json.dumps([{"type": "text", "content": "Answer with the tool."}])
+    first_output = json.dumps([{"role": "assistant", "parts": [{"type": "tool_call", "id": "call_1", "name": "get_weather", "arguments": {"city": "Bangalore"}}], "finish_reason": "tool_call"}])
     second_input = json.dumps([{"role": "tool", "content": "sunny", "tool_call_id": "call_1"}])
 
     insert_traces(
         [
             Traces(timestamp=now - timedelta(seconds=10), duration=timedelta(seconds=9), trace_id=trace_id, span_id=root_id, name="POST /chat", kind=TracesKind.SPAN_KIND_SERVER, resources=resources, attribute_write_mode="json_only"),
             Traces(
-                timestamp=now - timedelta(seconds=8),
-                trace_id=trace_id,
-                span_id=first_llm_id,
-                parent_span_id=root_id,
-                name="chat gpt-4o",
-                resources=resources,
-                attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.system_instructions": first_instructions, "gen_ai.input.messages": first_input, "gen_ai.output.messages": first_output, "gen_ai.response.finish_reasons": json.dumps(["tool_calls"])},
-                attribute_write_mode="json_only",
+                timestamp=now - timedelta(seconds=8), trace_id=trace_id, span_id=first_llm_id, parent_span_id=root_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": first_input, "gen_ai.output.messages": first_output}, attribute_write_mode="json_only"
             ),
             Traces(
-                timestamp=now - timedelta(seconds=6),
-                trace_id=trace_id,
-                span_id=tool_id,
-                parent_span_id=root_id,
-                name="execute_tool get_weather",
-                resources=resources,
-                attributes={"gen_ai.tool.name": "get_weather", "gen_ai.tool.call.id": "call_1", "gen_ai.tool.call.arguments": json.dumps({"city": "Bangalore"}), "gen_ai.tool.call.result": "sunny"},
-                attribute_write_mode="json_only",
+                timestamp=now - timedelta(seconds=6), trace_id=trace_id, span_id=tool_id, parent_span_id=root_id, name="execute_tool get_weather", resources=resources, attributes={"gen_ai.tool.name": "get_weather", "gen_ai.tool.call.id": "call_1", "gen_ai.tool.call.arguments": json.dumps({"city": "Bangalore"}), "gen_ai.tool.call.result": "sunny"}, attribute_write_mode="json_only"
             ),
             Traces(timestamp=now - timedelta(seconds=5), trace_id=trace_id, span_id=agent_id, parent_span_id=root_id, name="invoke_agent planner", resources=resources, attributes={"gen_ai.agent.name": "planner"}, attribute_write_mode="json_only"),
             Traces(timestamp=now - timedelta(seconds=4), trace_id=trace_id, span_id=second_llm_id, parent_span_id=root_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": second_input}, attribute_write_mode="json_only"),
             Traces(timestamp=now - timedelta(seconds=2), trace_id=trace_id, span_id=third_llm_id, parent_span_id=root_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.output.messages": "It is sunny in Bangalore."}, attribute_write_mode="json_only"),
-            Traces(
-                timestamp=now - timedelta(seconds=1),
-                trace_id=trace_id,
-                span_id=flattened_llm_id,
-                parent_span_id=root_id,
-                name="ChatCompletion",
-                resources=resources,
-                attributes={
-                    "gen_ai.request.model": "gpt-4o",
-                    "llm.input_messages.0.message.role": "user",
-                    "llm.input_messages.0.message.content": "thanks",
-                    "llm.output_messages.0.message.role": "assistant",
-                    "llm.output_messages.0.message.content": "You're welcome.",
-                    "llm.finish_reason": "stop",
-                },
-                attribute_write_mode="json_only",
-            ),
         ]
     )
 
@@ -79,14 +47,10 @@ def test_thread_returns_gen_ai_spans_in_order(
     assert response.status_code == HTTPStatus.OK, response.text
 
     thread = response.json()["data"]
-    assert [span["span_id"] for span in thread["spans"]] == [first_llm_id, tool_id, agent_id, second_llm_id, third_llm_id, flattened_llm_id]
+    assert [span["span_id"] for span in thread["spans"]] == [first_llm_id, tool_id, second_llm_id, third_llm_id]
     assert "nextCursor" not in thread
 
-    first, tool, agent, input_only, output_only, flattened = thread["spans"]
-    assert agent["attributes"]["gen_ai.agent.name"] == "planner"
-    assert agent["formatter"] == ""
-    assert agent["formatted_input"] == []
-    assert agent["formatted_output"] == []
+    first, tool, input_only, output_only = thread["spans"]
     assert tool["attributes"]["gen_ai.tool.call.arguments"] == json.dumps({"city": "Bangalore"})
     assert tool["attributes"]["gen_ai.tool.call.result"] == "sunny"
     assert first["time_unix"] == int((now - timedelta(seconds=8)).timestamp() * 1000)
@@ -100,12 +64,13 @@ def test_thread_returns_gen_ai_spans_in_order(
 
     tool_call = {"type": "tool_call", "name": "get_weather", "id": "call_1", "arguments": {"city": "Bangalore"}}
     assert first["formatter"] == "semconv"
-    assert first["formatted_input"] == [{"role": "system", "parts": [{"type": "text", "content": "Answer with the tool."}]}, {"role": "user", "parts": [{"type": "text", "content": "weather in Bangalore?"}]}]
+    assert first["formatted_input"] == [{"role": "user", "parts": [{"type": "text", "content": "weather in Bangalore?"}]}]
     assert first["formatted_output"] == [{"role": "assistant", "parts": [tool_call], "finish_reason": "tool_call"}]
     assert first["formatter_warnings"] == []
-    assert tool["formatter"] == "tool"
-    assert tool["formatted_input"] == [{"role": "assistant", "parts": [tool_call]}]
-    assert tool["formatted_output"] == [{"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_1", "response": "sunny"}]}]
+    # tool spans carry no messages until their converter lands
+    assert tool["formatter"] == ""
+    assert tool["formatted_input"] == []
+    assert tool["formatted_output"] == []
     assert input_only["formatter"] == "openai.chat"
     assert input_only["formatted_input"] == [{"role": "tool", "parts": [{"type": "tool_call_response", "id": "call_1", "response": "sunny"}]}]
     assert input_only["formatted_output"] == []
@@ -113,10 +78,6 @@ def test_thread_returns_gen_ai_spans_in_order(
     assert output_only["formatted_input"] == []
     assert output_only["formatted_output"] == [{"role": "assistant", "parts": [{"type": "text", "content": "It is sunny in Bangalore."}]}]
     assert output_only["formatter_warnings"] == ["bare assistant text, role assumed"]
-    assert flattened["formatter"] == "openinference"
-    assert flattened["attributes"]["llm.input_messages.0.message.content"] == "thanks"
-    assert flattened["formatted_input"] == [{"role": "user", "parts": [{"type": "text", "content": "thanks"}]}]
-    assert flattened["formatted_output"] == [{"role": "assistant", "parts": [{"type": "text", "content": "You're welcome."}], "finish_reason": "stop"}]
 
 
 def test_thread_paginates_with_cursors(
@@ -134,7 +95,7 @@ def test_thread_paginates_with_cursors(
     timestamps = [now - timedelta(seconds=6), now - timedelta(seconds=3), now - timedelta(seconds=3)]
     insert_traces(
         [
-            Traces(timestamp=timestamp, trace_id=trace_id, span_id=span_id, name="chat gpt-4o", resources={"service.name": "tracedetail-thread-pages"}, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": json.dumps([{"role": "user", "content": span_id}])}, attribute_write_mode="json_only")
+            Traces(timestamp=timestamp, trace_id=trace_id, span_id=span_id, name="chat gpt-4o", resources={"service.name": "tracedetail-thread-pages"}, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": span_id}])}, attribute_write_mode="json_only")
             for span_id, timestamp in zip(span_ids, timestamps, strict=True)
         ]
     )
@@ -196,7 +157,7 @@ def test_thread_paginates_across_buckets(
     span_ids = [TraceIdGenerator.span_id() for _ in timestamps]
     insert_traces(
         [
-            Traces(timestamp=timestamp, trace_id=trace_id, span_id=span_id, name="chat gpt-4o", resources={"service.name": "tracedetail-thread-buckets"}, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": json.dumps([{"role": "user", "content": span_id}])}, attribute_write_mode="json_only")
+            Traces(timestamp=timestamp, trace_id=trace_id, span_id=span_id, name="chat gpt-4o", resources={"service.name": "tracedetail-thread-buckets"}, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": span_id}])}, attribute_write_mode="json_only")
             for span_id, timestamp in zip(span_ids, timestamps, strict=True)
         ]
     )
@@ -241,25 +202,16 @@ def test_thread_opens_around_span(
     resources = {"service.name": "tracedetail-thread-anchor"}
     root_id = TraceIdGenerator.span_id()
     llm_ids = [TraceIdGenerator.span_id() for _ in range(5)]
-    http_id = TraceIdGenerator.span_id()
-    # http span, not a thread row, sits between the third and fourth llm spans
+    agent_id = TraceIdGenerator.span_id()
+    # agent span, not a thread row, sits between the third and fourth llm spans
     insert_traces(
         [
             Traces(timestamp=now - timedelta(seconds=20), duration=timedelta(seconds=19), trace_id=trace_id, span_id=root_id, name="POST /chat", kind=TracesKind.SPAN_KIND_SERVER, resources=resources, attribute_write_mode="json_only"),
             *(
-                Traces(
-                    timestamp=now - timedelta(seconds=18 - 3 * i),
-                    trace_id=trace_id,
-                    span_id=span_id,
-                    parent_span_id=root_id,
-                    name="chat gpt-4o",
-                    resources=resources,
-                    attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": json.dumps([{"role": "user", "content": span_id}])},
-                    attribute_write_mode="json_only",
-                )
+                Traces(timestamp=now - timedelta(seconds=18 - 3 * i), trace_id=trace_id, span_id=span_id, parent_span_id=root_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": span_id}])}, attribute_write_mode="json_only")
                 for i, span_id in enumerate(llm_ids)
             ),
-            Traces(timestamp=now - timedelta(seconds=11), trace_id=trace_id, span_id=http_id, parent_span_id=root_id, name="GET /weather", resources=resources, attributes={"http.request.method": "GET"}, attribute_write_mode="json_only"),
+            Traces(timestamp=now - timedelta(seconds=11), trace_id=trace_id, span_id=agent_id, parent_span_id=root_id, name="invoke_agent planner", resources=resources, attributes={"gen_ai.agent.name": "planner"}, attribute_write_mode="json_only"),
         ]
     )
 
@@ -272,7 +224,7 @@ def test_thread_opens_around_span(
         assert response.status_code == HTTPStatus.OK, f"{params}: {response.text}"
         return response.json()["data"]
 
-    # thread span: included with its neighbours
+    # span with messages: included with its neighbours
     around = get_page({"limit": 3, "spanId": llm_ids[2]})
     assert [span["span_id"] for span in around["spans"]] == llm_ids[1:4]
     assert around["prevCursor"]
@@ -280,11 +232,11 @@ def test_thread_opens_around_span(
     assert [span["span_id"] for span in get_page({"limit": 3, "before": around["prevCursor"]})["spans"]] == llm_ids[:1]
     assert [span["span_id"] for span in get_page({"limit": 3, "after": around["nextCursor"]})["spans"]] == llm_ids[4:]
 
-    # span outside the thread: only its neighbours
-    around_http = get_page({"limit": 2, "spanId": http_id})
-    assert [span["span_id"] for span in around_http["spans"]] == llm_ids[2:4]
-    assert around_http["prevCursor"]
-    assert around_http["nextCursor"]
+    # span without messages: only its neighbours
+    around_agent = get_page({"limit": 2, "spanId": agent_id})
+    assert [span["span_id"] for span in around_agent["spans"]] == llm_ids[2:4]
+    assert around_agent["prevCursor"]
+    assert around_agent["nextCursor"]
 
     # near the start, the short side gives its room to the other
     at_start = get_page({"limit": 3, "spanId": llm_ids[0]})
@@ -328,11 +280,11 @@ def test_thread_reads_spans_across_json_rollout(
     legacy_id, json_id = TraceIdGenerator.span_id(), TraceIdGenerator.span_id()
     insert_traces(
         [
-            Traces(timestamp=rollout - timedelta(minutes=10), trace_id=before_trace_id, span_id=before_ids[0], name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": json.dumps([{"role": "user", "content": "first"}])}, attribute_write_mode="legacy_only"),
-            Traces(timestamp=rollout - timedelta(minutes=8), trace_id=before_trace_id, span_id=TraceIdGenerator.span_id(), name="GET /weather", resources=resources, attributes={"http.request.method": "GET"}, attribute_write_mode="legacy_only"),
-            Traces(timestamp=rollout - timedelta(minutes=5), trace_id=before_trace_id, span_id=before_ids[1], name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.output.messages": json.dumps([{"role": "assistant", "content": "second"}])}, attribute_write_mode="legacy_only"),
-            Traces(timestamp=rollout - timedelta(minutes=5), trace_id=straddle_trace_id, span_id=legacy_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": json.dumps([{"role": "user", "content": "legacy"}])}, attribute_write_mode="legacy_only"),
-            Traces(timestamp=rollout + timedelta(minutes=5), trace_id=straddle_trace_id, span_id=json_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.request.model": "gpt-4o", "gen_ai.input.messages": json.dumps([{"role": "user", "content": "json"}])}, attribute_write_mode="json_only"),
+            Traces(timestamp=rollout - timedelta(minutes=10), trace_id=before_trace_id, span_id=before_ids[0], name="chat gpt-4o", resources=resources, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": "first"}])}, attribute_write_mode="legacy_only"),
+            Traces(timestamp=rollout - timedelta(minutes=8), trace_id=before_trace_id, span_id=TraceIdGenerator.span_id(), name="invoke_agent planner", resources=resources, attributes={"gen_ai.agent.name": "planner"}, attribute_write_mode="legacy_only"),
+            Traces(timestamp=rollout - timedelta(minutes=5), trace_id=before_trace_id, span_id=before_ids[1], name="chat gpt-4o", resources=resources, attributes={"gen_ai.output.messages": json.dumps([{"role": "assistant", "content": "second"}])}, attribute_write_mode="legacy_only"),
+            Traces(timestamp=rollout - timedelta(minutes=5), trace_id=straddle_trace_id, span_id=legacy_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": "legacy"}])}, attribute_write_mode="legacy_only"),
+            Traces(timestamp=rollout + timedelta(minutes=5), trace_id=straddle_trace_id, span_id=json_id, name="chat gpt-4o", resources=resources, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": "json"}])}, attribute_write_mode="json_only"),
         ]
     )
 
@@ -363,7 +315,7 @@ def test_thread_reads_spans_across_json_rollout(
     assert straddle_spans[1]["formatted_input"] == [{"role": "user", "parts": [{"type": "text", "content": "json"}]}]
 
 
-def test_thread_without_gen_ai_spans_is_empty(
+def test_thread_without_messages_is_empty(
     signoz: types.SigNoz,
     create_user_admin: None,  # pylint: disable=unused-argument
     get_token: Callable[[str, str], str],
@@ -372,14 +324,7 @@ def test_thread_without_gen_ai_spans_is_empty(
 ) -> None:
     seed_attribute_evolution("traces", ATTRIBUTE_JSON_ROLLOUT_TIME)
     trace_id = TraceIdGenerator.trace_id()
-    resources = {"service.name": "tracedetail-thread-empty"}
-    # messages without a gate key, as a failed call or an unmapped SDK writes them, are not a row either
-    insert_traces(
-        [
-            Traces(timestamp=datetime.now(tz=UTC) - timedelta(seconds=5), trace_id=trace_id, span_id=TraceIdGenerator.span_id(), name="GET /health", resources=resources, attribute_write_mode="json_only"),
-            Traces(timestamp=datetime.now(tz=UTC) - timedelta(seconds=4), trace_id=trace_id, span_id=TraceIdGenerator.span_id(), name="chat", resources=resources, attributes={"gen_ai.input.messages": json.dumps([{"role": "user", "content": "hi"}])}, attribute_write_mode="json_only"),
-        ]
-    )
+    insert_traces([Traces(timestamp=datetime.now(tz=UTC) - timedelta(seconds=5), trace_id=trace_id, span_id=TraceIdGenerator.span_id(), name="GET /health", resources={"service.name": "tracedetail-thread-empty"}, attribute_write_mode="json_only")])
 
     token = get_token(USER_ADMIN_EMAIL, USER_ADMIN_PASSWORD)
     response = requests.get(signoz.self.host_configs["8080"].get(f"/api/v1/traces/{trace_id}/thread"), headers={"Authorization": f"Bearer {token}"}, timeout=10)