Skip to content

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

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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/sdkVersion
export 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 (
SELECT
project_id AS projectId,
@@ -114,7 +99,7 @@ WITH filtered AS (
WHERE
project_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 BY
sdkName 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.ts
index 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,
+ };
+};