Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(web): default widget aggregation to the measure's natural aggregation (#16603)

Trang Nguyenfba6089411c1
diff --git a/packages/shared/src/features/query/dataModel.ts b/packages/shared/src/features/query/dataModel.ts
index df551d3d5a..e007b7e833 100644
--- a/packages/shared/src/features/query/dataModel.ts
+++ b/packages/shared/src/features/query/dataModel.ts
@@ -94,6 +94,7 @@ export const traceView: ViewDeclarationType = {
relationTable: "observations",
description: "Unique observations linked to the trace.",
unit: "observations",
+ defaultAggregation: "sum",
},
scoresCount: {
sql: "uniq(scores.id)",
@@ -102,6 +103,7 @@ export const traceView: ViewDeclarationType = {
relationTable: "scores",
description: "Unique scores attached to the trace.",
unit: "scores",
+ defaultAggregation: "sum",
},
uniqueUserIds: {
sql: "uniq(traces.user_id)",
@@ -125,6 +127,7 @@ export const traceView: ViewDeclarationType = {
description:
"Elapsed time between the first and last observation inside the trace.",
unit: "millisecond",
+ defaultAggregation: "avg",
},
totalTokens: {
sql: "sumMap(observations.usage_details)['total']",
@@ -133,6 +136,7 @@ export const traceView: ViewDeclarationType = {
relationTable: "observations",
description: "Sum of tokens consumed by all observations in the trace.",
unit: "tokens",
+ defaultAggregation: "sum",
},
totalCost: {
sql: "sum(observations.total_cost)",
@@ -141,6 +145,7 @@ export const traceView: ViewDeclarationType = {
relationTable: "observations",
description: "Total cost accumulated across observations in the trace.",
unit: "USD",
+ defaultAggregation: "sum",
},
},
tableRelations: {
@@ -265,6 +270,7 @@ export const eventsTracesView: ViewDeclarationType = {
type: "integer",
description: "Unique observations linked to the trace.",
unit: "observations",
+ defaultAggregation: "sum",
},
scoresCount: {
sql: "uniq(scores.id)",
@@ -273,6 +279,7 @@ export const eventsTracesView: ViewDeclarationType = {
relationTable: "scores",
description: "Unique scores attached to the trace.",
unit: "scores",
+ defaultAggregation: "sum",
},
uniqueUserIds: {
// Keep this numeric base aligned with v1: persisted widgets may use any
@@ -325,6 +332,7 @@ export const eventsTracesView: ViewDeclarationType = {
description:
"Elapsed time between the first and last observation inside the trace.",
unit: "millisecond",
+ defaultAggregation: "avg",
},
totalTokens: {
sql: "sumMapIf(events_traces.usage_details, events_traces.parent_span_id != '')['total']",
@@ -332,6 +340,7 @@ export const eventsTracesView: ViewDeclarationType = {
type: "integer",
description: "Sum of tokens consumed by all observations in the trace.",
unit: "tokens",
+ defaultAggregation: "sum",
},
totalCost: {
sql: "sumIf(toNullable(events_traces.total_cost), events_traces.parent_span_id != '')",
@@ -339,6 +348,7 @@ export const eventsTracesView: ViewDeclarationType = {
type: "decimal",
description: "Total cost accumulated across observations in the trace.",
unit: "USD",
+ defaultAggregation: "sum",
},
},
tableRelations: {
@@ -363,7 +373,7 @@ export const eventsTracesView: ViewDeclarationType = {
export const observationsView: ViewDeclarationType = {
name: "observations",
description:
- "Observations represent individual requests or operations within a trace. They are grouped into Spans, Generations, and Events.",
+ "Observations represent individual requests or operations within a trace, such as Spans, Generations, Events, and agent-specific types like Agents and Tools.",
dimensions: {
id: {
sql: "observations.id",
@@ -402,7 +412,7 @@ export const observationsView: ViewDeclarationType = {
alias: "type",
type: "string",
description:
- "Type of the observation. Can be a SPAN, GENERATION, or EVENT.",
+ "Type of the observation, e.g. SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, or GUARDRAIL.",
},
name: {
sql: "observations.name",
@@ -513,6 +523,7 @@ export const observationsView: ViewDeclarationType = {
description:
"Latency of an individual observation (start time to end time).",
unit: "millisecond",
+ defaultAggregation: "avg",
},
streamingLatency: {
// Return NULL if `completion_start_time` is NULL to avoid misleading latency values
@@ -523,6 +534,7 @@ export const observationsView: ViewDeclarationType = {
description:
"Latency of the generation step (completion start time to end time).",
unit: "millisecond",
+ defaultAggregation: "avg",
},
inputTokens: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'input') > 0, @@AGG1@@(usage_details))))",
@@ -531,6 +543,7 @@ export const observationsView: ViewDeclarationType = {
type: "integer",
description: "Sum of input tokens consumed by the observation.",
unit: "tokens",
+ defaultAggregation: "sum",
},
outputTokens: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'output') > 0, @@AGG1@@(usage_details))))",
@@ -539,6 +552,7 @@ export const observationsView: ViewDeclarationType = {
type: "integer",
description: "Sum of output tokens produced by the observation.",
unit: "tokens",
+ defaultAggregation: "sum",
},
totalTokens: {
sql: "@@AGG1@@(usage_details)['total']",
@@ -547,6 +561,7 @@ export const observationsView: ViewDeclarationType = {
type: "integer",
description: "Sum of tokens consumed by the observation.",
unit: "tokens",
+ defaultAggregation: "sum",
},
outputTokensPerSecond: {
// Calculate average output tokens per second. Denominator uses seconds to align
@@ -559,6 +574,7 @@ export const observationsView: ViewDeclarationType = {
description:
"Average number of output tokens produced per second between completion start time and span end time.",
unit: "tokens/s",
+ defaultAggregation: "avg",
},
tokensPerSecond: {
sql: "@@AGG1@@(usage_details)['total'] / nullIf(date_diff('second', @@AGG2@@(observations.start_time), @@AGG2@@(observations.end_time)), 0)",
@@ -568,6 +584,7 @@ export const observationsView: ViewDeclarationType = {
description:
"Average number of tokens consumed per second by the observation.",
unit: "tokens/s",
+ defaultAggregation: "avg",
},
inputCost: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'input') > 0, @@AGG1@@(cost_details))))",
@@ -576,6 +593,7 @@ export const observationsView: ViewDeclarationType = {
type: "decimal",
description: "Sum of input cost incurred by the observation.",
unit: "USD",
+ defaultAggregation: "sum",
},
outputCost: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'output') > 0, @@AGG1@@(cost_details))))",
@@ -584,6 +602,7 @@ export const observationsView: ViewDeclarationType = {
type: "decimal",
description: "Sum of output cost incurred by the observation.",
unit: "USD",
+ defaultAggregation: "sum",
},
totalCost: {
sql: "@@AGG1@@(total_cost)",
@@ -592,6 +611,7 @@ export const observationsView: ViewDeclarationType = {
type: "decimal",
description: "Total cost incurred by the observation.",
unit: "USD",
+ defaultAggregation: "sum",
},
timeToFirstToken: {
// Return NULL if `completion_start_time` is NULL to represent unknown TTFT
@@ -601,6 +621,7 @@ export const observationsView: ViewDeclarationType = {
type: "integer",
description: "Time to first token for the observation.",
unit: "millisecond",
+ defaultAggregation: "avg",
},
countScores: {
sql: "uniq(scores.id)",
@@ -609,6 +630,7 @@ export const observationsView: ViewDeclarationType = {
relationTable: "scores",
description: "Unique scores attached to the observation.",
unit: "scores",
+ defaultAggregation: "sum",
},
toolDefinitions: {
sql: "nullIf(length(mapKeys(@@AGG1@@(tool_definitions))), 0)",
@@ -617,14 +639,17 @@ export const observationsView: ViewDeclarationType = {
type: "integer",
description: "Number of available tools per observation.",
unit: "tools",
+ defaultAggregation: "avg",
},
toolCalls: {
sql: "nullIf(length(@@AGG1@@(tool_calls)), 0)",
aggs: { agg1: "any" },
alias: "toolCalls",
type: "integer",
- description: "Number of tool calls per observation.",
+ description:
+ "Number of tool calls made by the observation, including parallel calls. Use the Sum aggregation to get the total number of tool calls.",
unit: "calls",
+ defaultAggregation: "sum",
},
toolCallInvocations: {
sql: "countEqual(@@AGG1@@(observations.tool_call_names), calledToolNames)",
@@ -635,6 +660,7 @@ export const observationsView: ViewDeclarationType = {
description:
"Number of individual tool-call invocations, counting repeated calls to the same tool within one observation. Automatically grouped by the Called Tool Names dimension. Use the Sum aggregation for totals and rankings.",
unit: "calls",
+ defaultAggregation: "sum",
},
},
tableRelations: {
@@ -999,6 +1025,7 @@ function scoresNumericViewBase(version: "v1" | "v2"): ViewDeclarationType {
alias: "value",
type: "number",
description: "Value of the score.",
+ defaultAggregation: "avg",
},
},
tableRelations: createScoreTableRelations(version),
@@ -1088,6 +1115,7 @@ function scoresBooleanViewBase(version: "v1" | "v2"): ViewDeclarationType {
type: "number",
description:
"Numeric 0/1 value of the score. Its average is the true-rate.",
+ defaultAggregation: "avg",
},
},
tableRelations: createScoreTableRelations(version),
@@ -1179,7 +1207,7 @@ export const scoresListableCountViewV2: ViewDeclarationType =
export const eventsObservationsView: ViewDeclarationType = {
name: "events_observations",
description:
- "Observations represent individual requests or operations within a trace. They are grouped into Spans, Generations, and Events.",
+ "Observations represent individual requests or operations within a trace, such as Spans, Generations, Events, and agent-specific types like Agents and Tools.",
dimensions: {
id: {
sql: "events_observations.span_id",
@@ -1225,7 +1253,7 @@ export const eventsObservationsView: ViewDeclarationType = {
alias: "type",
type: "string",
description:
- "Type of the observation. Can be a SPAN, GENERATION, or EVENT.",
+ "Type of the observation, e.g. SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, or GUARDRAIL.",
},
name: {
sql: "events_observations.name",
@@ -1420,6 +1448,7 @@ export const eventsObservationsView: ViewDeclarationType = {
description:
"Latency of an individual observation (start time to end time).",
unit: "millisecond",
+ defaultAggregation: "avg",
},
streamingLatency: {
sql: "if(isNull(@@AGG1@@(events_observations.completion_start_time)), CAST(NULL AS Nullable(Int64)), date_diff('millisecond', @@AGG1@@(events_observations.completion_start_time), @@AGG1@@(events_observations.end_time)))",
@@ -1429,6 +1458,7 @@ export const eventsObservationsView: ViewDeclarationType = {
description:
"Latency of the generation step (completion start time to end time).",
unit: "millisecond",
+ defaultAggregation: "avg",
},
inputTokens: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'input') > 0, @@AGG1@@(usage_details))))",
@@ -1437,6 +1467,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "integer",
description: "Sum of input tokens consumed by the observation.",
unit: "tokens",
+ defaultAggregation: "sum",
},
outputTokens: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'output') > 0, @@AGG1@@(usage_details))))",
@@ -1445,6 +1476,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "integer",
description: "Sum of output tokens produced by the observation.",
unit: "tokens",
+ defaultAggregation: "sum",
},
totalTokens: {
sql: "@@AGG1@@(usage_details)['total']",
@@ -1453,6 +1485,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "integer",
description: "Sum of tokens consumed by the observation.",
unit: "tokens",
+ defaultAggregation: "sum",
},
outputTokensPerSecond: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'output') > 0, @@AGG1@@(usage_details)))) / nullIf(date_diff('second', @@AGG1@@(events_observations.completion_start_time), @@AGG1@@(events_observations.end_time)), 0)",
@@ -1462,6 +1495,7 @@ export const eventsObservationsView: ViewDeclarationType = {
description:
"Average number of output tokens produced per second between completion start time and span end time.",
unit: "tokens/s",
+ defaultAggregation: "avg",
},
tokensPerSecond: {
sql: "@@AGG1@@(usage_details)['total'] / nullIf(date_diff('second', @@AGG2@@(events_observations.start_time), @@AGG2@@(events_observations.end_time)), 0)",
@@ -1471,6 +1505,7 @@ export const eventsObservationsView: ViewDeclarationType = {
description:
"Average number of tokens consumed per second by the observation.",
unit: "tokens/s",
+ defaultAggregation: "avg",
},
inputCost: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'input') > 0, @@AGG1@@(cost_details))))",
@@ -1479,6 +1514,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "decimal",
description: "Sum of input cost incurred by the observation.",
unit: "USD",
+ defaultAggregation: "sum",
},
outputCost: {
sql: "arraySum(mapValues(mapFilter(x -> positionCaseInsensitive(x.1, 'output') > 0, @@AGG1@@(cost_details))))",
@@ -1487,6 +1523,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "decimal",
description: "Sum of output cost incurred by the observation.",
unit: "USD",
+ defaultAggregation: "sum",
},
totalCost: {
sql: "@@AGG1@@(toNullable(total_cost))",
@@ -1495,6 +1532,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "decimal",
description: "Total cost incurred by the observation.",
unit: "USD",
+ defaultAggregation: "sum",
},
timeToFirstToken: {
sql: "if(isNull(@@AGG1@@(events_observations.completion_start_time)), CAST(NULL AS Nullable(Int64)), date_diff('millisecond', @@AGG1@@(events_observations.start_time), @@AGG1@@(events_observations.completion_start_time)))",
@@ -1503,6 +1541,7 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "integer",
description: "Time to first token for the observation.",
unit: "millisecond",
+ defaultAggregation: "avg",
},
countScores: {
sql: "uniq(scores.id)",
@@ -1511,6 +1550,7 @@ export const eventsObservationsView: ViewDeclarationType = {
relationTable: "scores",
description: "Unique scores attached to the observation.",
unit: "scores",
+ defaultAggregation: "sum",
},
toolDefinitions: {
sql: "nullIf(length(mapKeys(@@AGG1@@(events_observations.tool_definitions))), 0)",
@@ -1519,14 +1559,17 @@ export const eventsObservationsView: ViewDeclarationType = {
type: "integer",
description: "Number of available tools per observation.",
unit: "tools",
+ defaultAggregation: "avg",
},
toolCalls: {
sql: "nullIf(length(@@AGG1@@(events_observations.tool_calls)), 0)",
aggs: { agg1: "any" },
alias: "toolCalls",
type: "integer",
- description: "Number of tool calls per observation.",
+ description:
+ "Number of tool calls made by the observation, including parallel calls. Use the Sum aggregation to get the total number of tool calls.",
unit: "calls",
+ defaultAggregation: "sum",
},
toolCallInvocations: {
sql: "countEqual(@@AGG1@@(events_observations.tool_call_names), calledToolNames)",
@@ -1537,12 +1580,14 @@ export const eventsObservationsView: ViewDeclarationType = {
description:
"Number of individual tool-call invocations, counting repeated calls to the same tool within one observation. Automatically grouped by the Called Tool Names dimension. Use the Sum aggregation for totals and rankings.",
unit: "calls",
+ defaultAggregation: "sum",
},
costByType: {
sql: "cost_value",
alias: "costByType",
type: "decimal",
unit: "USD",
+ defaultAggregation: "sum",
requiresDimension: "costType",
description:
"Sum of cost per category. The costType dimension is auto-included to emit the ARRAY JOIN that brings cost_value into scope.",
@@ -1552,6 +1597,7 @@ export const eventsObservationsView: ViewDeclarationType = {
alias: "usageByType",
type: "integer",
unit: "tokens",
+ defaultAggregation: "sum",
requiresDimension: "usageType",
description:
"Sum of token usage per category. The usageType dimension is auto-included to emit the ARRAY JOIN that brings usage_value into scope.",
diff --git a/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts b/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts
index 5085b671b2..329baa129a 100644
--- a/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts
+++ b/packages/shared/src/features/query/server/queryBuilder.filterValidation.test.ts
@@ -561,4 +561,38 @@ describe("toolCallInvocations measure", () => {
);
expect(compiledQuery.match(/\bSELECT\b/g)).toHaveLength(1);
});
+
+ it("honors a stored count aggregation instead of the UI default sum", async () => {
+ const { query: compiledQuery } = await new QueryBuilder(
+ undefined,
+ "v1",
+ ).build(
+ {
+ ...baseQuery,
+ metrics: [{ measure: "toolCallInvocations", aggregation: "count" }],
+ },
+ "test-project",
+ );
+
+ expect(compiledQuery).toContain("count(toolCallInvocations)");
+ expect(compiledQuery).not.toContain("sum(toolCallInvocations)");
+ });
+});
+
+describe("toolCalls stored aggregation", () => {
+ it("compiles count(toolCalls) when the widget stored count, not the UI default sum", async () => {
+ const { query: compiledQuery } = await new QueryBuilder(
+ undefined,
+ "v1",
+ ).build(
+ {
+ ...baseQuery,
+ metrics: [{ measure: "toolCalls", aggregation: "count" }],
+ },
+ "test-project",
+ );
+
+ expect(compiledQuery).toContain("count(toolCalls)");
+ expect(compiledQuery).not.toContain("sum(toolCalls)");
+ });
});
diff --git a/packages/shared/src/features/query/types.ts b/packages/shared/src/features/query/types.ts
index ddc5b08c72..2b9398a36a 100644
--- a/packages/shared/src/features/query/types.ts
+++ b/packages/shared/src/features/query/types.ts
@@ -70,6 +70,11 @@ export const viewDeclaration = z.object({
description: z.string().optional(),
type: z.string().optional(),
unit: z.string().optional(),
+ // Natural aggregation the widget builder preselects when the user
+ // switches to this measure (e.g. `sum` for toolCalls, where a carried-over
+ // `count` would count observations instead of tool calls). UI-only
+ // default; the query builder never reads it.
+ defaultAggregation: metricAggregations.optional(),
aggs: z.record(z.string(), z.string()).optional(),
// Override query semantics for specific user-selected aggregations while
// keeping the base declaration as the UI/default compatibility contract.
diff --git a/web/src/features/widgets/components/WidgetForm.tsx b/web/src/features/widgets/components/WidgetForm.tsx
index ce433bbb0d..be0140f5a0 100644
--- a/web/src/features/widgets/components/WidgetForm.tsx
+++ b/web/src/features/widgets/components/WidgetForm.tsx
@@ -111,6 +111,7 @@ import {
effectiveWidgetName,
makeWidgetFormSchema,
normalizeWidgetFormValues,
+ resolveMeasureChangeAggregation,
resolveWidgetFormVersion,
toDefaultValues,
toSavePayload,
@@ -752,10 +753,23 @@ export function WidgetForm({
};
// Single (non-pivot) measure change — heals the aggregation + chart type in
- // the same action (the histogram fix, in the initiating event handler).
+ // the same action (the histogram fix, in the initiating event handler). A
+ // carried-over "count" aggregation jumps to the new measure's natural
+ // default (e.g. sum for toolCalls) instead of counting observations.
const onMeasureChange = (newMeasure: string) => {
const nextMetrics = values.metrics.map((m, i) =>
- i === 0 ? { ...m, measure: newMeasure } : m,
+ i === 0
+ ? {
+ ...m,
+ measure: newMeasure,
+ aggregation: resolveMeasureChangeAggregation({
+ currentAggregation: m.aggregation,
+ newMeasure,
+ view: selectedView,
+ viewVersion,
+ }),
+ }
+ : m,
);
const candidate = normalizeWidgetFormValues(
{ ...values, metrics: nextMetrics },
@@ -1264,60 +1278,67 @@ function SingleMetricField({
return (
<div className="space-y-2">
- <Select value={measure} onValueChange={(value) => onMeasureChange(value)}>
- <SelectTrigger
- id="metrics-select"
- aria-invalid={error ? true : undefined}
- aria-describedby={error ? "single-metric-error" : undefined}
- >
- <SelectValue placeholder="Select metrics" />
- </SelectTrigger>
- <SelectContent>
- {availableMetrics.map((metric) => {
- const meta =
- viewDeclarations[ctx.viewVersion][ctx.view]?.measures?.[
- metric.value
- ];
- return (
- <WidgetPropertySelectItem
- key={metric.value}
- value={metric.value}
- label={metric.label}
- description={meta?.description}
- unit={meta?.unit}
- type={meta?.type}
- />
- );
- })}
- </SelectContent>
- </Select>
- {measure !== "count" && (
- <div className="space-y-1">
+ <div className="flex items-center gap-2">
+ <div className="flex-1">
<Select
- value={aggField.value}
- disabled={ctx.chartType === "HISTOGRAM"}
- onValueChange={(value) =>
- aggField.onChange(value as z.infer<typeof metricAggregations>)
- }
+ value={measure}
+ onValueChange={(value) => onMeasureChange(value)}
>
- <SelectTrigger id="aggregation-select">
- <SelectValue placeholder="Select Aggregation" />
+ <SelectTrigger
+ id="metrics-select"
+ aria-invalid={error ? true : undefined}
+ aria-describedby={error ? "single-metric-error" : undefined}
+ >
+ <SelectValue placeholder="Select metrics" />
</SelectTrigger>
<SelectContent>
- {aggregationOptions.map((aggregation) => (
- <SelectItem key={aggregation} value={aggregation}>
- {startCase(aggregation)}
- </SelectItem>
- ))}
+ {availableMetrics.map((metric) => {
+ const meta =
+ viewDeclarations[ctx.viewVersion][ctx.view]?.measures?.[
+ metric.value
+ ];
+ return (
+ <WidgetPropertySelectItem
+ key={metric.value}
+ value={metric.value}
+ label={metric.label}
+ description={meta?.description}
+ unit={meta?.unit}
+ type={meta?.type}
+ />
+ );
+ })}
</SelectContent>
</Select>
- {ctx.chartType === "HISTOGRAM" && (
- <p className="text-muted-foreground text-xs">
- Aggregation is automatically set to &quot;histogram&quot; for
- histogram charts
- </p>
- )}
</div>
+ {measure !== "count" && (
+ <div className="flex-1">
+ <Select
+ value={aggField.value}
+ disabled={ctx.chartType === "HISTOGRAM"}
+ onValueChange={(value) =>
+ aggField.onChange(value as z.infer<typeof metricAggregations>)
+ }
+ >
+ <SelectTrigger id="aggregation-select">
+ <SelectValue placeholder="Select Aggregation" />
+ </SelectTrigger>
+ <SelectContent>
+ {aggregationOptions.map((aggregation) => (
+ <SelectItem key={aggregation} value={aggregation}>
+ {startCase(aggregation)}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </div>
+ )}
+ </div>
+ {measure !== "count" && ctx.chartType === "HISTOGRAM" && (
+ <p className="text-muted-foreground text-xs">
+ Aggregation is automatically set to &quot;histogram&quot; for
+ histogram charts
+ </p>
)}
{error && (
<p id="single-metric-error" className="text-destructive text-xs">
@@ -1363,10 +1384,15 @@ function PivotMetricsField({
finalAggregation = "count";
} else {
const available = getAvailablePivotAggregations(index, measure);
+ const defaultAggregation =
+ viewDeclarations[ctx.viewVersion][ctx.view]?.measures?.[measure]
+ ?.defaultAggregation;
finalAggregation =
aggregation && available.includes(aggregation)
? aggregation
- : (available[0] ?? "sum");
+ : defaultAggregation && available.includes(defaultAggregation)
+ ? defaultAggregation
+ : (available[0] ?? "sum");
}
next[index] = { measure, aggregation: finalAggregation };
} else {
diff --git a/web/src/features/widgets/components/resolveAggregationAndChartType.clienttest.ts b/web/src/features/widgets/components/resolveAggregationAndChartType.clienttest.ts
index e5194e6b20..b03808be80 100644
--- a/web/src/features/widgets/components/resolveAggregationAndChartType.clienttest.ts
+++ b/web/src/features/widgets/components/resolveAggregationAndChartType.clienttest.ts
@@ -1,6 +1,7 @@
// @vitest-environment node
import { resolveAggregationAndChartType } from "./WidgetForm";
+import { resolveMeasureChangeAggregation } from "./widgetFormSchema";
const allAggs = [
"sum",
@@ -181,3 +182,89 @@ describe("resolveAggregationAndChartType", () => {
},
);
});
+
+// --- Measure change jumps a carried-over "count" to the measure's natural
+// aggregation (count of toolCalls counted observations, not calls) ---
+
+describe("resolveMeasureChangeAggregation", () => {
+ it.each([
+ ["v1", "toolCalls", "sum"],
+ ["v2", "toolCalls", "sum"],
+ ["v1", "toolCallInvocations", "sum"],
+ ["v2", "toolCallInvocations", "sum"],
+ ["v1", "totalTokens", "sum"],
+ ["v1", "totalCost", "sum"],
+ ["v1", "latency", "avg"],
+ ["v2", "timeToFirstToken", "avg"],
+ ] as const)(
+ "jumps count to the natural default on %s observations.%s → %s",
+ (viewVersion, newMeasure, expected) => {
+ expect(
+ resolveMeasureChangeAggregation({
+ currentAggregation: "count",
+ newMeasure,
+ view: "observations",
+ viewVersion,
+ }),
+ ).toBe(expected);
+ },
+ );
+
+ it("keeps a deliberately chosen aggregation on measure change", () => {
+ expect(
+ resolveMeasureChangeAggregation({
+ currentAggregation: "p95",
+ newMeasure: "totalTokens",
+ view: "observations",
+ viewVersion: "v1",
+ }),
+ ).toBe("p95");
+ });
+
+ it("does not replace a stored non-count aggregation with the new measure's default", () => {
+ // latency defaults to avg; a widget already on sum must stay on sum.
+ expect(
+ resolveMeasureChangeAggregation({
+ currentAggregation: "sum",
+ newMeasure: "latency",
+ view: "observations",
+ viewVersion: "v1",
+ }),
+ ).toBe("sum");
+ });
+
+ it("keeps count when the new measure declares no default", () => {
+ // uniqueUserIds (v2) deliberately has no default: its stored `count`
+ // contract is remapped to distinct-user semantics via aggregationOverrides.
+ expect(
+ resolveMeasureChangeAggregation({
+ currentAggregation: "count",
+ newMeasure: "uniqueUserIds",
+ view: "observations",
+ viewVersion: "v2",
+ }),
+ ).toBe("count");
+ });
+
+ it("keeps count when switching to the count measure", () => {
+ expect(
+ resolveMeasureChangeAggregation({
+ currentAggregation: "count",
+ newMeasure: "count",
+ view: "observations",
+ viewVersion: "v1",
+ }),
+ ).toBe("count");
+ });
+
+ it("keeps count for an unknown measure", () => {
+ expect(
+ resolveMeasureChangeAggregation({
+ currentAggregation: "count",
+ newMeasure: "doesNotExist",
+ view: "observations",
+ viewVersion: "v1",
+ }),
+ ).toBe("count");
+ });
+});
diff --git a/web/src/features/widgets/components/widgetFormAdapters.clienttest.ts b/web/src/features/widgets/components/widgetFormAdapters.clienttest.ts
index 83d22a778a..a9ce05910c 100644
--- a/web/src/features/widgets/components/widgetFormAdapters.clienttest.ts
+++ b/web/src/features/widgets/components/widgetFormAdapters.clienttest.ts
@@ -332,6 +332,44 @@ const fixtures: Record<string, WidgetInitialValues> = {
chartType: "LINE_TIME_SERIES",
chartConfig: { type: "LINE_TIME_SERIES" },
},
+ // Historical widgets that stored count(toolCalls), the silent undercount.
+ // Opening them must not rewrite count to sum via defaultAggregation.
+ "saved toolCalls with count aggregation": {
+ name: "My tool calls widget",
+ description: "saved copy",
+ view: "observations",
+ measure: "toolCalls",
+ aggregation: "count",
+ dimension: "none",
+ filters: [],
+ chartType: "NUMBER",
+ chartConfig: { type: "NUMBER" },
+ minVersion: 1,
+ },
+ "saved toolCalls with sum aggregation": {
+ name: "Total tool calls",
+ description: "saved copy",
+ view: "observations",
+ measure: "toolCalls",
+ aggregation: "sum",
+ dimension: "none",
+ filters: [],
+ chartType: "NUMBER",
+ chartConfig: { type: "NUMBER" },
+ minVersion: 1,
+ },
+ "saved toolCallInvocations with count aggregation": {
+ name: "Invocations count",
+ description: "saved copy",
+ view: "observations",
+ measure: "toolCallInvocations",
+ aggregation: "count",
+ dimension: "calledToolNames",
+ filters: [],
+ chartType: "HORIZONTAL_BAR",
+ chartConfig: { type: "HORIZONTAL_BAR" },
+ minVersion: 1,
+ },
};
describe("widget form adapters round-trip parity", () => {
@@ -509,6 +547,59 @@ describe("toDefaultValues normalizes malformed stored/imported widgets", () => {
});
});
+describe("opening a saved widget does not apply defaultAggregation", () => {
+ it.each([
+ ["saved toolCalls with count aggregation", "toolCalls", "count"],
+ ["saved toolCalls with sum aggregation", "toolCalls", "sum"],
+ [
+ "saved toolCallInvocations with count aggregation",
+ "toolCallInvocations",
+ "count",
+ ],
+ ] as const)(
+ "%s keeps the stored %s + %s pair",
+ (fixtureName, measure, aggregation) => {
+ const iv = fixtures[fixtureName];
+ const values = toDefaultValues(iv, fixtureViewVersion(iv));
+ expect(values.metrics).toEqual([{ measure, aggregation }]);
+
+ const payload = adapterSavePayload(iv);
+ expect(payload.metrics).toEqual([{ measure, agg: aggregation }]);
+ expect(payload.name).toBe(iv.name);
+ expect(payload.description).toBe(iv.description);
+ },
+ );
+
+ it("keeps a pivot slot that stored count(toolCalls) next to avg(latency)", () => {
+ const iv: WidgetInitialValues = {
+ name: "Mixed pivot",
+ description: "saved",
+ view: "observations",
+ measure: "latency",
+ aggregation: "avg",
+ dimension: "environment",
+ filters: [],
+ chartType: "PIVOT_TABLE",
+ metrics: [
+ { measure: "latency", agg: "avg" },
+ { measure: "toolCalls", agg: "count" },
+ ],
+ dimensions: [{ field: "environment" }],
+ chartConfig: { type: "PIVOT_TABLE", row_limit: 50 },
+ minVersion: 1,
+ };
+
+ expect(toDefaultValues(iv, fixtureViewVersion(iv)).metrics).toEqual([
+ { measure: "latency", aggregation: "avg" },
+ { measure: "toolCalls", aggregation: "count" },
+ ]);
+ expect(adapterSavePayload(iv).metrics).toEqual([
+ { measure: "latency", agg: "avg" },
+ { measure: "toolCalls", agg: "count" },
+ ]);
+ });
+});
+
describe("applyChartTypeChange dimension boundary", () => {
const pivotWithDims: WidgetFormValues = {
name: null,
@@ -599,3 +690,38 @@ describe("save seam: editor-space filters map to view space (double-map)", () =>
);
});
});
+
+// --- sum(toolCalls) reads as "number of tool calls" in suggested name/copy ---
+
+describe("buildWidgetName / buildWidgetDescription for sum of tool calls", () => {
+ it("names the widget by meaning, not aggregation mechanics", () => {
+ expect(
+ buildWidgetName({
+ aggregation: "sum",
+ measure: "toolCalls",
+ dimension: "none",
+ view: "observations",
+ }),
+ ).toBe("Number of Tool Calls (Observations)");
+ expect(
+ buildWidgetDescription({
+ aggregation: "sum",
+ measure: "toolCalls",
+ dimension: "none",
+ view: "observations",
+ filters: [],
+ }),
+ ).toBe("Shows the number of tool calls of Observations");
+ });
+
+ it("keeps the generic template for other aggregations of toolCalls", () => {
+ expect(
+ buildWidgetName({
+ aggregation: "avg",
+ measure: "toolCalls",
+ dimension: "none",
+ view: "observations",
+ }),
+ ).toBe("Avg Tool Calls (Observations)");
+ });
+});
diff --git a/web/src/features/widgets/components/widgetFormSchema.ts b/web/src/features/widgets/components/widgetFormSchema.ts
index 7d60f7eb48..cdc8b27cf5 100644
--- a/web/src/features/widgets/components/widgetFormSchema.ts
+++ b/web/src/features/widgets/components/widgetFormSchema.ts
@@ -121,6 +121,30 @@ export function resolveAggregationAndChartType(params: {
return Object.keys(result).length > 0 ? result : null;
}
+/**
+ * resolveMeasureChangeAggregation picks the aggregation applied when the user
+ * switches the single-metric measure. A carried-over "count" — the only
+ * aggregation that gets auto-selected (via the default count measure) rather
+ * than deliberately chosen — jumps to the new measure's declared natural
+ * aggregation: e.g. count → toolCalls lands on "sum" (total tool calls), where
+ * keeping "count" would silently count observations with ≥1 tool call instead.
+ * Any other current aggregation is treated as deliberate and kept; validity
+ * healing runs in {@link normalizeWidgetFormValues}.
+ */
+export function resolveMeasureChangeAggregation(params: {
+ currentAggregation: z.infer<typeof metricAggregations>;
+ newMeasure: string;
+ view: z.infer<typeof views>;
+ viewVersion: ViewVersion;
+}): z.infer<typeof metricAggregations> {
+ const { currentAggregation, newMeasure, view, viewVersion } = params;
+ if (currentAggregation !== "count") return currentAggregation;
+ return (
+ viewDeclarations[viewVersion][view]?.measures?.[newMeasure]
+ ?.defaultAggregation ?? currentAggregation
+ );
+}
+
/**
* A single measure + aggregation pair, matching the save payload's `metrics[]`
* element (minus the string `agg` alias). `measure` is intentionally NOT
diff --git a/web/src/features/widgets/utils.ts b/web/src/features/widgets/utils.ts
index 9ab5fde0d6..6cb282c881 100644
--- a/web/src/features/widgets/utils.ts
+++ b/web/src/features/widgets/utils.ts
@@ -160,6 +160,10 @@ export function buildWidgetName({
if (measure.toLowerCase() === "count") {
// For count measures, ignore aggregation and only show the measure
base = meas;
+ } else if (measure === "toolCalls" && aggregation.toLowerCase() === "sum") {
+ // Summing the per-observation call count is simply "the number of tool
+ // calls" — surface the meaning, not the aggregation mechanics.
+ base = "Number of Tool Calls";
} else {
const agg = startCase(aggregation.toLowerCase());
base = `${agg} ${meas}`;
@@ -203,6 +207,9 @@ export function buildWidgetDescription({
if (measure.toLowerCase() === "count") {
sentence = `Shows the count of ${viewLabel}`;
+ } else if (measure === "toolCalls" && aggregation.toLowerCase() === "sum") {
+ // Mirrors buildWidgetName: sum(toolCalls) is the number of tool calls.
+ sentence = `Shows the number of tool calls of ${viewLabel}`;
} else {
const aggLabel = startCase(aggregation.toLowerCase());
sentence = `Shows the ${aggLabel.toLowerCase()} ${measLabel.toLowerCase()} of ${viewLabel}`;