Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

perf(dashboards): per-mount scheduler store, SSE in the query cache, ClickHouse cancellation (#16904)

Nikita Kabardinee78faefb41a
diff --git a/web/src/__tests__/sse-dashboard-query.clienttest.ts b/web/src/__tests__/sse-dashboard-query.clienttest.ts
index e5fc1874a5..5b6f4b5a85 100644
--- a/web/src/__tests__/sse-dashboard-query.clienttest.ts
+++ b/web/src/__tests__/sse-dashboard-query.clienttest.ts
@@ -2,10 +2,13 @@
* Tests for the SSE dashboard query hook's parsing and progress logic.
*/
import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createElement } from "react";
import { TextDecoder, TextEncoder } from "util";
import {
parseSSEBuffer,
computeMonotonicPercent,
+ fetchDashboardSSERows,
useSSEDashboardQuery,
} from "@/src/hooks/useSSEDashboardQuery";
@@ -145,6 +148,13 @@ describe("useSSEDashboardQuery", () => {
const originalFetch = global.fetch;
const originalTextDecoder = global.TextDecoder;
+ const createWrapper = () => {
+ const queryClient = new QueryClient();
+ const wrapper = ({ children }: { children: React.ReactNode }) =>
+ createElement(QueryClientProvider, { client: queryClient }, children);
+ return wrapper;
+ };
+
const createStreamReader = (chunks: Uint8Array[]) => {
let index = 0;
@@ -181,6 +191,22 @@ describe("useSSEDashboardQuery", () => {
},
});
+ type TestInput = ReturnType<typeof createInput>;
+
+ // Mirrors production: the scheduler wrapper derives the cache key from the
+ // query input, so a changed input is a new key.
+ const renderSSEHook = (initial: { input: TestInput; enabled: boolean }) =>
+ renderHook(
+ ({ input, enabled }: { input: TestInput; enabled: boolean }) =>
+ useSSEDashboardQuery(input, {
+ enabled,
+ queryKey: ["sse-test", input],
+ staleTime: 0,
+ gcTime: Number.POSITIVE_INFINITY,
+ }),
+ { initialProps: initial, wrapper: createWrapper() },
+ );
+
afterEach(() => {
global.fetch = originalFetch;
global.TextDecoder = originalTextDecoder;
@@ -204,25 +230,17 @@ describe("useSSEDashboardQuery", () => {
})) as typeof fetch;
global.TextDecoder = TextDecoder as typeof global.TextDecoder;
- const { result, rerender } = renderHook(
- ({ enabled }) =>
- useSSEDashboardQuery(
- createInput("2026-03-22T00:00:00.000Z", "2026-03-23T00:00:00.000Z"),
- {
- enabled,
- queryId: "widget-1",
- },
- ),
- {
- initialProps: { enabled: true },
- },
+ const input = createInput(
+ "2026-03-22T00:00:00.000Z",
+ "2026-03-23T00:00:00.000Z",
);
+ const { result, rerender } = renderSSEHook({ input, enabled: true });
await waitFor(() => {
expect(result.current.isSuccess).toBe(true);
});
- rerender({ enabled: false });
+ rerender({ input, enabled: false });
await waitFor(() => {
expect(result.current.isSuccess).toBe(true);
@@ -292,17 +310,7 @@ describe("useSSEDashboardQuery", () => {
"2026-03-22T00:00:00.000Z",
"2026-03-23T00:00:00.000Z",
);
-
- const { result, rerender } = renderHook(
- ({ enabled }) =>
- useSSEDashboardQuery(input, {
- enabled,
- queryId: "widget-1",
- }),
- {
- initialProps: { enabled: true },
- },
- );
+ const { result, rerender } = renderSSEHook({ input, enabled: true });
await waitFor(() => {
expect(result.current.isSuccess).toBe(true);
@@ -311,17 +319,19 @@ describe("useSSEDashboardQuery", () => {
// Scheduler re-promotion: the widget is disabled, then re-enabled with the
// exact same query input (a re-run it did not need).
- rerender({ enabled: false });
- rerender({ enabled: true });
+ rerender({ input, enabled: false });
+ rerender({ input, enabled: true });
- // The second stream is in flight. The chart must NOT blank: the previously
- // loaded rows stay rendered until fresh rows arrive.
+ // The second stream is in flight (a background refetch). The chart must
+ // NOT blank: the previously loaded rows stay rendered until fresh rows
+ // arrive, and the run is not "pending" (no loading overlay).
await waitFor(() => {
expect(global.fetch).toHaveBeenCalledTimes(2);
});
await waitFor(() => {
- expect(result.current.isLoading).toBe(true);
+ expect(result.current.fetchStatus).toBe("fetching");
});
+ expect(result.current.isPending).toBe(false);
expect(result.current.data).toEqual([{ count_count: 42 }]);
(releaseSecondResponse as (() => void) | null)?.();
@@ -391,32 +401,22 @@ describe("useSSEDashboardQuery", () => {
"2026-03-22T00:00:00.000Z",
"2026-03-23T00:00:00.000Z",
);
-
- const { result, rerender } = renderHook(
- ({ enabled }) =>
- useSSEDashboardQuery(input, {
- enabled,
- queryId: "widget-1",
- }),
- {
- initialProps: { enabled: true },
- },
- );
+ const { result, rerender } = renderSSEHook({ input, enabled: true });
await waitFor(() => {
expect(result.current.isSuccess).toBe(true);
});
expect(result.current.data).toEqual([{ count_count: 42 }]);
- rerender({ enabled: false });
- rerender({ enabled: true });
+ rerender({ input, enabled: false });
+ rerender({ input, enabled: true });
// While the re-run is in flight, previous rows are still shown.
await waitFor(() => {
expect(global.fetch).toHaveBeenCalledTimes(2);
});
await waitFor(() => {
- expect(result.current.isLoading).toBe(true);
+ expect(result.current.fetchStatus).toBe("fetching");
});
expect(result.current.data).toEqual([{ count_count: 42 }]);
@@ -486,27 +486,20 @@ describe("useSSEDashboardQuery", () => {
"2026-03-23T00:00:00.000Z",
);
- const { result, rerender } = renderHook(
- ({ input }) =>
- useSSEDashboardQuery(input, {
- enabled: true,
- queryId: "widget-1",
- }),
- {
- initialProps: { input: firstInput },
- },
- );
+ const { result, rerender } = renderSSEHook({
+ input: firstInput,
+ enabled: true,
+ });
await waitFor(() => {
expect(result.current.isSuccess).toBe(true);
});
- rerender({ input: secondInput });
+ rerender({ input: secondInput, enabled: true });
expect(result.current.isPending).toBe(true);
expect(result.current.isLoading).toBe(true);
expect(result.current.isSuccess).toBe(false);
- expect(result.current.fetchStatus).toBe("fetching");
expect(result.current.data).toBeUndefined();
expect(result.current.progress).toBeNull();
expect(result.current.error).toBeNull();
@@ -526,3 +519,101 @@ describe("useSSEDashboardQuery", () => {
});
});
});
+
+// The two degrade paths that must fail visibly instead of wedging a widget or
+// caching partial rows as a fresh success.
+describe("fetchDashboardSSERows degrade paths", () => {
+ const originalFetch = global.fetch;
+ const originalTextDecoder = global.TextDecoder;
+
+ const input = {
+ projectId: "project-1",
+ version: "v1" as const,
+ query: {
+ view: "traces" as const,
+ dimensions: [],
+ metrics: [{ measure: "count", aggregation: "count" as const }],
+ filters: [],
+ timeDimension: null,
+ fromTimestamp: "2026-03-22T00:00:00.000Z",
+ toTimestamp: "2026-03-23T00:00:00.000Z",
+ orderBy: null,
+ },
+ };
+
+ afterEach(() => {
+ global.fetch = originalFetch;
+ global.TextDecoder = originalTextDecoder;
+ vi.restoreAllMocks();
+ });
+
+ it("aborts a stalled stream with a real error (never forever-pending)", async () => {
+ const encoder = new TextEncoder();
+ global.TextDecoder = TextDecoder as typeof global.TextDecoder;
+ global.fetch = vi.fn().mockImplementation(async (_url, init) => ({
+ ok: true,
+ body: {
+ getReader: () => ({
+ read: vi
+ .fn()
+ .mockResolvedValueOnce({
+ done: false,
+ value: encoder.encode('event: row\ndata: {"count_count":1}\n\n'),
+ })
+ // Second read never resolves β€” until the watchdog aborts.
+ .mockImplementation(
+ () =>
+ new Promise((_resolve, reject) => {
+ (init as RequestInit).signal?.addEventListener("abort", () =>
+ reject(new DOMException("aborted", "AbortError")),
+ );
+ }),
+ ),
+ }),
+ },
+ })) as typeof fetch;
+
+ await expect(
+ fetchDashboardSSERows(input, {
+ basePath: "",
+ signal: new AbortController().signal,
+ onProgress: () => undefined,
+ stallTimeoutMs: 30,
+ }),
+ ).rejects.toThrow(/stalled/);
+ });
+
+ it("treats a stream cut before its terminal event as an error, even with rows", async () => {
+ const encoder = new TextEncoder();
+ global.TextDecoder = TextDecoder as typeof global.TextDecoder;
+ let step = 0;
+ global.fetch = vi.fn().mockImplementation(async () => ({
+ ok: true,
+ body: {
+ getReader: () => ({
+ read: vi.fn().mockImplementation(async () => {
+ if (step === 0) {
+ step += 1;
+ return {
+ done: false,
+ value: encoder.encode(
+ 'event: row\ndata: {"count_count":42}\n\n',
+ ),
+ };
+ }
+ // Clean end without a "done"/"error" event: a cut stream.
+ return { done: true, value: undefined };
+ }),
+ }),
+ },
+ })) as typeof fetch;
+
+ await expect(
+ fetchDashboardSSERows(input, {
+ basePath: "",
+ signal: new AbortController().signal,
+ onProgress: () => undefined,
+ }),
+ ).rejects.toThrow("Stream ended unexpectedly");
+ });
+});
diff --git a/web/src/features/dashboard/README.md b/web/src/features/dashboard/README.md
new file mode 100644
index 0000000000..9843e4c1e3
--- /dev/null
+++ b/web/src/features/dashboard/README.md
@@ -0,0 +1,93 @@
+# Dashboard Feature
+
+## Surface
+
+Dashboards: the project Home page (a read-only dashboard viewer), the
+self-serve dashboard detail page, and the legacy curated Home cards that render
+as "preset" placements.
+
+## Entry Points
+
+- `web/src/pages/project/[projectId]/index.tsx` β€” Home. Controller resolves the
+ v3/v4 read path before anything mounts, then renders `HomeDashboard`.
+- `web/src/pages/project/[projectId]/dashboards/[dashboardId]/index.tsx` β€”
+ dashboard detail. Same controller split (`DashboardDetailView`).
+- Both pages create the per-mount scheduler store and provide it via
+ `DashboardQuerySchedulerProvider`.
+
+## Structure
+
+- `components/` β€” the legacy curated Home cards (TracesBarListChart,
+ ModelCostTable, …) rendered by `home-preset-registry.tsx` as preset
+ placements, plus dashboard-scoped dialogs/selectors. Cards receive a
+ **required** `metricsVersion` from the preset context β€” they never read the
+ session themselves.
+- `hooks/` β€” `useDashboardQueryScheduler.tsx`: the scheduler controller hook,
+ provider/context, executeQuery cache policy, and
+ `useScheduledDashboardExecuteQuery` (the one entry point widgets use to run
+ a dashboard query under the concurrency budget, over tRPC or SSE).
+- `stores/` β€” `dashboardQuerySchedulerStore.ts`: per-mount vanilla Zustand
+ store owning the widget query queue (register/unregister/markDone/
+ resetQueue/setMaxConcurrent). Created by the page, provided via context,
+ destroyed on unmount.
+- `server/` β€” `dashboard-router.ts` (tRPC). `executeQuery` requires an
+ explicit `version` and validates v2 against the session's read path.
+- `lib/`, `utils/` β€” pure helpers (table href building, import/export).
+
+Related but outside this folder: `web/src/features/widgets/` owns
+`DashboardGrid` / `DashboardWidget` / `WidgetContent` and the chart library;
+`web/src/hooks/useSSEDashboardQuery.ts` owns the SSE transport (kept there
+because `parseSSEBuffer` has non-dashboard consumers).
+
+## State Ownership
+
+- **Server/query state**: React Query. Both transports (tRPC fetch and the SSE
+ stream) cache rows under the same `["dashboard.executeQuery", input, retry]`
+ key, so identical widgets share one query/stream and a transport flip reuses
+ cached rows.
+- **Read path (v3/v4)**: session state, resolved by the page controller and
+ passed down as a required `readPath` prop β€” never mirrored into a store.
+- **Scheduler queue**: the per-mount vanilla store above. Widgets subscribe to
+ `items[queryId]?.status === "running"` only.
+- **SSE progress events**: high-frequency; deliberately kept OUT of the query
+ cache as local state on the mount that initiated the stream.
+- **Route state**: time range / filters / peeked dashboard live in the URL
+ hooks on the pages.
+
+## Performance And Stability Boundaries
+
+- Scheduler slot changes re-render only the widget whose slot changed β€” never
+ the page (the store replaced a page-level `useState` version counter that
+ re-rendered the whole grid on every queue transition).
+- Progress events re-render one widget's loading state at ClickHouse's
+ progress cadence; they must never enter the query cache or context values.
+- The scheduler reset key must contain only query-affecting params β€” never the
+ widget set (`useDashboardQueryScheduler.clienttest.ts` pins this).
+
+## Reliability Invariants
+
+- A widget query releases its scheduler slot on every terminal path β€” success,
+ error, stall (60s no-byte watchdog aborts the stream), or unmount
+ (unregister). A held slot at 90d windows (budget: 2) freezes the dashboard.
+- The SSE endpoint sets `cancel_http_readonly_queries_on_client_close`, so
+ when the browser disconnects (the handler breaks and the ClickHouse stream
+ socket closes) the server kills the query instead of running the abandoned
+ aggregation to completion; `max_execution_time` bounds any straggler.
+
+## Migration State
+
+- Done: controller split for the read path; scheduler on a per-mount vanilla
+ store; SSE rows/status in the React Query cache; per-widget reactive slot
+ subscriptions.
+- Still spread: the dashboard detail page is a single large component (draft
+ definition state, paste/import handlers, clone-first dialog state all
+ inline); the legacy preset cards fetch through bespoke `dashboard.chart`
+ query names. Next slice: extract the detail page's paste/import workflows
+ into `actions/*.ts`.
+
+## Development Context
+
+Read `.agents/skills/frontend-large-feature-architecture/SKILL.md` (and its
+`references/local-feature-state.md`) before adding state or effects here. For
+chart/formatting work, `web/src/features/widgets/chart-library/ARCHITECTURE.md`
+owns the data β†’ preparer β†’ visualiser contract.
diff --git a/web/src/features/dashboard/components/ChartScores.tsx b/web/src/features/dashboard/components/ChartScores.tsx
index f3aae23aed..872f4edd2c 100644
--- a/web/src/features/dashboard/components/ChartScores.tsx
+++ b/web/src/features/dashboard/components/ChartScores.tsx
@@ -18,7 +18,7 @@ import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashb
import { type DatabaseRow } from "@/src/server/api/services/sqlInterface";
import { Chart } from "@/src/features/widgets/chart-library/Chart";
import { timeSeriesToDataPoints } from "@/src/features/dashboard/lib/chart-data-adapters";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
// Static β€” hoisted so its reference is stable across re-renders (keeps the
// memoized <Chart> from reconciling on dashboard scheduler re-renders).
diff --git a/web/src/features/dashboard/components/LatencyChart.tsx b/web/src/features/dashboard/components/LatencyChart.tsx
index 4dc2dd9d45..7d4a574299 100644
--- a/web/src/features/dashboard/components/LatencyChart.tsx
+++ b/web/src/features/dashboard/components/LatencyChart.tsx
@@ -20,7 +20,7 @@ import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
import type { DatabaseRow } from "@/src/server/api/services/sqlInterface";
import { DashboardLineTimeSeriesChart } from "@/src/features/dashboard/components/DashboardLineTimeSeriesChart";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { useMemo } from "react";
export const GenerationLatencyChart = ({
diff --git a/web/src/features/dashboard/components/LatencyTables.tsx b/web/src/features/dashboard/components/LatencyTables.tsx
index bf0972968d..e09ceb385f 100644
--- a/web/src/features/dashboard/components/LatencyTables.tsx
+++ b/web/src/features/dashboard/components/LatencyTables.tsx
@@ -14,7 +14,7 @@ import { cn } from "@/src/utils/tailwind";
import { Popup } from "@/src/components/layouts/doc-popup";
import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
export type LatencyTableKind = "traces" | "generations" | "observations";
diff --git a/web/src/features/dashboard/components/ModelCostTable.tsx b/web/src/features/dashboard/components/ModelCostTable.tsx
index e7a5b3ad0a..2d61ab4167 100644
--- a/web/src/features/dashboard/components/ModelCostTable.tsx
+++ b/web/src/features/dashboard/components/ModelCostTable.tsx
@@ -10,7 +10,7 @@ import { TotalMetric } from "./TotalMetric";
import { truncate } from "@/src/utils/string";
import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { cn } from "@/src/utils/tailwind";
export const ModelCostTable = ({
diff --git a/web/src/features/dashboard/components/ModelUsageChart.tsx b/web/src/features/dashboard/components/ModelUsageChart.tsx
index 4cfb400ecb..500fea6d48 100644
--- a/web/src/features/dashboard/components/ModelUsageChart.tsx
+++ b/web/src/features/dashboard/components/ModelUsageChart.tsx
@@ -23,7 +23,7 @@ import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
import { type DatabaseRow } from "@/src/server/api/services/sqlInterface";
import { DashboardLineTimeSeriesChart } from "@/src/features/dashboard/components/DashboardLineTimeSeriesChart";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { useMemo } from "react";
export const ModelUsageChart = ({
diff --git a/web/src/features/dashboard/components/TracesBarListChart.tsx b/web/src/features/dashboard/components/TracesBarListChart.tsx
index e64f01ca4a..3ff5f158b8 100644
--- a/web/src/features/dashboard/components/TracesBarListChart.tsx
+++ b/web/src/features/dashboard/components/TracesBarListChart.tsx
@@ -8,7 +8,7 @@ import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { formatMetric } from "@/src/features/widgets/chart-library/utils";
import { BarListChartArea } from "@/src/features/dashboard/components/cards/BarListChartArea";
import { traceViewQuery } from "@/src/features/dashboard/lib/dashboard-utils";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { cn } from "@/src/utils/tailwind";
// Cap on bars fetched and rendered; the top list scrolls within the tile when
diff --git a/web/src/features/dashboard/components/TracesTimeSeriesChart.tsx b/web/src/features/dashboard/components/TracesTimeSeriesChart.tsx
index 6b69feb4a5..1cdd64e265 100644
--- a/web/src/features/dashboard/components/TracesTimeSeriesChart.tsx
+++ b/web/src/features/dashboard/components/TracesTimeSeriesChart.tsx
@@ -13,7 +13,7 @@ import { TabComponent } from "@/src/features/dashboard/components/TabsComponent"
import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
import { DashboardLineTimeSeriesChart } from "@/src/features/dashboard/components/DashboardLineTimeSeriesChart";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { useMemo } from "react";
export const TracesAndObservationsTimeSeriesChart = ({
diff --git a/web/src/features/dashboard/components/UserChart.tsx b/web/src/features/dashboard/components/UserChart.tsx
index caf9621873..24fc7ddcf4 100644
--- a/web/src/features/dashboard/components/UserChart.tsx
+++ b/web/src/features/dashboard/components/UserChart.tsx
@@ -9,7 +9,7 @@ import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
import { BarListChartArea } from "@/src/features/dashboard/components/cards/BarListChartArea";
import { traceViewQuery } from "@/src/features/dashboard/lib/dashboard-utils";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { cn } from "@/src/utils/tailwind";
// Cap on bars fetched and rendered; matches TracesBarListChart. The top list
diff --git a/web/src/features/dashboard/components/hooks.ts b/web/src/features/dashboard/components/hooks.ts
index 98a9ab9364..13ab7dc1c6 100644
--- a/web/src/features/dashboard/components/hooks.ts
+++ b/web/src/features/dashboard/components/hooks.ts
@@ -8,7 +8,7 @@ export type TimeSeriesChartDataPoint = {
import { type DatabaseRow } from "@/src/server/api/services/sqlInterface";
import { type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
type UseAllModelsOptions = {
enabled?: boolean;
diff --git a/web/src/features/dashboard/components/score-analytics/CategoricalScoreChart.tsx b/web/src/features/dashboard/components/score-analytics/CategoricalScoreChart.tsx
index 44695e3245..df3724d13e 100644
--- a/web/src/features/dashboard/components/score-analytics/CategoricalScoreChart.tsx
+++ b/web/src/features/dashboard/components/score-analytics/CategoricalScoreChart.tsx
@@ -14,7 +14,7 @@ import { Chart } from "@/src/features/widgets/chart-library/Chart";
import { scoreChartDataToDataPoints } from "@/src/features/dashboard/lib/chart-data-adapters";
import { isEmptyChart } from "@/src/features/dashboard/lib/score-analytics-utils";
import { NoDataOrLoading } from "@/src/components/NoDataOrLoading";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
export function CategoricalScoreChart(props: {
projectId: string;
diff --git a/web/src/features/dashboard/components/score-analytics/NumericScoreTimeSeriesChart.tsx b/web/src/features/dashboard/components/score-analytics/NumericScoreTimeSeriesChart.tsx
index cbc897a5d0..16ff9726b6 100644
--- a/web/src/features/dashboard/components/score-analytics/NumericScoreTimeSeriesChart.tsx
+++ b/web/src/features/dashboard/components/score-analytics/NumericScoreTimeSeriesChart.tsx
@@ -19,7 +19,7 @@ import { type QueryType, type ViewVersion } from "@langfuse/shared/query";
import { mapLegacyUiTableFilterToView } from "@/src/features/dashboard/lib/dashboardUiTableToViewMapping";
import { type DatabaseRow } from "@/src/server/api/services/sqlInterface";
import { DashboardLineTimeSeriesChart } from "@/src/features/dashboard/components/DashboardLineTimeSeriesChart";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
export function NumericScoreTimeSeriesChart(props: {
projectId: string;
diff --git a/web/src/hooks/useDashboardQueryScheduler.clienttest.ts b/web/src/features/dashboard/hooks/useDashboardQueryScheduler.clienttest.ts
similarity index 58%
rename from web/src/hooks/useDashboardQueryScheduler.clienttest.ts
rename to web/src/features/dashboard/hooks/useDashboardQueryScheduler.clienttest.ts
index 8311bd315e..3a0f3ff2c0 100644
--- a/web/src/hooks/useDashboardQueryScheduler.clienttest.ts
+++ b/web/src/features/dashboard/hooks/useDashboardQueryScheduler.clienttest.ts
@@ -5,14 +5,14 @@
* reset key changes (see `resetQueue`). The reset key must therefore depend
* only on genuinely query-affecting params (time range, filters, environment)
* and NOT on the set of widgets present β€” otherwise adding a widget re-runs
- * every sibling, which on the SSE path blanks already-rendered charts
- * (LFE-10986).
+ * every sibling, which on the SSE path blanks already-rendered charts.
*/
import { act, renderHook } from "@testing-library/react";
import {
getDashboardSchedulerResetKey,
useDashboardQueryScheduler,
-} from "@/src/hooks/useDashboardQueryScheduler";
+} from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
+import { type DashboardQuerySchedulerStore } from "@/src/features/dashboard/stores/dashboardQuerySchedulerStore";
describe("getDashboardSchedulerResetKey", () => {
const base = {
@@ -26,7 +26,7 @@ describe("getDashboardSchedulerResetKey", () => {
it("is composed of only query-affecting params (never the widget set)", () => {
// Pinning the exact composition guards against re-introducing the widget
- // id list, which would re-queue every sibling on "Add Widget" (LFE-10986).
+ // id list, which would re-queue every sibling on "Add Widget".
expect(getDashboardSchedulerResetKey(base)).toBe(
"project-1|dashboard-1|2026-01-01T00:00:00.000Z|2026-01-08T00:00:00.000Z|[]|default",
);
@@ -61,39 +61,43 @@ describe("getDashboardSchedulerResetKey", () => {
});
describe("useDashboardQueryScheduler", () => {
+ const canFetch = (store: DashboardQuerySchedulerStore, id: string) =>
+ store.getState().items[id]?.status === "running";
+
// Characterizes `register`'s incremental behavior (a new id is inserted as
// `queued` and scheduled without iterating existing items). This is the
- // property the reset-key fix relies on β€” not itself a guard for LFE-10986
- // (register never touched siblings, pre- or post-fix). The regression guard
- // for the bug is the getDashboardSchedulerResetKey composition test above.
+ // property the reset-key contract relies on (register never touched
+ // siblings, pre- or post-fix). The regression guard for the add-a-widget
+ // bug is the getDashboardSchedulerResetKey composition test above.
it("schedules a newly registered widget without touching done siblings", () => {
const { result } = renderHook(() =>
useDashboardQueryScheduler({ maxConcurrent: 2, resetKey: "k1" }),
);
+ const { actions } = result.current.getState();
act(() => {
- result.current.register("w1", 1);
- result.current.register("w2", 2);
+ actions.register("w1", 1);
+ actions.register("w2", 2);
});
// Both promoted (maxConcurrent = 2) then completed.
act(() => {
- result.current.markDone("w1");
- result.current.markDone("w2");
+ actions.markDone("w1");
+ actions.markDone("w2");
});
- expect(result.current.canFetch("w1")).toBe(false);
- expect(result.current.canFetch("w2")).toBe(false);
+ expect(canFetch(result.current, "w1")).toBe(false);
+ expect(canFetch(result.current, "w2")).toBe(false);
// "Add Widget": a brand-new placement registers and schedules on its own.
act(() => {
- result.current.register("w3", 3);
+ actions.register("w3", 3);
});
- expect(result.current.canFetch("w3")).toBe(true);
+ expect(canFetch(result.current, "w3")).toBe(true);
// The done siblings must stay done β€” never re-queued/re-run.
- expect(result.current.canFetch("w1")).toBe(false);
- expect(result.current.canFetch("w2")).toBe(false);
+ expect(canFetch(result.current, "w1")).toBe(false);
+ expect(canFetch(result.current, "w2")).toBe(false);
});
it("re-queues completed widgets when the reset key changes", () => {
@@ -102,19 +106,49 @@ describe("useDashboardQueryScheduler", () => {
useDashboardQueryScheduler({ maxConcurrent: 5, resetKey }),
{ initialProps: { resetKey: "k1" } },
);
+ const { actions } = result.current.getState();
act(() => {
- result.current.register("w1", 1);
+ actions.register("w1", 1);
});
act(() => {
- result.current.markDone("w1");
+ actions.markDone("w1");
});
- expect(result.current.canFetch("w1")).toBe(false);
+ expect(canFetch(result.current, "w1")).toBe(false);
// A genuine query-param change (new reset key) must refresh everything.
rerender({ resetKey: "k2" });
- expect(result.current.canFetch("w1")).toBe(true);
+ expect(canFetch(result.current, "w1")).toBe(true);
+ });
+
+ it("holds queued widgets until a running slot frees, in priority order", () => {
+ const { result } = renderHook(() =>
+ useDashboardQueryScheduler({ maxConcurrent: 1, resetKey: "k1" }),
+ );
+ const { actions } = result.current.getState();
+
+ act(() => {
+ actions.register("late", 10);
+ actions.register("early", 1);
+ });
+
+ // One slot: "late" grabbed it on registration; "early" waits.
+ expect(canFetch(result.current, "late")).toBe(true);
+ expect(canFetch(result.current, "early")).toBe(false);
+
+ // Slot frees on ANY completion path (done or unmount) β€” the waiter with
+ // the lowest priority value runs next.
+ act(() => {
+ actions.markDone("late");
+ });
+ expect(canFetch(result.current, "early")).toBe(true);
+
+ act(() => {
+ actions.register("next", 5);
+ actions.unregister("early");
+ });
+ expect(canFetch(result.current, "next")).toBe(true);
});
});
diff --git a/web/src/hooks/useDashboardQueryScheduler.tsx b/web/src/features/dashboard/hooks/useDashboardQueryScheduler.tsx
similarity index 64%
rename from web/src/hooks/useDashboardQueryScheduler.tsx
rename to web/src/features/dashboard/hooks/useDashboardQueryScheduler.tsx
index 865280ea8b..f49f09e402 100644
--- a/web/src/hooks/useDashboardQueryScheduler.tsx
+++ b/web/src/features/dashboard/hooks/useDashboardQueryScheduler.tsx
@@ -7,40 +7,22 @@ import { hashKey, useQuery, type UseQueryOptions } from "@tanstack/react-query";
import {
createContext,
type ReactNode,
- useCallback,
useContext,
useEffect,
useMemo,
useRef,
useState,
} from "react";
+import { useStore } from "zustand";
+import {
+ createDashboardQuerySchedulerStore,
+ type DashboardQuerySchedulerStore,
+} from "@/src/features/dashboard/stores/dashboardQuerySchedulerStore";
import {
useSSEDashboardQuery,
type QueryProgress,
} from "@/src/hooks/useSSEDashboardQuery";
-type SchedulerItemStatus = "queued" | "running" | "done";
-
-type SchedulerItem = {
- id: string;
- priority: number;
- isEligible: boolean;
- runKey: string;
- status: SchedulerItemStatus;
-};
-
-export type DashboardQuerySchedulerApi = {
- register: (
- id: string,
- priority: number,
- isEligible?: boolean,
- runKey?: string,
- ) => void;
- unregister: (id: string) => void;
- canFetch: (id: string) => boolean;
- markDone: (id: string) => void;
-};
-
const DAY_MS = 24 * 60 * 60 * 1000;
const SECOND_MS = 1000;
const MINUTE_MS = 60 * SECOND_MS;
@@ -102,156 +84,42 @@ const parseIsoDateMs = (value: unknown): number | null => {
return parsedMs;
};
+/**
+ * Owns one per-mount scheduler store for a dashboard page: creates it lazily
+ * and syncs the two page-driven inputs (concurrency budget, reset key) into
+ * store actions. Scheduler state changes no longer re-render the page β€” the
+ * store notifies only the widgets whose slot changed.
+ */
export const useDashboardQueryScheduler = ({
maxConcurrent,
resetKey,
}: {
maxConcurrent: number;
resetKey?: string;
-}): DashboardQuerySchedulerApi => {
- const itemsRef = useRef<Map<string, SchedulerItem>>(new Map());
- const [_version, setVersion] = useState(0);
- const previousResetKeyRef = useRef<string | undefined>(resetKey);
-
- const syncQueue = useCallback(() => {
- const items = itemsRef.current;
- let runningCount = 0;
- let changed = false;
-
- for (const item of items.values()) {
- if (item.status === "running") {
- runningCount += 1;
- }
- }
-
- const candidates = Array.from(items.values())
- .filter((item) => item.status === "queued" && item.isEligible)
- .sort((a, b) => a.priority - b.priority);
-
- for (const candidate of candidates) {
- if (runningCount >= maxConcurrent) break;
- candidate.status = "running";
- runningCount += 1;
- changed = true;
- }
-
- if (changed) {
- setVersion((value) => value + 1);
- }
- }, [maxConcurrent]);
-
- const register = useCallback(
- (id: string, priority: number, isEligible = true, runKey: string = id) => {
- const existingItem = itemsRef.current.get(id);
-
- if (!existingItem) {
- itemsRef.current.set(id, {
- id,
- priority,
- isEligible,
- runKey,
- status: "queued",
- });
- syncQueue();
- return;
- }
-
- const didRunKeyChange = existingItem.runKey !== runKey;
- const shouldRequeue = didRunKeyChange && existingItem.status === "done";
- const didChange =
- existingItem.priority !== priority ||
- existingItem.isEligible !== isEligible ||
- didRunKeyChange ||
- shouldRequeue;
-
- if (didChange) {
- existingItem.priority = priority;
- existingItem.isEligible = isEligible;
- existingItem.runKey = runKey;
- if (shouldRequeue) {
- existingItem.status = "queued";
- }
- setVersion((value) => value + 1);
- }
-
- syncQueue();
- },
- [syncQueue],
- );
-
- const unregister = useCallback(
- (id: string) => {
- const existing = itemsRef.current.get(id);
- if (!existing) return;
-
- itemsRef.current.delete(id);
- setVersion((value) => value + 1);
-
- if (existing.status === "running") {
- syncQueue();
- }
- },
- [syncQueue],
+}): DashboardQuerySchedulerStore => {
+ const [store] = useState(() =>
+ createDashboardQuerySchedulerStore({ maxConcurrent }),
);
- const markDone = useCallback(
- (id: string) => {
- const item = itemsRef.current.get(id);
- if (!item || item.status === "done") return;
-
- item.status = "done";
- setVersion((value) => value + 1);
- syncQueue();
- },
- [syncQueue],
- );
-
- const resetQueue = useCallback(() => {
- let changed = false;
-
- for (const item of itemsRef.current.values()) {
- if (item.status !== "queued") {
- item.status = "queued";
- changed = true;
- }
- }
-
- if (changed) {
- setVersion((value) => value + 1);
- }
-
- syncQueue();
- }, [syncQueue]);
-
- const canFetch = useCallback((id: string) => {
- const item = itemsRef.current.get(id);
- if (!item) return false;
- return item.status === "running";
- }, []);
-
useEffect(() => {
- syncQueue();
- }, [maxConcurrent, syncQueue]);
+ if (store.getState().maxConcurrent !== maxConcurrent) {
+ store.getState().actions.setMaxConcurrent(maxConcurrent);
+ }
+ }, [maxConcurrent, store]);
+ // Re-queue everything only when the key actually changes β€” never on mount.
+ const previousResetKeyRef = useRef<string | undefined>(resetKey);
useEffect(() => {
if (previousResetKeyRef.current === resetKey) return;
previousResetKeyRef.current = resetKey;
- resetQueue();
- }, [resetKey, resetQueue]);
+ store.getState().actions.resetQueue();
+ }, [resetKey, store]);
- return {
- register,
- unregister,
- canFetch,
- markDone,
- };
+ return store;
};
type DashboardQuerySchedulerContextValue = {
- scheduler: Pick<
- DashboardQuerySchedulerApi,
- "register" | "unregister" | "canFetch" | "markDone"
- >;
+ store: DashboardQuerySchedulerStore;
shouldBucketQueriesByTimeRange: boolean;
};
@@ -259,31 +127,17 @@ const DashboardQuerySchedulerContext =
createContext<DashboardQuerySchedulerContextValue | null>(null);
export const DashboardQuerySchedulerProvider = ({
- scheduler,
+ store,
shouldBucketQueriesByTimeRange = false,
children,
}: {
- scheduler: DashboardQuerySchedulerContextValue["scheduler"];
+ store: DashboardQuerySchedulerStore;
shouldBucketQueriesByTimeRange?: boolean;
children: ReactNode;
}) => {
const contextValue = useMemo(
- () => ({
- scheduler: {
- register: scheduler.register,
- unregister: scheduler.unregister,
- canFetch: scheduler.canFetch,
- markDone: scheduler.markDone,
- },
- shouldBucketQueriesByTimeRange,
- }),
- [
- scheduler.register,
- scheduler.unregister,
- scheduler.canFetch,
- scheduler.markDone,
- shouldBucketQueriesByTimeRange,
- ],
+ () => ({ store, shouldBucketQueriesByTimeRange }),
+ [store, shouldBucketQueriesByTimeRange],
);
return (
@@ -293,9 +147,15 @@ export const DashboardQuerySchedulerProvider = ({
);
};
-const useDashboardQuerySchedulerContext = () => {
- return useContext(DashboardQuerySchedulerContext);
-};
+// Surfaces without a provider (e.g. a single widget embedded outside a
+// dashboard) share one unmanaged store with an unlimited budget: every
+// registration is promoted immediately, so `canFetch` is effectively true.
+// Because it is shared module-wide, provider-less consumers must use
+// queryIds unique per mounted instance β€” a collision would let one
+// consumer's unmount unregister the other's slot.
+const unmanagedSchedulerStore = createDashboardQuerySchedulerStore({
+ maxConcurrent: Number.POSITIVE_INFINITY,
+});
type DashboardExecuteQueryInput = RouterInputs["dashboard"]["executeQuery"];
type DashboardExecuteQueryOutput = RouterOutputs["dashboard"]["executeQuery"];
@@ -440,12 +300,10 @@ export const useScheduledDashboardExecuteQuery = (
progress: QueryProgress | null;
error: string | null;
} => {
- const context = useDashboardQuerySchedulerContext();
+ const context = useContext(DashboardQuerySchedulerContext);
const utils = api.useUtils();
- const scheduler = context?.scheduler;
- const register = scheduler?.register;
- const unregister = scheduler?.unregister;
- const markDone = scheduler?.markDone;
+ const store = context?.store ?? unmanagedSchedulerStore;
+ const { actions } = store.getState();
const shouldBucketQueriesByTimeRange =
context?.shouldBucketQueriesByTimeRange ?? false;
const cachePolicy = useMemo(
@@ -473,18 +331,21 @@ export const useScheduledDashboardExecuteQuery = (
const { trpc, ...reactQueryOptions } = queryOptions;
useEffect(() => {
- if (!unregister) return;
return () => {
- unregister(queryId);
+ actions.unregister(queryId);
};
- }, [queryId, unregister]);
+ }, [queryId, actions]);
useEffect(() => {
- if (!register) return;
- register(queryId, priority, enabled, effectiveRunKey);
- }, [effectiveRunKey, enabled, priority, queryId, register]);
-
- const canFetch = scheduler ? scheduler.canFetch(queryId) : true;
+ actions.register(queryId, priority, enabled, effectiveRunKey);
+ }, [effectiveRunKey, enabled, priority, queryId, actions]);
+
+ // Reactive slot subscription: only this widget re-renders when its slot
+ // opens β€” never the page or its siblings.
+ const canFetch = useStore(
+ store,
+ (state) => state.items[queryId]?.status === "running",
+ );
// tRPC path (default)
const trpcResult = useQuery<DashboardExecuteQueryOutput, Error>({
@@ -503,26 +364,34 @@ export const useScheduledDashboardExecuteQuery = (
meta,
});
- // SSE path (opt-in)
+ // SSE path (opt-in) β€” same cache key as the tRPC path, so identical widgets
+ // share one stream and a transport flip reuses cached rows.
const sseResult = useSSEDashboardQuery(input, {
enabled: enabled && canFetch && useSSE,
- inputKey: effectiveRunKey,
- queryId,
+ queryKey: queryCacheKey,
+ staleTime:
+ typeof queryOptions.staleTime === "number"
+ ? queryOptions.staleTime
+ : cachePolicy.staleTime,
+ gcTime: queryOptions.gcTime ?? cachePolicy.gcTime,
+ meta,
});
const activeResult = useSSE ? sseResult : trpcResult;
+ // Release the scheduler slot whenever this query stops fetching for ANY
+ // reason β€” success, error, stall timeout, or abort. Holding a slot on a
+ // failed stream would freeze the whole dashboard at low concurrency.
useEffect(() => {
- if (!markDone) return;
if (!enabled || !canFetch) return;
if (activeResult.fetchStatus !== "idle") return;
if (activeResult.isPending) return;
- markDone(queryId);
+ actions.markDone(queryId);
}, [
canFetch,
enabled,
- markDone,
+ actions,
queryId,
activeResult.fetchStatus,
activeResult.isPending,
diff --git a/web/src/features/dashboard/stores/dashboardQuerySchedulerStore.ts b/web/src/features/dashboard/stores/dashboardQuerySchedulerStore.ts
new file mode 100644
index 0000000000..5ff20d261c
--- /dev/null
+++ b/web/src/features/dashboard/stores/dashboardQuerySchedulerStore.ts
@@ -0,0 +1,166 @@
+import { createStore, type StoreApi } from "zustand/vanilla";
+
+type SchedulerItemStatus = "queued" | "running" | "done";
+
+type SchedulerItem = {
+ id: string;
+ priority: number;
+ isEligible: boolean;
+ runKey: string;
+ status: SchedulerItemStatus;
+};
+
+type DashboardQuerySchedulerState = {
+ /** Immutable record β€” widgets subscribe to `items[id]?.status`. */
+ items: Record<string, SchedulerItem>;
+ maxConcurrent: number;
+ actions: {
+ register: (
+ id: string,
+ priority: number,
+ isEligible?: boolean,
+ runKey?: string,
+ ) => void;
+ unregister: (id: string) => void;
+ markDone: (id: string) => void;
+ /** Re-queues every item β€” only for genuine query-param changes (reset key). */
+ resetQueue: () => void;
+ setMaxConcurrent: (maxConcurrent: number) => void;
+ };
+};
+
+export type DashboardQuerySchedulerStore =
+ StoreApi<DashboardQuerySchedulerState>;
+
+// Promote queued eligible items (by ascending priority) into free running
+// slots. Returns the same reference when nothing changed so subscribers
+// don't wake up.
+const promote = (
+ items: Record<string, SchedulerItem>,
+ maxConcurrent: number,
+): Record<string, SchedulerItem> => {
+ let running = 0;
+ for (const item of Object.values(items)) {
+ if (item.status === "running") running += 1;
+ }
+ if (running >= maxConcurrent) return items;
+
+ const candidates = Object.values(items)
+ .filter((item) => item.status === "queued" && item.isEligible)
+ .sort((a, b) => a.priority - b.priority);
+ if (candidates.length === 0) return items;
+
+ const next = { ...items };
+ for (const candidate of candidates) {
+ if (running >= maxConcurrent) break;
+ next[candidate.id] = { ...candidate, status: "running" };
+ running += 1;
+ }
+ return next;
+};
+
+/**
+ * Per-mount scheduler for a dashboard's widget queries: widgets register,
+ * at most `maxConcurrent` run at once, the rest wait in priority order.
+ * Created by the page (lazy useState) and provided via context; widgets
+ * subscribe to their own item's status only, so a slot opening re-renders
+ * just the widget that got it β€” not the whole grid.
+ */
+export function createDashboardQuerySchedulerStore({
+ maxConcurrent,
+}: {
+ maxConcurrent: number;
+}): DashboardQuerySchedulerStore {
+ return createStore<DashboardQuerySchedulerState>((set) => ({
+ items: {},
+ maxConcurrent,
+ actions: {
+ register: (id, priority, isEligible = true, runKey = id) =>
+ set((state) => {
+ const existing = state.items[id];
+ if (!existing) {
+ const items = promote(
+ {
+ ...state.items,
+ [id]: { id, priority, isEligible, runKey, status: "queued" },
+ },
+ state.maxConcurrent,
+ );
+ return { items };
+ }
+
+ const didRunKeyChange = existing.runKey !== runKey;
+ // A changed run key re-queues a completed item (its inputs changed);
+ // queued/running items just carry the new key into their next run.
+ const shouldRequeue = didRunKeyChange && existing.status === "done";
+ const didChange =
+ existing.priority !== priority ||
+ existing.isEligible !== isEligible ||
+ didRunKeyChange;
+ if (!didChange) {
+ const items = promote(state.items, state.maxConcurrent);
+ return items === state.items ? state : { items };
+ }
+
+ const items = promote(
+ {
+ ...state.items,
+ [id]: {
+ ...existing,
+ priority,
+ isEligible,
+ runKey,
+ status: shouldRequeue ? "queued" : existing.status,
+ },
+ },
+ state.maxConcurrent,
+ );
+ return { items };
+ }),
+
+ unregister: (id) =>
+ set((state) => {
+ if (!state.items[id]) return state;
+ const { [id]: _removed, ...rest } = state.items;
+ return { items: promote(rest, state.maxConcurrent) };
+ }),
+
+ markDone: (id) =>
+ set((state) => {
+ const item = state.items[id];
+ if (!item || item.status === "done") return state;
+ return {
+ items: promote(
+ { ...state.items, [id]: { ...item, status: "done" } },
+ state.maxConcurrent,
+ ),
+ };
+ }),
+
+ resetQueue: () =>
+ set((state) => {
+ let changed = false;
+ const requeued: Record<string, SchedulerItem> = {};
+ for (const item of Object.values(state.items)) {
+ if (item.status !== "queued") {
+ requeued[item.id] = { ...item, status: "queued" };
+ changed = true;
+ } else {
+ requeued[item.id] = item;
+ }
+ }
+ if (!changed) {
+ const items = promote(state.items, state.maxConcurrent);
+ return items === state.items ? state : { items };
+ }
+ return { items: promote(requeued, state.maxConcurrent) };
+ }),
+
+ setMaxConcurrent: (maxConcurrent) =>
+ set((state) => ({
+ maxConcurrent,
+ items: promote(state.items, maxConcurrent),
+ })),
+ },
+ }));
+}
diff --git a/web/src/features/widgets/components/DashboardWidget.tsx b/web/src/features/widgets/components/DashboardWidget.tsx
index a64576ab17..9a1e70001d 100644
--- a/web/src/features/widgets/components/DashboardWidget.tsx
+++ b/web/src/features/widgets/components/DashboardWidget.tsx
@@ -63,7 +63,7 @@ import {
getChartLoadingStateProps,
} from "@/src/features/widgets/chart-library/chartLoadingStateUtils";
import { type ResolvedReadPath } from "@/src/features/events/hooks/useReadPath";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { CopyWidgetDialog } from "@/src/features/widgets/components/CopyWidgetDialog";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
import { Badge } from "@/src/components/ui/badge";
diff --git a/web/src/features/widgets/components/InlineWidget.tsx b/web/src/features/widgets/components/InlineWidget.tsx
index 900773cd4d..1cffdc8c11 100644
--- a/web/src/features/widgets/components/InlineWidget.tsx
+++ b/web/src/features/widgets/components/InlineWidget.tsx
@@ -7,7 +7,7 @@ import {
type ViewVersion,
getResultUnit,
} from "@langfuse/shared/query";
-import { useScheduledDashboardExecuteQuery } from "@/src/hooks/useDashboardQueryScheduler";
+import { useScheduledDashboardExecuteQuery } from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import { Chart } from "@/src/features/widgets/chart-library/Chart";
import { ChartLoadingState } from "@/src/features/widgets/chart-library/ChartLoadingState";
import {
diff --git a/web/src/hooks/useSSEDashboardQuery.ts b/web/src/hooks/useSSEDashboardQuery.ts
index de3db6a6bf..559ee45f6d 100644
--- a/web/src/hooks/useSSEDashboardQuery.ts
+++ b/web/src/hooks/useSSEDashboardQuery.ts
@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useState } from "react";
+import { hashKey, useQuery, type QueryKey } from "@tanstack/react-query";
import { type RouterInputs } from "@/src/utils/api";
import { env } from "@/src/env.mjs";
@@ -12,17 +13,14 @@ export type QueryProgress = {
percent: number;
};
-type SSEQueryStatus = "idle" | "loading" | "success" | "error";
-
type SSEQueryResult = {
data: Record<string, unknown>[] | undefined;
progress: QueryProgress | null;
- status: SSEQueryStatus;
isLoading: boolean;
isSuccess: boolean;
isError: boolean;
error: string | null;
- fetchStatus: "fetching" | "idle";
+ fetchStatus: "fetching" | "paused" | "idle";
isPending: boolean;
};
@@ -72,213 +70,226 @@ export function computeMonotonicPercent(
return Math.max(prevMax, rawPercent);
}
-export function useSSEDashboardQuery(
+// A stream that stops producing bytes for this long is dead β€” the server caps
+// query execution well below this, and progress events flow throughout.
+const SSE_STALL_TIMEOUT_MS = 60_000;
+
+/**
+ * Consumes one execute-query SSE stream to completion and returns its rows.
+ * Progress events go to the caller as a side channel (they are high-frequency
+ * and must stay out of the query cache). A stream that stalls (no bytes for
+ * `stallTimeoutMs`) is aborted and surfaces as a normal error β€” never as a
+ * forever-pending query holding a scheduler slot.
+ *
+ * Exported for tests; the hook below is the only production caller.
+ */
+export async function fetchDashboardSSERows(
input: DashboardExecuteQueryInput,
- options: {
- enabled?: boolean;
- inputKey?: string;
- queryId: string;
+ {
+ basePath,
+ signal,
+ onProgress,
+ stallTimeoutMs = SSE_STALL_TIMEOUT_MS,
+ }: {
+ basePath: string;
+ signal: AbortSignal;
+ onProgress: (progress: QueryProgress) => void;
+ stallTimeoutMs?: number;
},
-): SSEQueryResult {
- const { enabled = true, inputKey: inputKeyOverride } = options;
- const [data, setData] = useState<Record<string, unknown>[] | undefined>(
- undefined,
- );
- const [progress, setProgress] = useState<QueryProgress | null>(null);
- const [status, setStatus] = useState<SSEQueryStatus>("idle");
- const [error, setError] = useState<string | null>(null);
- const [stateInputKey, setStateInputKey] = useState<string | null>(null);
- const maxPercentRef = useRef(0);
- // Input key of the last run that produced a successful result currently held
- // in `data`. Used to keep-previous-data across a same-input re-run so an
- // already-rendered widget never blanks on a re-run it did not need (e.g. the
- // scheduler re-promoting an item). A genuine input change still clears.
- const lastSuccessfulInputKeyRef = useRef<string | null>(null);
- const basePath = env.NEXT_PUBLIC_BASE_PATH ?? "";
-
- // Stable reference for the input to avoid re-triggering on every render
- const inputRef = useRef(input);
- inputRef.current = input;
+): Promise<Record<string, unknown>[]> {
+ const controller = new AbortController();
+ const onOuterAbort = () => controller.abort();
+ if (signal.aborted) controller.abort();
+ signal.addEventListener("abort", onOuterAbort);
+
+ let stalled = false;
+ let watchdog: ReturnType<typeof setTimeout> | undefined;
+ const armWatchdog = () => {
+ clearTimeout(watchdog);
+ watchdog = setTimeout(() => {
+ stalled = true;
+ controller.abort();
+ }, stallTimeoutMs);
+ };
- const runQuery = useCallback(
- async (runInputKey: string, signal: AbortSignal) => {
- const isSameInputAsLastSuccess =
- lastSuccessfulInputKeyRef.current === runInputKey;
- setStateInputKey(runInputKey);
- setStatus("loading");
- setProgress(null);
- setError(null);
- // Keep the previously loaded rows when re-running the exact same query, so
- // the chart stays rendered instead of flashing empty; only clear when the
- // input actually changed (a genuinely new query).
- if (!isSameInputAsLastSuccess) {
- setData(undefined);
+ let maxPercent = 0;
+ const rows: Record<string, unknown>[] = [];
+
+ try {
+ armWatchdog();
+ const resp = await fetch(`${basePath}/api/dashboard/execute-query-stream`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(input),
+ signal: controller.signal,
+ });
+
+ if (!resp.ok) {
+ const body = await resp.text();
+ let message = `HTTP ${resp.status}`;
+ try {
+ const parsed = JSON.parse(body);
+ if (parsed.message) message = parsed.message;
+ } catch {
+ if (body) message = body;
}
- maxPercentRef.current = 0;
+ throw new Error(message);
+ }
- try {
- const resp = await fetch(
- `${basePath}/api/dashboard/execute-query-stream`,
- {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify(inputRef.current),
- signal,
- },
- );
+ if (!resp.body) {
+ throw new Error("No response body");
+ }
- if (!resp.ok) {
- const body = await resp.text();
- let message = `HTTP ${resp.status}`;
- try {
- const parsed = JSON.parse(body);
- if (parsed.message) message = parsed.message;
- } catch {
- if (body) message = body;
- }
- throw new Error(message);
+ const reader = resp.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = "";
+ let done: "success" | "error" | null = null;
+ let errorMessage = "";
+
+ const handleEvent = (event: SSEEvent) => {
+ if (done) return;
+ if (event.type === "progress") {
+ try {
+ const p = JSON.parse(event.data);
+ const readRows = Number(p.read_rows);
+ const totalRows = Number(p.total_rows_to_read);
+ maxPercent = computeMonotonicPercent(readRows, totalRows, maxPercent);
+ onProgress({
+ read_rows: readRows,
+ total_rows_to_read: totalRows,
+ elapsed_ns: Number(p.elapsed_ns),
+ read_bytes: Number(p.read_bytes),
+ percent: maxPercent,
+ });
+ } catch {
+ // Ignore malformed progress events
}
-
- if (!resp.body) {
- throw new Error("No response body");
+ } else if (event.type === "row") {
+ try {
+ rows.push(JSON.parse(event.data));
+ } catch {
+ // Ignore malformed row events
}
-
- const reader = resp.body.getReader();
- const decoder = new TextDecoder();
- let buffer = "";
- const rows: Record<string, unknown>[] = [];
- let terminated = false;
-
- const handleEvent = (event: SSEEvent) => {
- if (terminated) return;
- if (event.type === "progress") {
- try {
- const p = JSON.parse(event.data);
- const readRows = Number(p.read_rows);
- const totalRows = Number(p.total_rows_to_read);
- const percent = computeMonotonicPercent(
- readRows,
- totalRows,
- maxPercentRef.current,
- );
- maxPercentRef.current = percent;
-
- setProgress({
- read_rows: readRows,
- total_rows_to_read: totalRows,
- elapsed_ns: Number(p.elapsed_ns),
- read_bytes: Number(p.read_bytes),
- percent,
- });
- } catch {
- // Ignore malformed progress events
- }
- } else if (event.type === "row") {
- try {
- rows.push(JSON.parse(event.data));
- } catch {
- // Ignore malformed row events
- }
- } else if (event.type === "done") {
- setData(rows);
- setStatus("success");
- lastSuccessfulInputKeyRef.current = runInputKey;
- terminated = true;
- } else if (event.type === "error") {
- try {
- const err = JSON.parse(event.data);
- setError(err.message ?? "Unknown error");
- } catch {
- setError(event.data);
- }
- setStatus("error");
- // An errored re-run must not keep stale success rows behind the
- // error state (keep-previous-data applies to in-flight/success
- // only). lastSuccessfulInputKeyRef is intentionally left untouched.
- setData(undefined);
- terminated = true;
- }
- };
-
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
-
- buffer += decoder.decode(value, { stream: true });
- const { events, remaining } = parseSSEBuffer(buffer);
- buffer = remaining;
-
- for (const event of events) {
- handleEvent(event);
- }
+ } else if (event.type === "done") {
+ done = "success";
+ } else if (event.type === "error") {
+ try {
+ const err = JSON.parse(event.data);
+ errorMessage = err.message ?? "Unknown error";
+ } catch {
+ errorMessage = event.data;
}
+ done = "error";
+ }
+ };
- // Flush any remaining buffer (e.g. "done" event without trailing newline)
- if (!terminated && buffer.trim()) {
- const { events } = parseSSEBuffer(buffer + "\n\n");
- for (const event of events) {
- handleEvent(event);
- }
- }
+ while (!done) {
+ const { done: streamEnded, value } = await reader.read();
+ if (streamEnded) break;
+ armWatchdog();
- // Fallback if stream ended without a terminal event
- if (!terminated) {
- if (rows.length > 0) {
- setData(rows);
- setStatus("success");
- lastSuccessfulInputKeyRef.current = runInputKey;
- } else {
- setError("Stream ended unexpectedly");
- setStatus("error");
- setData(undefined);
- }
- }
- } catch (err) {
- if (signal.aborted) return;
- setError(err instanceof Error ? err.message : "Unknown error");
- setStatus("error");
- setData(undefined);
+ buffer += decoder.decode(value, { stream: true });
+ const { events, remaining } = parseSSEBuffer(buffer);
+ buffer = remaining;
+
+ for (const event of events) {
+ handleEvent(event);
}
- },
- [basePath],
- );
+ }
- // Derive a stable key from the input to detect changes
- const inputKey = inputKeyOverride ?? JSON.stringify(input);
+ // Flush any remaining buffer (e.g. "done" event without trailing newline)
+ if (!done && buffer.trim()) {
+ const { events } = parseSSEBuffer(buffer + "\n\n");
+ for (const event of events) {
+ handleEvent(event);
+ }
+ }
- useEffect(() => {
- if (!enabled) {
- setStatus((current) =>
- current === "success" || current === "error" ? current : "idle",
- );
- return;
+ if (done === "error") {
+ throw new Error(errorMessage);
+ }
+ // No terminal event = the stream was cut (server crash, proxy timeout).
+ // Partial rows must not land in the query cache as a fresh success and
+ // silently render an incomplete chart β€” fail visibly instead.
+ if (done !== "success") {
+ throw new Error("Stream ended unexpectedly");
+ }
+ return rows;
+ } catch (error) {
+ if (stalled) {
+ throw new Error("The query stream stalled and was aborted");
}
+ throw error;
+ } finally {
+ clearTimeout(watchdog);
+ signal.removeEventListener("abort", onOuterAbort);
+ }
+}
- const abortController = new AbortController();
- runQuery(inputKey, abortController.signal);
+/**
+ * SSE transport for a dashboard executeQuery, backed by the React Query
+ * cache: rows/status live in the cache under the SAME key as the tRPC
+ * transport, so identical widgets share one ClickHouse stream (dedupe), a
+ * transport flip reuses cached rows, and cache/gc policy applies uniformly.
+ * Only the high-frequency progress events stay out of the cache, as local
+ * state on the mount that initiated the fetch.
+ */
+export function useSSEDashboardQuery(
+ input: DashboardExecuteQueryInput,
+ options: {
+ enabled?: boolean;
+ queryKey: QueryKey;
+ staleTime: number;
+ gcTime: number;
+ meta?: Record<string, unknown>;
+ },
+): SSEQueryResult {
+ const { enabled = true, queryKey, staleTime, gcTime, meta } = options;
+ const basePath = env.NEXT_PUBLIC_BASE_PATH ?? "";
- return () => {
- abortController.abort();
- };
- }, [enabled, inputKey, runQuery]);
+ const [progress, setProgress] = useState<QueryProgress | null>(null);
+ // A new key is a new run: drop the previous run's progress in the same
+ // render instead of showing it over the fresh pending state.
+ const keyHash = hashKey(queryKey);
+ const [lastKeyHash, setLastKeyHash] = useState(keyHash);
+ if (lastKeyHash !== keyHash) {
+ setLastKeyHash(keyHash);
+ setProgress(null);
+ }
- const hasCurrentState = stateInputKey === inputKey;
- const shouldHidePreviousRunState = enabled && !hasCurrentState;
- const isPendingForCurrentRun =
- enabled &&
- (status === "idle" || status === "loading" || shouldHidePreviousRunState);
- const effectiveStatus = isPendingForCurrentRun ? "loading" : status;
+ const query = useQuery<Record<string, unknown>[], Error>({
+ queryKey,
+ queryFn: async ({ signal }) => {
+ setProgress(null);
+ return fetchDashboardSSERows(input, {
+ basePath,
+ signal,
+ onProgress: setProgress,
+ });
+ },
+ enabled,
+ staleTime,
+ gcTime,
+ // A failed stream must fail visibly (inline widget error + released
+ // scheduler slot), not silently re-run a heavy ClickHouse query.
+ retry: false,
+ refetchOnWindowFocus: false,
+ refetchOnReconnect: false,
+ refetchOnMount: false,
+ // The widget owns the error UX; the global toast handler stays silent.
+ meta: { ...meta, silentAllErrors: true },
+ });
return {
- data: shouldHidePreviousRunState ? undefined : data,
- progress: shouldHidePreviousRunState ? null : progress,
- status: effectiveStatus,
- isLoading: effectiveStatus === "loading",
- isSuccess: effectiveStatus === "success",
- isError: effectiveStatus === "error",
- error: shouldHidePreviousRunState ? null : error,
- // Compatibility with existing scheduler expectations
- fetchStatus: isPendingForCurrentRun ? "fetching" : "idle",
- isPending: isPendingForCurrentRun,
+ // An errored re-run must not keep stale success rows behind the error
+ // state (keep-previous-data applies to in-flight/success only).
+ data: query.isError ? undefined : query.data,
+ progress: query.isError ? null : progress,
+ isLoading: query.isLoading,
+ isSuccess: query.isSuccess,
+ isError: query.isError,
+ error: query.error ? query.error.message : null,
+ fetchStatus: query.fetchStatus,
+ isPending: query.isPending,
};
}
diff --git a/web/src/pages/api/dashboard/execute-query-stream.ts b/web/src/pages/api/dashboard/execute-query-stream.ts
index 25154ac2fa..19b5f9df11 100644
--- a/web/src/pages/api/dashboard/execute-query-stream.ts
+++ b/web/src/pages/api/dashboard/execute-query-stream.ts
@@ -129,8 +129,18 @@ export default async function handler(
});
res.flushHeaders();
+ // A closed client should also stop the ClickHouse query, not just this
+ // response: the `break` below tears down the CH stream (its socket closes
+ // within one progress event), and cancel_http_readonly_queries_on_client_close
+ // makes ClickHouse kill the query on that close instead of running the
+ // abandoned aggregation to completion. max_execution_time still bounds the
+ // stragglers either way.
let aborted = false;
- req.on("close", () => {
+ // `res`, not `req`: the request stream can end once the POST body is
+ // consumed, while the response lives for the whole stream β€” its close
+ // fires on a client disconnect mid-stream (and only after res.end() on
+ // the happy path, where the loop has already finished).
+ res.on("close", () => {
aborted = true;
});
@@ -145,7 +155,13 @@ export default async function handler(
for await (const event of queryClickhouseWithProgress<
Record<string, unknown>
- >(chOpts)) {
+ >({
+ ...chOpts,
+ clickhouseSettings: {
+ ...chOpts.clickhouseSettings,
+ cancel_http_readonly_queries_on_client_close: 1,
+ },
+ })) {
if (aborted) break;
if (isProgressRow(event)) {
diff --git a/web/src/pages/project/[projectId]/dashboards/[dashboardId]/index.tsx b/web/src/pages/project/[projectId]/dashboards/[dashboardId]/index.tsx
index 959527d9ea..3551bbd7ca 100644
--- a/web/src/pages/project/[projectId]/dashboards/[dashboardId]/index.tsx
+++ b/web/src/pages/project/[projectId]/dashboards/[dashboardId]/index.tsx
@@ -66,7 +66,7 @@ import {
getDashboardQuerySchedulerMaxConcurrent,
getDashboardSchedulerResetKey,
useDashboardQueryScheduler,
-} from "@/src/hooks/useDashboardQueryScheduler";
+} from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import {
parsePastedWidget,
toWidgetCreateFields,
@@ -1153,14 +1153,14 @@ function DashboardDetailView({ readPath }: { readPath: ResolvedReadPath }) {
],
);
- const scheduler = useDashboardQueryScheduler({
+ const schedulerStore = useDashboardQueryScheduler({
maxConcurrent: getDashboardQuerySchedulerMaxConcurrent(timeRange),
resetKey: schedulerResetKey,
});
return (
<DashboardQuerySchedulerProvider
- scheduler={scheduler}
+ store={schedulerStore}
shouldBucketQueriesByTimeRange={!("from" in timeRange)}
>
<Page
diff --git a/web/src/pages/project/[projectId]/index.tsx b/web/src/pages/project/[projectId]/index.tsx
index ad4d4a47bb..dfd265f7f3 100644
--- a/web/src/pages/project/[projectId]/index.tsx
+++ b/web/src/pages/project/[projectId]/index.tsx
@@ -38,7 +38,7 @@ import {
DashboardQuerySchedulerProvider,
getDashboardQuerySchedulerMaxConcurrent,
useDashboardQueryScheduler,
-} from "@/src/hooks/useDashboardQueryScheduler";
+} from "@/src/features/dashboard/hooks/useDashboardQueryScheduler";
import Link from "next/link";
import { PencilIcon } from "lucide-react";
import { showErrorToast } from "@/src/features/notifications/showErrorToast";
@@ -271,14 +271,14 @@ function HomeDashboard({ readPath }: { readPath: ResolvedReadPath }) {
userFilterState,
]);
- const scheduler = useDashboardQueryScheduler({
+ const schedulerStore = useDashboardQueryScheduler({
maxConcurrent: getDashboardQuerySchedulerMaxConcurrent(timeRange),
resetKey: schedulerResetKey,
});
return (
<DashboardQuerySchedulerProvider
- scheduler={scheduler}
+ store={schedulerStore}
shouldBucketQueriesByTimeRange={!("from" in timeRange)}
>
<Page
diff --git a/web/src/utils/api.ts b/web/src/utils/api.ts
index eceb31fc51..748aef7447 100644
--- a/web/src/utils/api.ts
+++ b/web/src/utils/api.ts
@@ -452,6 +452,20 @@ const handleTrpcError = (error: unknown, shouldSilenceError = false) => {
},
});
}
+ } else if (shouldSilenceError) {
+ // A silenced non-tRPC query error β€” the surface owns the error UX
+ // end-to-end (meta silentAllErrors, e.g. the SSE dashboard transport:
+ // stall aborts and stream failures render inline per widget, and genuine
+ // server failures are logged server-side). Breadcrumb, not capture.
+ addBreadcrumb({
+ category: "trpc",
+ type: "http",
+ level: "warning",
+ message: "Suppressed silenced non-tRPC query error (not sent to Sentry)",
+ data: {
+ message: error instanceof Error ? error.message : String(error),
+ },
+ });
} else {
// For non-TRPC errors, still send to Sentry (coerced to a real Error).
reportError(error, { area: "trpc" });
@@ -602,6 +616,12 @@ const shouldSilenceError = (
return true;
}
+ // For queries whose surface owns the error UX entirely (e.g. a widget's
+ // inline error state) β€” non-HTTP errors carry no status to match against.
+ if (meta?.silentAllErrors === true) {
+ return true;
+ }
+
if (Array.isArray(meta?.silentHttpCodes)) {
const httpStatus = getHttpStatus(error);
return (