πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
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.tsindex 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.mdnew file mode 100644index 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.tsxindex 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/dashbimport { 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 whendiff --git a/web/src/features/dashboard/components/TracesTimeSeriesChart.tsx b/web/src/features/dashboard/components/TracesTimeSeriesChart.tsxindex 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.tsxindex 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 listdiff --git a/web/src/features/dashboard/components/hooks.ts b/web/src/features/dashboard/components/hooks.tsindex 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.tsxindex 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.tsxindex 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.tssimilarity index 58%rename from web/src/hooks/useDashboardQueryScheduler.clienttest.tsrename to web/src/features/dashboard/hooks/useDashboardQueryScheduler.clienttest.tsindex 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.tsxsimilarity index 64%rename from web/src/hooks/useDashboardQueryScheduler.tsxrename to web/src/features/dashboard/hooks/useDashboardQueryScheduler.tsxindex 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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)}><Pagediff --git a/web/src/pages/project/[projectId]/index.tsx b/web/src/pages/project/[projectId]/index.tsxindex 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)}><Pagediff --git a/web/src/utils/api.ts b/web/src/utils/api.tsindex 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 (