🪢 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(web): cache v4 SDK usage checks in Redis (#16163)
Max Deichmannbf78bcefd23f
diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.tsindex 50bfa8753b..83a3b80195 100644--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts@@ -8,6 +8,18 @@ vi.mock("@/src/server/auth", () => ({getServerAuthSession: vi.fn(),}));+/**+ * Mutable Redis stub shared with the mocked "@langfuse/shared/src/server"+ * barrel. Defaults to status "end" (cache unavailable, direct-query mode);+ * cache tests flip status to "ready" and stub mget/setex.+ */+const redisMock = vi.hoisted(() => ({+ status: "end" as string,+ disconnect: vi.fn(),+ mget: vi.fn(),+ setex: vi.fn(),+}));+const sharedServerMock = vi.hoisted(() => ({queryClickhouse: vi.fn(),isForceV3ExperienceProject: vi.fn(() => false),@@ -119,10 +131,7 @@ vi.mock("@langfuse/shared/src/server", async () => {warn: vi.fn(),error: vi.fn(),},- redis: {- status: "end",- disconnect: vi.fn(),- },+ redis: redisMock,ClickHouseClientManager: {getInstance: () => ({closeAllConnections: vi.fn(),@@ -376,8 +385,41 @@ const accessibleProjectsFindManyArgs = {},};+// The server computes its own detection window from "now" (hour-aligned);+// tests pin the clock so query params and trimming are deterministic.+const TEST_NOW = new Date("2026-06-25T00:30:00Z");+const HOT_START_ISO = "2026-06-25T00:00:00.000Z";+const HOT_START_CLICKHOUSE = "2026-06-25 00:00:00.000";+const WINDOW_END_CLICKHOUSE = "2026-06-25 01:00:00.000";+const WINDOW_START_CLICKHOUSE = "2026-06-11 01:00:00.000";+// Recent SDK gap cutoff: TEST_NOW floored to the minute (zero+// seconds/millis) so repeated calls within the minute share one ClickHouse+// query-cache key.+const RECENT_CUTOFF_CLICKHOUSE = "2026-06-25 00:30:00.000";++const sdkUsageCacheKey = `langfuse:v4:sdk-usage:v1:${projectId}`;++/** In-memory Redis fake: mget/setex against a Map, status "ready". */+const enableRedisCache = (initialEntries: Record<string, string> = {}) => {+ const store = new Map<string, string>(Object.entries(initialEntries));+ redisMock.status = "ready";+ redisMock.mget.mockImplementation(async (keys: string[]) =>+ keys.map((key) => store.get(key) ?? null),+ );+ redisMock.setex.mockImplementation(+ async (key: string, _ttlSeconds: number, value: string) => {+ store.set(key, value);+ return "OK";+ },+ );+ return store;+};+describe("v4TransitionRouter", () => {beforeEach(() => {+ vi.useFakeTimers({ toFake: ["Date"] });+ vi.setSystemTime(TEST_NOW);+ redisMock.status = "end";sharedEnvMock.CLICKHOUSE_READ_ONLY_URL ="https://clickhouse-read.example.com";sharedEnvMock.CLICKHOUSE_EVENTS_READ_ONLY_URL =@@ -393,6 +435,7 @@ describe("v4TransitionRouter", () => {});afterEach(() => {+ vi.useRealTimers();vi.clearAllMocks();});@@ -424,8 +467,6 @@ describe("v4TransitionRouter", () => {const rows = await caller.legacyApiUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(rows).toEqual([@@ -532,28 +573,12 @@ describe("v4TransitionRouter", () => {);});- it("rejects ranges over 30 days", async () => {- const caller = createCaller();-- await expect(- caller.legacyApiUsageSummary({- projectId,- fromTimestamp: new Date("2026-05-25T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),- }),- ).rejects.toThrow("30 days");-- expect(mockedQueryClickhouse).not.toHaveBeenCalled();- });-it("queries the main service once when no separate read replica is configured", async () => {sharedEnvMock.CLICKHOUSE_READ_ONLY_URL = sharedEnvMock.CLICKHOUSE_URL;const caller = createCaller();await caller.legacyApiUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(mockedQueryClickhouse).toHaveBeenCalledTimes(1);@@ -578,8 +603,6 @@ describe("v4TransitionRouter", () => {await expect(caller.legacyApiUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),}),).resolves.toEqual([{@@ -616,8 +639,6 @@ describe("v4TransitionRouter", () => {await expect(caller.legacyApiUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),}),).resolves.toEqual([{@@ -647,8 +668,6 @@ describe("v4TransitionRouter", () => {const summary = await caller.sdkUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary).toMatchObject({@@ -678,18 +697,13 @@ describe("v4TransitionRouter", () => {it("rejects project summaries outside the caller session", async () => {const caller = createCaller();- const range = {- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),- };await expect(- caller.sdkUsageSummary({ projectId: outsideProjectId, ...range }),+ caller.sdkUsageSummary({ projectId: outsideProjectId }),).rejects.toThrow("User is not a member of this project");await expect(caller.legacyApiUsageSummary({projectId: outsideProjectId,- ...range,}),).rejects.toThrow("User is not a member of this project");expect(mockedQueryClickhouse).not.toHaveBeenCalled();@@ -991,8 +1005,6 @@ describe("v4TransitionRouter", () => {createSessionWithOrgRole("OWNER"),).sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),}),).resolves.toEqual([]);@@ -1018,8 +1030,6 @@ describe("v4TransitionRouter", () => {createSessionWithOrgRole("ADMIN"),).sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),}),).resolves.toEqual([]);});@@ -1189,8 +1199,6 @@ describe("v4TransitionRouter", () => {const rows = await caller.sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(rows).toEqual([@@ -1200,41 +1208,44 @@ describe("v4TransitionRouter", () => {status: "sdk_usage_inconclusive",upgradePath: "sdk",},+ // Most recently seen first: the server re-sorts after merging cached+ // and live series.sdkUsageSeries: [{source: "ingestion-api-dual-write",ingestionPath: "ingestion_api",deliveryMode: "delayed",sdkName: "python",- sdkVersion: "3.9.0",+ sdkVersion: "4.7.0",canonicalSdkName: "python",- sdkVersionMajor: 3,+ sdkVersionMajor: 4,latestSdkMajor: 4,isValidSdkVersion: true,- publicKey: "pk-lf-python",- eventCount: 8,- firstSeen: "2026-06-24T01:00:00Z",- lastSeen: "2026-06-24T02:00:00Z",+ publicKey: "pk-lf-current-python",+ eventCount: 6,+ firstSeen: "2026-06-24T13:30:00Z",+ lastSeen: "2026-06-24T14:00:00Z",attributionStatus: "attributed",- v4MigrationStatus: "upgrade_required",+ v4MigrationStatus: "compatible",remediationType: "update_sdk",- actionLevel: "required",+ actionLevel: "none",},{source: "ingestion-api-dual-write",ingestionPath: "ingestion_api",deliveryMode: "delayed",sdkName: "python",- sdkVersion: "4.14.1",+ sdkVersion: "4.6.9",canonicalSdkName: "python",sdkVersionMajor: 4,latestSdkMajor: 4,isValidSdkVersion: true,- publicKey: "pk-lf-python",- eventCount: 13,- firstSeen: "2026-06-24T03:00:00Z",- lastSeen: "2026-06-24T04:00:00Z",+ publicKey: "pk-lf-pre-v4-python",+ eventCount: 5,+ firstSeen: "2026-06-24T12:00:00Z",+ lastSeen: "2026-06-24T13:00:00Z",attributionStatus: "attributed",+ // Latest-major semantics: current major is compatible (no minor advice).v4MigrationStatus: "compatible",remediationType: "update_sdk",actionLevel: "none",@@ -1244,17 +1255,16 @@ describe("v4TransitionRouter", () => {ingestionPath: "ingestion_api",deliveryMode: "delayed",sdkName: "python",- sdkVersion: "4.6.9",+ sdkVersion: "4.14.1",canonicalSdkName: "python",sdkVersionMajor: 4,latestSdkMajor: 4,isValidSdkVersion: true,- publicKey: "pk-lf-pre-v4-python",- eventCount: 5,- firstSeen: "2026-06-24T12:00:00Z",- lastSeen: "2026-06-24T13:00:00Z",+ publicKey: "pk-lf-python",+ eventCount: 13,+ firstSeen: "2026-06-24T03:00:00Z",+ lastSeen: "2026-06-24T04:00:00Z",attributionStatus: "attributed",- // Latest-major semantics: current major is compatible (no minor advice).v4MigrationStatus: "compatible",remediationType: "update_sdk",actionLevel: "none",@@ -1264,19 +1274,19 @@ describe("v4TransitionRouter", () => {ingestionPath: "ingestion_api",deliveryMode: "delayed",sdkName: "python",- sdkVersion: "4.7.0",+ sdkVersion: "3.9.0",canonicalSdkName: "python",- sdkVersionMajor: 4,+ sdkVersionMajor: 3,latestSdkMajor: 4,isValidSdkVersion: true,- publicKey: "pk-lf-current-python",- eventCount: 6,- firstSeen: "2026-06-24T13:30:00Z",- lastSeen: "2026-06-24T14:00:00Z",+ publicKey: "pk-lf-python",+ eventCount: 8,+ firstSeen: "2026-06-24T01:00:00Z",+ lastSeen: "2026-06-24T02:00:00Z",attributionStatus: "attributed",- v4MigrationStatus: "compatible",+ v4MigrationStatus: "upgrade_required",remediationType: "update_sdk",- actionLevel: "none",+ actionLevel: "required",},],},@@ -1388,13 +1398,17 @@ describe("v4TransitionRouter", () => {expect(usageQuery?.query).not.toContain("toDate(timestamp)");expect(usageQuery?.params).toMatchObject({projectIds: [projectId, secondProjectId],- fromTimestamp: "2026-06-24 00:00:00.000",- toTimestamp: "2026-06-25 00:00:00.000",+ fromTimestamp: WINDOW_START_CLICKHOUSE,+ toTimestamp: RECENT_CUTOFF_CLICKHOUSE,ingressSources: ["ingestion-api-dual-write", "otel-dual-write", "otel"],});expect(usageQuery?.tags).toEqual({route: "v4-sdk-usage-summary",});+ expect(usageQuery?.clickhouseSettings).toEqual({+ use_query_cache: 1,+ query_cache_ttl: 300,+ });const experimentUsageQuery = mockedQueryClickhouse.mock.calls[1]?.[0];expect(experimentUsageQuery?.query).toContain(@@ -1409,12 +1423,16 @@ describe("v4TransitionRouter", () => {expect(experimentUsageQuery?.query).not.toContain("hostName()");expect(experimentUsageQuery?.params).toMatchObject({projectIds: [projectId, secondProjectId],- fromTimestamp: "2026-06-24 00:00:00.000",- toTimestamp: "2026-06-25 00:00:00.000",+ fromTimestamp: WINDOW_START_CLICKHOUSE,+ toTimestamp: WINDOW_END_CLICKHOUSE,});expect(experimentUsageQuery?.tags).toEqual({route: "v4-experiment-instrumentation-summary",});+ // The query_log-backed experiment check must not enable the query cache.+ expect(+ experimentUsageQuery?.clickhouseSettings?.use_query_cache,+ ).toBeUndefined();});it("finds dataset-run-items POST usage when only the main service has it", async () => {@@ -1439,8 +1457,6 @@ describe("v4TransitionRouter", () => {const [summary] = await caller.sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary?.experimentInstrumentationMigration).toEqual({@@ -1475,8 +1491,6 @@ describe("v4TransitionRouter", () => {const summary = await caller.sdkUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary).toMatchObject({@@ -1559,21 +1573,20 @@ describe("v4TransitionRouter", () => {const summary = await caller.sdkUsageSummary({projectId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});+ // Sorted by lastSeen descending after the merge step.expect(summary.sdkUsageSeries).toEqual([- expect.objectContaining({- source: "otel-dual-write",- remediationType: "update_otel_instrumentation",- eventCount: 3,- }),expect.objectContaining({source: "ingestion-api-dual-write",remediationType: "upgrade_instrumentation",eventCount: 2,}),+ expect.objectContaining({+ source: "otel-dual-write",+ remediationType: "update_otel_instrumentation",+ eventCount: 3,+ }),]);const usageQuery = mockedQueryClickhouse.mock.calls[0]?.[0];@@ -1615,8 +1628,6 @@ describe("v4TransitionRouter", () => {const [summary] = await caller.sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary).toMatchObject({@@ -1650,8 +1661,6 @@ describe("v4TransitionRouter", () => {const [summary] = await caller.sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary).toMatchObject({@@ -1694,8 +1703,6 @@ describe("v4TransitionRouter", () => {const [summary] = await caller.sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary?.experimentInstrumentationMigration).toEqual({@@ -1726,8 +1733,6 @@ describe("v4TransitionRouter", () => {const [summary] = await caller.sdkUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(summary?.experimentInstrumentationMigration).toEqual({@@ -1778,8 +1783,6 @@ describe("v4TransitionRouter", () => {const rows = await caller.legacyApiUsageSummaryByProject({orgId,- fromTimestamp: new Date("2026-06-24T00:00:00Z"),- toTimestamp: new Date("2026-06-25T00:00:00Z"),});expect(rows).toEqual([@@ -1830,4 +1833,379 @@ describe("v4TransitionRouter", () => {preferredClickhouseService: "ReadWrite",});});++ describe("redis caching", () => {+ /** Series entry as stored in the SDK usage cache blob (numbers, not SQL strings). */+ const cachedSdkSeries = (+ overrides: Partial<{+ sdkVersion: string;+ publicKey: string;+ v4MigrationStatus: "compatible" | "upgrade_required" | "unknown";+ actionLevel: "required" | "none";+ eventCount: number;+ firstSeen: string;+ lastSeen: string;+ }> = {},+ ) => ({+ source: "ingestion-api-dual-write" as const,+ ingestionPath: "ingestion_api" as const,+ deliveryMode: "delayed" as const,+ sdkName: "python",+ sdkVersion: "3.9.0",+ canonicalSdkName: "python" as const,+ sdkVersionMajor: 3,+ latestSdkMajor: 4,+ isValidSdkVersion: true,+ attributionStatus: "attributed" as const,+ publicKey: "pk-lf-python",+ v4MigrationStatus: "upgrade_required" as const,+ remediationType: "update_sdk" as const,+ actionLevel: "required" as const,+ eventCount: 5,+ firstSeen: "2026-06-20T01:00:00Z",+ lastSeen: "2026-06-24T10:00:00Z",+ ...overrides,+ });++ const sdkUsageBlob = (series: unknown[], hotStart = HOT_START_ISO) =>+ JSON.stringify({+ version: 1,+ computedAt: "2026-06-25T00:00:00.000Z",+ hotStart,+ series,+ });++ it("splits SDK usage into a cached-historical and a live-gap query on cache miss", async () => {+ enableRedisCache();+ const historicalRow = mockSdkUsageRow({+ projectId,+ sdkName: "python",+ sdkVersion: "3.9.0",+ publicKey: "pk-lf-python",+ eventCount: "5",+ firstSeen: "2026-06-20T01:00:00Z",+ lastSeen: "2026-06-24T10:00:00Z",+ });+ const gapRow = mockSdkUsageRow({+ projectId,+ sdkName: "python",+ sdkVersion: "3.9.0",+ publicKey: "pk-lf-python",+ eventCount: "2",+ firstSeen: "2026-06-25T00:05:00Z",+ lastSeen: "2026-06-25T00:15:00Z",+ });+ mockedQueryClickhouse.mockImplementation(async (args) => {+ // SDK path also fans out a query_log experiment-POST check; only+ // events_core participates in the history/gap split under test.+ if (!args.query.includes("FROM events_core")) return [];+ return (args.params?.toTimestamp as string) === HOT_START_CLICKHOUSE+ ? [historicalRow]+ : [gapRow];+ });+ const caller = createCaller();++ const summary = await caller.sdkUsageSummary({+ projectId,+ });++ // One merged series: counts add, seen-range unions across the boundary.+ expect(summary.sdkUsageSeries).toEqual([+ expect.objectContaining({+ sdkVersion: "3.9.0",+ eventCount: 7,+ firstSeen: "2026-06-20T01:00:00Z",+ lastSeen: "2026-06-25T00:15:00Z",+ }),+ ]);++ const eventsCoreCalls = mockedQueryClickhouse.mock.calls.filter(+ ([args]) => args.query.includes("FROM events_core"),+ );+ expect(eventsCoreCalls).toHaveLength(2);+ const [historicalCall] = eventsCoreCalls.filter(+ ([args]) => args.params?.toTimestamp === HOT_START_CLICKHOUSE,+ );+ const [gapCall] = eventsCoreCalls.filter(+ ([args]) => args.params?.toTimestamp === RECENT_CUTOFF_CLICKHOUSE,+ );+ // Half-open boundary: an event exactly at hotStart lands only in the+ // live gap query.+ expect(historicalCall?.[0].query).toContain(+ "AND start_time < {toTimestamp: DateTime64(3)}",+ );+ expect(historicalCall?.[0].params).toMatchObject({+ fromTimestamp: WINDOW_START_CLICKHOUSE,+ });+ expect(gapCall?.[0].query).toContain(+ "AND start_time <= {toTimestamp: DateTime64(3)}",+ );+ expect(gapCall?.[0].params).toMatchObject({+ fromTimestamp: HOT_START_CLICKHOUSE,+ toTimestamp: RECENT_CUTOFF_CLICKHOUSE,+ });+ // Both events_core SELECTs opt into the ClickHouse query cache; the+ // minute-aligned cutoff keeps their AST identical within a minute.+ for (const [args] of eventsCoreCalls) {+ expect(args.clickhouseSettings).toEqual({+ use_query_cache: 1,+ query_cache_ttl: 300,+ });+ }++ // Only the historical SDK slice is cached (1h TTL); the gap stays live.+ // query_log experiment usage is not Redis-cached in this PR.+ expect(redisMock.setex).toHaveBeenCalledTimes(1);+ const sdkWrite = redisMock.setex.mock.calls.find(+ ([key]) => key === sdkUsageCacheKey,+ );+ expect(sdkWrite?.[1]).toBe(60 * 60);+ expect(JSON.parse(sdkWrite?.[2] as string)).toMatchObject({+ version: 1,+ hotStart: HOT_START_ISO,+ series: [expect.objectContaining({ eventCount: 5 })],+ });+ });++ it("serves cached SDK history with a live gap query on cache hit", async () => {+ enableRedisCache({+ [sdkUsageCacheKey]: sdkUsageBlob([cachedSdkSeries()]),+ });+ mockedQueryClickhouse.mockImplementation(async (args) => {+ if (!args.query.includes("FROM events_core")) return [];+ return [+ mockSdkUsageRow({+ projectId,+ sdkName: "python",+ sdkVersion: "3.9.0",+ publicKey: "pk-lf-python",+ eventCount: "2",+ firstSeen: "2026-06-25T00:05:00Z",+ lastSeen: "2026-06-25T00:15:00Z",+ }),+ ];+ });+ const caller = createCaller();++ const summary = await caller.sdkUsageSummary({+ projectId,+ });++ expect(summary.sdkUsageSeries).toEqual([+ expect.objectContaining({+ sdkVersion: "3.9.0",+ eventCount: 7,+ firstSeen: "2026-06-20T01:00:00Z",+ lastSeen: "2026-06-25T00:15:00Z",+ }),+ ]);+ // No dataset-run-items POST usage in the uncached query_log check.+ expect(summary.experimentInstrumentationMigration).toEqual({+ status: "not_required",+ upgradePath: null,+ });++ const eventsCoreCalls = mockedQueryClickhouse.mock.calls.filter(+ ([args]) => args.query.includes("FROM events_core"),+ );+ expect(eventsCoreCalls).toHaveLength(1);+ expect(eventsCoreCalls[0]?.[0].params).toMatchObject({+ fromTimestamp: HOT_START_CLICKHOUSE,+ toTimestamp: RECENT_CUTOFF_CLICKHOUSE,+ });+ expect(redisMock.setex).not.toHaveBeenCalled();+ });++ it("drops cached SDK series that aged out of the 14-day window", async () => {+ enableRedisCache({+ [sdkUsageCacheKey]: sdkUsageBlob([+ cachedSdkSeries(),+ cachedSdkSeries({+ sdkVersion: "2.0.0",+ // Older than now - 14d (2026-06-11T00:30Z): trimmed at read time.+ firstSeen: "2026-06-08T00:00:00Z",+ lastSeen: "2026-06-10T00:00:00Z",+ }),+ ]),+ });+ mockedQueryClickhouse.mockImplementation(async (args) => {+ if (!args.query.includes("FROM events_core")) return [];+ return [];+ });+ const caller = createCaller();++ const summary = await caller.sdkUsageSummary({+ projectId,+ });++ expect(summary.sdkUsageSeries).toEqual([+ expect.objectContaining({ sdkVersion: "3.9.0" }),+ ]);+ });++ it("treats blobs with corrupt JSON as cache misses", async () => {+ enableRedisCache({+ [sdkUsageCacheKey]: "not-json",+ });+ mockedQueryClickhouse.mockImplementation(async (args) => {+ if (!args.query.includes("FROM events_core")) return [];+ return [];+ });+ const caller = createCaller();++ await caller.sdkUsageSummary({+ projectId,+ });++ // Historical refill plus live gap, both against events_core.+ const eventsCoreCalls = mockedQueryClickhouse.mock.calls.filter(+ ([args]) => args.query.includes("FROM events_core"),+ );+ expect(eventsCoreCalls).toHaveLength(2);+ expect(+ redisMock.setex.mock.calls.some(([key]) => key === sdkUsageCacheKey),+ ).toBe(true);+ });++ describe("migrationActions", () => {+ const mockPrismaForActions = ({+ evalCount = 0,+ }: { evalCount?: number } = {}) => ({+ jobConfiguration: {+ groupBy: vi+ .fn()+ .mockResolvedValue(+ evalCount > 0 ? [{ projectId, _count: { _all: evalCount } }] : [],+ ),+ },+ posthogIntegration: { findMany: vi.fn().mockResolvedValue([]) },+ mixpanelIntegration: { findMany: vi.fn().mockResolvedValue([]) },+ blobStorageIntegration: { findMany: vi.fn().mockResolvedValue([]) },+ });++ it("on cold cache, runs history+gap queries, writes back, and derives the SDK flag", async () => {+ enableRedisCache();+ mockedQueryClickhouse.mockImplementation(async (args) => {+ if (!args.query.includes("FROM events_core")) return [];+ return (args.params?.toTimestamp as string) === HOT_START_CLICKHOUSE+ ? [+ mockSdkUsageRow({+ projectId,+ sdkName: "python",+ sdkVersion: "3.9.0",+ publicKey: "pk-lf-python",+ eventCount: "5",+ firstSeen: "2026-06-20T01:00:00Z",+ lastSeen: "2026-06-24T10:00:00Z",+ }),+ ]+ : [];+ });+ const caller = createCaller(mockPrismaForActions());++ await expect(caller.migrationActions({ projectId })).resolves.toEqual({+ forceV3Experience: false,+ sdkActionNeeded: true,+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ evalsActionNeeded: false,+ exportsActionNeeded: false,+ });++ const eventsCoreCalls = mockedQueryClickhouse.mock.calls.filter(+ ([args]) => args.query.includes("FROM events_core"),+ );+ expect(eventsCoreCalls).toHaveLength(2);+ expect(+ redisMock.setex.mock.calls.some(([key]) => key === sdkUsageCacheKey),+ ).toBe(true);+ });++ it("on cache hit, runs the live gap query and merges for the SDK flag", async () => {+ enableRedisCache({+ [sdkUsageCacheKey]: sdkUsageBlob([+ cachedSdkSeries({ actionLevel: "required" }),+ ]),+ });+ mockedQueryClickhouse.mockImplementation(async (args) => {+ if (!args.query.includes("FROM events_core")) return [];+ return [];+ });+ const caller = createCaller(mockPrismaForActions({ evalCount: 2 }));++ await expect(caller.migrationActions({ projectId })).resolves.toEqual({+ forceV3Experience: false,+ sdkActionNeeded: true,+ // query_log-backed categories stay unknown until the follow-up PR.+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ evalsActionNeeded: true,+ exportsActionNeeded: false,+ });++ const eventsCoreCalls = mockedQueryClickhouse.mock.calls.filter(+ ([args]) => args.query.includes("FROM events_core"),+ );+ expect(eventsCoreCalls).toHaveLength(1);+ expect(eventsCoreCalls[0]?.[0].params).toMatchObject({+ fromTimestamp: HOT_START_CLICKHOUSE,+ toTimestamp: RECENT_CUTOFF_CLICKHOUSE,+ });+ expect(redisMock.setex).not.toHaveBeenCalled();+ });++ it("short-circuits partner-managed (forced v3) projects without any I/O", async () => {+ enableRedisCache();+ sharedServerMock.isForceV3ExperienceProject.mockReturnValueOnce(true);+ const prismaMock = mockPrismaForActions();+ const caller = createCaller(prismaMock);++ await expect(caller.migrationActions({ projectId })).resolves.toEqual({+ forceV3Experience: true,+ sdkActionNeeded: null,+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ evalsActionNeeded: false,+ exportsActionNeeded: false,+ });++ expect(prismaMock.jobConfiguration.groupBy).not.toHaveBeenCalled();+ expect(redisMock.mget).not.toHaveBeenCalled();+ expect(mockedQueryClickhouse).not.toHaveBeenCalled();+ });++ it("when Redis is unavailable, queries the full window and derives the SDK flag", async () => {+ redisMock.status = "end";+ mockedQueryClickhouse.mockImplementation(async (args) => {+ if (!args.query.includes("FROM events_core")) return [];+ return [+ mockSdkUsageRow({+ projectId,+ sdkName: "python",+ sdkVersion: "3.9.0",+ publicKey: "pk-lf-python",+ eventCount: "3",+ firstSeen: "2026-06-20T01:00:00Z",+ lastSeen: "2026-06-24T10:00:00Z",+ }),+ ];+ });+ const caller = createCaller(mockPrismaForActions());++ await expect(+ caller.migrationActions({ projectId }),+ ).resolves.toMatchObject({+ sdkActionNeeded: true,+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ });++ const eventsCoreCalls = mockedQueryClickhouse.mock.calls.filter(+ ([args]) => args.query.includes("FROM events_core"),+ );+ expect(eventsCoreCalls).toHaveLength(1);+ expect(redisMock.mget).not.toHaveBeenCalled();+ });+ });+ });});diff --git a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsxindex 90229c6109..b5e92dc7a4 100644--- a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx@@ -10,6 +10,7 @@ const mocks = vi.hoisted(() => ({openMigrationPanel: vi.fn(),setOpenMobileSidebar: vi.fn(),migrationData: undefined as unknown as ProjectMigrationStatus,+ cachedActionNeeded: false,}));vi.mock("@/src/components/ui/sidebar", () => ({@@ -38,6 +39,11 @@ vi.mock("@/src/features/projects/hooks", () => ({vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({useProjectV4MigrationData: () => mocks.migrationData,+ // The nav item reads the shared migration-actions signal; unknown+ // categories keep the pill hidden.+ useProjectV4MigrationActions: () => ({+ actionNeeded: mocks.cachedActionNeeded,+ }),}));vi.mock("@/src/features/v4-migration/hooks/useOpenV4MigrationPanel", () => ({@@ -68,6 +74,7 @@ const migrationStatus = (describe("v4 migration entry points", () => {beforeEach(() => {mocks.migrationData = migrationStatus();+ mocks.cachedActionNeeded = false;});it("hides the project chip and sidebar item when the project is up to date", () => {@@ -89,6 +96,7 @@ describe("v4 migration entry points", () => {mocks.migrationData = migrationStatus({evals: { status: "loaded", count: 1 },});+ mocks.cachedActionNeeded = true;render(<>diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsxindex 4692ba8efc..7bb85777e6 100644--- a/web/src/features/v4-migration/V4MigrationNavItem.tsx+++ b/web/src/features/v4-migration/V4MigrationNavItem.tsx@@ -3,8 +3,7 @@ import { SidebarMenuButton, useSidebar } from "@/src/components/ui/sidebar";import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { useQueryProject } from "@/src/features/projects/hooks";-import { useProjectV4MigrationData } from "@/src/features/v4-migration/hooks/useV4MigrationData";-import { getProjectMigrationReadiness } from "@/src/features/v4-migration/migrationData";+import { useProjectV4MigrationActions } from "@/src/features/v4-migration/hooks/useV4MigrationData";import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";export function V4MigrationNavItem() {@@ -13,23 +12,9 @@ export function V4MigrationNavItem() {const openMigrationPanel = useOpenV4MigrationPanel();const { isMobile, setOpenMobile: setOpenMobileSidebar } = useSidebar();const capture = usePostHogClientCapture();- const migrationData = useProjectV4MigrationData({- projectId: project?.id,- enabled: v4UpgradeUiEnabled && Boolean(project),- });+ const { actionNeeded } = useProjectV4MigrationActions(project?.id);- if (!v4UpgradeUiEnabled || !project) {- return null;- }- const readiness = getProjectMigrationReadiness({- sdk: migrationData.sdk,- evals: migrationData.evals,- experiments: migrationData.experiments,- apis: migrationData.apis,- exports: migrationData.exports,- forceV3Experience: migrationData.forceV3Experience,- });- if (readiness !== "action-needed") {+ if (!v4UpgradeUiEnabled || !project || !actionNeeded) {return null;}const label = "Action required";diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.tsindex 6235c1b358..49212e0742 100644--- a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts@@ -1,13 +1,17 @@import { renderHook } from "@testing-library/react";import { vi } from "vitest";-import { useAccountV4MigrationData } from "@/src/features/v4-migration/hooks/useV4MigrationData";+import {+ useAccountV4MigrationData,+ useProjectV4MigrationActions,+} from "@/src/features/v4-migration/hooks/useV4MigrationData";const mocks = vi.hoisted(() => ({summaryByProject: vi.fn(),traceLevelEvalSummaryByProject: vi.fn(),legacyApiUsageSummaryByProject: vi.fn(),sdkUsageSummaryByProject: vi.fn(),+ migrationActionsUseQuery: vi.fn(),queryResultSets: [] as unknown[][],}));@@ -33,6 +37,12 @@ vi.mock("@/src/utils/api", () => ({});return mocks.queryResultSets.shift() ?? [];},+ v4Transition: {+ migrationActions: {+ useQuery: (...args: unknown[]) =>+ mocks.migrationActionsUseQuery(...args),+ },+ },},}));@@ -192,3 +202,78 @@ describe("account v4 migration data", () => {});});});++describe("migration actions", () => {+ const cachedActions = (+ overrides: Partial<{+ forceV3Experience: boolean;+ sdkActionNeeded: boolean | null;+ experimentsActionNeeded: boolean | null;+ apisActionNeeded: boolean | null;+ evalsActionNeeded: boolean;+ exportsActionNeeded: boolean;+ }> = {},+ ) => ({+ forceV3Experience: false,+ sdkActionNeeded: null,+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ evalsActionNeeded: false,+ exportsActionNeeded: false,+ ...overrides,+ });++ beforeEach(() => {+ mocks.migrationActionsUseQuery.mockReset();+ });++ it("reports no action while the query has no data", () => {+ mocks.migrationActionsUseQuery.mockReturnValue({ data: undefined });++ const { result } = renderHook(() =>+ useProjectV4MigrationActions("project-1"),+ );++ expect(result.current).toEqual({ actionNeeded: false });+ });++ it("treats unknown categories as no signal instead of action needed", () => {+ mocks.migrationActionsUseQuery.mockReturnValue({+ data: cachedActions(),+ });++ const { result } = renderHook(() =>+ useProjectV4MigrationActions("project-1"),+ );++ expect(result.current).toEqual({ actionNeeded: false });+ });++ it("needs action when any known category requires it", () => {+ mocks.migrationActionsUseQuery.mockReturnValue({+ data: cachedActions({ sdkActionNeeded: true }),+ });++ const { result } = renderHook(() =>+ useProjectV4MigrationActions("project-1"),+ );++ expect(result.current).toEqual({ actionNeeded: true });+ });++ it("suppresses the signal for partner-managed (forced v3) projects", () => {+ mocks.migrationActionsUseQuery.mockReturnValue({+ data: cachedActions({+ forceV3Experience: true,+ sdkActionNeeded: true,+ evalsActionNeeded: true,+ }),+ });++ const { result } = renderHook(() =>+ useProjectV4MigrationActions("project-1"),+ );++ expect(result.current).toEqual({ actionNeeded: false });+ });+});diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.tsindex 52c0430708..6be2acc074 100644--- a/web/src/features/v4-migration/hooks/useV4MigrationData.ts+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.ts@@ -1,12 +1,9 @@-import { useState } from "react";-import { api } from "@/src/utils/api";import {countLegacyApiEntrypoints,normalizeLegacyApiEntrypoint,} from "@/src/features/v4/utils";import {- createV4MigrationDetectionRange,getLegacyIntegrationLabels,getMigrationActionState,getMigrationCountState,@@ -33,7 +30,6 @@ export function useAccountV4MigrationData(params: {enabled: boolean;}): Map<string, ProjectMigrationStatus> {const { organizations, enabled } = params;- const [detectionRange] = useState(createV4MigrationDetectionRange);const integrationQueries = api.useQueries((t) =>organizations.map((organization) =>@@ -61,10 +57,7 @@ export function useAccountV4MigrationData(params: {const sdkQueries = api.useQueries((t) =>organizations.map((organization) =>t.v4Transition.sdkUsageSummaryByProject(- {- orgId: organization.id,- ...detectionRange,- },+ { orgId: organization.id },{...queryOptions,enabled,@@ -76,10 +69,7 @@ export function useAccountV4MigrationData(params: {const apiQueries = api.useQueries((t) =>organizations.map((organization) =>t.v4Transition.legacyApiUsageSummaryByProject(- {- orgId: organization.id,- ...detectionRange,- },+ { orgId: organization.id },{...queryOptions,enabled,@@ -148,13 +138,9 @@ function useProjectV4SdkSummary(params: {enabled: boolean;}) {const { projectId, enabled } = params;- const [detectionRange] = useState(createV4MigrationDetectionRange);const queryEnabled = enabled && Boolean(projectId);const sdkQuery = api.v4Transition.sdkUsageSummary.useQuery(- {- projectId: projectId ?? "",- ...detectionRange,- },+ { projectId: projectId ?? "" },{...queryOptions,enabled: queryEnabled,@@ -190,13 +176,35 @@ export function useProjectV4EvalData(params: {return getMigrationCountState(evalQuery, (data) => data.traceLevelEvalCount);}+export function useProjectV4MigrationActions(projectId: string | undefined): {+ actionNeeded: boolean;+} {+ const query = api.v4Transition.migrationActions.useQuery(+ { projectId: projectId ?? "" },+ { ...queryOptions, enabled: Boolean(projectId) },+ );+ const actions = query.data;++ if (!actions || actions.forceV3Experience) {+ return { actionNeeded: false };+ }+ return {+ actionNeeded: [+ actions.sdkActionNeeded,+ actions.experimentsActionNeeded,+ actions.apisActionNeeded,+ actions.evalsActionNeeded,+ actions.exportsActionNeeded,+ ].some((categoryActionNeeded) => categoryActionNeeded === true),+ };+}+export function useProjectV4MigrationData(params: {projectId: string | undefined;enabled: boolean;}) {const { projectId, enabled } = params;const queryEnabled = enabled && Boolean(projectId);- const [detectionRange] = useState(createV4MigrationDetectionRange);const forceV3Experience = useForceV3Experience(projectId);const { sdkQuery, summary: sdkSummary } = useProjectV4SdkSummary({projectId,@@ -207,10 +215,7 @@ export function useProjectV4MigrationData(params: {{ ...queryOptions, enabled: queryEnabled },);const apiQuery = api.v4Transition.legacyApiUsageSummary.useQuery(- {- projectId: projectId ?? "",- ...detectionRange,- },+ { projectId: projectId ?? "" },{...queryOptions,enabled: queryEnabled,diff --git a/web/src/features/v4-migration/migrationData.clienttest.ts b/web/src/features/v4-migration/migrationData.clienttest.tsindex 2070c30217..48c36641cd 100644--- a/web/src/features/v4-migration/migrationData.clienttest.ts+++ b/web/src/features/v4-migration/migrationData.clienttest.ts@@ -1,5 +1,4 @@import {- createV4MigrationDetectionRange,getLegacyIntegrationLabels,getMigrationActionState,getMigrationCountState,@@ -29,17 +28,6 @@ const migrationStatus = (});describe("v4 migration data", () => {- it("uses a stable fourteen-day range aligned to the hour", () => {- const range = createV4MigrationDetectionRange(- new Date("2026-07-23T10:42:31.000Z").getTime(),- );-- expect(range).toEqual({- fromTimestamp: new Date("2026-07-09T11:00:00.000Z"),- toTimestamp: new Date("2026-07-23T11:00:00.000Z"),- });- });-it("keeps loading and errors distinct from a real zero", () => {expect(getMigrationCountState(null, () => 4)).toEqual({status: "loading",diff --git a/web/src/features/v4-migration/migrationData.ts b/web/src/features/v4-migration/migrationData.tsindex 0cc152949b..56decf738b 100644--- a/web/src/features/v4-migration/migrationData.ts+++ b/web/src/features/v4-migration/migrationData.ts@@ -3,20 +3,6 @@ import { type V4MigrationSdkState } from "@/src/features/v4-migration/sdkVersionexport const V4_MIGRATION_LOOKBACK_DAYS = 14;-const V4_MIGRATION_LOOKBACK_MS =- V4_MIGRATION_LOOKBACK_DAYS * 24 * 60 * 60 * 1000;-const RANGE_BUCKET_MS = 60 * 60 * 1000;--export const createV4MigrationDetectionRange = (now = Date.now()) => {- const toTimestamp = new Date(- (Math.floor(now / RANGE_BUCKET_MS) + 1) * RANGE_BUCKET_MS,- );- return {- fromTimestamp: new Date(toTimestamp.getTime() - V4_MIGRATION_LOOKBACK_MS),- toTimestamp,- };-};-export type MigrationCountState =| { status: "loading"; count: 0 }| { status: "error"; count: 0 }diff --git a/web/src/features/v4/server/v4TransitionCache.ts b/web/src/features/v4/server/v4TransitionCache.tsnew file mode 100644index 0000000000..9751d67cbf--- /dev/null+++ b/web/src/features/v4/server/v4TransitionCache.ts@@ -0,0 +1,175 @@+import { z } from "zod/v4";+import { logger, redis } from "@langfuse/shared/src/server";++/**+ * Redis caching for the v4 transition SDK usage check.+ *+ * SDK ingestion is read from the indexed `events_core` table. A per-project+ * blob covers the detection window up to an hour-aligned `hotStart` boundary;+ * readers always query the small `[hotStart, now]` gap live and merge it with+ * the blob so new SDK versions register within minutes. The TTL is one hour so+ * left-edge overcount on the sliding 14-day window (and stale classification+ * fields embedded in the blob) stay bounded to ~1h.+ *+ * Deprecated public API and experiment POST usage come from `system.query_log`+ * and are intentionally not cached here — that path lives in a follow-up PR+ * with a worker-maintained pipeline. Sidebar and panel SDK reads share this+ * blob + gap-fill path so both stay consistent.+ *+ * Helpers degrade gracefully: no Redis, Redis errors, or unparsable entries+ * behave like cache misses and never fail the request.+ */++/** Customer-ingress sources. Historical and experiment materializations are excluded. */+export const MIGRATION_INGRESS_EVENT_SOURCES = [+ "ingestion-api-dual-write",+ "otel-dual-write",+ "otel",+] as const;++/** Historical blob TTL: 60 minutes (1 hour). */+export const SDK_USAGE_CACHE_TTL_SECONDS = 60 * 60;++const sdkUsageSeriesSchema = z.object({+ source: z.enum(MIGRATION_INGRESS_EVENT_SOURCES),+ ingestionPath: z.enum(["otel", "ingestion_api"]),+ deliveryMode: z.enum(["realtime", "delayed"]),+ sdkName: z.string(),+ sdkVersion: z.string(),+ canonicalSdkName: z.enum(["python", "javascript"]).nullable(),+ sdkVersionMajor: z.number().nullable(),+ latestSdkMajor: z.number().nullable(),+ isValidSdkVersion: z.boolean(),+ attributionStatus: z.enum([+ "attributed",+ "missing_name",+ "missing_version",+ "missing_name_and_version",+ ]),+ publicKey: z.string(),+ v4MigrationStatus: z.enum(["compatible", "upgrade_required", "unknown"]),+ remediationType: z.enum([+ "update_sdk",+ "update_otel_instrumentation",+ "upgrade_instrumentation",+ ]),+ actionLevel: z.enum(["required", "none"]),+ eventCount: z.number(),+ firstSeen: z.string(),+ lastSeen: z.string(),+});++export type CachedSdkUsageSeries = z.infer<typeof sdkUsageSeriesSchema>;++const sdkUsageBlobSchema = z.object({+ version: z.literal(1),+ computedAt: z.string(),+ /** Hour-aligned ISO timestamp; the blob covers events strictly before it. */+ hotStart: z.string(),+ series: z.array(sdkUsageSeriesSchema),+});++export type SdkUsageCacheBlob = z.infer<typeof sdkUsageBlobSchema>;++const sdkUsageKey = (projectId: string) =>+ `langfuse:v4:sdk-usage:v1:${projectId}`;++export const isV4TransitionCacheAvailable = (): boolean =>+ redis != null && redis.status !== "end" && redis.status !== "close";++const readBlobs = async <T>(+ keys: string[],+ schema: z.ZodType<T>,+): Promise<(T | null)[]> => {+ if (!isV4TransitionCacheAvailable() || keys.length === 0) {+ return keys.map(() => null);+ }+ try {+ const rawValues = await redis!.mget(keys);+ return rawValues.map((rawValue) => {+ if (!rawValue) return null;+ try {+ const parsed = schema.safeParse(JSON.parse(rawValue));+ return parsed.success ? parsed.data : null;+ } catch {+ return null;+ }+ });+ } catch (error) {+ logger.warn("Failed to read v4 transition cache from Redis", { error });+ return keys.map(() => null);+ }+};++const writeBlobs = async (+ entries: { key: string; ttlSeconds: number; value: unknown }[],+): Promise<void> => {+ if (!isV4TransitionCacheAvailable() || entries.length === 0) return;+ try {+ await Promise.all(+ entries.map((entry) =>+ redis!.setex(entry.key, entry.ttlSeconds, JSON.stringify(entry.value)),+ ),+ );+ } catch (error) {+ logger.warn("Failed to write v4 transition cache to Redis", { error });+ }+};++export const readSdkUsageCache = (+ projectIds: string[],+): Promise<(SdkUsageCacheBlob | null)[]> =>+ readBlobs(projectIds.map(sdkUsageKey), sdkUsageBlobSchema);++export const writeSdkUsageCache = (+ entries: {+ projectId: string;+ hotStart: Date;+ series: CachedSdkUsageSeries[];+ }[],+ now = new Date(),+): Promise<void> =>+ writeBlobs(+ entries.map((entry) => ({+ key: sdkUsageKey(entry.projectId),+ ttlSeconds: SDK_USAGE_CACHE_TTL_SECONDS,+ value: {+ version: 1,+ computedAt: now.toISOString(),+ hotStart: entry.hotStart.toISOString(),+ series: entry.series,+ } satisfies SdkUsageCacheBlob,+ })),+ );++const MINUTE_MS = 60 * 1000;+const HOUR_MS = 60 * MINUTE_MS;++/** Trailing detection window used for SDK cache blobs and usage queries. */+export const V4_TRANSITION_DETECTION_WINDOW_MS = 14 * 24 * HOUR_MS;++/**+ * Detection windows are computed server-side so cache entries are shared+ * across requesters and long-lived tabs cannot pin stale ranges.+ */+export const getV4TransitionDetectionWindow = (nowMs = Date.now()) => {+ const hotStart = new Date(Math.floor(nowMs / HOUR_MS) * HOUR_MS);+ const windowEnd = new Date(hotStart.getTime() + HOUR_MS);+ return {+ /** Start of the current hour; cached SDK blobs cover strictly before it. */+ hotStart,+ windowEnd,+ windowStart: new Date(+ windowEnd.getTime() - V4_TRANSITION_DETECTION_WINDOW_MS,+ ),+ /**+ * Upper bound for the live SDK `events_core` gap query, floored to the+ * current minute. Every request within the same minute sees the identical+ * boundary, so the rendered ClickHouse datetime literal (and thus the whole+ * query AST) is stable and can hit the ClickHouse query result cache.+ * Events after the cutoff surface on the next minute; there is no permanent+ * gap. Minute (not hour) alignment keeps freshness at ~1 minute.+ */+ recentCutoff: new Date(Math.floor(nowMs / MINUTE_MS) * MINUTE_MS),+ };+};diff --git a/web/src/features/v4/server/v4TransitionQueryLogUsage.ts b/web/src/features/v4/server/v4TransitionQueryLogUsage.tsindex 4ddaeb3a38..e2b7f37923 100644--- a/web/src/features/v4/server/v4TransitionQueryLogUsage.ts+++ b/web/src/features/v4/server/v4TransitionQueryLogUsage.ts@@ -1,6 +1,10 @@/*** ClickHouse system.query_log helpers for v4 transition checks* (legacy public API usage and experiment POST /dataset-run-items).+ *+ * Legacy API stays on a direct query_log read (no Redis worker yet). The+ * public summary uses the server detection window so behavior matches the+ * pre-split service; internal helpers still accept from/to for reuse.*/import { env } from "@langfuse/shared/src/env";import {@@ -10,6 +14,10 @@ import {systemTableRef,type PreferredClickhouseService,} from "@langfuse/shared/src/server";+import {+ getV4TransitionDetectionWindow,+ V4_TRANSITION_DETECTION_WINDOW_MS,+} from "@/src/features/v4/server/v4TransitionCache";type LegacyApiUsageSummaryByProjectRow = {projectId: string;@@ -83,6 +91,13 @@ const querySystemQueryLogAcrossServices = async <T>({);};+/**+ * Read-time aging-out rule: drop entries whose last activity left the trailing+ * detection window (same rule as the SDK path).+ */+const isWithinDetectionWindow = (lastSeen: string, nowMs: number): boolean =>+ Date.parse(lastSeen) >= nowMs - V4_TRANSITION_DETECTION_WINDOW_MS;+export type DatasetRunItemsPostUsageResult =| {status: "success";@@ -278,7 +293,7 @@ SETTINGS skip_unavailable_shards = 1}));};-export const getLegacyApiUsageSummaries = async ({+const queryLegacyApiUsageSummaries = async ({projectIds,fromTimestamp,toTimestamp,@@ -350,3 +365,31 @@ export const getLegacyApiUsageSummaries = async ({left.entrypoint.localeCompare(right.entrypoint),);};++/**+ * Deprecated public API usage per project. Reads `system.query_log` directly;+ * Redis caching and the worker pipeline for this path land in a follow-up PR.+ * The always-mounted sidebar never calls this procedure.+ */+export const getLegacyApiUsageSummaries = async ({+ projectIds,+}: {+ projectIds: string[];+}): Promise<LegacyApiUsageSummaryByProjectResultRow[]> => {+ if (projectIds.length === 0) return [];++ const nowMs = Date.now();+ const { windowStart, windowEnd } = getV4TransitionDetectionWindow(nowMs);+ const rows = await queryLegacyApiUsageSummaries({+ projectIds,+ fromTimestamp: windowStart,+ toTimestamp: windowEnd,+ });+ return rows+ .filter((row) => isWithinDetectionWindow(row.lastSeen, nowMs))+ .sort(+ (left, right) =>+ left.projectId.localeCompare(right.projectId) ||+ left.entrypoint.localeCompare(right.entrypoint),+ );+};diff --git a/web/src/features/v4/server/v4TransitionRouter.ts b/web/src/features/v4/server/v4TransitionRouter.tsindex 5400c5748a..8014ffd1d1 100644--- a/web/src/features/v4/server/v4TransitionRouter.ts+++ b/web/src/features/v4/server/v4TransitionRouter.ts@@ -7,48 +7,13 @@ import {import { isForceV3ExperienceProject } from "@langfuse/shared/src/server";import {getAccessibleOrganizationProjects,+ getMigrationActions,getLegacyApiUsageSummaries,getLegacyIntegrationSummaries,getSdkUsageSummaries,getTraceLevelEvalSummaries,} from "@/src/features/v4/server/v4TransitionService";-const MAX_DETECTION_RANGE_MS = 30 * 24 * 60 * 60 * 1000;--const projectTimeRangeInputSchema = z- .object({- projectId: z.string(),- fromTimestamp: z.date(),- toTimestamp: z.date(),- })- .refine(- ({ fromTimestamp, toTimestamp }) =>- toTimestamp.getTime() > fromTimestamp.getTime(),- { message: "fromTimestamp must be before toTimestamp" },- )- .refine(- ({ fromTimestamp, toTimestamp }) =>- toTimestamp.getTime() - fromTimestamp.getTime() <= MAX_DETECTION_RANGE_MS,- { message: "V4 migration ranges cannot exceed 30 days" },- );--const organizationTimeRangeInputSchema = z- .object({- orgId: z.string(),- fromTimestamp: z.date(),- toTimestamp: z.date(),- })- .refine(- ({ fromTimestamp, toTimestamp }) =>- toTimestamp.getTime() > fromTimestamp.getTime(),- { message: "fromTimestamp must be before toTimestamp" },- )- .refine(- ({ fromTimestamp, toTimestamp }) =>- toTimestamp.getTime() - fromTimestamp.getTime() <= MAX_DETECTION_RANGE_MS,- { message: "V4 migration ranges cannot exceed 30 days" },- );-export const v4TransitionRouter = createTRPCRouter({forceV3Experience: protectedProjectProcedure.input(z.object({ projectId: z.string() }))@@ -123,18 +88,16 @@ export const v4TransitionRouter = createTRPCRouter({}),sdkUsageSummary: protectedProjectProcedure- .input(projectTimeRangeInputSchema)+ .input(z.object({ projectId: z.string() })).query(async ({ input }) => {const [summary] = await getSdkUsageSummaries({projectIds: [input.projectId],- fromTimestamp: input.fromTimestamp,- toTimestamp: input.toTimestamp,});return summary!;}),sdkUsageSummaryByProject: protectedOrganizationProcedure- .input(organizationTimeRangeInputSchema)+ .input(z.object({ orgId: z.string() })).query(async ({ input, ctx }) => {const projects = await getAccessibleOrganizationProjects({prisma: ctx.prisma,@@ -143,23 +106,19 @@ export const v4TransitionRouter = createTRPCRouter({});return getSdkUsageSummaries({projectIds: projects.map((project) => project.id),- fromTimestamp: input.fromTimestamp,- toTimestamp: input.toTimestamp,});}),legacyApiUsageSummary: protectedProjectProcedure- .input(projectTimeRangeInputSchema)+ .input(z.object({ projectId: z.string() })).query(({ input }) =>getLegacyApiUsageSummaries({projectIds: [input.projectId],- fromTimestamp: input.fromTimestamp,- toTimestamp: input.toTimestamp,}),),legacyApiUsageSummaryByProject: protectedOrganizationProcedure- .input(organizationTimeRangeInputSchema)+ .input(z.object({ orgId: z.string() })).query(async ({ input, ctx }) => {const projects = await getAccessibleOrganizationProjects({prisma: ctx.prisma,@@ -168,8 +127,21 @@ export const v4TransitionRouter = createTRPCRouter({});return getLegacyApiUsageSummaries({projectIds: projects.map((project) => project.id),- fromTimestamp: input.fromTimestamp,- toTimestamp: input.toTimestamp,});}),++ /**+ * Migration signal for always-mounted UI (the sidebar "Action required"+ * pill). Postgres for eval/export signals; SDK via the same Redis + live+ * gap-fill path as sdkUsageSummary. Deprecated API / experiment signals+ * stay `null` until the follow-up query_log worker pipeline lands.+ */+ migrationActions: protectedProjectProcedure+ .input(z.object({ projectId: z.string() }))+ .query(({ input, ctx }) =>+ getMigrationActions({+ prisma: ctx.prisma,+ projectId: input.projectId,+ }),+ ),});diff --git a/web/src/features/v4/server/v4TransitionSdkUsage.ts b/web/src/features/v4/server/v4TransitionSdkUsage.tsindex 70083745dd..e4cf70442a 100644--- a/web/src/features/v4/server/v4TransitionSdkUsage.ts+++ b/web/src/features/v4/server/v4TransitionSdkUsage.ts@@ -1,5 +1,10 @@/*** SDK / events_core usage checks for the v4 transition.+ *+ * Historical series come from a per-project Redis blob; the remaining gap up+ * to a minute-aligned recentCutoff is queried live from events_core (with+ * ClickHouse use_query_cache). Detection windows are server-side — no client+ * from/to. Experiment POST usage is delegated to the query_log module.*/import {convertDateToClickhouseDateTime,@@ -9,13 +14,16 @@ import {} from "@langfuse/shared/src/server";import { getSdkVersionCapabilityStatus } from "@/src/features/sdk-version/lib/sdkVersionCapabilities";import { getDatasetRunItemsPostUsageByProject } from "@/src/features/v4/server/v4TransitionQueryLogUsage";--/** Customer-ingress sources. Historical and experiment materializations are excluded. */-const MIGRATION_INGRESS_EVENT_SOURCES = [- "ingestion-api-dual-write",- "otel-dual-write",- "otel",-] as const;+import {+ getV4TransitionDetectionWindow,+ isV4TransitionCacheAvailable,+ MIGRATION_INGRESS_EVENT_SOURCES,+ readSdkUsageCache,+ V4_TRANSITION_DETECTION_WINDOW_MS,+ writeSdkUsageCache,+ type CachedSdkUsageSeries,+ type SdkUsageCacheBlob,+} from "@/src/features/v4/server/v4TransitionCache";type MigrationIngressSource = (typeof MIGRATION_INGRESS_EVENT_SOURCES)[number];type MigrationIngestionPath = "otel" | "ingestion_api";@@ -48,25 +56,7 @@ type SdkUsageSummaryByProjectRow = {lastSeen: string;};-type SdkUsageSummaryByProjectSeries = {- source: MigrationIngressSource;- ingestionPath: MigrationIngestionPath;- deliveryMode: MigrationDeliveryMode;- sdkName: string;- sdkVersion: string;- canonicalSdkName: "python" | "javascript" | null;- sdkVersionMajor: number | null;- latestSdkMajor: number | null;- isValidSdkVersion: boolean;- attributionStatus: IngestionSdkAttributionStatus;- publicKey: string;- v4MigrationStatus: V4MigrationStatus;- remediationType: MigrationRemediationType;- actionLevel: MigrationActionLevel;- eventCount: number;- firstSeen: string;- lastSeen: string;-};+type SdkUsageSummaryByProjectSeries = CachedSdkUsageSeries;// Counts stay out of this row on purpose: the client derives every displayed// count from sdkUsageSeries in sdkVersionStatus.ts, so duplicating the@@ -88,20 +78,15 @@ type SdkUsageSummaryByProjectResultRow = {const toBoolean = (value: boolean | string | number): boolean =>value === true || value === 1 || value === "1";-export const getSdkUsageSummaries = async ({- projectIds,- fromTimestamp,- toTimestamp,-}: {- projectIds: string[];- fromTimestamp: Date;- toTimestamp: Date;-}): Promise<SdkUsageSummaryByProjectResultRow[]> => {- if (projectIds.length === 0) return [];+/**+ * TTL for the SDK `events_core` usage query result cache. Longer than the+ * ~1-minute cache-key lifetime (the minute-aligned recent cutoff) so entries+ * are not evicted between identical minutes; effective reuse per key is still+ * ~1 minute because the key rotates every minute.+ */+const SDK_USAGE_QUERY_CACHE_TTL_SECONDS = 5 * 60;- const [rows, datasetRunItemsPostUsageResult] = await Promise.all([- queryClickhouse<SdkUsageSummaryByProjectRow>({- query: `+const buildSdkUsageQuery = (endBoundary: "inclusive" | "exclusive") => `WITH filtered AS (SELECTproject_id AS projectId,@@ -114,7 +99,7 @@ WITH filtered AS (WHEREproject_id IN {projectIds: Array(String)}AND start_time >= {fromTimestamp: DateTime64(3)}- AND start_time <= {toTimestamp: DateTime64(3)}+ AND start_time ${endBoundary === "inclusive" ? "<=" : "<"} {toTimestamp: DateTime64(3)}AND source IN {ingressSources: Array(String)}AND NOT startsWith(environment, 'langfuse-')AND ingestion_sdk_name NOT IN {internalSdkNames: Array(String)}@@ -216,101 +201,388 @@ ORDER BYsdkName ASC,sdkVersion ASC,publicKey ASC- `,- params: {- projectIds,- fromTimestamp: convertDateToClickhouseDateTime(fromTimestamp),- toTimestamp: convertDateToClickhouseDateTime(toTimestamp),- internalSdkNames: [...INTERNAL_INGESTION_SDK_NAMES],- ingressSources: [...MIGRATION_INGRESS_EVENT_SOURCES],- },- tags: { route: "v4-sdk-usage-summary" },- preferredClickhouseService: "EventsReadOnly",- }),- getDatasetRunItemsPostUsageByProject({+ `;++const querySdkUsageRows = ({+ projectIds,+ fromTimestamp,+ toTimestamp,+ endBoundary,+}: {+ projectIds: string[];+ fromTimestamp: Date;+ toTimestamp: Date;+ endBoundary: "inclusive" | "exclusive";+}): Promise<SdkUsageSummaryByProjectRow[]> =>+ queryClickhouse<SdkUsageSummaryByProjectRow>({+ query: buildSdkUsageQuery(endBoundary),+ params: {projectIds,- fromTimestamp,- toTimestamp,- }),- ]);+ fromTimestamp: convertDateToClickhouseDateTime(fromTimestamp),+ toTimestamp: convertDateToClickhouseDateTime(toTimestamp),+ internalSdkNames: [...INTERNAL_INGESTION_SDK_NAMES],+ ingressSources: [...MIGRATION_INGRESS_EVENT_SOURCES],+ },+ tags: { route: "v4-sdk-usage-summary" },+ preferredClickhouseService: "EventsReadOnly",+ // Enable the ClickHouse query result cache for this SDK `events_core`+ // SELECT only. Cache reuse requires an identical query AST, so the caller+ // passes a minute-aligned `recentCutoff` (see getV4TransitionDetectionWindow):+ // the rendered datetime literals carry no varying seconds/millis, so every+ // request within the same minute produces the same cache key. That key+ // rotates each minute; the 300s TTL simply outlives one key so entries are+ // not evicted before the next identical minute. These are query-level+ // settings and the result cache is per ClickHouse server/process; the+ // SELECT uses no nondeterministic functions, so cached rows stay valid for+ // the key's lifetime. Not applied to `system.query_log`.+ clickhouseSettings: {+ use_query_cache: 1,+ query_cache_ttl: SDK_USAGE_QUERY_CACHE_TTL_SECONDS,+ },+ });++const toSdkUsageSeries = (+ row: SdkUsageSummaryByProjectRow,+): SdkUsageSummaryByProjectSeries => ({+ source: row.source,+ ingestionPath: row.ingestionPath,+ deliveryMode: row.deliveryMode,+ sdkName: row.sdkName,+ sdkVersion: row.sdkVersion,+ canonicalSdkName: row.canonicalSdkName,+ sdkVersionMajor:+ row.sdkVersionMajor === null ? null : Number(row.sdkVersionMajor),+ latestSdkMajor:+ row.latestSdkMajor === null ? null : Number(row.latestSdkMajor),+ isValidSdkVersion: toBoolean(row.isValidSdkVersion),+ attributionStatus: row.attributionStatus,+ publicKey: row.publicKey,+ v4MigrationStatus: row.v4MigrationStatus,+ remediationType: row.remediationType,+ actionLevel: row.actionLevel,+ eventCount: Number(row.eventCount),+ firstSeen: row.firstSeen,+ lastSeen: row.lastSeen,+});- const rowsByProjectId = new Map<string, SdkUsageSummaryByProjectRow[]>();+const groupSdkUsageRowsByProject = (+ rows: SdkUsageSummaryByProjectRow[],+): Map<string, SdkUsageSummaryByProjectSeries[]> => {+ const byProject = new Map<string, SdkUsageSummaryByProjectSeries[]>();for (const row of rows) {- const projectRows = rowsByProjectId.get(row.projectId) ?? [];- projectRows.push(row);- rowsByProjectId.set(row.projectId, projectRows);+ const projectSeries = byProject.get(row.projectId) ?? [];+ projectSeries.push(toSdkUsageSeries(row));+ byProject.set(row.projectId, projectSeries);}- const projectsUsingDatasetRunItemsPost = new Set(- datasetRunItemsPostUsageResult.rows- .filter((row) => Number(row.count) > 0)- .map((row) => row.projectId),+ return byProject;+};++const sdkUsageSeriesKey = (series: SdkUsageSummaryByProjectSeries): string =>+ [series.source, series.sdkName, series.sdkVersion, series.publicKey].join(+ "\u0000",);- return projectIds.map((projectId) => {- const projectRows = (rowsByProjectId.get(projectId) ?? []).map(- (row): SdkUsageSummaryByProjectSeries => ({- source: row.source,- ingestionPath: row.ingestionPath,- deliveryMode: row.deliveryMode,- sdkName: row.sdkName,- sdkVersion: row.sdkVersion,- canonicalSdkName: row.canonicalSdkName,- sdkVersionMajor:- row.sdkVersionMajor === null ? null : Number(row.sdkVersionMajor),- latestSdkMajor:- row.latestSdkMajor === null ? null : Number(row.latestSdkMajor),- isValidSdkVersion: toBoolean(row.isValidSdkVersion),- attributionStatus: row.attributionStatus,- publicKey: row.publicKey,- v4MigrationStatus: row.v4MigrationStatus,- remediationType: row.remediationType,- actionLevel: row.actionLevel,- eventCount: Number(row.eventCount),- firstSeen: row.firstSeen,- lastSeen: row.lastSeen,- }),+/**+ * Merges cached historical series with live gap series per series key.+ * Counts add and seen-ranges union; classification fields come from the live+ * row when present because they embed rules (e.g. latest SDK major) that may+ * have changed since the historical entry was cached.+ */+const mergeSdkUsageSeries = (+ historical: SdkUsageSummaryByProjectSeries[],+ live: SdkUsageSummaryByProjectSeries[],+): SdkUsageSummaryByProjectSeries[] => {+ const byKey = new Map<string, SdkUsageSummaryByProjectSeries>();+ for (const series of historical) {+ byKey.set(sdkUsageSeriesKey(series), series);+ }+ for (const series of live) {+ const key = sdkUsageSeriesKey(series);+ const existing = byKey.get(key);+ byKey.set(+ key,+ existing+ ? {+ ...series,+ eventCount: existing.eventCount + series.eventCount,+ firstSeen:+ existing.firstSeen < series.firstSeen+ ? existing.firstSeen+ : series.firstSeen,+ lastSeen:+ existing.lastSeen > series.lastSeen+ ? existing.lastSeen+ : series.lastSeen,+ }+ : series,);- const sdkUsageSeries = projectRows;- const langfuseSdkUsage = projectRows.filter(- (series) => series.canonicalSdkName !== null,+ }+ return Array.from(byKey.values());+};++/** Matches the SQL ordering within a project: most recently seen first. */+const sortSdkUsageSeries = (+ series: SdkUsageSummaryByProjectSeries[],+): SdkUsageSummaryByProjectSeries[] =>+ [...series].sort(+ (left, right) =>+ right.lastSeen.localeCompare(left.lastSeen) ||+ left.source.localeCompare(right.source) ||+ left.sdkName.localeCompare(right.sdkName) ||+ left.sdkVersion.localeCompare(right.sdkVersion) ||+ left.publicKey.localeCompare(right.publicKey),+ );++/**+ * Read-time aging-out rule shared by every cached usage source: cached+ * entries may cover a window computed hours ago, so entries whose last+ * activity left the trailing detection window are dropped on read.+ */+const isWithinDetectionWindow = (lastSeen: string, nowMs: number): boolean =>+ Date.parse(lastSeen) >= nowMs - V4_TRANSITION_DETECTION_WINDOW_MS;++const trimSdkUsageSeries = (+ series: SdkUsageSummaryByProjectSeries[],+ nowMs: number,+): SdkUsageSummaryByProjectSeries[] =>+ series.filter((entry) => isWithinDetectionWindow(entry.lastSeen, nowMs));++const isSdkUsageBlobUsable = (+ blob: SdkUsageCacheBlob | null,+ nowMs: number,+): blob is SdkUsageCacheBlob => {+ if (!blob) return false;+ const blobHotStartMs = Date.parse(blob.hotStart);+ // Reject unparsable or future hotStart; Redis TTL is the only freshness+ // bound — we do not expire blobs early based on age.+ return Number.isFinite(blobHotStartMs) && blobHotStartMs <= nowMs;+};++/**+ * SDK ingestion series for the trailing detection window, per project.+ *+ * Historical data (everything before the current hour) is served from a+ * per-project Redis blob and only queried from ClickHouse on cache miss.+ * The remaining gap up to now is always queried live from the indexed+ * `events_core` table so freshness never depends on the cache: a user who+ * upgrades their SDK sees the new version within minutes.+ */+export const getSdkUsageSeriesByProject = async ({+ projectIds,+ nowMs,+}: {+ projectIds: string[];+ nowMs: number;+}): Promise<Map<string, SdkUsageSummaryByProjectSeries[]>> => {+ const { hotStart, recentCutoff, windowStart } =+ getV4TransitionDetectionWindow(nowMs);++ if (!isV4TransitionCacheAvailable()) {+ const rows = await querySdkUsageRows({+ projectIds,+ fromTimestamp: windowStart,+ toTimestamp: recentCutoff,+ endBoundary: "inclusive",+ });+ const byProject = groupSdkUsageRowsByProject(rows);+ return new Map(+ projectIds.map((projectId) => [+ projectId,+ sortSdkUsageSeries(+ trimSdkUsageSeries(byProject.get(projectId) ?? [], nowMs),+ ),+ ]),);- const hasCurrentExperimentInstrumentation =- langfuseSdkUsage.length > 0 &&- langfuseSdkUsage.every(- (series) =>- getSdkVersionCapabilityStatus(- { language: series.sdkName, version: series.sdkVersion },- "experimentLinkDeprecation",- ) === "supported",+ }++ const cachedBlobs = await readSdkUsageCache(projectIds);+ const cachedSeriesByProject = new Map<+ string,+ SdkUsageSummaryByProjectSeries[]+ >();+ const gapStartMsByProject = new Map<string, number>();+ const missedProjectIds: string[] = [];+ projectIds.forEach((projectId, index) => {+ const blob = cachedBlobs[index] ?? null;+ if (isSdkUsageBlobUsable(blob, nowMs)) {+ cachedSeriesByProject.set(projectId, blob.series);+ gapStartMsByProject.set(projectId, Date.parse(blob.hotStart));+ } else {+ missedProjectIds.push(projectId);+ gapStartMsByProject.set(projectId, hotStart.getTime());+ }+ });++ // Group the live queries by gap start so every project's uncached slice is+ // fetched exactly once without overlapping its cached window. Gap starts+ // are hour-aligned, so this stays a handful of groups at most.+ const gapProjectIdsByStartMs = new Map<number, string[]>();+ for (const [projectId, gapStartMs] of gapStartMsByProject) {+ const group = gapProjectIdsByStartMs.get(gapStartMs) ?? [];+ group.push(projectId);+ gapProjectIdsByStartMs.set(gapStartMs, group);+ }++ const [historicalRows, ...gapRowSets] = await Promise.all([+ missedProjectIds.length > 0+ ? querySdkUsageRows({+ projectIds: missedProjectIds,+ fromTimestamp: windowStart,+ toTimestamp: hotStart,+ endBoundary: "exclusive",+ })+ : Promise.resolve([] as SdkUsageSummaryByProjectRow[]),+ ...Array.from(gapProjectIdsByStartMs.entries()).map(+ ([gapStartMs, gapProjectIds]) =>+ querySdkUsageRows({+ projectIds: gapProjectIds,+ fromTimestamp: new Date(gapStartMs),+ toTimestamp: recentCutoff,+ endBoundary: "inclusive",+ }),+ ),+ ]);++ const historicalByProject = groupSdkUsageRowsByProject(historicalRows);+ const liveByProject = groupSdkUsageRowsByProject(gapRowSets.flat());++ // Empty results are cached too; otherwise idle projects would re-run the+ // historical query on every request.+ await writeSdkUsageCache(+ missedProjectIds.map((projectId) => ({+ projectId,+ hotStart,+ series: historicalByProject.get(projectId) ?? [],+ })),+ new Date(nowMs),+ );++ return new Map(+ projectIds.map((projectId) => {+ const historical =+ cachedSeriesByProject.get(projectId) ??+ historicalByProject.get(projectId) ??+ [];+ const merged = mergeSdkUsageSeries(+ historical,+ liveByProject.get(projectId) ?? [],);- const hasInconclusiveExperimentSdkUsage = langfuseSdkUsage.some(- (series) => {- const runnerStatus = getSdkVersionCapabilityStatus(- { language: series.sdkName, version: series.sdkVersion },- "experimentRunner",- );- const currentInstrumentationStatus = getSdkVersionCapabilityStatus(+ return [projectId, sortSdkUsageSeries(trimSdkUsageSeries(merged, nowMs))];+ }),+ );+};++/**+ * Whether each project called `POST /api/public/dataset-run-items` within the+ * detection window. Reads `system.query_log` directly; Redis caching for this+ * path lands in a follow-up PR with the worker pipeline.+ */+const getExperimentPostUsageByProject = async ({+ projectIds,+ nowMs,+}: {+ projectIds: string[];+ nowMs: number;+}): Promise<Map<string, boolean | "check_failed">> => {+ const { windowStart, windowEnd } = getV4TransitionDetectionWindow(nowMs);+ const usageByProject = new Map<string, boolean | "check_failed">();++ const queryResult = await getDatasetRunItemsPostUsageByProject({+ projectIds,+ fromTimestamp: windowStart,+ toTimestamp: windowEnd,+ });+ if (queryResult.status === "error") {+ projectIds.forEach((projectId) =>+ usageByProject.set(projectId, "check_failed"),+ );+ return usageByProject;+ }++ const projectsUsingDatasetRunItemsPost = new Set(+ queryResult.rows+ .filter((row) => Number(row.count) > 0)+ .map((row) => row.projectId),+ );+ projectIds.forEach((projectId) =>+ usageByProject.set(+ projectId,+ projectsUsingDatasetRunItemsPost.has(projectId),+ ),+ );+ return usageByProject;+};++const deriveExperimentInstrumentationMigration = ({+ sdkUsageSeries,+ postUsage,+}: {+ sdkUsageSeries: SdkUsageSummaryByProjectSeries[];+ postUsage: boolean | "check_failed";+}): SdkUsageSummaryByProjectResultRow["experimentInstrumentationMigration"] => {+ if (postUsage === "check_failed") {+ return { status: "check_failed", upgradePath: null };+ }+ if (!postUsage) {+ return { status: "not_required", upgradePath: null };+ }+ const langfuseSdkUsage = sdkUsageSeries.filter(+ (series) => series.canonicalSdkName !== null,+ );+ const hasCurrentExperimentInstrumentation =+ langfuseSdkUsage.length > 0 &&+ langfuseSdkUsage.every(+ (series) =>+ getSdkVersionCapabilityStatus({ language: series.sdkName, version: series.sdkVersion },"experimentLinkDeprecation",- );- return (- currentInstrumentationStatus === "unknown" ||- (runnerStatus !== "unsupported" &&- currentInstrumentationStatus !== "supported")- );- },+ ) === "supported",);- const experimentInstrumentationMigration: SdkUsageSummaryByProjectResultRow["experimentInstrumentationMigration"] =- datasetRunItemsPostUsageResult.status === "error"- ? { status: "check_failed", upgradePath: null }- : !projectsUsingDatasetRunItemsPost.has(projectId)- ? { status: "not_required", upgradePath: null }- : hasCurrentExperimentInstrumentation- ? { status: "not_required", upgradePath: null }- : hasInconclusiveExperimentSdkUsage- ? { status: "sdk_usage_inconclusive", upgradePath: "sdk" }- : { status: "required", upgradePath: "api" };+ const hasInconclusiveExperimentSdkUsage = langfuseSdkUsage.some((series) => {+ const runnerStatus = getSdkVersionCapabilityStatus(+ { language: series.sdkName, version: series.sdkVersion },+ "experimentRunner",+ );+ const currentInstrumentationStatus = getSdkVersionCapabilityStatus(+ { language: series.sdkName, version: series.sdkVersion },+ "experimentLinkDeprecation",+ );+ return (+ currentInstrumentationStatus === "unknown" ||+ (runnerStatus !== "unsupported" &&+ currentInstrumentationStatus !== "supported")+ );+ });+ return hasCurrentExperimentInstrumentation+ ? { status: "not_required", upgradePath: null }+ : hasInconclusiveExperimentSdkUsage+ ? { status: "sdk_usage_inconclusive", upgradePath: "sdk" }+ : { status: "required", upgradePath: "api" };+};- return { projectId, experimentInstrumentationMigration, sdkUsageSeries };+export const getSdkUsageSummaries = async ({+ projectIds,+}: {+ projectIds: string[];+}): Promise<SdkUsageSummaryByProjectResultRow[]> => {+ if (projectIds.length === 0) return [];++ const nowMs = Date.now();+ const [seriesByProject, postUsageByProject] = await Promise.all([+ getSdkUsageSeriesByProject({ projectIds, nowMs }),+ getExperimentPostUsageByProject({ projectIds, nowMs }),+ ]);++ return projectIds.map((projectId) => {+ const sdkUsageSeries = seriesByProject.get(projectId) ?? [];+ return {+ projectId,+ experimentInstrumentationMigration:+ deriveExperimentInstrumentationMigration({+ sdkUsageSeries,+ postUsage: postUsageByProject.get(projectId) ?? "check_failed",+ }),+ sdkUsageSeries,+ };});};diff --git a/web/src/features/v4/server/v4TransitionService.ts b/web/src/features/v4/server/v4TransitionService.tsindex 450f265ac0..eca01fd860 100644--- a/web/src/features/v4/server/v4TransitionService.ts+++ b/web/src/features/v4/server/v4TransitionService.ts@@ -1,7 +1,7 @@/**- * v4 transition orchestration: Postgres summaries and re-exports for the- * tRPC router. SDK / events_core and system.query_log logic live in sibling- * modules.+ * v4 transition orchestration: Postgres summaries, sidebar migration actions,+ * and re-exports for the tRPC router. SDK / events_core and system.query_log+ * logic live in sibling modules.*/import {AnalyticsIntegrationExportSource,@@ -9,6 +9,8 @@ import {type PrismaClient,} from "@langfuse/shared/src/db";import type { Session } from "next-auth";+import { isForceV3ExperienceProject } from "@langfuse/shared/src/server";+import { getSdkUsageSeriesByProject } from "@/src/features/v4/server/v4TransitionSdkUsage";export { getSdkUsageSummaries } from "@/src/features/v4/server/v4TransitionSdkUsage";export { getLegacyApiUsageSummaries } from "@/src/features/v4/server/v4TransitionQueryLogUsage";@@ -202,3 +204,54 @@ export const getTraceLevelEvalSummaries = async ({traceLevelEvalCount: countByProjectId.get(projectId) ?? 0,}));};++/**+ * Migration signals for the always-mounted sidebar "Action required" pill.+ * SDK uses the same Redis + live gap-fill path as the panel summaries so the+ * pill cannot go stale relative to them. Deprecated API / experiment signals+ * stay `null` until the follow-up query_log worker pipeline lands.+ */+export const getMigrationActions = async ({+ prisma,+ projectId,+}: {+ prisma: PrismaClient;+ projectId: string;+}) => {+ // Forced-v3 projects are partner-managed: the client suppresses every+ // migration signal, so skip all I/O on this always-mounted hot path.+ if (isForceV3ExperienceProject(projectId)) {+ return {+ forceV3Experience: true,+ sdkActionNeeded: null,+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ evalsActionNeeded: false,+ exportsActionNeeded: false,+ };+ }++ const nowMs = Date.now();+ const projectIds = [projectId];++ const [evalSummaries, integrationSummaries, seriesByProject] =+ await Promise.all([+ getTraceLevelEvalSummaries({ prisma, projectIds }),+ getLegacyIntegrationSummaries({ prisma, projectIds }),+ getSdkUsageSeriesByProject({ projectIds, nowMs }),+ ]);++ const sdkUsageSeries = seriesByProject.get(projectId) ?? [];++ return {+ forceV3Experience: isForceV3ExperienceProject(projectId),+ sdkActionNeeded: sdkUsageSeries.some(+ (series) => series.actionLevel === "required",+ ),+ experimentsActionNeeded: null,+ apisActionNeeded: null,+ evalsActionNeeded: (evalSummaries[0]?.traceLevelEvalCount ?? 0) > 0,+ exportsActionNeeded:+ (integrationSummaries[0]?.legacyIntegrationCount ?? 0) > 0,+ };+};