Skip to content

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

chore(widgets): log high cardinality errors (#15996)

Nimarc302e67ae930
diff --git a/packages/shared/src/features/query/validateQuery.ts b/packages/shared/src/features/query/validateQuery.ts
index 7846f5dd92..e655ba82a0 100644
--- a/packages/shared/src/features/query/validateQuery.ts
+++ b/packages/shared/src/features/query/validateQuery.ts
@@ -5,9 +5,26 @@ import { getViewDeclaration } from "./dataModel";
* Result of query validation.
* Either valid (query is safe to run) or invalid with a reason.
*/
+export type HighCardinalityValidationCode =
+ | "entity_dimension_unbounded"
+ | "time_dimension"
+ | "additional_entity_dimension"
+ | "missing_top_n"
+ | "invalid_order_by";
+
+export type HighCardinalityValidationError = {
+ code: HighCardinalityValidationCode;
+ /** Schema-owned dimension field names, never dimension values. */
+ dimensions: string[];
+};
+
export type QueryValidationResult =
| { valid: true }
- | { valid: false; reason: string };
+ | {
+ valid: false;
+ reason: string;
+ highCardinality?: HighCardinalityValidationError;
+ };
const MAX_ENTITY_DIMENSION_BOUND_VALUES = 50;
@@ -113,6 +130,10 @@ function validateEntityDimension(
return {
valid: false,
reason: `High cardinality dimension '${field}' must be filtered with a finite positive filter.`,
+ highCardinality: {
+ code: "entity_dimension_unbounded",
+ dimensions: [field],
+ },
};
}
@@ -178,6 +199,10 @@ export function validateQuery(
return {
valid: false,
reason: `High cardinality dimension(s) '${highCardDims.join(", ")}' cannot be used with timeDimension. Time series queries with high cardinality dimensions produce unbounded result sets.`,
+ highCardinality: {
+ code: "time_dimension",
+ dimensions: highCardDims,
+ },
};
}
@@ -186,6 +211,10 @@ export function validateQuery(
return {
valid: false,
reason: `High cardinality dimension(s) '${highCardDims.join(", ")}' cannot be used with entityDimension. Entity-dimension queries with additional high cardinality dimensions produce unbounded result sets.`,
+ highCardinality: {
+ code: "additional_entity_dimension",
+ dimensions: highCardDims,
+ },
};
}
@@ -204,6 +233,10 @@ export function validateQuery(
return {
valid: false,
reason: `High cardinality dimension(s) '${highCardDims.join(", ")}' require both 'config.row_limit' and 'orderBy' with direction 'desc' on a measure field.`,
+ highCardinality: {
+ code: "missing_top_n",
+ dimensions: highCardDims,
+ },
};
}
@@ -227,6 +260,10 @@ export function validateQuery(
reason:
`High cardinality dimension(s) '${highCardDims.join(", ")}' require 'orderBy' with direction 'desc' on a measure field. ` +
`'${invalidOrderByFields.join(", ")}' ${invalidOrderByFields.length === 1 ? "is" : "are"} not a measure in this query.`,
+ highCardinality: {
+ code: "invalid_order_by",
+ dimensions: highCardDims,
+ },
};
}
diff --git a/web/src/__tests__/server/queryBuilder.servertest.ts b/web/src/__tests__/server/queryBuilder.servertest.ts
index 548baaff71..18e4934555 100644
--- a/web/src/__tests__/server/queryBuilder.servertest.ts
+++ b/web/src/__tests__/server/queryBuilder.servertest.ts
@@ -4336,6 +4336,12 @@ describe("validateQuery", () => {
const result = validateQuery(query, "v2");
expect(result.valid).toBe(false);
+ expect(result).toMatchObject({
+ highCardinality: {
+ code: "missing_top_n",
+ dimensions: ["traceId"],
+ },
+ });
expect((result as { valid: false; reason: string }).reason).toContain(
"High cardinality dimension(s) 'traceId'",
);
@@ -4372,6 +4378,12 @@ describe("validateQuery", () => {
const result = validateQuery(query, "v2");
expect(result.valid).toBe(false);
+ expect(result).toMatchObject({
+ highCardinality: {
+ code: "entity_dimension_unbounded",
+ dimensions: ["experimentName"],
+ },
+ });
expect((result as { valid: false; reason: string }).reason).toContain(
"High cardinality dimension 'experimentName'",
);
@@ -4456,6 +4468,12 @@ describe("validateQuery", () => {
const result = validateQuery(query, "v2");
expect(result.valid).toBe(false);
+ expect(result).toMatchObject({
+ highCardinality: {
+ code: "additional_entity_dimension",
+ dimensions: ["traceId"],
+ },
+ });
expect((result as { valid: false; reason: string }).reason).toContain(
"High cardinality dimension(s) 'traceId'",
);
@@ -4494,6 +4512,12 @@ describe("validateQuery", () => {
const result = validateQuery(query, "v2");
expect(result.valid).toBe(false);
+ expect(result).toMatchObject({
+ highCardinality: {
+ code: "invalid_order_by",
+ dimensions: ["traceId"],
+ },
+ });
expect((result as { valid: false; reason: string }).reason).toContain(
"High cardinality dimension(s) 'traceId'",
);
@@ -4590,6 +4614,12 @@ describe("validateQuery", () => {
const result = validateQuery(query, "v2");
expect(result.valid).toBe(false);
+ expect(result).toMatchObject({
+ highCardinality: {
+ code: "time_dimension",
+ dimensions: ["traceId"],
+ },
+ });
expect((result as { valid: false; reason: string }).reason).toContain(
"traceId",
);
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index 1677216082..6f432e034a 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -193,6 +193,7 @@ export const events = {
"widget_json_downloaded",
"widget_copied_to_clipboard",
"widget_view_as_table",
+ "widget_high_cardinality_error",
"widget_pasted",
"widget_paste_rejected",
"widget_duplicated",
diff --git a/web/src/features/widgets/components/DashboardWidget.tsx b/web/src/features/widgets/components/DashboardWidget.tsx
index f3032124bc..01a0abf25e 100644
--- a/web/src/features/widgets/components/DashboardWidget.tsx
+++ b/web/src/features/widgets/components/DashboardWidget.tsx
@@ -42,6 +42,7 @@ import {
} from "@/src/features/widgets/utils/import-export-utils";
import { copyTextToClipboard } from "@/src/utils/clipboard";
import { useClipboardWidgetProbe } from "@/src/features/widgets/hooks/useClipboardWidgetProbe";
+import { useCaptureWidgetHighCardinalityError } from "@/src/features/widgets/hooks/useWidgetQueryErrorCapture";
import { isPasteablePlacementPayload } from "@/src/features/dashboard/utils/dashboard-import-export";
import {
DropdownMenu,
@@ -269,6 +270,12 @@ export function DashboardWidget({
: ({ valid: true } as const),
[widgetQuery, metricsVersion, widget.data],
);
+ useCaptureWidgetHighCardinalityError({
+ validation: queryValidation,
+ surface: "dashboard_tile",
+ chartType: widget.data?.chartType,
+ isV4: metricsVersion === "v2",
+ });
const queryResult = useScheduledDashboardExecuteQuery(
{
projectId,
diff --git a/web/src/features/widgets/components/WidgetForm.tsx b/web/src/features/widgets/components/WidgetForm.tsx
index de10e664a6..04acd5ae10 100644
--- a/web/src/features/widgets/components/WidgetForm.tsx
+++ b/web/src/features/widgets/components/WidgetForm.tsx
@@ -113,6 +113,7 @@ import {
getWidgetFilterColumns,
} from "./widgetFilterColumns";
import { WIDGET_FILTER_PRESETS } from "@/src/features/widgets/constants/widgetFilterPresets";
+import { useCaptureWidgetHighCardinalityError } from "@/src/features/widgets/hooks/useWidgetQueryErrorCapture";
import {
applyChartTypeChange,
deriveEffectiveSort,
@@ -733,6 +734,13 @@ export function WidgetForm({
return validateQuery(query, viewVersion);
}, [query, unsupportedFilterColumns, unsupportedFilters.length, viewVersion]);
+ useCaptureWidgetHighCardinalityError({
+ validation: queryValidation,
+ surface: widgetId ? "edit_editor" : "create_editor",
+ chartType,
+ isV4: viewVersion === "v2",
+ });
+
const queryResult = api.dashboard.executeQuery.useQuery(
{
projectId,
diff --git a/web/src/features/widgets/hooks/useWidgetQueryErrorCapture.ts b/web/src/features/widgets/hooks/useWidgetQueryErrorCapture.ts
new file mode 100644
index 0000000000..b15b04146a
--- /dev/null
+++ b/web/src/features/widgets/hooks/useWidgetQueryErrorCapture.ts
@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+import { type QueryValidationResult } from "@langfuse/shared/query";
+import { type DashboardWidgetChartType } from "@langfuse/shared/src/db";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
+
+type WidgetHighCardinalityErrorSurface =
+ | "create_editor"
+ | "edit_editor"
+ | "dashboard_tile";
+
+export function useCaptureWidgetHighCardinalityError({
+ validation,
+ surface,
+ chartType,
+ isV4,
+}: {
+ validation: QueryValidationResult;
+ surface: WidgetHighCardinalityErrorSurface;
+ chartType?: DashboardWidgetChartType;
+ isV4: boolean;
+}) {
+ const capture = usePostHogClientCapture();
+ const lastCapturedEncounter = useRef<string | null>(null);
+
+ useEffect(() => {
+ const error = validation.valid ? undefined : validation.highCardinality;
+ if (!error) {
+ lastCapturedEncounter.current = null;
+ return;
+ }
+ if (!chartType) return;
+
+ const properties = {
+ surface,
+ chartType,
+ isV4,
+ validationCode: error.code,
+ highCardinalityDimensions: error.dimensions,
+ };
+ const encounter = JSON.stringify(properties);
+ if (lastCapturedEncounter.current === encounter) return;
+ lastCapturedEncounter.current = encounter;
+
+ capture("dashboard:widget_high_cardinality_error", properties);
+ }, [capture, chartType, isV4, surface, validation]);
+}