Skip to content

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

fix(v4): classify migration ingestion paths by source (#16061)

Max Deichmann98354975a337
diff --git a/web/src/__tests__/server/unit/timelineBuckets.servertest.ts b/web/src/__tests__/server/unit/timelineBuckets.servertest.ts
deleted file mode 100644
index 25d8948bfe..0000000000
--- a/web/src/__tests__/server/unit/timelineBuckets.servertest.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveTimelineGranularity } from "@/src/features/v4/server/timelineBuckets";
-
-const START = new Date("2026-06-01T00:00:00.000Z");
-const minuteMs = 60 * 1000;
-
-const rangeEndingAfter = (minutes: number) =>
- new Date(START.getTime() + minutes * minuteMs);
-
-describe("resolveTimelineGranularity", () => {
- it("keeps short V4 ranges granular", () => {
- expect(resolveTimelineGranularity(START, rangeEndingAfter(5))).toBe(
- "minute",
- );
- expect(resolveTimelineGranularity(START, rangeEndingAfter(30))).toBe(
- "minute",
- );
- });
-
- it("matches the V4 preset bucket strategy", () => {
- expect(resolveTimelineGranularity(START, rangeEndingAfter(60))).toBe("2m");
- expect(resolveTimelineGranularity(START, rangeEndingAfter(3 * 60))).toBe(
- "5m",
- );
- expect(resolveTimelineGranularity(START, rangeEndingAfter(24 * 60))).toBe(
- "hour",
- );
- expect(
- resolveTimelineGranularity(START, rangeEndingAfter(7 * 24 * 60)),
- ).toBe("hour");
- expect(
- resolveTimelineGranularity(START, rangeEndingAfter(30 * 24 * 60)),
- ).toBe("day");
- });
-});
diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
index 55ffcc2448..b86f8b54af 100644
--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
@@ -135,6 +135,119 @@ const mockedQueryClickhouse = vi.mocked(queryClickhouse);
const projectId = "project-v4-transition";
const orgId = "org-v4-transition";
const secondProjectId = "project-v4-transition-second";
+const outsideProjectId = "project-v4-transition-outside";
+
+/** ClickHouse mock row shaped like the SQL-classified sdkUsageSummary output. */
+const mockSdkUsageRow = (overrides: {
+ projectId: string;
+ source?: "ingestion-api-dual-write" | "otel-dual-write" | "otel";
+ ingestionPath?: "ingestion_api" | "otel";
+ deliveryMode?: "delayed" | "realtime";
+ sdkName?: string;
+ sdkVersion?: string;
+ canonicalSdkName?: "python" | "javascript" | null;
+ sdkVersionMajor?: number | string | null;
+ latestSdkMajor?: number | string | null;
+ isValidSdkVersion?: boolean | string | number;
+ attributionStatus?: string;
+ publicKey?: string;
+ v4MigrationStatus?: "compatible" | "upgrade_required" | "unknown";
+ remediationType?:
+ | "update_sdk"
+ | "update_otel_instrumentation"
+ | "upgrade_instrumentation";
+ actionLevel?: "required" | "none";
+ eventCount?: string | number;
+ firstSeen?: string;
+ lastSeen?: string;
+}) => {
+ const source = overrides.source ?? "ingestion-api-dual-write";
+ const ingestionPath =
+ overrides.ingestionPath ??
+ (source === "ingestion-api-dual-write" ? "ingestion_api" : "otel");
+ const deliveryMode =
+ overrides.deliveryMode ?? (source === "otel" ? "realtime" : "delayed");
+ const sdkName = overrides.sdkName ?? "python";
+ const sdkVersion = overrides.sdkVersion ?? "4.7.0";
+ const canonicalSdkName =
+ overrides.canonicalSdkName !== undefined
+ ? overrides.canonicalSdkName
+ : sdkName === "python" || sdkName === "langfuse-python"
+ ? ("python" as const)
+ : sdkName === "javascript" || sdkName.startsWith("@langfuse/")
+ ? ("javascript" as const)
+ : null;
+ const sdkVersionMajor =
+ overrides.sdkVersionMajor !== undefined
+ ? overrides.sdkVersionMajor
+ : Number(sdkVersion.match(/^v?(\d+)/)?.[1] ?? NaN);
+ const resolvedMajor = Number.isFinite(Number(sdkVersionMajor))
+ ? Number(sdkVersionMajor)
+ : null;
+ const latestMajor =
+ canonicalSdkName === "python"
+ ? 4
+ : canonicalSdkName === "javascript"
+ ? 5
+ : null;
+ const v4MigrationStatus =
+ overrides.v4MigrationStatus ??
+ (canonicalSdkName === null || resolvedMajor === null
+ ? "unknown"
+ : resolvedMajor >= (latestMajor ?? 0)
+ ? "compatible"
+ : "upgrade_required");
+ const remediationType =
+ overrides.remediationType ??
+ (canonicalSdkName !== null
+ ? "update_sdk"
+ : ingestionPath === "otel"
+ ? "update_otel_instrumentation"
+ : "upgrade_instrumentation");
+ const actionLevel =
+ overrides.actionLevel ??
+ (remediationType === "update_sdk"
+ ? v4MigrationStatus === "compatible"
+ ? "none"
+ : "required"
+ : remediationType === "update_otel_instrumentation"
+ ? deliveryMode === "realtime"
+ ? "none"
+ : "required"
+ : "required");
+
+ return {
+ projectId: overrides.projectId,
+ source,
+ ingestionPath,
+ deliveryMode,
+ sdkName,
+ sdkVersion,
+ canonicalSdkName,
+ sdkVersionMajor: resolvedMajor,
+ latestSdkMajor:
+ overrides.latestSdkMajor !== undefined
+ ? overrides.latestSdkMajor
+ : latestMajor,
+ isValidSdkVersion: overrides.isValidSdkVersion ?? resolvedMajor !== null,
+ attributionStatus:
+ overrides.attributionStatus ??
+ (sdkName === "unknown" && sdkVersion === "unknown"
+ ? "missing_name_and_version"
+ : sdkName === "unknown"
+ ? "missing_name"
+ : sdkVersion === "unknown"
+ ? "missing_version"
+ : "attributed"),
+ publicKey: overrides.publicKey ?? "pk-lf-python",
+ v4MigrationStatus,
+ remediationType,
+ actionLevel,
+ eventCount: overrides.eventCount ?? "1",
+ firstSeen: overrides.firstSeen ?? "2026-06-24T01:00:00Z",
+ lastSeen: overrides.lastSeen ?? "2026-06-24T02:00:00Z",
+ };
+};
// Mocked Prisma delegates only implement the methods a test exercises, so
// accept any subset of PrismaClient keys with loosely typed values.
@@ -240,11 +353,26 @@ const session: Session = {
},
};
+const accessibleProjectsFindManyArgs = {
+ where: {
+ orgId,
+ deletedAt: null,
+ id: { in: [projectId, secondProjectId] },
+ },
+ select: {
+ id: true,
+ name: true,
+ },
+ orderBy: {
+ createdAt: "desc" as const,
+ },
+};
+
describe("v4TransitionRouter", () => {
beforeEach(() => {
mockedQueryClickhouse.mockResolvedValue([
{
- time: "2026-06-24T12:00:00Z",
+ projectId,
entrypoint: "publicapi: GET /api/public/traces/{id}",
count: "0.6666666666666666",
lastSeen: "2026-06-24T12:34:56.789123Z",
@@ -256,51 +384,31 @@ describe("v4TransitionRouter", () => {
vi.clearAllMocks();
});
- it("queries legacy public API usage with UTC buckets and route classification", async () => {
+ it("summarizes legacy public API usage for a project with route classification", async () => {
const caller = createCaller();
- const rows = await caller.timeSeriesByEntrypoint({
+ const rows = await caller.legacyApiUsageSummary({
projectId,
fromTimestamp: new Date("2026-06-24T00:00:00Z"),
toTimestamp: new Date("2026-06-25T00:00:00Z"),
- granularity: "auto",
});
- expect(rows).toHaveLength(25);
- expect(new Set(rows.map((row) => row.time)).size).toBe(24);
- expect(rows[0]).toEqual({
- time: "2026-06-24T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[12]).toEqual({
- time: "2026-06-24T12:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[13]).toEqual({
- time: "2026-06-24T12:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces/{id}",
- count: 0.6666666666666666,
- lastSeen: "2026-06-24T12:34:56.789123Z",
- });
- expect(rows[24]).toEqual({
- time: "2026-06-24T23:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
+ expect(rows).toEqual([
+ {
+ projectId,
+ entrypoint: "publicapi: GET /api/public/traces/{id}",
+ count: 0.6666666666666666,
+ lastSeen: "2026-06-24T12:34:56.789123Z",
+ },
+ ]);
expect(mockedQueryClickhouse).toHaveBeenCalledTimes(1);
const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
expect(clickhouseQuery?.query).toContain(
"FROM clusterAllReplicas('test-cluster', 'system.query_log')",
);
- expect(clickhouseQuery?.query).toContain(
- "toStartOfInterval(event_time_microseconds, INTERVAL 1 HOUR, 'UTC') AS bucket_time",
- );
+ expect(clickhouseQuery?.query).not.toContain("toStartOfInterval");
+ expect(clickhouseQuery?.query).not.toContain("bucket_time");
expect(clickhouseQuery?.query).toContain(
"splitByChar('?', JSONExtractString(log_comment, 'route'))[1]",
);
@@ -321,8 +429,17 @@ describe("v4TransitionRouter", () => {
"JSONExtractString(log_comment, 'surface') = 'publicapi'",
);
expect(clickhouseQuery?.query).toContain(
- "JSONExtractString(log_comment, 'projectId') = {projectId: String}",
+ "JSONExtractString(log_comment, 'projectId') IN {projectIds: Array(String)}",
+ );
+ expect(clickhouseQuery?.query).toContain(
+ "GROUP BY project_id, legacy_route",
);
+ expect(clickhouseQuery?.params).toMatchObject({
+ projectIds: [projectId],
+ });
+ expect(clickhouseQuery?.tags).toEqual({
+ route: "v4-legacy-api-usage-summary",
+ });
expect(clickhouseQuery?.clickhouseSettings).toEqual({
skip_unavailable_shards: 1,
});
@@ -363,275 +480,120 @@ describe("v4TransitionRouter", () => {
);
});
- it("fills daily buckets for a 30 day timeline", async () => {
- mockedQueryClickhouse.mockResolvedValueOnce([
- {
- time: "2026-06-10T00:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: "42",
- lastSeen: "2026-06-10T17:42:00Z",
- },
- ]);
-
- const caller = v4TransitionRouter.createCaller(
- createInnerTRPCContext({ session, headers: {} }),
- );
-
- const rows = await caller.timeSeriesByEntrypoint({
- projectId,
- fromTimestamp: new Date("2026-05-26T00:00:00Z"),
- toTimestamp: new Date("2026-06-25T00:00:00Z"),
- granularity: "auto",
- });
-
- expect(rows).toHaveLength(31);
- expect(new Set(rows.map((row) => row.time)).size).toBe(30);
- expect(rows[0]).toEqual({
- time: "2026-05-26T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[15]).toEqual({
- time: "2026-06-10T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[16]).toEqual({
- time: "2026-06-10T00:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: 42,
- lastSeen: "2026-06-10T17:42:00Z",
- });
- expect(rows[30]).toEqual({
- time: "2026-06-24T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
-
- const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
- expect(clickhouseQuery?.query).toContain(
- "toStartOfInterval(event_time_microseconds, INTERVAL 1 DAY, 'UTC') AS bucket_time",
- );
- });
-
- it("fills 2 minute buckets for a 1 hour timeline", async () => {
- mockedQueryClickhouse.mockResolvedValueOnce([
- {
- time: "2026-06-24T00:20:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: "8",
- lastSeen: "2026-06-24T00:21:30Z",
- },
- ]);
-
+ it("rejects ranges over 30 days", async () => {
const caller = createCaller();
- const rows = await caller.timeSeriesByEntrypoint({
- projectId,
- fromTimestamp: new Date("2026-06-24T00:00:00Z"),
- toTimestamp: new Date("2026-06-24T01:00:00Z"),
- granularity: "auto",
- });
-
- expect(rows).toHaveLength(31);
- expect(new Set(rows.map((row) => row.time)).size).toBe(30);
- expect(rows[0]).toEqual({
- time: "2026-06-24T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[10]).toEqual({
- time: "2026-06-24T00:20:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[11]).toEqual({
- time: "2026-06-24T00:20:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: 8,
- lastSeen: "2026-06-24T00:21:30Z",
- });
- expect(rows[30]).toEqual({
- time: "2026-06-24T00:58:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
+ 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");
- const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
- expect(clickhouseQuery?.query).toContain(
- "toStartOfInterval(event_time_microseconds, INTERVAL 2 MINUTE, 'UTC') AS bucket_time",
- );
+ expect(mockedQueryClickhouse).not.toHaveBeenCalled();
});
- it("fills 2 minute buckets for a 45 minute timeline", async () => {
- mockedQueryClickhouse.mockResolvedValueOnce([
- {
- time: "2026-06-24T00:16:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: "8",
- lastSeen: "2026-06-24T00:17:45Z",
- },
- ]);
-
+ it("queries SDK usage for only the authorized project", async () => {
+ mockedQueryClickhouse
+ .mockResolvedValueOnce([
+ mockSdkUsageRow({
+ projectId,
+ sdkName: "python",
+ sdkVersion: "4.7.0",
+ publicKey: "pk-lf-python",
+ eventCount: "2",
+ firstSeen: "2026-06-24T01:00:00Z",
+ lastSeen: "2026-06-24T02:00:00Z",
+ }),
+ ])
+ .mockResolvedValueOnce([]);
const caller = createCaller();
- const rows = await caller.timeSeriesByEntrypoint({
+ const summary = await caller.sdkUsageSummary({
projectId,
fromTimestamp: new Date("2026-06-24T00:00:00Z"),
- toTimestamp: new Date("2026-06-24T00:45:00Z"),
- granularity: "auto",
- });
-
- expect(rows).toHaveLength(24);
- expect(new Set(rows.map((row) => row.time)).size).toBe(23);
- expect(rows[0]).toEqual({
- time: "2026-06-24T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[8]).toEqual({
- time: "2026-06-24T00:16:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[9]).toEqual({
- time: "2026-06-24T00:16:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: 8,
- lastSeen: "2026-06-24T00:17:45Z",
- });
- expect(rows[23]).toEqual({
- time: "2026-06-24T00:44:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
+ toTimestamp: new Date("2026-06-25T00:00:00Z"),
});
- const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
- expect(clickhouseQuery?.query).toContain(
- "toStartOfInterval(event_time_microseconds, INTERVAL 2 MINUTE, 'UTC') AS bucket_time",
- );
- });
-
- it("fills 5 minute buckets for a 3 hour timeline", async () => {
- mockedQueryClickhouse.mockResolvedValueOnce([
- {
- time: "2026-06-24T01:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: "12",
- lastSeen: "2026-06-24T01:04:59Z",
- },
- ]);
-
- const caller = createCaller();
-
- const rows = await caller.timeSeriesByEntrypoint({
+ expect(summary).toMatchObject({
projectId,
- fromTimestamp: new Date("2026-06-24T00:00:00Z"),
- toTimestamp: new Date("2026-06-24T03:00:00Z"),
- granularity: "auto",
- });
-
- expect(rows).toHaveLength(37);
- expect(new Set(rows.map((row) => row.time)).size).toBe(36);
- expect(rows[0]).toEqual({
- time: "2026-06-24T00:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- expect(rows[12]).toEqual({
- time: "2026-06-24T01:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
+ sdkUsageSeries: [
+ {
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
+ sdkName: "python",
+ sdkVersion: "4.7.0",
+ eventCount: 2,
+ v4MigrationStatus: "compatible",
+ remediationType: "update_sdk",
+ actionLevel: "none",
+ },
+ ],
});
- expect(rows[13]).toEqual({
- time: "2026-06-24T01:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: 12,
- lastSeen: "2026-06-24T01:04:59Z",
+ expect(mockedQueryClickhouse).toHaveBeenCalledTimes(2);
+ expect(mockedQueryClickhouse.mock.calls[0]?.[0].params).toMatchObject({
+ projectIds: [projectId],
});
- expect(rows[36]).toEqual({
- time: "2026-06-24T02:55:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
+ expect(mockedQueryClickhouse.mock.calls[1]?.[0].params).toMatchObject({
+ projectIds: [projectId],
});
-
- const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
- expect(clickhouseQuery?.query).toContain(
- "toStartOfInterval(event_time_microseconds, INTERVAL 5 MINUTE, 'UTC') AS bucket_time",
- );
});
- it("uses hour buckets for a 7 day timeline", async () => {
- mockedQueryClickhouse.mockResolvedValueOnce([]);
-
+ it("rejects project summaries outside the caller session", async () => {
const caller = createCaller();
-
- const rows = await caller.timeSeriesByEntrypoint({
- projectId,
- fromTimestamp: new Date("2026-06-18T00:00:00Z"),
+ const range = {
+ fromTimestamp: new Date("2026-06-24T00:00:00Z"),
toTimestamp: new Date("2026-06-25T00:00:00Z"),
- granularity: "auto",
- });
-
- expect(rows).toEqual([]);
-
- const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
- expect(clickhouseQuery?.query).toContain(
- "toStartOfInterval(event_time_microseconds, INTERVAL 1 HOUR, 'UTC') AS bucket_time",
- );
- });
-
- it("rejects ranges over 30 days", async () => {
- const caller = createCaller();
+ };
await expect(
- caller.timeSeriesByEntrypoint({
- projectId,
- fromTimestamp: new Date("2026-05-25T00:00:00Z"),
- toTimestamp: new Date("2026-06-25T00:00:00Z"),
- granularity: "auto",
+ caller.sdkUsageSummary({ projectId: outsideProjectId, ...range }),
+ ).rejects.toThrow("User is not a member of this project");
+ await expect(
+ caller.legacyApiUsageSummary({
+ projectId: outsideProjectId,
+ ...range,
}),
- ).rejects.toThrow("30 days");
-
+ ).rejects.toThrow("User is not a member of this project");
expect(mockedQueryClickhouse).not.toHaveBeenCalled();
});
it("summarizes legacy integrations", async () => {
const mockPrisma = {
posthogIntegration: {
- findUnique: vi.fn().mockResolvedValue({
- enabled: true,
- exportSource: "TRACES_OBSERVATIONS",
- }),
+ findMany: vi.fn().mockResolvedValue([
+ {
+ projectId,
+ enabled: true,
+ exportSource: "TRACES_OBSERVATIONS",
+ },
+ ]),
},
mixpanelIntegration: {
- findUnique: vi.fn().mockResolvedValue({
- enabled: true,
- exportSource: "EVENTS",
- }),
+ findMany: vi.fn().mockResolvedValue([
+ {
+ projectId,
+ enabled: true,
+ exportSource: "EVENTS",
+ },
+ ]),
},
blobStorageIntegration: {
- findUnique: vi.fn().mockResolvedValue({
- enabled: true,
- exportSource: "TRACES_OBSERVATIONS_EVENTS",
- }),
+ findMany: vi.fn().mockResolvedValue([
+ {
+ projectId,
+ enabled: true,
+ exportSource: "TRACES_OBSERVATIONS_EVENTS",
+ },
+ ]),
},
};
const caller = createCaller(mockPrisma);
await expect(caller.summary({ projectId })).resolves.toEqual({
+ projectId,
legacyIntegrationCount: 2,
legacyIntegrations: {
posthog: true,
@@ -640,127 +602,99 @@ describe("v4TransitionRouter", () => {
},
});
- expect(mockPrisma.posthogIntegration.findUnique).toHaveBeenCalledWith({
- where: { projectId },
- select: { enabled: true, exportSource: true },
+ expect(mockPrisma.posthogIntegration.findMany).toHaveBeenCalledWith({
+ where: { projectId: { in: [projectId] } },
+ select: { projectId: true, enabled: true, exportSource: true },
});
- expect(mockPrisma.mixpanelIntegration.findUnique).toHaveBeenCalledWith({
- where: { projectId },
- select: { enabled: true, exportSource: true },
+ expect(mockPrisma.mixpanelIntegration.findMany).toHaveBeenCalledWith({
+ where: { projectId: { in: [projectId] } },
+ select: { projectId: true, enabled: true, exportSource: true },
});
- expect(mockPrisma.blobStorageIntegration.findUnique).toHaveBeenCalledWith({
- where: { projectId },
- select: { enabled: true, exportSource: true },
+ expect(mockPrisma.blobStorageIntegration.findMany).toHaveBeenCalledWith({
+ where: { projectId: { in: [projectId] } },
+ select: { projectId: true, enabled: true, exportSource: true },
});
});
it("summarizes trace-level evals", async () => {
const mockPrisma = {
jobConfiguration: {
- findMany: vi.fn().mockResolvedValue([
- { targetObject: "dataset", variableMapping: [] },
- {
- targetObject: "trace",
- variableMapping: [
- {
- templateVariable: "input",
- langfuseObject: "generation",
- objectName: "my-generation",
- selectedColumnId: "input",
- },
- ],
- },
+ groupBy: vi.fn().mockResolvedValue([
{
- targetObject: "trace",
- variableMapping: [
- {
- templateVariable: "input",
- langfuseObject: "trace",
- selectedColumnId: "input",
- },
- ],
+ projectId,
+ _count: { _all: 3 },
},
]),
},
};
const caller = createCaller(mockPrisma);
- // The third config maps from the trace itself, so the set is not fully
- // assistant-migratable.
await expect(caller.traceLevelEvalSummary({ projectId })).resolves.toEqual({
+ projectId,
traceLevelEvalCount: 3,
- allAssistantMigratable: false,
});
- expect(mockPrisma.jobConfiguration.findMany).toHaveBeenCalledWith({
+ expect(mockPrisma.jobConfiguration.groupBy).toHaveBeenCalledWith({
+ by: ["projectId"],
where: {
- projectId,
+ projectId: { in: [projectId] },
jobType: "EVAL",
targetObject: { in: ["trace", "dataset"] },
status: "ACTIVE",
timeScope: { has: "NEW" },
},
- select: { targetObject: true, variableMapping: true },
+ _count: { _all: true },
});
});
- it("marks evals as assistant-migratable when all are dataset targets or single-observation mappings", async () => {
+ it("returns zero evals when no active configs exist", async () => {
const mockPrisma = {
jobConfiguration: {
- findMany: vi.fn().mockResolvedValue([
- { targetObject: "dataset", variableMapping: [] },
- {
- targetObject: "trace",
- variableMapping: [
- {
- templateVariable: "input",
- langfuseObject: "generation",
- objectName: "my-generation",
- selectedColumnId: "input",
- },
- {
- templateVariable: "output",
- langfuseObject: "generation",
- objectName: "my-generation",
- selectedColumnId: "output",
- },
- ],
- },
- ]),
+ groupBy: vi.fn().mockResolvedValue([]),
},
};
const caller = createCaller(mockPrisma);
await expect(caller.traceLevelEvalSummary({ projectId })).resolves.toEqual({
- traceLevelEvalCount: 2,
- allAssistantMigratable: true,
+ projectId,
+ traceLevelEvalCount: 0,
});
});
it("does not count disabled legacy integrations", async () => {
const mockPrisma = {
posthogIntegration: {
- findUnique: vi.fn().mockResolvedValue({
- enabled: false,
- exportSource: "TRACES_OBSERVATIONS",
- }),
+ findMany: vi.fn().mockResolvedValue([
+ {
+ projectId,
+ enabled: false,
+ exportSource: "TRACES_OBSERVATIONS",
+ },
+ ]),
},
mixpanelIntegration: {
- findUnique: vi.fn().mockResolvedValue({
- enabled: true,
- exportSource: "TRACES_OBSERVATIONS_EVENTS",
- }),
+ findMany: vi.fn().mockResolvedValue([
+ {
+ projectId,
+ enabled: true,
+ exportSource: "TRACES_OBSERVATIONS_EVENTS",
+ },
+ ]),
},
blobStorageIntegration: {
- findUnique: vi.fn().mockResolvedValue({
- enabled: false,
- exportSource: "TRACES_OBSERVATIONS_EVENTS",
- }),
+ findMany: vi.fn().mockResolvedValue([
+ {
+ projectId,
+ enabled: false,
+ exportSource: "TRACES_OBSERVATIONS_EVENTS",
+ },
+ ]),
},
};
const caller = createCaller(mockPrisma);
await expect(caller.summary({ projectId })).resolves.toEqual({
+ projectId,
legacyIntegrationCount: 1,
legacyIntegrations: {
posthog: false,
@@ -840,28 +774,18 @@ describe("v4TransitionRouter", () => {
],
});
- expect(mockPrisma.project.findMany).toHaveBeenCalledWith({
- where: {
- orgId,
- deletedAt: null,
- id: { in: [projectId, secondProjectId] },
- },
- select: {
- id: true,
- name: true,
- },
- orderBy: {
- createdAt: "desc",
- },
- });
+ expect(mockPrisma.project.findMany).toHaveBeenCalledWith(
+ accessibleProjectsFindManyArgs,
+ );
});
it("summarizes trace-level evals by active organization project", async () => {
const mockPrisma = {
project: {
- findMany: vi
- .fn()
- .mockResolvedValue([{ id: projectId }, { id: secondProjectId }]),
+ findMany: vi.fn().mockResolvedValue([
+ { id: projectId, name: "V4 Transition Project" },
+ { id: secondProjectId, name: "Second Project" },
+ ]),
},
jobConfiguration: {
groupBy: vi.fn().mockResolvedValue([
@@ -887,16 +811,9 @@ describe("v4TransitionRouter", () => {
},
]);
- expect(mockPrisma.project.findMany).toHaveBeenCalledWith({
- where: {
- orgId,
- deletedAt: null,
- id: { in: [projectId, secondProjectId] },
- },
- select: {
- id: true,
- },
- });
+ expect(mockPrisma.project.findMany).toHaveBeenCalledWith(
+ accessibleProjectsFindManyArgs,
+ );
expect(mockPrisma.jobConfiguration.groupBy).toHaveBeenCalledWith({
by: ["projectId"],
where: {
@@ -1028,13 +945,13 @@ describe("v4TransitionRouter", () => {
async (role) => {
const mockPrisma = {
posthogIntegration: {
- findUnique: vi.fn().mockResolvedValue(null),
+ findMany: vi.fn().mockResolvedValue([]),
},
mixpanelIntegration: {
- findUnique: vi.fn().mockResolvedValue(null),
+ findMany: vi.fn().mockResolvedValue([]),
},
blobStorageIntegration: {
- findUnique: vi.fn().mockResolvedValue(null),
+ findMany: vi.fn().mockResolvedValue([]),
},
};
@@ -1044,6 +961,7 @@ describe("v4TransitionRouter", () => {
);
await expect(caller.summary({ projectId })).resolves.toEqual({
+ projectId,
legacyIntegrationCount: 0,
legacyIntegrations: {
posthog: false,
@@ -1057,90 +975,79 @@ describe("v4TransitionRouter", () => {
it("summarizes outdated SDK usage series by organization project", async () => {
mockedQueryClickhouse
.mockResolvedValueOnce([
- {
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "3.9.0",
publicKey: "pk-lf-python",
- count: "8",
- eventsCount: "8",
+ eventCount: "8",
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T02:00:00Z",
- hasDelayedOtelEvents: "1",
- },
- {
+ }),
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "4.14.1",
publicKey: "pk-lf-python",
- count: "13",
- eventsCount: "13",
+ eventCount: "13",
firstSeen: "2026-06-24T03:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "1",
- },
- {
+ }),
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "4.6.9",
publicKey: "pk-lf-pre-v4-python",
- count: "5",
- eventsCount: "0",
+ eventCount: "5",
firstSeen: "2026-06-24T12:00:00Z",
lastSeen: "2026-06-24T13:00:00Z",
- hasDelayedOtelEvents: "1",
- },
- {
+ }),
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "4.7.0",
publicKey: "pk-lf-current-python",
- count: "6",
- eventsCount: "6",
+ eventCount: "6",
firstSeen: "2026-06-24T13:30:00Z",
lastSeen: "2026-06-24T14:00:00Z",
- hasDelayedOtelEvents: "1",
- },
- {
+ }),
+ mockSdkUsageRow({
projectId: secondProjectId,
sdkName: "@langfuse/tracing",
sdkVersion: "5.3.9",
publicKey: "pk-lf-old-js",
- count: "5",
- eventsCount: "5",
+ eventCount: "5",
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "1",
- },
- {
+ }),
+ mockSdkUsageRow({
projectId: secondProjectId,
+ source: "otel",
sdkName: "unknown",
sdkVersion: "unknown",
publicKey: "pk-lf-otel",
- count: "3",
- eventsCount: "3",
+ eventCount: "3",
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "0",
- },
- {
+ }),
+ mockSdkUsageRow({
projectId: secondProjectId,
+ source: "otel-dual-write",
sdkName: "custom-otel-writer",
sdkVersion: "1.2.3",
publicKey: "pk-lf-custom-otel",
- count: "2",
- eventsCount: "2",
+ eventCount: "2",
firstSeen: "2026-06-24T02:00:00Z",
lastSeen: "2026-06-24T03:00:00Z",
- hasDelayedOtelEvents: "1",
- },
+ }),
])
.mockResolvedValueOnce([{ projectId, count: "1" }]);
const mockPrisma = {
project: {
- findMany: vi
- .fn()
- .mockResolvedValue([{ id: projectId }, { id: secondProjectId }]),
+ findMany: vi.fn().mockResolvedValue([
+ { id: projectId, name: "V4 Transition Project" },
+ { id: secondProjectId, name: "Second Project" },
+ ]),
},
};
const caller = createCaller(mockPrisma);
@@ -1160,56 +1067,81 @@ describe("v4TransitionRouter", () => {
},
sdkUsageSeries: [
{
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
sdkName: "python",
sdkVersion: "3.9.0",
canonicalSdkName: "python",
+ sdkVersionMajor: 3,
+ latestSdkMajor: 4,
+ isValidSdkVersion: true,
publicKey: "pk-lf-python",
- count: 8,
- eventsCount: 8,
+ eventCount: 8,
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T02:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed",
v4MigrationStatus: "upgrade_required",
+ remediationType: "update_sdk",
+ actionLevel: "required",
},
{
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
sdkName: "python",
sdkVersion: "4.14.1",
canonicalSdkName: "python",
+ sdkVersionMajor: 4,
+ latestSdkMajor: 4,
+ isValidSdkVersion: true,
publicKey: "pk-lf-python",
- count: 13,
- eventsCount: 13,
+ eventCount: 13,
firstSeen: "2026-06-24T03:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed",
v4MigrationStatus: "compatible",
+ remediationType: "update_sdk",
+ actionLevel: "none",
},
{
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
sdkName: "python",
sdkVersion: "4.6.9",
canonicalSdkName: "python",
+ sdkVersionMajor: 4,
+ latestSdkMajor: 4,
+ isValidSdkVersion: true,
publicKey: "pk-lf-pre-v4-python",
- count: 5,
- eventsCount: 0,
+ eventCount: 5,
firstSeen: "2026-06-24T12:00:00Z",
lastSeen: "2026-06-24T13:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed",
- v4MigrationStatus: "upgrade_recommended",
+ // Latest-major semantics: current major is compatible (no minor advice).
+ v4MigrationStatus: "compatible",
+ remediationType: "update_sdk",
+ actionLevel: "none",
},
{
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
sdkName: "python",
sdkVersion: "4.7.0",
canonicalSdkName: "python",
+ sdkVersionMajor: 4,
+ latestSdkMajor: 4,
+ isValidSdkVersion: true,
publicKey: "pk-lf-current-python",
- count: 6,
- eventsCount: 6,
+ eventCount: 6,
firstSeen: "2026-06-24T13:30:00Z",
lastSeen: "2026-06-24T14:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed",
v4MigrationStatus: "compatible",
+ remediationType: "update_sdk",
+ actionLevel: "none",
},
],
},
@@ -1221,95 +1153,100 @@ describe("v4TransitionRouter", () => {
},
sdkUsageSeries: [
{
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
sdkName: "@langfuse/tracing",
sdkVersion: "5.3.9",
canonicalSdkName: "javascript",
+ sdkVersionMajor: 5,
+ latestSdkMajor: 5,
+ isValidSdkVersion: true,
publicKey: "pk-lf-old-js",
- count: 5,
- eventsCount: 5,
+ eventCount: 5,
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed",
- v4MigrationStatus: "upgrade_recommended",
+ v4MigrationStatus: "compatible",
+ remediationType: "update_sdk",
+ actionLevel: "none",
},
{
+ source: "otel",
+ ingestionPath: "otel",
+ deliveryMode: "realtime",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
+ sdkVersionMajor: null,
+ latestSdkMajor: null,
+ isValidSdkVersion: false,
publicKey: "pk-lf-otel",
- count: 3,
- eventsCount: 3,
+ eventCount: 3,
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: false,
attributionStatus: "missing_name_and_version",
v4MigrationStatus: "unknown",
+ remediationType: "update_otel_instrumentation",
+ actionLevel: "none",
},
{
+ source: "otel-dual-write",
+ ingestionPath: "otel",
+ deliveryMode: "delayed",
sdkName: "custom-otel-writer",
sdkVersion: "1.2.3",
canonicalSdkName: null,
+ sdkVersionMajor: 1,
+ latestSdkMajor: null,
+ isValidSdkVersion: true,
publicKey: "pk-lf-custom-otel",
- count: 2,
- eventsCount: 2,
+ eventCount: 2,
firstSeen: "2026-06-24T02:00:00Z",
lastSeen: "2026-06-24T03:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed",
v4MigrationStatus: "unknown",
+ remediationType: "update_otel_instrumentation",
+ actionLevel: "required",
},
],
},
]);
- expect(mockPrisma.project.findMany).toHaveBeenCalledWith({
- where: {
- orgId,
- deletedAt: null,
- id: { in: [projectId, secondProjectId] },
- },
- select: {
- id: true,
- },
- });
+ expect(mockPrisma.project.findMany).toHaveBeenCalledWith(
+ accessibleProjectsFindManyArgs,
+ );
expect(mockedQueryClickhouse).toHaveBeenCalledTimes(2);
const usageQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
expect(usageQuery?.query).toContain("FROM events_core");
- expect(usageQuery?.query).toContain("UNION ALL");
- expect(usageQuery?.query).toContain("FROM scores FINAL");
- const [eventsQuery, scoresQuery] = usageQuery?.query.split("UNION ALL") ?? [
- "",
- "",
- ];
- expect(eventsQuery).not.toContain("execution_trace_id IS NULL");
- expect(scoresQuery).toContain("execution_trace_id IS NULL");
+ expect(usageQuery?.query).not.toContain("WITH selected");
+ expect(usageQuery?.query).not.toContain("FROM selected");
+ expect(usageQuery?.query).not.toContain("UNION ALL");
+ expect(usageQuery?.query).not.toContain("FROM scores");
+ expect(usageQuery?.query).toContain(
+ "source IN {ingressSources: Array(String)}",
+ );
expect(usageQuery?.query).not.toContain("system.columns");
expect(
usageQuery?.query.match(/project_id IN \{projectIds: Array\(String\)\}/g),
- ).toHaveLength(2);
+ ).toHaveLength(1);
expect(usageQuery?.query).toContain(
- "GROUP BY project_id, sdk_name, sdk_version, public_key",
+ "GROUP BY projectId, source, sdkName, sdkVersion, publicKey",
);
expect(usageQuery?.query).toContain(
- "if(countIf(is_otel_ingestion) > 0, argMaxIf(is_delayed_otel, event_time, is_otel_ingestion), NULL) AS hasDelayedOtelEvents",
+ "if(source = 'otel', 'realtime', 'delayed') AS deliveryMode",
);
- expect(usageQuery?.query.match(/AS event_time/g)).toHaveLength(2);
+ expect(usageQuery?.query).not.toContain("hasDelayedOtelEvents");
expect(usageQuery?.query).toContain(
- "formatDateTime(min(event_time), '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS firstSeen",
+ "formatDateTime(firstSeenAt, '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS firstSeen",
);
expect(usageQuery?.query).toContain(
- "formatDateTime(max(event_time), '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS lastSeen",
+ "formatDateTime(lastSeenAt, '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS lastSeen",
);
expect(usageQuery?.query).toContain(
"ingestion_sdk_name NOT IN {internalSdkNames: Array(String)}",
);
- const [eventsUsageQuery, scoresUsageQuery] =
- usageQuery?.query.split("UNION ALL") ?? [];
- expect(eventsUsageQuery).toContain(
- "AND NOT startsWith(environment, 'langfuse-')",
- );
- expect(scoresUsageQuery).toContain(
+ expect(usageQuery?.query).toContain(
"AND NOT startsWith(environment, 'langfuse-')",
);
expect(usageQuery?.query).not.toContain("toDate(start_time)");
@@ -1318,9 +1255,10 @@ describe("v4TransitionRouter", () => {
projectIds: [projectId, secondProjectId],
fromTimestamp: "2026-06-24 00:00:00.000",
toTimestamp: "2026-06-25 00:00:00.000",
+ ingressSources: ["ingestion-api-dual-write", "otel-dual-write", "otel"],
});
expect(usageQuery?.tags).toEqual({
- route: "v4-org-sdk-usage-summary",
+ route: "v4-sdk-usage-summary",
});
const experimentUsageQuery = mockedQueryClickhouse.mock.calls[1]?.[0];
@@ -1339,24 +1277,160 @@ describe("v4TransitionRouter", () => {
toTimestamp: "2026-06-25 00:00:00.000",
});
expect(experimentUsageQuery?.tags).toEqual({
- route: "v4-org-experiment-instrumentation-summary",
+ route: "v4-experiment-instrumentation-summary",
});
});
- it("requires removing dataset-run-items POST usage for native OTel instrumentation", async () => {
+ it("summarizes SDK usage for a single project with exactly that projectId", async () => {
+ mockedQueryClickhouse
+ .mockResolvedValueOnce([
+ mockSdkUsageRow({
+ projectId,
+ sdkName: "python",
+ sdkVersion: "4.7.0",
+ publicKey: "pk-lf-python",
+ eventCount: "6",
+ firstSeen: "2026-06-24T13:30:00Z",
+ lastSeen: "2026-06-24T14:00:00Z",
+ }),
+ ])
+ .mockResolvedValueOnce([]);
+
+ const caller = createCaller();
+
+ 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({
+ projectId,
+ experimentInstrumentationMigration: {
+ status: "not_required",
+ upgradePath: null,
+ },
+ sdkUsageSeries: [
+ {
+ sdkName: "python",
+ sdkVersion: "4.7.0",
+ v4MigrationStatus: "compatible",
+ remediationType: "update_sdk",
+ actionLevel: "none",
+ eventCount: 6,
+ },
+ ],
+ });
+
+ expect(mockedQueryClickhouse).toHaveBeenCalledTimes(2);
+ expect(mockedQueryClickhouse.mock.calls[0]?.[0]?.params).toMatchObject({
+ projectIds: [projectId],
+ });
+ expect(mockedQueryClickhouse.mock.calls[1]?.[0]?.params).toMatchObject({
+ projectIds: [projectId],
+ });
+ expect(mockedQueryClickhouse.mock.calls[0]?.[0]?.tags).toEqual({
+ route: "v4-sdk-usage-summary",
+ });
+ expect(mockedQueryClickhouse.mock.calls[1]?.[0]?.tags).toEqual({
+ route: "v4-experiment-instrumentation-summary",
+ });
+ });
+
+ it("keeps source-specific series and consumes SQL-owned classification", async () => {
mockedQueryClickhouse
.mockResolvedValueOnce([
{
projectId,
+ source: "otel-dual-write",
+ ingestionPath: "otel",
+ deliveryMode: "delayed",
sdkName: "unknown",
sdkVersion: "unknown",
- publicKey: "pk-lf-otel",
- count: "3",
+ canonicalSdkName: null,
+ sdkVersionMajor: null,
+ isValidSdkVersion: false,
+ attributionStatus: "missing_name_and_version",
+ publicKey: "pk-lf-shared",
+ v4MigrationStatus: "unknown",
+ remediationType: "update_otel_instrumentation",
+ actionLevel: "required",
+ eventCount: "3",
firstSeen: "2026-06-24T01:00:00Z",
+ lastSeen: "2026-06-24T02:00:00Z",
+ },
+ {
+ projectId,
+ source: "ingestion-api-dual-write",
+ ingestionPath: "ingestion_api",
+ deliveryMode: "delayed",
+ sdkName: "unknown",
+ sdkVersion: "unknown",
+ canonicalSdkName: null,
+ sdkVersionMajor: null,
+ isValidSdkVersion: false,
+ attributionStatus: "missing_name_and_version",
+ publicKey: "pk-lf-shared",
+ v4MigrationStatus: "unknown",
+ remediationType: "upgrade_instrumentation",
+ actionLevel: "required",
+ eventCount: "2",
+ firstSeen: "2026-06-24T03:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "0",
},
])
+ .mockResolvedValueOnce([]);
+ const caller = createCaller();
+
+ const summary = await caller.sdkUsageSummary({
+ projectId,
+ fromTimestamp: new Date("2026-06-24T00:00:00Z"),
+ toTimestamp: new Date("2026-06-25T00:00:00Z"),
+ });
+
+ 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,
+ }),
+ ]);
+
+ const usageQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
+ expect(usageQuery?.query).toContain(
+ "GROUP BY projectId, source, sdkName, sdkVersion, publicKey",
+ );
+ expect(usageQuery?.query).toContain(
+ "source IN {ingressSources: Array(String)}",
+ );
+ expect(usageQuery?.query).toContain(
+ "if(source = 'otel', 'realtime', 'delayed') AS deliveryMode",
+ );
+ expect(usageQuery?.query).not.toContain("hasDelayedOtelEvents");
+ expect(usageQuery?.params).toMatchObject({
+ ingressSources: ["ingestion-api-dual-write", "otel-dual-write", "otel"],
+ });
+ });
+
+ it("requires removing dataset-run-items POST usage for native OTel instrumentation", async () => {
+ mockedQueryClickhouse
+ .mockResolvedValueOnce([
+ mockSdkUsageRow({
+ projectId,
+ source: "otel",
+ sdkName: "unknown",
+ sdkVersion: "unknown",
+ publicKey: "pk-lf-otel",
+ eventCount: "3",
+ firstSeen: "2026-06-24T01:00:00Z",
+ lastSeen: "2026-06-24T04:00:00Z",
+ }),
+ ])
.mockResolvedValueOnce([{ projectId, count: "1" }]);
const caller = createCaller({
project: {
@@ -1382,16 +1456,15 @@ describe("v4TransitionRouter", () => {
it("preserves SDK usage when the experiment instrumentation check fails", async () => {
mockedQueryClickhouse
.mockResolvedValueOnce([
- {
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "3.9.0",
publicKey: "pk-lf-python",
- count: "3",
+ eventCount: "3",
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "1",
- },
+ }),
])
.mockRejectedValueOnce(new Error("query_log unavailable"));
const caller = createCaller({
@@ -1417,6 +1490,8 @@ describe("v4TransitionRouter", () => {
sdkName: "python",
sdkVersion: "3.9.0",
v4MigrationStatus: "upgrade_required",
+ remediationType: "update_sdk",
+ actionLevel: "required",
},
],
});
@@ -1425,16 +1500,15 @@ describe("v4TransitionRouter", () => {
it("requires an API upgrade when POST usage predates the experiment runner", async () => {
mockedQueryClickhouse
.mockResolvedValueOnce([
- {
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "3.3.5",
publicKey: "pk-lf-python",
- count: "3",
+ eventCount: "3",
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "1",
- },
+ }),
])
.mockResolvedValueOnce([{ projectId, count: "1" }]);
const caller = createCaller({
@@ -1458,16 +1532,15 @@ describe("v4TransitionRouter", () => {
it("does not require an upgrade for current experiment instrumentation", async () => {
mockedQueryClickhouse
.mockResolvedValueOnce([
- {
+ mockSdkUsageRow({
projectId,
sdkName: "python",
sdkVersion: "4.0.0",
publicKey: "pk-lf-python",
- count: "3",
+ eventCount: "3",
firstSeen: "2026-06-24T01:00:00Z",
lastSeen: "2026-06-24T04:00:00Z",
- hasDelayedOtelEvents: "1",
- },
+ }),
])
.mockResolvedValueOnce([{ projectId, count: "1" }]);
const caller = createCaller({
@@ -1494,18 +1567,21 @@ describe("v4TransitionRouter", () => {
projectId,
entrypoint: "publicapi: GET /api/public/traces/{id}",
count: "0.6666666666666666",
+ lastSeen: "2026-06-24T12:34:56.789123Z",
},
{
projectId: secondProjectId,
entrypoint: "publicapi: GET /api/public/metrics",
count: 3,
+ lastSeen: "2026-06-24T15:00:00.000000Z",
},
]);
const mockPrisma = {
project: {
- findMany: vi
- .fn()
- .mockResolvedValue([{ id: projectId }, { id: secondProjectId }]),
+ findMany: vi.fn().mockResolvedValue([
+ { id: projectId, name: "V4 Transition Project" },
+ { id: secondProjectId, name: "Second Project" },
+ ]),
},
};
const caller = createCaller(mockPrisma);
@@ -1521,14 +1597,19 @@ describe("v4TransitionRouter", () => {
projectId,
entrypoint: "publicapi: GET /api/public/traces/{id}",
count: 0.6666666666666666,
+ lastSeen: "2026-06-24T12:34:56.789123Z",
},
{
projectId: secondProjectId,
entrypoint: "publicapi: GET /api/public/metrics",
count: 3,
+ lastSeen: "2026-06-24T15:00:00.000000Z",
},
]);
+ expect(mockPrisma.project.findMany).toHaveBeenCalledWith(
+ accessibleProjectsFindManyArgs,
+ );
expect(mockedQueryClickhouse).toHaveBeenCalledTimes(1);
const clickhouseQuery = mockedQueryClickhouse.mock.calls[0]?.[0];
expect(clickhouseQuery?.query).not.toContain("toStartOfInterval");
@@ -1540,6 +1621,9 @@ describe("v4TransitionRouter", () => {
"JSONExtractString(log_comment, 'projectId') IN {projectIds: Array(String)}",
);
expect(clickhouseQuery?.query).toContain("project_id AS projectId");
+ expect(clickhouseQuery?.query).toContain(
+ "formatDateTime(max(event_time_microseconds), '%Y-%m-%dT%H:%i:%S.%fZ', 'UTC') AS lastSeen",
+ );
expect(clickhouseQuery?.query).toContain(
"GROUP BY project_id, legacy_route",
);
@@ -1547,7 +1631,7 @@ describe("v4TransitionRouter", () => {
projectIds: [projectId, secondProjectId],
});
expect(clickhouseQuery?.tags).toEqual({
- route: "v4-org-legacy-api-usage-summary",
+ route: "v4-legacy-api-usage-summary",
});
});
});
diff --git a/web/src/features/evals/pages/remap-evaluator.tsx b/web/src/features/evals/pages/remap-evaluator.tsx
index 003e75c0fe..2fa3f844a2 100644
--- a/web/src/features/evals/pages/remap-evaluator.tsx
+++ b/web/src/features/evals/pages/remap-evaluator.tsx
@@ -21,7 +21,6 @@ import {
} from "@/src/components/ui/dropdown-menu";
import { BotMessageSquare, ChevronDown, Zap } from "lucide-react";
import { useEvalCapabilities } from "@/src/features/evals/hooks/useEvalCapabilities";
-import { useQueryProject } from "@/src/features/projects/hooks";
import {
useCanUseInAppAgent,
useInAppAiAgent,
@@ -49,19 +48,16 @@ export default function RemapEvaluatorPage() {
const evalConfigId = router.query.evaluator as string;
const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);
const capture = usePostHogClientCapture();
- const { organization } = useQueryProject();
const canUseAssistant = useCanUseInAppAgent();
const { openAssistant, submit } = useInAppAiAgent();
const sdk = useProjectV4SdkData({
projectId,
- orgId: organization?.id,
enabled: v4UpgradeUiEnabled && Boolean(projectId),
});
const evalCapabilities = useEvalCapabilities(projectId);
const upgradePlan = useEvalUpgradeAssistantPlan({
projectId,
- orgId: organization?.id,
enabled: v4UpgradeUiEnabled && Boolean(projectId),
});
diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
index 9c926804e9..ea379dc350 100644
--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
@@ -26,21 +26,86 @@ import { TABLE_AGGREGATION_OPTIONS } from "@langfuse/shared";
import { rangeFromString } from "@/src/utils/date-range-utils";
const makeSdkUsageSeries = (
- overrides: Partial<V4MigrationSdkUsageSeries>,
-): V4MigrationSdkUsageSeries => ({
- sdkName: "python",
- sdkVersion: "4.7.1",
- canonicalSdkName: "python",
- publicKey: "pk-lf-1234567890abcdef",
- count: 10,
- eventsCount: 10,
- firstSeen: "2026-07-20T10:00:00Z",
- lastSeen: "2026-07-23T10:00:00Z",
- hasDelayedOtelEvents: null,
- attributionStatus: "attributed",
- v4MigrationStatus: "compatible",
- ...overrides,
-});
+ overrides: Partial<V4MigrationSdkUsageSeries> = {},
+): V4MigrationSdkUsageSeries => {
+ const source = overrides.source ?? "ingestion-api-dual-write";
+ const ingestionPath =
+ overrides.ingestionPath ??
+ (source === "ingestion-api-dual-write" ? "ingestion_api" : "otel");
+ const deliveryMode =
+ overrides.deliveryMode ?? (source === "otel" ? "realtime" : "delayed");
+ const sdkName = overrides.sdkName ?? "python";
+ const sdkVersion = overrides.sdkVersion ?? "4.7.1";
+ const canonicalSdkName =
+ overrides.canonicalSdkName !== undefined
+ ? overrides.canonicalSdkName
+ : sdkName === "python"
+ ? "python"
+ : sdkName === "javascript" || sdkName.startsWith("@langfuse/")
+ ? "javascript"
+ : null;
+ const sdkVersionMajor =
+ overrides.sdkVersionMajor !== undefined
+ ? overrides.sdkVersionMajor
+ : Number(sdkVersion.match(/^v?(\d+)/)?.[1] ?? NaN);
+ const resolvedMajor = Number.isFinite(sdkVersionMajor)
+ ? Number(sdkVersionMajor)
+ : null;
+ const latestMajor =
+ canonicalSdkName === "python"
+ ? 4
+ : canonicalSdkName === "javascript"
+ ? 5
+ : null;
+ const v4MigrationStatus =
+ overrides.v4MigrationStatus ??
+ (canonicalSdkName === null || resolvedMajor === null
+ ? "unknown"
+ : resolvedMajor >= (latestMajor ?? 0)
+ ? "compatible"
+ : "upgrade_required");
+ const remediationType =
+ overrides.remediationType ??
+ (canonicalSdkName !== null
+ ? "update_sdk"
+ : ingestionPath === "otel"
+ ? "update_otel_instrumentation"
+ : "upgrade_instrumentation");
+ const actionLevel =
+ overrides.actionLevel ??
+ (remediationType === "update_sdk"
+ ? v4MigrationStatus === "compatible"
+ ? "none"
+ : "required"
+ : remediationType === "update_otel_instrumentation"
+ ? deliveryMode === "realtime"
+ ? "none"
+ : "required"
+ : "required");
+
+ return {
+ source,
+ ingestionPath,
+ deliveryMode,
+ sdkName,
+ sdkVersion,
+ canonicalSdkName,
+ sdkVersionMajor: resolvedMajor,
+ latestSdkMajor:
+ overrides.latestSdkMajor !== undefined
+ ? overrides.latestSdkMajor
+ : latestMajor,
+ isValidSdkVersion: overrides.isValidSdkVersion ?? resolvedMajor !== null,
+ publicKey: overrides.publicKey ?? "pk-lf-1234567890abcdef",
+ eventCount: overrides.eventCount ?? 10,
+ firstSeen: overrides.firstSeen ?? "2026-07-20T10:00:00Z",
+ lastSeen: overrides.lastSeen ?? "2026-07-23T10:00:00Z",
+ attributionStatus: overrides.attributionStatus ?? "attributed",
+ v4MigrationStatus,
+ remediationType,
+ actionLevel,
+ };
+};
const cleanSdkState = (): V4MigrationSdkState => ({
status: "latest",
@@ -402,11 +467,10 @@ describe("V4MigrationDetailsContent", () => {
sdkUsageSeries: [
makeSdkUsageSeries({}),
makeSdkUsageSeries({
+ source: "otel",
sdkName: "otelcol",
sdkVersion: "0.98.0",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: false,
}),
],
};
@@ -417,20 +481,25 @@ describe("V4MigrationDetailsContent", () => {
expect(
screen.queryByText("Update OTel Instrumentation"),
).not.toBeInTheDocument();
+ expect(
+ screen.getByText("Detected V4-compatible instrumentation"),
+ ).toBeInTheDocument();
+ expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
+ expect(screen.getByText("otelcol 0.98.0")).toBeInTheDocument();
+ expect(screen.getByText("· up to date")).toBeInTheDocument();
+ expect(screen.getByText("· real-time")).toBeInTheDocument();
});
- it("lists every detected SDK series when one needs an upgrade", () => {
+ it("lists only required SDK series in Update SDK and shows compatible ones as detected", () => {
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
- v4MigrationStatus: "upgrade_required",
}),
makeSdkUsageSeries({
sdkVersion: "4.6.9",
publicKey: "pk-lf-fedcba0987654321",
- v4MigrationStatus: "upgrade_recommended",
}),
],
upgradeRequiredCount: 1,
@@ -444,11 +513,16 @@ describe("V4MigrationDetailsContent", () => {
within(screen.getByText("Update SDK").closest("button")!).getByText("1"),
).toBeInTheDocument();
expect(screen.getByText("Python 2.60.3")).toBeInTheDocument();
- expect(screen.getByText("Python 4.6.9")).toBeInTheDocument();
expect(screen.getByText(/upgrade required/)).toBeInTheDocument();
+ // Compatible current-major traffic lands in the detected section.
expect(
- screen.getByText("· recommended to upgrade to >= 4.7.0"),
+ screen.getByText("Detected V4-compatible instrumentation"),
).toBeInTheDocument();
+ expect(screen.getByText("Python 4.6.9")).toBeInTheDocument();
+ expect(screen.getByText("· up to date")).toBeInTheDocument();
+ expect(
+ screen.queryByText("· recommended to upgrade to >= 4.7.0"),
+ ).not.toBeInTheDocument();
// The explicit evidence link targets this key + SDK name/version over the
// detection lookback window, so versions on the same key stay distinct.
const outdatedRow = screen.getByText("Python 2.60.3").closest("li")!;
@@ -459,6 +533,7 @@ describe("V4MigrationDetailsContent", () => {
"href",
`/project/project-1/observations?filter=${encodeURIComponent(
"ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef," +
+ "ingestionSource;stringOptions;;any of;ingestion-api-dual-write," +
"ingestionSdkName;stringOptions;;any of;python," +
"ingestionSdkVersion;stringOptions;;any of;2.60.3",
)}&dateRange=14d`,
@@ -475,13 +550,12 @@ describe("V4MigrationDetailsContent", () => {
).not.toBeInTheDocument();
});
- it("hides Update SDK when current-major SDKs only need a recommended bump", () => {
+ it("hides Update SDK when every SDK series is already compatible", () => {
mocks.migrationData.sdk = {
status: "latest",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "4.6.9",
- v4MigrationStatus: "upgrade_recommended",
}),
],
upgradeRequiredCount: 0,
@@ -491,11 +565,11 @@ describe("V4MigrationDetailsContent", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
- expect(screen.queryByText("Python 4.6.9")).not.toBeInTheDocument();
- expect(
- screen.queryByText("· recommended to upgrade to >= 4.7.0"),
- ).not.toBeInTheDocument();
expect(screen.queryByText(/needs an update/)).not.toBeInTheDocument();
+ expect(
+ screen.getByText("Detected V4-compatible instrumentation"),
+ ).toBeInTheDocument();
+ expect(screen.getByText("Python 4.6.9")).toBeInTheDocument();
});
it("keeps outdated SDK usage surfaced when a newer version later used the same key", () => {
@@ -507,7 +581,6 @@ describe("V4MigrationDetailsContent", () => {
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
- v4MigrationStatus: "upgrade_required",
firstSeen: "2026-07-20T09:00:00Z",
lastSeen: "2026-07-20T10:00:00Z",
}),
@@ -526,22 +599,24 @@ describe("V4MigrationDetailsContent", () => {
within(screen.getByText("Update SDK").closest("button")!).getByText("1"),
).toBeInTheDocument();
expect(screen.getByText("Python 2.60.3")).toBeInTheDocument();
- expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
expect(screen.getByText(/upgrade required/)).toBeInTheDocument();
expect(screen.queryByText(/upgrade completed/)).not.toBeInTheDocument();
+ // Compatible series are listed under the detected section, not Update SDK.
+ expect(
+ screen.getByText("Detected V4-compatible instrumentation"),
+ ).toBeInTheDocument();
+ expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
});
it("renders the key as plain text when an offender has no observation evidence", () => {
- // A scores-only offender: detection counts score ingestions, but the
- // events table has nothing for this key — a link would open an empty
- // table, so the evidence link must stay hidden.
+ // A series with no events_core rows: a link would open an empty table,
+ // so the evidence link must stay hidden.
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
- v4MigrationStatus: "upgrade_required",
- eventsCount: 0,
+ eventCount: 0,
}),
],
upgradeRequiredCount: 1,
@@ -562,11 +637,10 @@ describe("V4MigrationDetailsContent", () => {
status: "otel_header_required",
sdkUsageSeries: [
makeSdkUsageSeries({
- sdkName: "openlit",
- sdkVersion: "1.35.4",
+ source: "otel-dual-write",
+ sdkName: "unknown",
+ sdkVersion: "unknown",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: true,
publicKey: "",
}),
],
@@ -577,6 +651,7 @@ describe("V4MigrationDetailsContent", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("No API key")).toBeInTheDocument();
+ expect(screen.getByText("Custom instrumentation")).toBeInTheDocument();
const evidenceLink = screen.getByRole("link", {
name: "View observations",
});
@@ -584,8 +659,7 @@ describe("V4MigrationDetailsContent", () => {
"href",
`/project/project-1/observations?filter=${encodeURIComponent(
"ingestionApiKey;stringOptions;;any of;," +
- "ingestionSdkName;stringOptions;;any of;openlit," +
- "ingestionSdkVersion;stringOptions;;any of;1.35.4",
+ "ingestionSource;stringOptions;;any of;otel-dual-write",
)}&dateRange=14d`,
);
expect(evidenceLink).toHaveAttribute("target", "_blank");
@@ -705,25 +779,23 @@ describe("V4MigrationDetailsContent", () => {
);
});
- it("shows delayed OTel exporters and hides the clean SDK section", () => {
+ it("shows delayed OTel exporters and moves realtime OTel to Detected", () => {
mocks.migrationData.sdk = {
status: "otel_header_required",
sdkUsageSeries: [
makeSdkUsageSeries({}),
makeSdkUsageSeries({
+ source: "otel-dual-write",
sdkName: "openlit",
sdkVersion: "1.35.4",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: true,
publicKey: "pk-lf-aaaa000011112222",
}),
makeSdkUsageSeries({
+ source: "otel",
sdkName: "otelcol",
sdkVersion: "0.98.0",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: false,
publicKey: "pk-lf-bbbb333344445555",
}),
],
@@ -741,10 +813,15 @@ describe("V4MigrationDetailsContent", () => {
).toBeInTheDocument();
expect(screen.getByText(/delayed ingestion path/)).toBeInTheDocument();
expect(screen.getByText("openlit 1.35.4")).toBeInTheDocument();
- expect(screen.getByText("otelcol 0.98.0")).toBeInTheDocument();
expect(screen.getByText("· delayed")).toBeInTheDocument();
- expect(screen.getByText("· real-time")).toBeInTheDocument();
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
+ // Compatible SDK + realtime OTel land in the detected section.
+ expect(
+ screen.getByText("Detected V4-compatible instrumentation"),
+ ).toBeInTheDocument();
+ expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
+ expect(screen.getByText("otelcol 0.98.0")).toBeInTheDocument();
+ expect(screen.getByText("· real-time")).toBeInTheDocument();
});
it("keeps Update SDK visible for a recognized SDK with an unparsable version", () => {
@@ -753,7 +830,10 @@ describe("V4MigrationDetailsContent", () => {
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "not-a-version",
+ sdkVersionMajor: null,
+ isValidSdkVersion: false,
v4MigrationStatus: "unknown",
+ actionLevel: "required",
}),
],
upgradeRequiredCount: 0,
@@ -813,11 +893,11 @@ describe("V4MigrationDetailsContent", () => {
status: "unknown",
sdkUsageSeries: [
makeSdkUsageSeries({
+ source: "ingestion-api-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
}),
],
upgradeRequiredCount: 0,
@@ -844,7 +924,8 @@ describe("V4MigrationDetailsContent", () => {
expect(evidenceLink).toHaveAttribute(
"href",
`/project/project-1/observations?filter=${encodeURIComponent(
- "ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef",
+ "ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef," +
+ "ingestionSource;stringOptions;;any of;ingestion-api-dual-write",
)}&dateRange=14d`,
);
expect(evidenceLink).toHaveAttribute("target", "_blank");
@@ -874,12 +955,12 @@ describe("V4MigrationDetailsContent", () => {
status: "unknown",
sdkUsageSeries: [
makeSdkUsageSeries({
+ source: "ingestion-api-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
publicKey: "",
attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
}),
],
upgradeRequiredCount: 0,
diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsx
index ab65b841f5..25912b3790 100644
--- a/web/src/features/v4-migration/V4MigrationContent.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.tsx
@@ -33,9 +33,9 @@ import { cn } from "@/src/utils/tailwind";
import { copyTextToClipboard } from "@/src/utils/clipboard";
import {
formatSdkUpgradeRequirement,
- formatSdkUpgradeRecommendation,
formatSdkVersion,
getCustomInstrumentationSectionState,
+ getDetectedInstrumentationSeries,
getOtelSectionState,
getSdkSectionState,
isActionableSdkSeries,
@@ -54,10 +54,7 @@ import {
import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
import { numberFormatter } from "@/src/utils/numbers";
import { formatCompactRelativeTime } from "@/src/utils/dates";
-import {
- useProject,
- useQueryProjectOrOrganization,
-} from "@/src/features/projects/hooks";
+import { useQueryProjectOrOrganization } from "@/src/features/projects/hooks";
import { V4PreviewToggleRow } from "@/src/features/events/components/V4SidebarToggle";
import {
useEvalUpgradeAssistantPlan,
@@ -139,6 +136,8 @@ function Section({
children,
defaultOpen,
analyticsSection,
+ statusVariant = "action",
+ tone = "default",
}: {
title: string;
/** Number of affected items, shown muted after the title. */
@@ -149,6 +148,10 @@ function Section({
defaultOpen?: boolean;
/** Funnel dimension for the section_expanded event (snake_case). */
analyticsSection: string;
+ statusVariant?: "action" | "done";
+ /** "muted" recesses the trigger to match the settled-checks summary line, so
+ * a section that needs no action does not read as an action item. */
+ tone?: "default" | "muted";
}) {
const capture = usePostHogClientCapture();
return (
@@ -163,8 +166,15 @@ function Section({
}}
>
<CollapsibleTrigger className="group flex w-full items-center gap-2.5 py-2.5 text-left">
- <V4MigrationStatusDot variant="action" />
- <span className="text-foreground flex items-center gap-1.5 text-sm font-bold">
+ <V4MigrationStatusDot variant={statusVariant} />
+ <span
+ className={cn(
+ "flex items-center gap-1.5 text-sm",
+ tone === "muted"
+ ? "text-muted-foreground"
+ : "text-foreground font-bold",
+ )}
+ >
{title}
{typeof count === "number" && (
// Same count-badge recipe as the "My Views" table button.
@@ -217,12 +227,11 @@ function ExternalLink({
}
// Evidence deep-link filter for one SDK usage series: always the exact public
-// key (including the empty value used by raw OTel ingestion), plus the
+// key (including the empty value used by raw OTel ingestion), source, plus the
// ingestion SDK name/version when the series carries exact values — so two SDK
// versions on the same key link to distinct result sets.
// "unknown" is the attribution fallback bucket, not an exact value, so those
-// dimensions fall back to key-only. The delayed-OTel `source` dimension is
-// deliberately not linked either: it is a prefix match, not an exact one.
+// dimensions fall back to key + source.
function buildSdkUsageEvidenceFilter(usage: V4MigrationSdkUsageSeries): string {
const filters: FilterState = [
{
@@ -231,6 +240,12 @@ function buildSdkUsageEvidenceFilter(usage: V4MigrationSdkUsageSeries): string {
operator: "any of",
value: [usage.publicKey],
},
+ {
+ column: "ingestionSource",
+ type: "stringOptions",
+ operator: "any of",
+ value: [usage.source],
+ },
];
if (usage.sdkName !== "unknown") {
filters.push({
@@ -320,7 +335,7 @@ function SdkUsageSeriesRows({
series,
needsAction,
suffix,
- unknownSeriesLabel = "OTLP exporter",
+ unknownSeriesLabel = "Custom instrumentation",
hideMissingApiKey = false,
projectId,
analyticsSection,
@@ -359,7 +374,7 @@ function SdkUsageSeriesRows({
? null
: "No API key";
const evidenceHref =
- projectId && usage.eventsCount > 0
+ projectId && usage.eventCount > 0
? `/project/${projectId}/observations?filter=${encodeURIComponent(
buildSdkUsageEvidenceFilter(usage),
)}&dateRange=${V4_MIGRATION_LOOKBACK_DAYS}d`
@@ -367,7 +382,7 @@ function SdkUsageSeriesRows({
return (
<li
- key={`${usage.sdkName}:${usage.sdkVersion}:${usage.publicKey}`}
+ key={`${usage.source}:${usage.sdkName}:${usage.sdkVersion}:${usage.publicKey}`}
// Message-box style: soft fill + a thicker left edge to group the
// two lines of one item.
className="bg-muted/50 border-border rounded-md border-l-4 p-2 text-sm"
@@ -390,8 +405,7 @@ function SdkUsageSeriesRows({
{/* Deep link to the exact evidence: the events table filtered by
this public key, plus SDK name and version when attributed,
over the detection lookback. An empty public key is an exact
- filter value for raw OTel ingestion; scores-only offenders
- stay unlinked because their target would be empty. */}
+ filter value for raw OTel ingestion. */}
{evidenceHref ? (
<>
<span aria-hidden="true">·</span>
@@ -442,12 +456,7 @@ export function V4MigrationSdkSection({
projectId?: string;
}) {
const section = getSdkSectionState(sdk);
- if (
- section.status === "latest" ||
- section.status === "recommended" ||
- section.status === "no_data"
- )
- return null;
+ if (section.status === "latest" || section.status === "no_data") return null;
const isTransient =
section.status === "checking" || section.status === "error";
@@ -500,11 +509,7 @@ export function V4MigrationSdkSection({
needsAction={isActionableSdkSeries}
suffix={(usage) =>
usage.v4MigrationStatus === "upgrade_required" ? (
- <span>· {formatSdkUpgradeRequirement(usage.canonicalSdkName)}</span>
- ) : usage.v4MigrationStatus === "upgrade_recommended" ? (
- <span>
- · {formatSdkUpgradeRecommendation(usage.canonicalSdkName)}
- </span>
+ <span>· {formatSdkUpgradeRequirement(usage.latestSdkMajor)}</span>
) : usage.v4MigrationStatus === "unknown" ? (
<span>· version not recognized</span>
) : null
@@ -558,9 +563,9 @@ export function V4MigrationOtelSection({
series={section.series}
projectId={projectId}
analyticsSection="otel"
- needsAction={(usage) => usage.hasDelayedOtelEvents === true}
+ needsAction={(usage) => usage.actionLevel === "required"}
suffix={(usage) =>
- usage.hasDelayedOtelEvents === true ? (
+ usage.deliveryMode === "delayed" ? (
<span>· delayed</span>
) : (
<span>· real-time</span>
@@ -636,6 +641,45 @@ export function V4MigrationCustomInstrumentationSection({
);
}
+export function V4MigrationDetectedInstrumentationSection({
+ sdk,
+ projectId,
+}: {
+ sdk: V4MigrationSdkState;
+ projectId?: string;
+}) {
+ const series = getDetectedInstrumentationSeries(sdk);
+ if (series.length === 0) return null;
+
+ return (
+ <Section
+ title="Detected V4-compatible instrumentation"
+ analyticsSection="detected_instrumentation"
+ count={series.length}
+ statusVariant="done"
+ tone="muted"
+ >
+ <p className="text-muted-foreground text-sm leading-relaxed">
+ These configurations are already on the latest SDK major or use
+ real-time OTel ingestion.
+ </p>
+ <SdkUsageSeriesRows
+ series={series}
+ projectId={projectId}
+ analyticsSection="detected_instrumentation"
+ needsAction={() => false}
+ suffix={(usage) =>
+ usage.remediationType === "update_sdk" ? (
+ <span>· up to date</span>
+ ) : (
+ <span>· real-time</span>
+ )
+ }
+ />
+ </Section>
+ );
+}
+
// The four checker sections below are presentational (data via props) so the
// state gallery story can render every variant without tRPC or router mocks.
@@ -1256,10 +1300,8 @@ export function V4MigrationDetailsContent({
const projectId =
projectIdProp ??
(typeof routeProjectId === "string" ? routeProjectId : undefined);
- const { organization } = useProject(projectId ?? null);
const migrationData = useProjectV4MigrationData({
projectId,
- orgId: organization?.id,
enabled: Boolean(projectId),
});
const { canToggleV4, isBetaEnabled } = useV4Beta();
@@ -1357,7 +1399,6 @@ export function V4MigrationDetailsContent({
const [evalMigrationDialogOpen, setEvalMigrationDialogOpen] = useState(false);
const upgradePlan = useEvalUpgradeAssistantPlan({
projectId,
- orgId: organization?.id,
enabled: Boolean(projectId),
});
const evalsUrl =
@@ -1445,6 +1486,11 @@ export function V4MigrationDetailsContent({
{cleanSummary}
</p>
)}
+
+ <V4MigrationDetectedInstrumentationSection
+ sdk={migrationData.sdk}
+ projectId={evidenceProjectId}
+ />
</div>
</div>
diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
index 24b0c8e82a..45ed5ce7fb 100644
--- a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
@@ -8,45 +8,107 @@ import {
} from "./sdkVersionStatus";
const makeSdkUsageSeries = (
- overrides: Partial<V4MigrationSdkUsageSeries>,
-): V4MigrationSdkUsageSeries => ({
- sdkName: "python",
- sdkVersion: "4.7.1",
- canonicalSdkName: "python",
- publicKey: "pk-lf-1234567890abcdef",
- count: 10,
- eventsCount: 10,
- firstSeen: "2026-07-20T10:00:00Z",
- lastSeen: "2026-07-23T10:00:00Z",
- hasDelayedOtelEvents: null,
- attributionStatus: "attributed",
- v4MigrationStatus: "compatible",
- ...overrides,
-});
+ overrides: Partial<V4MigrationSdkUsageSeries> = {},
+): V4MigrationSdkUsageSeries => {
+ const source = overrides.source ?? "ingestion-api-dual-write";
+ const ingestionPath =
+ overrides.ingestionPath ??
+ (source === "ingestion-api-dual-write" ? "ingestion_api" : "otel");
+ const deliveryMode =
+ overrides.deliveryMode ?? (source === "otel" ? "realtime" : "delayed");
+ const sdkName = overrides.sdkName ?? "python";
+ const sdkVersion = overrides.sdkVersion ?? "4.7.1";
+ const canonicalSdkName =
+ overrides.canonicalSdkName !== undefined
+ ? overrides.canonicalSdkName
+ : sdkName === "python"
+ ? "python"
+ : sdkName === "javascript" || sdkName.startsWith("@langfuse/")
+ ? "javascript"
+ : null;
+ const sdkVersionMajor =
+ overrides.sdkVersionMajor !== undefined
+ ? overrides.sdkVersionMajor
+ : Number(sdkVersion.match(/^v?(\d+)/)?.[1] ?? NaN);
+ const resolvedMajor = Number.isFinite(sdkVersionMajor)
+ ? Number(sdkVersionMajor)
+ : null;
+ const latestMajor =
+ canonicalSdkName === "python"
+ ? 4
+ : canonicalSdkName === "javascript"
+ ? 5
+ : null;
+ const v4MigrationStatus =
+ overrides.v4MigrationStatus ??
+ (canonicalSdkName === null || resolvedMajor === null
+ ? "unknown"
+ : resolvedMajor >= (latestMajor ?? 0)
+ ? "compatible"
+ : "upgrade_required");
+ const remediationType =
+ overrides.remediationType ??
+ (canonicalSdkName !== null
+ ? "update_sdk"
+ : ingestionPath === "otel"
+ ? "update_otel_instrumentation"
+ : "upgrade_instrumentation");
+ const actionLevel =
+ overrides.actionLevel ??
+ (remediationType === "update_sdk"
+ ? v4MigrationStatus === "compatible"
+ ? "none"
+ : "required"
+ : remediationType === "update_otel_instrumentation"
+ ? deliveryMode === "realtime"
+ ? "none"
+ : "required"
+ : "required");
+
+ return {
+ source,
+ ingestionPath,
+ deliveryMode,
+ sdkName,
+ sdkVersion,
+ canonicalSdkName,
+ sdkVersionMajor: resolvedMajor,
+ latestSdkMajor:
+ overrides.latestSdkMajor !== undefined
+ ? overrides.latestSdkMajor
+ : latestMajor,
+ isValidSdkVersion: overrides.isValidSdkVersion ?? resolvedMajor !== null,
+ publicKey: overrides.publicKey ?? "pk-lf-1234567890abcdef",
+ eventCount: overrides.eventCount ?? 10,
+ firstSeen: overrides.firstSeen ?? "2026-07-20T10:00:00Z",
+ lastSeen: overrides.lastSeen ?? "2026-07-23T10:00:00Z",
+ attributionStatus: overrides.attributionStatus ?? "attributed",
+ v4MigrationStatus,
+ remediationType,
+ actionLevel,
+ };
+};
const outdatedSdkSeries = () =>
makeSdkUsageSeries({
sdkVersion: "2.60.3",
- v4MigrationStatus: "upgrade_required",
});
const delayedOtelSeries = () =>
makeSdkUsageSeries({
+ source: "otel-dual-write",
sdkName: "openlit",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: true,
publicKey: "pk-lf-otel-1234567890",
});
const customIngestionSeries = () =>
makeSdkUsageSeries({
+ source: "ingestion-api-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: null,
publicKey: "pk-lf-custom-123456789",
});
@@ -118,11 +180,14 @@ const setSdk = (
status,
sdkUsageSeries: series,
upgradeRequiredCount: series.filter(
- (usage) => usage.v4MigrationStatus === "upgrade_required",
+ (usage) =>
+ usage.remediationType === "update_sdk" &&
+ usage.actionLevel === "required",
).length,
delayedOtelIngestionCount: series.filter(
(usage) =>
- usage.canonicalSdkName === null && usage.hasDelayedOtelEvents === true,
+ usage.remediationType === "update_otel_instrumentation" &&
+ usage.actionLevel === "required",
).length,
};
};
@@ -182,14 +247,22 @@ describe("V4MigrationDelayBadge", () => {
});
it("stays hidden when an SDK version is merely unrecognized", () => {
- // An unparsable version puts the series in the panel's Update SDK
- // section for review, but is no proof of delayed ingestion.
- setSdk("unknown", [
- makeSdkUsageSeries({
- sdkVersion: "not-semver",
- v4MigrationStatus: "unknown",
- }),
- ]);
+ // An unparsable version can still be a panel review item, but the delay
+ // badge only fires for confirmed-outdated majors (upgradeRequiredCount).
+ mocks.sdk = {
+ status: "unknown",
+ sdkUsageSeries: [
+ makeSdkUsageSeries({
+ sdkVersion: "not-semver",
+ sdkVersionMajor: null,
+ isValidSdkVersion: false,
+ v4MigrationStatus: "unknown",
+ actionLevel: "required",
+ }),
+ ],
+ upgradeRequiredCount: 0,
+ delayedOtelIngestionCount: 0,
+ };
render(<V4MigrationDelayBadge />);
expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();
});
diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.tsx
index 5cdcfab7ae..0925741c93 100644
--- a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx
+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.tsx
@@ -26,7 +26,7 @@ import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
export function V4MigrationDelayBadge() {
const v4UpgradeUiFlagEnabled = useV4UpgradeUiFlag();
const openMigrationPanel = useOpenV4MigrationPanel();
- const { project, organization } = useQueryProject();
+ const { project } = useQueryProject();
const forceV3 = useForceV3Experience(project?.id);
const { isBetaEnabled } = useV4Beta();
const capture = usePostHogClientCapture();
@@ -36,7 +36,6 @@ export function V4MigrationDelayBadge() {
const enabled = v4UpgradeUiFlagEnabled && (!forceV3 || isBetaEnabled);
const sdk = useProjectV4SdkData({
projectId: project?.id,
- orgId: organization?.id,
enabled: enabled && Boolean(project),
});
@@ -94,12 +93,11 @@ export function V4MigrationDelayBadge() {
/** Shared gating for the eval "Action required" badges: v4 upgrade UI flag,
* project context, and a loaded, non-zero deprecated-eval count. */
function useEvalUpdateRequiredBadgeState() {
- const { project, organization } = useQueryProject();
+ const { project } = useQueryProject();
const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
const enabled = v4UpgradeUiEnabled && Boolean(project);
const evalState = useProjectV4EvalData({
projectId: project?.id,
- orgId: organization?.id,
enabled,
});
@@ -109,7 +107,7 @@ function useEvalUpdateRequiredBadgeState() {
evalState.status === "loaded" &&
evalState.count > 0;
- return { project, organization, enabled, visible };
+ return { project, enabled, visible };
}
/** Opens the evaluator migration choices from the v4 migration badge. */
@@ -117,11 +115,9 @@ export function V4MigrationUpdateRequiredBadge() {
const router = useRouter();
const [dialogOpen, setDialogOpen] = useState(false);
const capture = usePostHogClientCapture();
- const { project, visible, enabled, organization } =
- useEvalUpdateRequiredBadgeState();
+ const { project, visible, enabled } = useEvalUpdateRequiredBadgeState();
const upgradePlan = useEvalUpgradeAssistantPlan({
projectId: project?.id,
- orgId: organization?.id,
enabled,
});
diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsx
index a0d61b789e..4692ba8efc 100644
--- a/web/src/features/v4-migration/V4MigrationNavItem.tsx
+++ b/web/src/features/v4-migration/V4MigrationNavItem.tsx
@@ -8,14 +8,13 @@ import { getProjectMigrationReadiness } from "@/src/features/v4-migration/migrat
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
export function V4MigrationNavItem() {
- const { project, organization } = useQueryProject();
+ const { project } = useQueryProject();
const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);
const openMigrationPanel = useOpenV4MigrationPanel();
const { isMobile, setOpenMobile: setOpenMobileSidebar } = useSidebar();
const capture = usePostHogClientCapture();
const migrationData = useProjectV4MigrationData({
projectId: project?.id,
- orgId: organization?.id,
enabled: v4UpgradeUiEnabled && Boolean(project),
});
diff --git a/web/src/features/v4-migration/V4MigrationPanel.tsx b/web/src/features/v4-migration/V4MigrationPanel.tsx
index c31135acb5..60b8e561c2 100644
--- a/web/src/features/v4-migration/V4MigrationPanel.tsx
+++ b/web/src/features/v4-migration/V4MigrationPanel.tsx
@@ -2,7 +2,7 @@
import { X } from "lucide-react";
import { Button } from "@/src/components/ui/button";
import { useV4MigrationPanel } from "@/src/features/v4-migration/V4MigrationPanelProvider";
-import { useProject, useQueryProject } from "@/src/features/projects/hooks";
+import { useQueryProject } from "@/src/features/projects/hooks";
import {
V4MigrationHeaderContent,
V4MigrationDetailsContent,
@@ -34,10 +34,8 @@ export const V4MigrationPanel = ({
: undefined,
}
: targetProject;
- const { organization } = useProject(project?.id ?? null);
const migrationData = useProjectV4MigrationData({
projectId: project?.id,
- orgId: organization?.id,
enabled: open && Boolean(project?.id),
});
const liveReadiness = getProjectMigrationReadiness(migrationData);
diff --git a/web/src/features/v4-migration/V4MigrationSections.stories.tsx b/web/src/features/v4-migration/V4MigrationSections.stories.tsx
index 7b54f552e8..4a1adf5909 100644
--- a/web/src/features/v4-migration/V4MigrationSections.stories.tsx
+++ b/web/src/features/v4-migration/V4MigrationSections.stories.tsx
@@ -4,6 +4,7 @@ import preview from "../../../.storybook/preview";
import {
V4MigrationApisSection,
V4MigrationCustomInstrumentationSection,
+ V4MigrationDetectedInstrumentationSection,
V4MigrationEvalsSection,
V4MigrationExperimentsSection,
V4MigrationIntegrationsSection,
@@ -18,21 +19,88 @@ import {
const HOUR_MS = 60 * 60 * 1000;
const makeSeries = (
- overrides: Partial<V4MigrationSdkUsageSeries>,
-): V4MigrationSdkUsageSeries => ({
- sdkName: "python",
- sdkVersion: "4.7.1",
- canonicalSdkName: "python",
- publicKey: "pk-lf-1234567890abcdef",
- count: 10,
- eventsCount: 10,
- firstSeen: new Date(Date.now() - 72 * HOUR_MS).toISOString(),
- lastSeen: new Date(Date.now() - 19 * HOUR_MS).toISOString(),
- hasDelayedOtelEvents: null,
- attributionStatus: "attributed",
- v4MigrationStatus: "compatible",
- ...overrides,
-});
+ overrides: Partial<V4MigrationSdkUsageSeries> = {},
+): V4MigrationSdkUsageSeries => {
+ const source = overrides.source ?? "ingestion-api-dual-write";
+ const ingestionPath =
+ overrides.ingestionPath ??
+ (source === "ingestion-api-dual-write" ? "ingestion_api" : "otel");
+ const deliveryMode =
+ overrides.deliveryMode ?? (source === "otel" ? "realtime" : "delayed");
+ const sdkName = overrides.sdkName ?? "python";
+ const sdkVersion = overrides.sdkVersion ?? "4.7.1";
+ const canonicalSdkName =
+ overrides.canonicalSdkName !== undefined
+ ? overrides.canonicalSdkName
+ : sdkName === "python"
+ ? "python"
+ : sdkName === "javascript" || sdkName.startsWith("@langfuse/")
+ ? "javascript"
+ : null;
+ const sdkVersionMajor =
+ overrides.sdkVersionMajor !== undefined
+ ? overrides.sdkVersionMajor
+ : Number(sdkVersion.match(/^v?(\d+)/)?.[1] ?? NaN);
+ const resolvedMajor = Number.isFinite(sdkVersionMajor)
+ ? Number(sdkVersionMajor)
+ : null;
+ const latestMajor =
+ canonicalSdkName === "python"
+ ? 4
+ : canonicalSdkName === "javascript"
+ ? 5
+ : null;
+ const v4MigrationStatus =
+ overrides.v4MigrationStatus ??
+ (canonicalSdkName === null || resolvedMajor === null
+ ? "unknown"
+ : resolvedMajor >= (latestMajor ?? 0)
+ ? "compatible"
+ : "upgrade_required");
+ const remediationType =
+ overrides.remediationType ??
+ (canonicalSdkName !== null
+ ? "update_sdk"
+ : ingestionPath === "otel"
+ ? "update_otel_instrumentation"
+ : "upgrade_instrumentation");
+ const actionLevel =
+ overrides.actionLevel ??
+ (remediationType === "update_sdk"
+ ? v4MigrationStatus === "compatible"
+ ? "none"
+ : "required"
+ : remediationType === "update_otel_instrumentation"
+ ? deliveryMode === "realtime"
+ ? "none"
+ : "required"
+ : "required");
+
+ return {
+ source,
+ ingestionPath,
+ deliveryMode,
+ sdkName,
+ sdkVersion,
+ canonicalSdkName,
+ sdkVersionMajor: resolvedMajor,
+ latestSdkMajor:
+ overrides.latestSdkMajor !== undefined
+ ? overrides.latestSdkMajor
+ : latestMajor,
+ isValidSdkVersion: overrides.isValidSdkVersion ?? resolvedMajor !== null,
+ publicKey: overrides.publicKey ?? "pk-lf-1234567890abcdef",
+ eventCount: overrides.eventCount ?? 10,
+ firstSeen:
+ overrides.firstSeen ?? new Date(Date.now() - 72 * HOUR_MS).toISOString(),
+ lastSeen:
+ overrides.lastSeen ?? new Date(Date.now() - 19 * HOUR_MS).toISOString(),
+ attributionStatus: overrides.attributionStatus ?? "attributed",
+ v4MigrationStatus,
+ remediationType,
+ actionLevel,
+ };
+};
const makeSdkState = (
overrides: Partial<V4MigrationSdkState>,
@@ -46,78 +114,68 @@ const makeSdkState = (
const outdatedPython = makeSeries({
sdkVersion: "2.60.3",
- v4MigrationStatus: "upgrade_required",
});
-// Scores-only offender: detection sees its score ingestions but the events
-// table has nothing for it, so the key renders as plain text, not a link.
+// Series with no observation evidence: the key renders as plain text, not a link.
const scoresOnlyPython = makeSeries({
sdkVersion: "2.44.0",
- v4MigrationStatus: "upgrade_required",
publicKey: "pk-lf-scores-only-0001",
- eventsCount: 0,
+ eventCount: 0,
});
const outdatedJavascript = makeSeries({
sdkName: "javascript",
sdkVersion: "3.38.5",
canonicalSdkName: "javascript",
- v4MigrationStatus: "upgrade_required",
publicKey: "pk-lf-fedcba0987654321",
});
-const recommendedPython = makeSeries({
+const compatiblePython = makeSeries({
sdkVersion: "4.6.9",
- v4MigrationStatus: "upgrade_recommended",
- publicKey: "pk-lf-recommended-0001",
+ publicKey: "pk-lf-compatible-0001",
lastSeen: new Date(Date.now() - 2 * HOUR_MS).toISOString(),
});
const unrecognizedSdk = makeSeries({
sdkName: "my-custom-wrapper",
sdkVersion: "0.4.0",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
publicKey: "pk-lf-4444555566667777",
});
const delayedOtelExporter = makeSeries({
+ source: "otel-dual-write",
sdkName: "openlit",
sdkVersion: "1.35.4",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: true,
publicKey: "pk-lf-aaaa000011112222",
lastSeen: new Date(Date.now() - 0.25 * HOUR_MS).toISOString(),
});
const unnamedDelayedOtelExporter = makeSeries({
+ source: "otel-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: true,
publicKey: "pk-lf-8888999900001111",
});
const realtimeOtelExporter = makeSeries({
+ source: "otel",
sdkName: "otelcol",
sdkVersion: "0.98.0",
canonicalSdkName: null,
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: false,
publicKey: "pk-lf-bbbb333344445555",
lastSeen: new Date(Date.now() - 70 * HOUR_MS).toISOString(),
});
// Ingestion-API traffic without a Langfuse SDK header: custom instrumentation
// or an SDK too old to send attribution headers.
const customInstrumentation = makeSeries({
+ source: "ingestion-api-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: null,
publicKey: "pk-lf-cccc666677778888",
});
const sdkOutdatedState = makeSdkState({
status: "legacy",
sdkUsageSeries: [
- recommendedPython,
+ compatiblePython,
outdatedPython,
scoresOnlyPython,
outdatedJavascript,
@@ -146,6 +204,11 @@ const customInstrumentationState = makeSdkState({
sdkUsageSeries: [customInstrumentation],
});
+const detectedInstrumentationState = makeSdkState({
+ status: "latest",
+ sdkUsageSeries: [makeSeries({}), realtimeOtelExporter],
+});
+
const combinedState = makeSdkState({
status: "legacy",
sdkUsageSeries: [
@@ -153,6 +216,7 @@ const combinedState = makeSdkState({
delayedOtelExporter,
realtimeOtelExporter,
customInstrumentation,
+ makeSeries({}),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 1,
@@ -213,6 +277,14 @@ export const UpgradeInstrumentation = meta.story({
),
});
+export const DetectedInstrumentation = meta.story({
+ render: () => (
+ <V4MigrationDetectedInstrumentationSection
+ sdk={detectedInstrumentationState}
+ />
+ ),
+});
+
export const EvalsDeprecated = meta.story({
render: () => (
<V4MigrationEvalsSection
@@ -255,18 +327,17 @@ export const IntegrationsDeprecated = meta.story({
),
});
-// All sections hide themselves when nothing needs action; the empty output
-// here is the intended state, not a broken story.
+// Action sections hide when nothing needs action; Detected still surfaces
+// compatible SDK / realtime OTel rows with path labels.
export const HiddenWhenClean = meta.story({
render: () => {
- const sdk = makeSdkState({
- sdkUsageSeries: [makeSeries({}), realtimeOtelExporter],
- });
+ const sdk = detectedInstrumentationState;
return (
<div>
<V4MigrationSdkSection sdk={sdk} />
<V4MigrationOtelSection sdk={sdk} />
<V4MigrationCustomInstrumentationSection sdk={sdk} />
+ <V4MigrationDetectedInstrumentationSection sdk={sdk} />
</div>
);
},
@@ -310,7 +381,7 @@ export const VariantMatrix = meta.story({
/>,
],
[
- "5. OTel header required (delayed, unnamed, real-time exporters)",
+ "5. OTel header required (delayed exporters only)",
<V4MigrationOtelSection
key="5"
sdk={otelHeaderRequiredState}
@@ -326,9 +397,16 @@ export const VariantMatrix = meta.story({
/>,
],
[
- "7. Evals deprecated (assistant can migrate)",
- <V4MigrationEvalsSection
+ "7. Detected V4-compatible instrumentation (compatible SDK + realtime OTel)",
+ <V4MigrationDetectedInstrumentationSection
key="7"
+ sdk={detectedInstrumentationState}
+ />,
+ ],
+ [
+ "8. Evals deprecated (assistant can migrate)",
+ <V4MigrationEvalsSection
+ key="8"
state={{ status: "loaded", count: 3 }}
assistant={{ onMigrate: fn() }}
evalsUrl="/project/demo/evals"
@@ -336,9 +414,9 @@ export const VariantMatrix = meta.story({
/>,
],
[
- "8. Evals deprecated, single (assistant plans the order, no auto-migrate)",
+ "9. Evals deprecated, single (assistant plans the order, no auto-migrate)",
<V4MigrationEvalsSection
- key="8"
+ key="9"
state={{ status: "loaded", count: 1 }}
assistant={{ onMigrate: fn() }}
evalsUrl="/project/demo/evals"
@@ -346,45 +424,45 @@ export const VariantMatrix = meta.story({
/>,
],
[
- "9. Experiments update required (deprecated API call)",
+ "10. Experiments update required (deprecated API call)",
<V4MigrationExperimentsSection
- key="9"
+ key="10"
state={{ status: "loaded", result: "required" }}
upgradePath="api"
defaultOpen
/>,
],
[
- "10. Experiments update required (outdated SDK)",
+ "11. Experiments update required (outdated SDK)",
<V4MigrationExperimentsSection
- key="10"
+ key="11"
state={{ status: "loaded", result: "required" }}
upgradePath="sdk"
defaultOpen
/>,
],
[
- "11. Experiments needs review (inconclusive SDK usage)",
+ "12. Experiments needs review (inconclusive SDK usage)",
<V4MigrationExperimentsSection
- key="11"
+ key="12"
state={{ status: "loaded", result: "sdk_usage_inconclusive" }}
upgradePath="sdk"
defaultOpen
/>,
],
[
- "12. Deprecated APIs called",
+ "13. Deprecated APIs called",
<V4MigrationApisSection
- key="12"
+ key="13"
state={{ status: "loaded", count: apiUsage.length }}
usage={apiUsage}
defaultOpen
/>,
],
[
- "13. Deprecated integrations exporting",
+ "14. Deprecated integrations exporting",
<V4MigrationIntegrationsSection
- key="13"
+ key="14"
state={{ status: "loaded", count: integrations.length }}
integrations={integrations}
integrationsUrl="/project/demo/settings/integrations"
@@ -392,38 +470,39 @@ export const VariantMatrix = meta.story({
/>,
],
[
- "14. Checker still loading (evals shown; same chip on all checkers)",
+ "15. Checker still loading (evals shown; same chip on all checkers)",
<V4MigrationEvalsSection
- key="14"
+ key="15"
state={{ status: "loading", count: 0 }}
assistant={null}
defaultOpen
/>,
],
[
- "15. Checker failed (evals shown; same chip on all checkers)",
+ "16. Checker failed (evals shown; same chip on all checkers)",
<V4MigrationEvalsSection
- key="15"
+ key="16"
state={{ status: "error", count: 0 }}
assistant={null}
defaultOpen
/>,
],
[
- "16. Clean sections collapse into one summary line",
- <p key="16" className="text-muted-foreground py-1.5 text-sm">
+ "17. Clean sections collapse into one summary line",
+ <p key="17" className="text-muted-foreground py-1.5 text-sm">
Evals, experiments, APIs and integrations are up to date.
</p>,
],
[
- "17. Everything at once",
- <div key="17">
+ "18. Everything at once",
+ <div key="18">
<V4MigrationSdkSection sdk={combinedState} defaultOpen />
<V4MigrationOtelSection sdk={combinedState} defaultOpen />
<V4MigrationCustomInstrumentationSection
sdk={combinedState}
defaultOpen
/>
+ <V4MigrationDetectedInstrumentationSection sdk={combinedState} />
<V4MigrationEvalsSection
state={{ status: "loaded", count: 2 }}
assistant={{ onMigrate: fn() }}
diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts
index cefd0dba44..6235c1b358 100644
--- a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts
+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts
@@ -42,16 +42,23 @@ const loadedQuery = <T>(data: T) => ({
});
const currentSdkSeries = {
+ source: "ingestion-api-dual-write" as const,
+ ingestionPath: "ingestion_api" as const,
+ deliveryMode: "delayed" as const,
sdkName: "python",
sdkVersion: "4.7.0",
canonicalSdkName: "python" as const,
+ sdkVersionMajor: 4,
+ latestSdkMajor: 4,
+ isValidSdkVersion: true,
publicKey: "pk-lf-python",
- count: 1,
+ eventCount: 1,
firstSeen: "2026-07-23T09:00:00Z",
lastSeen: "2026-07-23T10:00:00Z",
- hasDelayedOtelEvents: true,
attributionStatus: "attributed" as const,
v4MigrationStatus: "compatible" as const,
+ remediationType: "update_sdk" as const,
+ actionLevel: "none" as const,
};
describe("account v4 migration data", () => {
@@ -103,11 +110,13 @@ describe("account v4 migration data", () => {
projectId: "project-1",
entrypoint: "publicapi: GET /api/public/traces",
count: 4,
+ lastSeen: "2026-07-23T10:00:00Z",
},
{
projectId: "project-1",
entrypoint: "publicapi: GET /api/public/sessions",
count: 2,
+ lastSeen: "2026-07-23T09:30:00Z",
},
]),
],
diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.ts
index 4df5b195ba..52c0430708 100644
--- a/web/src/features/v4-migration/hooks/useV4MigrationData.ts
+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.ts
@@ -1,9 +1,11 @@
import { useState } from "react";
import { api } from "@/src/utils/api";
-import { countLegacyApiEntrypoints } from "@/src/features/v4/utils";
import {
- aggregateLegacyApiUsage,
+ countLegacyApiEntrypoints,
+ normalizeLegacyApiEntrypoint,
+} from "@/src/features/v4/utils";
+import {
createV4MigrationDetectionRange,
getLegacyIntegrationLabels,
getMigrationActionState,
@@ -143,15 +145,14 @@ export function useAccountV4MigrationData(params: {
function useProjectV4SdkSummary(params: {
projectId: string | undefined;
- orgId: string | undefined;
enabled: boolean;
}) {
- const { projectId, orgId, enabled } = params;
+ const { projectId, enabled } = params;
const [detectionRange] = useState(createV4MigrationDetectionRange);
- const queryEnabled = enabled && Boolean(projectId) && Boolean(orgId);
- const sdkQuery = api.v4Transition.sdkUsageSummaryByProject.useQuery(
+ const queryEnabled = enabled && Boolean(projectId);
+ const sdkQuery = api.v4Transition.sdkUsageSummary.useQuery(
{
- orgId: orgId ?? "",
+ projectId: projectId ?? "",
...detectionRange,
},
{
@@ -160,14 +161,11 @@ function useProjectV4SdkSummary(params: {
trpc: { context: { skipBatch: true } },
},
);
- const summary = sdkQuery.data?.find((row) => row.projectId === projectId);
-
- return { sdkQuery, summary };
+ return { sdkQuery, summary: sdkQuery.data };
}
export function useProjectV4SdkData(params: {
projectId: string | undefined;
- orgId: string | undefined;
enabled: boolean;
}) {
const { sdkQuery, summary } = useProjectV4SdkSummary(params);
@@ -181,7 +179,6 @@ export function useProjectV4SdkData(params: {
export function useProjectV4EvalData(params: {
projectId: string | undefined;
- orgId: string | undefined;
enabled: boolean;
}) {
const { projectId, enabled } = params;
@@ -195,27 +192,24 @@ export function useProjectV4EvalData(params: {
export function useProjectV4MigrationData(params: {
projectId: string | undefined;
- orgId: string | undefined;
enabled: boolean;
}) {
- const { projectId, orgId, enabled } = params;
+ const { projectId, enabled } = params;
const queryEnabled = enabled && Boolean(projectId);
const [detectionRange] = useState(createV4MigrationDetectionRange);
const forceV3Experience = useForceV3Experience(projectId);
const { sdkQuery, summary: sdkSummary } = useProjectV4SdkSummary({
projectId,
- orgId,
enabled,
});
const evalQuery = api.v4Transition.traceLevelEvalSummary.useQuery(
{ projectId: projectId ?? "" },
{ ...queryOptions, enabled: queryEnabled },
);
- const apiQuery = api.v4Transition.timeSeriesByEntrypoint.useQuery(
+ const apiQuery = api.v4Transition.legacyApiUsageSummary.useQuery(
{
projectId: projectId ?? "",
...detectionRange,
- granularity: "auto",
},
{
...queryOptions,
@@ -228,7 +222,17 @@ export function useProjectV4MigrationData(params: {
{ ...queryOptions, enabled: queryEnabled },
);
- const apiUsage = aggregateLegacyApiUsage(apiQuery.data);
+ const apiUsage = (apiQuery.data ?? [])
+ .map((row) => ({
+ endpoint: normalizeLegacyApiEntrypoint(row.entrypoint),
+ count: row.count,
+ lastSeen: row.lastSeen,
+ }))
+ .sort(
+ (left, right) =>
+ right.lastSeen.localeCompare(left.lastSeen) ||
+ left.endpoint.localeCompare(right.endpoint),
+ );
const legacyIntegrations = getLegacyIntegrationLabels(
integrationQuery.data?.legacyIntegrations,
);
@@ -245,9 +249,7 @@ export function useProjectV4MigrationData(params: {
),
experiments: getMigrationActionState(
sdkQuery,
- (rows) =>
- rows.find((row) => row.projectId === projectId)
- ?.experimentInstrumentationMigration.status ?? "not_required",
+ (summary) => summary.experimentInstrumentationMigration.status,
),
experimentInstrumentationUpgradePath:
sdkSummary?.experimentInstrumentationMigration.upgradePath ?? null,
diff --git a/web/src/features/v4-migration/migrationData.clienttest.ts b/web/src/features/v4-migration/migrationData.clienttest.ts
index 502d8ee6cd..2070c30217 100644
--- a/web/src/features/v4-migration/migrationData.clienttest.ts
+++ b/web/src/features/v4-migration/migrationData.clienttest.ts
@@ -1,5 +1,4 @@
import {
- aggregateLegacyApiUsage,
createV4MigrationDetectionRange,
getLegacyIntegrationLabels,
getMigrationActionState,
@@ -128,48 +127,6 @@ describe("v4 migration data", () => {
).toBe("unavailable");
});
- it("aggregates real API usage by normalized endpoint and sorts most recent first", () => {
- expect(
- aggregateLegacyApiUsage([
- {
- time: "2026-07-23T09:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: 2,
- lastSeen: "2026-07-23T09:42:00Z",
- },
- {
- time: "2026-07-23T10:00:00Z",
- entrypoint: "publicapi: GET /api/public/traces",
- count: 3,
- lastSeen: "2026-07-23T10:37:00Z",
- },
- {
- time: "2026-07-23T10:00:00Z",
- entrypoint: "",
- count: 0,
- lastSeen: null,
- },
- {
- time: "2026-07-23T08:00:00Z",
- entrypoint: "publicapi: GET /api/public/sessions",
- count: 20,
- lastSeen: "2026-07-23T08:37:00Z",
- },
- ]),
- ).toEqual([
- {
- endpoint: "GET /api/public/traces",
- count: 5,
- lastSeen: "2026-07-23T10:37:00Z",
- },
- {
- endpoint: "GET /api/public/sessions",
- count: 20,
- lastSeen: "2026-07-23T08:37:00Z",
- },
- ]);
- });
-
it("returns only enabled legacy integration labels", () => {
expect(
getLegacyIntegrationLabels({
diff --git a/web/src/features/v4-migration/migrationData.ts b/web/src/features/v4-migration/migrationData.ts
index 9adb232c20..0cc152949b 100644
--- a/web/src/features/v4-migration/migrationData.ts
+++ b/web/src/features/v4-migration/migrationData.ts
@@ -1,5 +1,4 @@
import { type RouterOutputs } from "@/src/utils/api";
-import { normalizeLegacyApiEntrypoint } from "@/src/features/v4/utils";
import { type V4MigrationSdkState } from "@/src/features/v4-migration/sdkVersionStatus";
export const V4_MIGRATION_LOOKBACK_DAYS = 14;
@@ -134,46 +133,6 @@ export const getProjectMigrationReadiness = (
return "action-needed";
};
-type LegacyApiUsagePoint =
- RouterOutputs["v4Transition"]["timeSeriesByEntrypoint"][number];
-
-type LegacyApiUsageSummary = {
- endpoint: string;
- count: number;
- lastSeen: string;
-};
-
-export const aggregateLegacyApiUsage = (
- rows: LegacyApiUsagePoint[] | undefined,
-): LegacyApiUsageSummary[] => {
- const usageByEndpoint = new Map<
- string,
- { count: number; lastSeen: string }
- >();
-
- for (const row of rows ?? []) {
- const endpoint = normalizeLegacyApiEntrypoint(row.entrypoint);
- if (!endpoint || row.count <= 0 || !row.lastSeen) continue;
- const current = usageByEndpoint.get(endpoint);
- usageByEndpoint.set(endpoint, {
- count: (current?.count ?? 0) + row.count,
- lastSeen:
- current && current.lastSeen > row.lastSeen
- ? current.lastSeen
- : row.lastSeen,
- });
- }
-
- return Array.from(usageByEndpoint, ([endpoint, usage]) => ({
- endpoint,
- ...usage,
- })).sort(
- (left, right) =>
- right.lastSeen.localeCompare(left.lastSeen) ||
- left.endpoint.localeCompare(right.endpoint),
- );
-};
-
type LegacyIntegrationSummary =
RouterOutputs["v4Transition"]["summary"]["legacyIntegrations"];
diff --git a/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts b/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts
index c7b0dcbef8..3a9d0d4c70 100644
--- a/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts
+++ b/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts
@@ -1,28 +1,134 @@
import {
formatSdkUpgradeRequirement,
- formatSdkUpgradeRecommendation,
- getSdkSectionState,
formatSdkVersion,
+ getCustomInstrumentationSectionState,
+ getDetectedInstrumentationSeries,
+ getOtelSectionState,
+ getSdkSectionState,
getV4MigrationSdkState,
type V4MigrationSdkUsageSeries,
} from "@/src/features/v4-migration/sdkVersionStatus";
const sdkSeries = (
overrides: Partial<V4MigrationSdkUsageSeries> = {},
-): V4MigrationSdkUsageSeries => ({
- sdkName: "python",
- sdkVersion: "4.7.0",
- canonicalSdkName: "python" as const,
- publicKey: "pk-lf-python",
- count: 1,
- eventsCount: 1,
- firstSeen: "2026-07-23T09:00:00Z",
- lastSeen: "2026-07-23T10:00:00Z",
- hasDelayedOtelEvents: false,
- attributionStatus: "attributed" as const,
- v4MigrationStatus: "compatible" as const,
- ...overrides,
-});
+): V4MigrationSdkUsageSeries => {
+ const source = overrides.source ?? "ingestion-api-dual-write";
+ const ingestionPath =
+ overrides.ingestionPath ??
+ (source === "ingestion-api-dual-write" ? "ingestion_api" : "otel");
+ const deliveryMode =
+ overrides.deliveryMode ?? (source === "otel" ? "realtime" : "delayed");
+ const sdkName = overrides.sdkName ?? "python";
+ const sdkVersion = overrides.sdkVersion ?? "4.7.0";
+ const canonicalSdkName =
+ overrides.canonicalSdkName !== undefined
+ ? overrides.canonicalSdkName
+ : sdkName === "python"
+ ? "python"
+ : sdkName === "javascript" || sdkName.startsWith("@langfuse/")
+ ? "javascript"
+ : null;
+ const sdkVersionMajor =
+ overrides.sdkVersionMajor !== undefined
+ ? overrides.sdkVersionMajor
+ : Number(sdkVersion.match(/^v?(\d+)/)?.[1] ?? NaN);
+ const resolvedMajor = Number.isFinite(sdkVersionMajor)
+ ? Number(sdkVersionMajor)
+ : null;
+ const latestMajor =
+ canonicalSdkName === "python"
+ ? 4
+ : canonicalSdkName === "javascript"
+ ? 5
+ : null;
+ const v4MigrationStatus =
+ overrides.v4MigrationStatus ??
+ (canonicalSdkName === null || resolvedMajor === null
+ ? "unknown"
+ : resolvedMajor >= (latestMajor ?? 0)
+ ? "compatible"
+ : "upgrade_required");
+ const remediationType =
+ overrides.remediationType ??
+ (canonicalSdkName !== null
+ ? "update_sdk"
+ : ingestionPath === "otel"
+ ? "update_otel_instrumentation"
+ : "upgrade_instrumentation");
+ const actionLevel =
+ overrides.actionLevel ??
+ (remediationType === "update_sdk"
+ ? v4MigrationStatus === "compatible"
+ ? "none"
+ : "required"
+ : remediationType === "update_otel_instrumentation"
+ ? deliveryMode === "realtime"
+ ? "none"
+ : "required"
+ : "required");
+
+ return {
+ source,
+ ingestionPath,
+ deliveryMode,
+ sdkName,
+ sdkVersion,
+ canonicalSdkName,
+ sdkVersionMajor: resolvedMajor,
+ latestSdkMajor:
+ overrides.latestSdkMajor !== undefined
+ ? overrides.latestSdkMajor
+ : latestMajor,
+ isValidSdkVersion: overrides.isValidSdkVersion ?? resolvedMajor !== null,
+ publicKey: overrides.publicKey ?? "pk-lf-python",
+ eventCount: overrides.eventCount ?? 1,
+ firstSeen: overrides.firstSeen ?? "2026-07-23T09:00:00Z",
+ lastSeen: overrides.lastSeen ?? "2026-07-23T10:00:00Z",
+ attributionStatus: overrides.attributionStatus ?? "attributed",
+ v4MigrationStatus,
+ remediationType,
+ actionLevel,
+ };
+};
+
+const delayedOtelSeries = (
+ overrides: Partial<V4MigrationSdkUsageSeries> = {},
+) =>
+ sdkSeries({
+ source: "otel-dual-write",
+ sdkName: "unknown",
+ sdkVersion: "unknown",
+ canonicalSdkName: null,
+ publicKey: "",
+ attributionStatus: "missing_name_and_version",
+ ...overrides,
+ });
+
+const realtimeOtelSeries = (
+ overrides: Partial<V4MigrationSdkUsageSeries> = {},
+) =>
+ sdkSeries({
+ source: "otel",
+ sdkName: "unknown",
+ sdkVersion: "unknown",
+ canonicalSdkName: null,
+ publicKey: "",
+ attributionStatus: "missing_name_and_version",
+ ...overrides,
+ });
+
+const customIngestionSeries = (
+ overrides: Partial<V4MigrationSdkUsageSeries> = {},
+) =>
+ sdkSeries({
+ source: "ingestion-api-dual-write",
+ sdkName: "unknown",
+ sdkVersion: "unknown",
+ canonicalSdkName: null,
+ publicKey: "pk-lf-custom",
+ attributionStatus: "missing_name_and_version",
+ ...overrides,
+ });
const getLoadedSdkState = (...sdkUsageSeries: ReturnType<typeof sdkSeries>[]) =>
getV4MigrationSdkState({
@@ -44,22 +150,34 @@ describe("v4 migration SDK status", () => {
getLoadedSdkState(
sdkSeries(),
sdkSeries({
- sdkVersion: "4.6.9",
+ sdkVersion: "3.9.0",
publicKey: "pk-lf-old-python",
- v4MigrationStatus: "upgrade_required",
}),
),
).toMatchObject({
status: "legacy",
upgradeRequiredCount: 1,
});
+ expect(
+ getSdkSectionState(
+ getLoadedSdkState(
+ sdkSeries(),
+ sdkSeries({
+ sdkVersion: "3.9.0",
+ publicKey: "pk-lf-old-python",
+ }),
+ ),
+ ),
+ ).toMatchObject({
+ status: "legacy",
+ actionableCount: 1,
+ });
});
- it("treats the current major below the recommended minor as functional", () => {
+ it("treats current-major SDKs as compatible with no action", () => {
const state = getLoadedSdkState(
sdkSeries({
sdkVersion: "4.6.9",
- v4MigrationStatus: "upgrade_recommended",
}),
);
@@ -68,19 +186,24 @@ describe("v4 migration SDK status", () => {
upgradeRequiredCount: 0,
});
expect(getSdkSectionState(state)).toMatchObject({
- status: "recommended",
+ status: "no_data",
actionableCount: 0,
- recommendedCount: 1,
});
+ expect(getDetectedInstrumentationSeries(state)).toEqual([
+ expect.objectContaining({
+ sdkVersion: "4.6.9",
+ actionLevel: "none",
+ remediationType: "update_sdk",
+ }),
+ ]);
});
it("orders SDK usage by most recent last seen", () => {
const state = getLoadedSdkState(
sdkSeries({
- sdkVersion: "4.6.9",
+ sdkVersion: "3.9.0",
publicKey: "pk-lf-older-outdated",
lastSeen: "2026-07-22T10:00:00Z",
- v4MigrationStatus: "upgrade_required",
}),
sdkSeries({
publicKey: "pk-lf-newer-compatible",
@@ -95,40 +218,24 @@ describe("v4 migration SDK status", () => {
});
it("does not require action for raw OTel already using real-time ingestion", () => {
- expect(
- getLoadedSdkState(
- sdkSeries({
- sdkName: "unknown",
- sdkVersion: "unknown",
- canonicalSdkName: null,
- publicKey: "",
- attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: false,
- }),
- ),
- ).toMatchObject({
+ const state = getLoadedSdkState(realtimeOtelSeries());
+ expect(state).toMatchObject({
status: "otel_realtime",
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
});
+ expect(getOtelSectionState(state).delayedCount).toBe(0);
+ expect(getDetectedInstrumentationSeries(state)).toEqual([
+ expect.objectContaining({
+ source: "otel",
+ deliveryMode: "realtime",
+ actionLevel: "none",
+ }),
+ ]);
});
it("requires the ingestion header for delayed raw OTel traffic", () => {
- expect(
- getLoadedSdkState(
- sdkSeries(),
- sdkSeries({
- sdkName: "unknown",
- sdkVersion: "unknown",
- canonicalSdkName: null,
- publicKey: "",
- attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: true,
- }),
- ),
- ).toMatchObject({
+ expect(getLoadedSdkState(sdkSeries(), delayedOtelSeries())).toMatchObject({
status: "otel_header_required",
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 1,
@@ -139,8 +246,7 @@ describe("v4 migration SDK status", () => {
expect(
getLoadedSdkState(
sdkSeries({
- sdkVersion: "4.6.9",
- v4MigrationStatus: "upgrade_required",
+ sdkVersion: "3.9.0",
}),
sdkSeries(),
),
@@ -152,30 +258,32 @@ describe("v4 migration SDK status", () => {
it("keeps custom-instrumentation traffic action-needed despite a compatible SDK", () => {
expect(
- getLoadedSdkState(
- sdkSeries(),
- sdkSeries({
- sdkName: "unknown",
- sdkVersion: "unknown",
- canonicalSdkName: null,
- publicKey: "pk-lf-custom",
- attributionStatus: "missing_name_and_version",
- v4MigrationStatus: "unknown",
- hasDelayedOtelEvents: null,
- }),
- ),
+ getLoadedSdkState(sdkSeries(), customIngestionSeries()),
).toMatchObject({ status: "unknown" });
+ expect(
+ getCustomInstrumentationSectionState(
+ getLoadedSdkState(sdkSeries(), customIngestionSeries()),
+ ).series,
+ ).toHaveLength(1);
});
- it("keeps a recognized SDK with an invalid version unknown", () => {
+ it("treats a recognized SDK with an invalid version as requiring action", () => {
+ // SQL marks invalid versions upgrade-unknown with actionLevel required, so
+ // the combined status follows the upgradeRequiredCount → legacy path.
expect(
getLoadedSdkState(
sdkSeries({
sdkVersion: "invalid",
+ sdkVersionMajor: null,
+ isValidSdkVersion: false,
v4MigrationStatus: "unknown",
+ actionLevel: "required",
}),
),
- ).toMatchObject({ status: "unknown" });
+ ).toMatchObject({
+ status: "legacy",
+ upgradeRequiredCount: 1,
+ });
});
it("distinguishes loading, errors, and a loaded result with no data", () => {
@@ -204,24 +312,13 @@ describe("v4 migration SDK status", () => {
});
it.each([
- ["javascript", "upgrade required to >= 5.0.0"],
- ["python", "upgrade required to >= 4.0.0"],
+ [5, "upgrade required to >= 5.0.0"],
+ [4, "upgrade required to >= 4.0.0"],
[null, "upgrade required"],
] as const)(
- "formats %s upgrade guidance with its minimum compatible version",
- (sdkName, expected) => {
- expect(formatSdkUpgradeRequirement(sdkName)).toBe(expected);
- },
- );
-
- it.each([
- ["javascript", "recommended to upgrade to >= 5.4.0"],
- ["python", "recommended to upgrade to >= 4.7.0"],
- [null, "recommended to upgrade"],
- ] as const)(
- "formats %s recommendation guidance with the preferred minor version",
- (sdkName, expected) => {
- expect(formatSdkUpgradeRecommendation(sdkName)).toBe(expected);
+ "formats latest major %s as upgrade guidance",
+ (latestSdkMajor, expected) => {
+ expect(formatSdkUpgradeRequirement(latestSdkMajor)).toBe(expected);
},
);
});
diff --git a/web/src/features/v4-migration/sdkVersionStatus.ts b/web/src/features/v4-migration/sdkVersionStatus.ts
index 583ebfdda5..abf2036bfa 100644
--- a/web/src/features/v4-migration/sdkVersionStatus.ts
+++ b/web/src/features/v4-migration/sdkVersionStatus.ts
@@ -1,8 +1,5 @@
import { type RouterOutputs } from "@/src/utils/api";
-import {
- getSdkVersionCapabilityMinimum,
- type SdkVersionInfo,
-} from "@/src/features/sdk-version/lib/sdkVersionCapabilities";
+import { type SdkVersionInfo } from "@/src/features/sdk-version/lib/sdkVersionCapabilities";
export type V4MigrationSdkStatus =
| "checking"
@@ -14,8 +11,7 @@ export type V4MigrationSdkStatus =
| "legacy"
| "latest";
-type SdkUsageSummary =
- RouterOutputs["v4Transition"]["sdkUsageSummaryByProject"][number];
+type SdkUsageSummary = RouterOutputs["v4Transition"]["sdkUsageSummary"];
export type V4MigrationSdkUsageSeries =
SdkUsageSummary["sdkUsageSeries"][number];
@@ -30,16 +26,13 @@ export type V4MigrationSdkState = {
const requiresOtelIngestionHeader = (
series: V4MigrationSdkUsageSeries,
): boolean =>
- series.hasDelayedOtelEvents === true && series.canonicalSdkName === null;
+ series.remediationType === "update_otel_instrumentation" &&
+ series.actionLevel === "required";
-// Ingestion-API series without a recognized Langfuse SDK: custom
-// instrumentation against POST /api/public/ingestion, an unrecognized SDK
-// name, or an SDK too old to send attribution headers. (hasDelayedOtelEvents
-// is null for non-OTel ingestion.)
+// SQL owns remediation classification; the client only groups rows for display.
export const isCustomInstrumentationSeries = (
series: V4MigrationSdkUsageSeries,
-): boolean =>
- series.hasDelayedOtelEvents === null && series.canonicalSdkName === null;
+): boolean => series.remediationType === "upgrade_instrumentation";
const sortSdkUsageSeries = (
rows: V4MigrationSdkUsageSeries[],
@@ -66,24 +59,26 @@ export const getV4MigrationSdkState = (params: {
const sdkUsageSeries = sortSdkUsageSeries(params.summary.sdkUsageSeries);
const upgradeRequiredCount = sdkUsageSeries.filter(
- (series) => series.v4MigrationStatus === "upgrade_required",
+ (series) =>
+ series.remediationType === "update_sdk" &&
+ series.actionLevel === "required",
).length;
const delayedOtelIngestionCount = sdkUsageSeries.filter(
requiresOtelIngestionHeader,
).length;
const hasUnknownRecognizedSdk = sdkUsageSeries.some(
(series) =>
- series.canonicalSdkName !== null &&
+ series.remediationType === "update_sdk" &&
series.v4MigrationStatus === "unknown",
);
const hasCompatibleSdk = sdkUsageSeries.some(
(series) =>
- series.v4MigrationStatus === "compatible" ||
- series.v4MigrationStatus === "upgrade_recommended",
+ series.remediationType === "update_sdk" && series.actionLevel === "none",
);
const hasRealtimeOtelIngestion = sdkUsageSeries.some(
(series) =>
- series.canonicalSdkName === null && series.hasDelayedOtelEvents === false,
+ series.remediationType === "update_otel_instrumentation" &&
+ series.actionLevel === "none",
);
// Custom-instrumentation traffic is always an action item in the panel, so
// the combined status must not report the project as fully migrated while
@@ -113,58 +108,41 @@ export const getV4MigrationSdkState = (params: {
};
};
-// A series is an OTel exporter when it has no recognized Langfuse SDK name but
-// arrived through OTel ingestion (hasDelayedOtelEvents is null for non-OTel
-// series). Recognized SDKs that ship via OTLP manage their own headers, so
-// they stay in the SDK bucket.
+// Recognized Langfuse SDK traffic stays in the SDK bucket even when it uses
+// OTLP; raw/third-party OTel is classified separately by SQL.
export const isOtelExporterSeries = (
series: V4MigrationSdkUsageSeries,
-): boolean =>
- series.canonicalSdkName === null && series.hasDelayedOtelEvents !== null;
+): boolean => series.remediationType === "update_otel_instrumentation";
-// Both section states below implement the offender rule: a section renders
-// only while it contains at least one series needing action, but a rendered
-// section lists every series detected on its ingestion path.
+// Action sections contain only SQL-classified required rows. Successful rows
+// are shown separately in the detected-instrumentation section.
export const isActionableSdkSeries = (
series: V4MigrationSdkUsageSeries,
): boolean =>
- series.v4MigrationStatus === "upgrade_required" ||
- // A recognized SDK with an unparsable version still needs the user's
- // attention; without it the section would hide while the project-level
- // status keeps reporting action needed.
- series.v4MigrationStatus === "unknown";
+ series.remediationType === "update_sdk" && series.actionLevel === "required";
export type V4MigrationSdkSectionState = {
/** "latest" and "no_data" mean no relevant rows; the section hides itself.
* Unrecognized SDKs are not mixed in here: they belong to the custom
* instrumentation section. */
- status:
- | "checking"
- | "error"
- | "legacy"
- | "recommended"
- | "latest"
- | "no_data";
- /** All detected recognized-SDK series, most recently seen first. */
+ status: "checking" | "error" | "legacy" | "latest" | "no_data";
+ /** Recognized-SDK series requiring action, most recently seen first. */
series: V4MigrationSdkUsageSeries[];
/** Series needing action: pending upgrades plus unrecognized versions.
* Drives both the section badge and the body copy so they always agree. */
actionableCount: number;
- /** Functional SDKs below the preferred minor version. */
- recommendedCount: number;
};
export const getSdkSectionState = (
sdk: V4MigrationSdkState,
): V4MigrationSdkSectionState => {
const series = sdk.sdkUsageSeries.filter(
- (usage) => usage.canonicalSdkName !== null,
+ (usage) =>
+ usage.remediationType === "update_sdk" &&
+ usage.actionLevel === "required",
);
const actionableCount = series.filter(isActionableSdkSeries).length;
- const recommendedCount = series.filter(
- (usage) => usage.v4MigrationStatus === "upgrade_recommended",
- ).length;
return {
status:
@@ -174,12 +152,9 @@ export const getSdkSectionState = (
? "no_data"
: actionableCount > 0
? "legacy"
- : recommendedCount > 0
- ? "recommended"
- : "latest",
+ : "latest",
series,
actionableCount,
- recommendedCount,
};
};
@@ -195,7 +170,7 @@ export const getCustomInstrumentationSectionState = (
});
export type V4MigrationOtelSectionState = {
- /** All detected OTel exporter series, most recently seen first. */
+ /** Delayed OTel exporter series requiring action, most recently seen first. */
series: V4MigrationSdkUsageSeries[];
delayedCount: number;
};
@@ -203,14 +178,21 @@ export type V4MigrationOtelSectionState = {
export const getOtelSectionState = (
sdk: V4MigrationSdkState,
): V4MigrationOtelSectionState => {
- const series = sdk.sdkUsageSeries.filter(isOtelExporterSeries);
+ const series = sdk.sdkUsageSeries.filter(
+ (usage) => isOtelExporterSeries(usage) && usage.actionLevel === "required",
+ );
return {
series,
- delayedCount: series.filter((usage) => usage.hasDelayedOtelEvents === true)
+ delayedCount: series.filter((usage) => usage.actionLevel === "required")
.length,
};
};
+export const getDetectedInstrumentationSeries = (
+ sdk: V4MigrationSdkState,
+): V4MigrationSdkUsageSeries[] =>
+ sdk.sdkUsageSeries.filter((usage) => usage.actionLevel === "none");
+
export const formatSdkVersion = (sdkVersion: SdkVersionInfo | undefined) => {
if (!sdkVersion?.language || !sdkVersion.version) return null;
@@ -224,28 +206,9 @@ export const formatSdkVersion = (sdkVersion: SdkVersionInfo | undefined) => {
};
export const formatSdkUpgradeRequirement = (
- sdkName: V4MigrationSdkUsageSeries["canonicalSdkName"],
+ latestSdkMajor: V4MigrationSdkUsageSeries["latestSdkMajor"],
) => {
- const minimumVersion = getSdkVersionCapabilityMinimum(
- sdkName,
- "appRootObservations",
- );
-
- const requiredMajor = minimumVersion?.split(".")[0];
- return requiredMajor
- ? `upgrade required to >= ${requiredMajor}.0.0`
+ return latestSdkMajor
+ ? `upgrade required to >= ${latestSdkMajor}.0.0`
: "upgrade required";
};
-
-export const formatSdkUpgradeRecommendation = (
- sdkName: V4MigrationSdkUsageSeries["canonicalSdkName"],
-) => {
- const minimumVersion = getSdkVersionCapabilityMinimum(
- sdkName,
- "appRootObservations",
- );
-
- return minimumVersion
- ? `recommended to upgrade to >= ${minimumVersion}`
- : "recommended to upgrade";
-};
diff --git a/web/src/features/v4-migration/useV4UpgradeAssistantSupport.ts b/web/src/features/v4-migration/useV4UpgradeAssistantSupport.ts
index 3dff5db914..79afb8ef60 100644
--- a/web/src/features/v4-migration/useV4UpgradeAssistantSupport.ts
+++ b/web/src/features/v4-migration/useV4UpgradeAssistantSupport.ts
@@ -55,7 +55,6 @@ export type V4UpgradeAssistantMode =
*/
export function useEvalUpgradeAssistantPlan(params: {
projectId: string | undefined;
- orgId: string | undefined;
enabled: boolean;
}) {
const canUseAssistant = useCanUseInAppAgent();
diff --git a/web/src/features/v4/server/timelineBuckets.ts b/web/src/features/v4/server/timelineBuckets.ts
deleted file mode 100644
index 18217e461c..0000000000
--- a/web/src/features/v4/server/timelineBuckets.ts
+++ /dev/null
@@ -1,114 +0,0 @@
-export type ResolvedTimelineGranularity =
- | "minute"
- | "2m"
- | "5m"
- | "hour"
- | "day";
-
-const MINUTE_MS = 60 * 1000;
-const HOUR_MS = 60 * MINUTE_MS;
-const DAY_MS = 24 * HOUR_MS;
-export const MAX_TIMELINE_RANGE_MS = 30 * DAY_MS;
-const TIMELINE_GRANULARITY_DURATION_TOLERANCE_MS = 1000;
-
-const timelineGranularityRules: ReadonlyArray<{
- maxDurationMs: number;
- granularity: ResolvedTimelineGranularity;
-}> = [
- { maxDurationMs: 30 * MINUTE_MS, granularity: "minute" },
- { maxDurationMs: HOUR_MS, granularity: "2m" },
- { maxDurationMs: 3 * HOUR_MS, granularity: "5m" },
- { maxDurationMs: 7 * DAY_MS, granularity: "hour" },
- { maxDurationMs: MAX_TIMELINE_RANGE_MS, granularity: "day" },
-];
-
-export const resolveTimelineGranularity = (
- fromTimestamp: Date,
- toTimestamp: Date,
-): ResolvedTimelineGranularity => {
- const diffMs = toTimestamp.getTime() - fromTimestamp.getTime();
-
- return (
- timelineGranularityRules.find(
- (rule) =>
- diffMs <=
- rule.maxDurationMs + TIMELINE_GRANULARITY_DURATION_TOLERANCE_MS,
- )?.granularity ?? "day"
- );
-};
-
-export const getTimelineBucketSql = (
- sql: string,
- granularity: ResolvedTimelineGranularity,
-): string => {
- const intervalByGranularity: Record<ResolvedTimelineGranularity, string> = {
- minute: "1 MINUTE",
- "2m": "2 MINUTE",
- "5m": "5 MINUTE",
- hour: "1 HOUR",
- day: "1 DAY",
- };
-
- return `toStartOfInterval(${sql}, INTERVAL ${intervalByGranularity[granularity]}, 'UTC')`;
-};
-
-export const floorTimelineBucket = (
- timestamp: Date,
- granularity: ResolvedTimelineGranularity,
-): Date => {
- const bucket = new Date(timestamp);
-
- switch (granularity) {
- case "minute":
- bucket.setUTCSeconds(0, 0);
- return bucket;
- case "2m":
- bucket.setUTCMinutes(Math.floor(bucket.getUTCMinutes() / 2) * 2, 0, 0);
- return bucket;
- case "5m":
- bucket.setUTCMinutes(Math.floor(bucket.getUTCMinutes() / 5) * 5, 0, 0);
- return bucket;
- case "hour":
- bucket.setUTCMinutes(0, 0, 0);
- return bucket;
- case "day":
- bucket.setUTCHours(0, 0, 0, 0);
- return bucket;
- default: {
- const exhaustiveCheck: never = granularity;
- throw new Error(`Invalid timeline granularity: ${exhaustiveCheck}`);
- }
- }
-};
-
-export const addTimelineBucket = (
- timestamp: Date,
- granularity: ResolvedTimelineGranularity,
-): Date => {
- const next = new Date(timestamp);
-
- switch (granularity) {
- case "minute":
- next.setUTCMinutes(next.getUTCMinutes() + 1);
- return next;
- case "2m":
- next.setUTCMinutes(next.getUTCMinutes() + 2);
- return next;
- case "5m":
- next.setUTCMinutes(next.getUTCMinutes() + 5);
- return next;
- case "hour":
- next.setUTCHours(next.getUTCHours() + 1);
- return next;
- case "day":
- next.setUTCDate(next.getUTCDate() + 1);
- return next;
- default: {
- const exhaustiveCheck: never = granularity;
- throw new Error(`Invalid timeline granularity: ${exhaustiveCheck}`);
- }
- }
-};
-
-export const formatTimelineBucket = (timestamp: Date): string =>
- timestamp.toISOString().replace(/\.\d{3}Z$/, "Z");
diff --git a/web/src/features/v4/server/v4TransitionRouter.ts b/web/src/features/v4/server/v4TransitionRouter.ts
index b28fbcecd5..25218268fa 100644
--- a/web/src/features/v4/server/v4TransitionRouter.ts
+++ b/web/src/features/v4/server/v4TransitionRouter.ts
@@ -4,13 +4,13 @@ import {
protectedOrganizationProcedure,
protectedProjectProcedure,
} from "@/src/server/api/trpc";
-import { AnalyticsIntegrationExportSource } from "@langfuse/shared/src/db";
-import type { Prisma } from "@langfuse/shared/src/db";
-import { variableMapping } from "@langfuse/shared";
+import {
+ AnalyticsIntegrationExportSource,
+ type Prisma,
+ type PrismaClient,
+} from "@langfuse/shared/src/db";
import type { Session } from "next-auth";
import {
- classifyIngestionSdkAttribution,
- classifyIngestionSdkVersion,
convertDateToClickhouseDateTime,
INTERNAL_INGESTION_SDK_NAMES,
isForceV3ExperienceProject,
@@ -18,20 +18,9 @@ import {
queryClickhouse,
systemTableRef,
type IngestionSdkAttributionStatus,
- type IngestionSdkUpgradeStatus,
} from "@langfuse/shared/src/server";
import { getSdkVersionCapabilityStatus } from "@/src/features/sdk-version/lib/sdkVersionCapabilities";
-import {
- addTimelineBucket,
- floorTimelineBucket,
- formatTimelineBucket,
- getTimelineBucketSql,
- MAX_TIMELINE_RANGE_MS,
- resolveTimelineGranularity,
- type ResolvedTimelineGranularity,
-} from "./timelineBuckets";
-
-const timelineGranularity = z.literal("auto");
+const MAX_DETECTION_RANGE_MS = 30 * 24 * 60 * 60 * 1000;
const legacyIntegrationExportSources =
new Set<AnalyticsIntegrationExportSource>([
@@ -42,6 +31,23 @@ const legacyIntegrationExportSources =
const TRACE_EVAL_TARGET = "trace";
const DATASET_EVAL_TARGET = "dataset";
+/** Customer-ingress sources. Historical and experiment materializations are excluded. */
+const MIGRATION_INGRESS_EVENT_SOURCES = [
+ "ingestion-api-dual-write",
+ "otel-dual-write",
+ "otel",
+] as const;
+
+type MigrationIngressSource = (typeof MIGRATION_INGRESS_EVENT_SOURCES)[number];
+type MigrationIngestionPath = "otel" | "ingestion_api";
+type MigrationDeliveryMode = "realtime" | "delayed";
+type MigrationRemediationType =
+ | "update_sdk"
+ | "update_otel_instrumentation"
+ | "upgrade_instrumentation";
+type MigrationActionLevel = "required" | "none";
+type V4MigrationStatus = "compatible" | "upgrade_required" | "unknown";
+
const isLegacyIntegrationExportSource = (
exportSource: AnalyticsIntegrationExportSource | null | undefined,
) => exportSource != null && legacyIntegrationExportSources.has(exportSource);
@@ -57,12 +63,11 @@ const isEnabledLegacyIntegration = (
isLegacyIntegrationExportSource(integration.exportSource),
);
-const timelineInputSchema = z
+const projectTimeRangeInputSchema = z
.object({
projectId: z.string(),
fromTimestamp: z.date(),
toTimestamp: z.date(),
- granularity: timelineGranularity.default("auto"),
})
.refine(
({ fromTimestamp, toTimestamp }) =>
@@ -71,8 +76,8 @@ const timelineInputSchema = z
)
.refine(
({ fromTimestamp, toTimestamp }) =>
- toTimestamp.getTime() - fromTimestamp.getTime() <= MAX_TIMELINE_RANGE_MS,
- { message: "V4 timeline ranges cannot exceed 30 days" },
+ toTimestamp.getTime() - fromTimestamp.getTime() <= MAX_DETECTION_RANGE_MS,
+ { message: "V4 migration ranges cannot exceed 30 days" },
);
const organizationTimeRangeInputSchema = z
@@ -88,81 +93,63 @@ const organizationTimeRangeInputSchema = z
)
.refine(
({ fromTimestamp, toTimestamp }) =>
- toTimestamp.getTime() - fromTimestamp.getTime() <= MAX_TIMELINE_RANGE_MS,
+ toTimestamp.getTime() - fromTimestamp.getTime() <= MAX_DETECTION_RANGE_MS,
{ message: "V4 migration ranges cannot exceed 30 days" },
);
-type LegacyApiUsageRow = {
- time: string;
- entrypoint: string;
- count: string | number;
- lastSeen: string;
-};
-
-type LegacyApiUsageResultRow = {
- time: string;
- entrypoint: string;
- count: number;
- lastSeen: string | null;
-};
-
type LegacyApiUsageSummaryByProjectRow = {
projectId: string;
entrypoint: string;
count: string | number;
+ lastSeen: string;
};
type LegacyApiUsageSummaryByProjectResultRow = {
projectId: string;
entrypoint: string;
count: number;
-};
-
-type DecoratedSdkUsageSummaryRow = {
- sdkName: string;
- sdkVersion: string;
- publicKey: string;
- count: number;
- firstSeen: string | null;
- lastSeen: string | null;
- hasDelayedOtelEvents: boolean | null;
- attributionStatus: IngestionSdkAttributionStatus;
- canonicalSdkName: "python" | "javascript" | null;
- upgradeStatus: IngestionSdkUpgradeStatus | "outdated_minor";
+ lastSeen: string;
};
type SdkUsageSummaryByProjectRow = {
projectId: string;
+ source: MigrationIngressSource;
+ ingestionPath: MigrationIngestionPath;
+ deliveryMode: MigrationDeliveryMode;
sdkName: string;
sdkVersion: string;
+ canonicalSdkName: "python" | "javascript" | null;
+ sdkVersionMajor: string | number | null;
+ latestSdkMajor: string | number | null;
+ isValidSdkVersion: boolean | string | number;
+ attributionStatus: IngestionSdkAttributionStatus;
publicKey: string;
- count: string | number;
- /** Hits from events_core only (count also includes score ingestions). */
- eventsCount: string | number;
+ v4MigrationStatus: V4MigrationStatus;
+ remediationType: MigrationRemediationType;
+ actionLevel: MigrationActionLevel;
+ eventCount: string | number;
firstSeen: string;
lastSeen: string;
- hasDelayedOtelEvents: boolean | string | number | null;
};
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;
- count: number;
- /** Hits with observation evidence: rows in events_core, excluding scores.
- Zero means the offender is scores-only and an events-table evidence
- link would open an empty result set. */
- eventsCount: number;
+ v4MigrationStatus: V4MigrationStatus;
+ remediationType: MigrationRemediationType;
+ actionLevel: MigrationActionLevel;
+ eventCount: number;
firstSeen: string;
lastSeen: string;
- hasDelayedOtelEvents: boolean | null;
- attributionStatus: IngestionSdkAttributionStatus;
- v4MigrationStatus:
- | "compatible"
- | "upgrade_recommended"
- | "upgrade_required"
- | "unknown";
};
// Counts stay out of this row on purpose: the client derives every displayed
@@ -187,49 +174,10 @@ type DatasetRunItemsPostUsageByProjectRow = {
count: string | number;
};
-const getEmptyTimelineBuckets = (
- fromTimestamp: Date,
- toTimestamp: Date,
- granularity: ResolvedTimelineGranularity,
-): LegacyApiUsageResultRow[] => {
- const buckets: LegacyApiUsageResultRow[] = [];
-
- for (
- let bucket = floorTimelineBucket(fromTimestamp, granularity);
- bucket.getTime() < toTimestamp.getTime();
- bucket = addTimelineBucket(bucket, granularity)
- ) {
- buckets.push({
- time: formatTimelineBucket(bucket),
- entrypoint: "",
- count: 0,
- lastSeen: null,
- });
- }
-
- return buckets;
-};
-
-const compareTimelineRows = (
- left: LegacyApiUsageResultRow,
- right: LegacyApiUsageResultRow,
-): number => {
- if (left.time < right.time) return -1;
- if (left.time > right.time) return 1;
- if (left.entrypoint === right.entrypoint) return 0;
- if (left.entrypoint === "") return -1;
- if (right.entrypoint === "") return 1;
- return left.entrypoint.localeCompare(right.entrypoint);
-};
-
const toBoolean = (value: boolean | string | number): boolean =>
value === true || value === 1 || value === "1";
-const toNullableBoolean = (
- value: boolean | string | number | null,
-): boolean | null => (value === null ? null : toBoolean(value));
-
-type TraceLevelEvalSummaryByProjectResultRow = {
+type TraceLevelEvalSummaryResultRow = {
projectId: string;
traceLevelEvalCount: number;
};
@@ -281,304 +229,261 @@ const getLegacyIntegrations = ({
blobStorage: isEnabledLegacyIntegration(blobStorageIntegration),
});
-export const v4TransitionRouter = createTRPCRouter({
- // Whether this project is forced onto the v3 experience
- forceV3Experience: protectedProjectProcedure
- .input(z.object({ projectId: z.string() }))
- .query(({ input }) => isForceV3ExperienceProject(input.projectId)),
-
- summary: protectedProjectProcedure
- .input(z.object({ projectId: z.string() }))
- .query(async ({ input, ctx }) => {
- const [posthogIntegration, mixpanelIntegration, blobStorageIntegration] =
- await Promise.all([
- ctx.prisma.posthogIntegration.findUnique({
- where: { projectId: input.projectId },
- select: { enabled: true, exportSource: true },
- }),
- ctx.prisma.mixpanelIntegration.findUnique({
- where: { projectId: input.projectId },
- select: { enabled: true, exportSource: true },
- }),
- ctx.prisma.blobStorageIntegration.findUnique({
- where: { projectId: input.projectId },
- select: { enabled: true, exportSource: true },
- }),
- ]);
-
- const legacyIntegrations = getLegacyIntegrations({
- posthogIntegration,
- mixpanelIntegration,
- blobStorageIntegration,
- });
-
- return {
- legacyIntegrationCount:
- Object.values(legacyIntegrations).filter(Boolean).length,
- legacyIntegrations,
- };
- }),
-
- traceLevelEvalSummary: protectedProjectProcedure
- .input(z.object({ projectId: z.string() }))
- .query(async ({ input, ctx }) => {
- // Only active evaluators running on new data require migration;
- // inactive or backfill-only (EXISTING) configs are not counted.
- const legacyEvalConfigs = await ctx.prisma.jobConfiguration.findMany({
- where: {
- projectId: input.projectId,
- jobType: "EVAL",
- targetObject: { in: [TRACE_EVAL_TARGET, DATASET_EVAL_TARGET] },
- status: "ACTIVE",
- timeScope: { has: "NEW" },
- },
- select: { targetObject: true, variableMapping: true },
- });
-
- // The in-app assistant can only complete the eval migration when every
- // remaining legacy evaluator is trivially repointable: dataset targets,
- // or trace targets whose variables all read from one named observation.
- const allAssistantMigratable =
- legacyEvalConfigs.length > 0 &&
- legacyEvalConfigs.every((config) => {
- if (config.targetObject === DATASET_EVAL_TARGET) return true;
- const parsed = z
- .array(variableMapping)
- .safeParse(config.variableMapping);
- if (!parsed.success || parsed.data.length === 0) return false;
- if (
- parsed.data.some((mapping) => mapping.langfuseObject === "trace")
- ) {
- return false;
- }
- const observationNames = new Set(
- parsed.data.map((mapping) => mapping.objectName ?? ""),
- );
- return observationNames.size === 1;
- });
-
- return {
- traceLevelEvalCount: legacyEvalConfigs.length,
- allAssistantMigratable,
- };
- }),
-
- summaryByProject: protectedOrganizationProcedure
- .input(z.object({ orgId: z.string() }))
- .query(async ({ input, ctx }) => {
- const projects = await ctx.prisma.project.findMany({
- where: getAccessibleOrganizationProjectWhere({
- orgId: input.orgId,
- session: ctx.session,
- }),
- select: {
- id: true,
- name: true,
- },
- orderBy: {
- createdAt: "desc",
- },
- });
- const projectIds = projects.map((project) => project.id);
-
- if (projectIds.length === 0) {
- return { projects: [] };
- }
-
- const [
- posthogIntegrations,
- mixpanelIntegrations,
- blobStorageIntegrations,
- ] = await Promise.all([
- ctx.prisma.posthogIntegration.findMany({
- where: { projectId: { in: projectIds } },
- select: { projectId: true, enabled: true, exportSource: true },
- }),
- ctx.prisma.mixpanelIntegration.findMany({
- where: { projectId: { in: projectIds } },
- select: { projectId: true, enabled: true, exportSource: true },
- }),
- ctx.prisma.blobStorageIntegration.findMany({
- where: { projectId: { in: projectIds } },
- select: { projectId: true, enabled: true, exportSource: true },
- }),
- ]);
-
- const posthogIntegrationsByProjectId = new Map(
- posthogIntegrations.map((integration) => [
- integration.projectId,
- integration,
- ]),
- );
- const mixpanelIntegrationsByProjectId = new Map(
- mixpanelIntegrations.map((integration) => [
- integration.projectId,
- integration,
- ]),
- );
- const blobStorageIntegrationsByProjectId = new Map(
- blobStorageIntegrations.map((integration) => [
- integration.projectId,
- integration,
- ]),
- );
-
- return {
- projects: projects.map((project) => {
- const legacyIntegrations = getLegacyIntegrations({
- posthogIntegration: posthogIntegrationsByProjectId.get(project.id),
- mixpanelIntegration: mixpanelIntegrationsByProjectId.get(
- project.id,
- ),
- blobStorageIntegration: blobStorageIntegrationsByProjectId.get(
- project.id,
- ),
- });
-
- return {
- projectId: project.id,
- projectName: project.name,
- legacyIntegrationCount:
- Object.values(legacyIntegrations).filter(Boolean).length,
- legacyIntegrations,
- forceV3Experience: isForceV3ExperienceProject(project.id),
- };
- }),
- };
- }),
-
- traceLevelEvalSummaryByProject: protectedOrganizationProcedure
- .input(z.object({ orgId: z.string() }))
- .query(async ({ input, ctx }) => {
- const projects = await ctx.prisma.project.findMany({
- where: getAccessibleOrganizationProjectWhere({
- orgId: input.orgId,
- session: ctx.session,
- }),
- select: {
- id: true,
- },
- });
- const projectIds = projects.map((project) => project.id);
-
- if (projectIds.length === 0) return [];
-
- // Only active evaluators running on new data require migration;
- // inactive or backfill-only (EXISTING) configs are not counted.
- const traceLevelEvalCounts = await ctx.prisma.jobConfiguration.groupBy({
- by: ["projectId"],
- where: {
- projectId: { in: projectIds },
- jobType: "EVAL",
- targetObject: { in: [TRACE_EVAL_TARGET, DATASET_EVAL_TARGET] },
- status: "ACTIVE",
- timeScope: { has: "NEW" },
- },
- _count: { _all: true },
- });
- const traceLevelEvalCountsByProjectId = new Map(
- traceLevelEvalCounts.map((row) => [row.projectId, row._count._all]),
- );
-
- return projectIds.map(
- (projectId): TraceLevelEvalSummaryByProjectResultRow => ({
- projectId,
- traceLevelEvalCount:
- traceLevelEvalCountsByProjectId.get(projectId) ?? 0,
- }),
- );
- }),
+type V4TransitionPrisma = Pick<
+ PrismaClient,
+ | "project"
+ | "posthogIntegration"
+ | "mixpanelIntegration"
+ | "blobStorageIntegration"
+ | "jobConfiguration"
+>;
+
+const getAccessibleOrganizationProjects = async ({
+ prisma,
+ orgId,
+ session,
+}: {
+ prisma: V4TransitionPrisma;
+ orgId: string;
+ session: Session;
+}) =>
+ prisma.project.findMany({
+ where: getAccessibleOrganizationProjectWhere({ orgId, session }),
+ select: { id: true, name: true },
+ orderBy: { createdAt: "desc" },
+ });
+
+const getLegacyIntegrationSummaries = async ({
+ prisma,
+ projectIds,
+}: {
+ prisma: V4TransitionPrisma;
+ projectIds: string[];
+}) => {
+ if (projectIds.length === 0) return [];
+
+ const [posthogIntegrations, mixpanelIntegrations, blobStorageIntegrations] =
+ await Promise.all([
+ prisma.posthogIntegration.findMany({
+ where: { projectId: { in: projectIds } },
+ select: { projectId: true, enabled: true, exportSource: true },
+ }),
+ prisma.mixpanelIntegration.findMany({
+ where: { projectId: { in: projectIds } },
+ select: { projectId: true, enabled: true, exportSource: true },
+ }),
+ prisma.blobStorageIntegration.findMany({
+ where: { projectId: { in: projectIds } },
+ select: { projectId: true, enabled: true, exportSource: true },
+ }),
+ ]);
+
+ const posthogByProjectId = new Map(
+ posthogIntegrations.map((integration) => [
+ integration.projectId,
+ integration,
+ ]),
+ );
+ const mixpanelByProjectId = new Map(
+ mixpanelIntegrations.map((integration) => [
+ integration.projectId,
+ integration,
+ ]),
+ );
+ const blobStorageByProjectId = new Map(
+ blobStorageIntegrations.map((integration) => [
+ integration.projectId,
+ integration,
+ ]),
+ );
- sdkUsageSummaryByProject: protectedOrganizationProcedure
- .input(organizationTimeRangeInputSchema)
- .query(async ({ input, ctx }) => {
- const projects = await ctx.prisma.project.findMany({
- where: getAccessibleOrganizationProjectWhere({
- orgId: input.orgId,
- session: ctx.session,
- }),
- select: {
- id: true,
- },
- });
- const projectIds = projects.map((project) => project.id);
+ return projectIds.map((projectId) => {
+ const legacyIntegrations = getLegacyIntegrations({
+ posthogIntegration: posthogByProjectId.get(projectId),
+ mixpanelIntegration: mixpanelByProjectId.get(projectId),
+ blobStorageIntegration: blobStorageByProjectId.get(projectId),
+ });
- if (projectIds.length === 0) return [];
+ return {
+ projectId,
+ legacyIntegrationCount:
+ Object.values(legacyIntegrations).filter(Boolean).length,
+ legacyIntegrations,
+ };
+ });
+};
- const scoresUnionSql = `
- UNION ALL
+const getTraceLevelEvalSummaries = async ({
+ prisma,
+ projectIds,
+}: {
+ prisma: V4TransitionPrisma;
+ projectIds: string[];
+}): Promise<TraceLevelEvalSummaryResultRow[]> => {
+ if (projectIds.length === 0) return [];
+
+ const counts = await prisma.jobConfiguration.groupBy({
+ by: ["projectId"],
+ where: {
+ projectId: { in: projectIds },
+ jobType: "EVAL",
+ targetObject: { in: [TRACE_EVAL_TARGET, DATASET_EVAL_TARGET] },
+ status: "ACTIVE",
+ timeScope: { has: "NEW" },
+ },
+ _count: { _all: true },
+ });
+ const countByProjectId = new Map(
+ counts.map((row) => [row.projectId, row._count._all]),
+ );
- SELECT
- project_id,
- timestamp AS event_time,
- if(ingestion_sdk_name = '', 'unknown', ingestion_sdk_name) AS sdk_name,
- if(ingestion_sdk_version = '', 'unknown', ingestion_sdk_version) AS sdk_version,
- ingestion_api_key AS public_key,
- false AS is_otel_ingestion,
- false AS is_delayed_otel,
- true AS is_score_ingestion
- FROM scores FINAL
- WHERE
- project_id IN {projectIds: Array(String)}
- AND timestamp >= {fromTimestamp: DateTime64(3)}
- AND timestamp <= {toTimestamp: DateTime64(3)}
- AND NOT startsWith(environment, 'langfuse-')
- AND execution_trace_id IS NULL
- AND source != 'ANNOTATION'
- AND ingestion_sdk_name NOT IN {internalSdkNames: Array(String)}
- AND is_deleted = 0`;
+ return projectIds.map((projectId) => ({
+ projectId,
+ traceLevelEvalCount: countByProjectId.get(projectId) ?? 0,
+ }));
+};
- const [rows, datasetRunItemsPostUsageResult] = await Promise.all([
- queryClickhouse<SdkUsageSummaryByProjectRow>({
- query: `
-WITH selected AS (
+const getSdkUsageSummaries = async ({
+ projectIds,
+ fromTimestamp,
+ toTimestamp,
+}: {
+ projectIds: string[];
+ fromTimestamp: Date;
+ toTimestamp: Date;
+}): Promise<SdkUsageSummaryByProjectResultRow[]> => {
+ if (projectIds.length === 0) return [];
+
+ const [rows, datasetRunItemsPostUsageResult] = await Promise.all([
+ queryClickhouse<SdkUsageSummaryByProjectRow>({
+ query: `
+WITH filtered AS (
SELECT
- project_id,
- start_time AS event_time,
- if(ingestion_sdk_name = '', 'unknown', ingestion_sdk_name) AS sdk_name,
- if(ingestion_sdk_version = '', 'unknown', ingestion_sdk_version) AS sdk_version,
- ingestion_api_key AS public_key,
- (source = 'otel' OR startsWith(source, 'otel-dual-write')) AS is_otel_ingestion,
- startsWith(source, 'otel-dual-write') AS is_delayed_otel,
- false AS is_score_ingestion
+ project_id AS projectId,
+ source,
+ if(ingestion_sdk_name = '', 'unknown', ingestion_sdk_name) AS sdkName,
+ if(ingestion_sdk_version = '', 'unknown', ingestion_sdk_version) AS sdkVersion,
+ ingestion_api_key AS publicKey,
+ start_time
FROM events_core
WHERE
project_id IN {projectIds: Array(String)}
AND start_time >= {fromTimestamp: DateTime64(3)}
AND start_time <= {toTimestamp: DateTime64(3)}
+ AND source IN {ingressSources: Array(String)}
AND NOT startsWith(environment, 'langfuse-')
AND ingestion_sdk_name NOT IN {internalSdkNames: Array(String)}
AND is_deleted = 0
- ${scoresUnionSql}
+),
+series AS (
+ SELECT
+ projectId,
+ source,
+ sdkName,
+ sdkVersion,
+ publicKey,
+ count() AS eventCount,
+ min(start_time) AS firstSeenAt,
+ max(start_time) AS lastSeenAt
+ FROM filtered
+ GROUP BY projectId, source, sdkName, sdkVersion, publicKey
+),
+classified AS (
+ SELECT
+ *,
+ multiIf(
+ lowerUTF8(trimBoth(sdkName)) IN ('python', 'langfuse-python'), 'python',
+ lowerUTF8(trimBoth(sdkName)) IN (
+ 'javascript', 'js', 'typescript', 'ts', 'langfuse-js', 'langfuse-ts',
+ '@langfuse/client', '@langfuse/browser', '@langfuse/core',
+ '@langfuse/langchain', '@langfuse/otel', '@langfuse/openai',
+ '@langfuse/tracing', '@langfuse/vercel-ai-sdk'
+ ), 'javascript',
+ NULL
+ ) AS canonicalSdkName,
+ match(
+ lowerUTF8(sdkVersion),
+ '^v?[0-9]+\\.[0-9]+\\.[0-9]+([-+].+|(a|b|rc)[0-9]+)?$'
+ ) AS isValidSdkVersion,
+ toUInt32OrNull(extract(lowerUTF8(sdkVersion), '^v?([0-9]+)\\.'))
+ AS sdkVersionMajor,
+ if(startsWith(source, 'otel'), 'otel', 'ingestion_api') AS ingestionPath,
+ if(source = 'otel', 'realtime', 'delayed') AS deliveryMode,
+ multiIf(
+ sdkName = 'unknown' AND sdkVersion = 'unknown', 'missing_name_and_version',
+ sdkName = 'unknown', 'missing_name',
+ sdkVersion = 'unknown', 'missing_version',
+ 'attributed'
+ ) AS attributionStatus
+ FROM series
+),
+scored AS (
+ SELECT
+ *,
+ multiIf(
+ canonicalSdkName = 'python', 4,
+ canonicalSdkName = 'javascript', 5,
+ NULL
+ ) AS latestSdkMajor,
+ multiIf(
+ canonicalSdkName IS NULL, 'unknown',
+ NOT isValidSdkVersion OR sdkVersionMajor IS NULL, 'unknown',
+ sdkVersionMajor >= latestSdkMajor, 'compatible',
+ 'upgrade_required'
+ ) AS v4MigrationStatus,
+ multiIf(
+ canonicalSdkName IS NOT NULL, 'update_sdk',
+ ingestionPath = 'otel', 'update_otel_instrumentation',
+ 'upgrade_instrumentation'
+ ) AS remediationType
+ FROM classified
)
-
SELECT
- project_id AS projectId,
- sdk_name AS sdkName,
- sdk_version AS sdkVersion,
- public_key AS publicKey,
- count() AS count,
- countIf(NOT is_score_ingestion) AS eventsCount,
- formatDateTime(min(event_time), '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS firstSeen,
- formatDateTime(max(event_time), '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS lastSeen,
- if(countIf(is_otel_ingestion) > 0, argMaxIf(is_delayed_otel, event_time, is_otel_ingestion), NULL) AS hasDelayedOtelEvents
-FROM selected
-GROUP BY project_id, sdk_name, sdk_version, public_key
-ORDER BY project_id ASC, sdk_name ASC, sdk_version ASC, public_key ASC
- `,
- params: {
- projectIds,
- fromTimestamp: convertDateToClickhouseDateTime(input.fromTimestamp),
- toTimestamp: convertDateToClickhouseDateTime(input.toTimestamp),
- internalSdkNames: [...INTERNAL_INGESTION_SDK_NAMES],
- },
- tags: {
- route: "v4-org-sdk-usage-summary",
- },
- preferredClickhouseService: "EventsReadOnly",
- }),
- queryClickhouse<DatasetRunItemsPostUsageByProjectRow>({
- query: `
+ projectId,
+ source,
+ ingestionPath,
+ deliveryMode,
+ sdkName,
+ sdkVersion,
+ canonicalSdkName,
+ sdkVersionMajor,
+ latestSdkMajor,
+ isValidSdkVersion,
+ attributionStatus,
+ publicKey,
+ v4MigrationStatus,
+ remediationType,
+ multiIf(
+ remediationType = 'update_sdk',
+ if(v4MigrationStatus = 'compatible', 'none', 'required'),
+ remediationType = 'update_otel_instrumentation',
+ if(deliveryMode = 'realtime', 'none', 'required'),
+ 'required'
+ ) AS actionLevel,
+ eventCount,
+ formatDateTime(firstSeenAt, '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS firstSeen,
+ formatDateTime(lastSeenAt, '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS lastSeen
+FROM scored
+ORDER BY
+ projectId ASC,
+ lastSeenAt DESC,
+ source ASC,
+ 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",
+ }),
+ queryClickhouse<DatasetRunItemsPostUsageByProjectRow>({
+ query: `
SELECT
JSONExtractString(log_comment, 'projectId') AS projectId,
count() AS count
@@ -595,186 +500,127 @@ WHERE
AND splitByChar('?', JSONExtractString(log_comment, 'route'))[1] = 'POST /api/public/dataset-run-items'
GROUP BY projectId
SETTINGS skip_unavailable_shards = 1
- `,
- params: {
- projectIds,
- fromTimestamp: convertDateToClickhouseDateTime(input.fromTimestamp),
- toTimestamp: convertDateToClickhouseDateTime(input.toTimestamp),
- },
- tags: {
- route: "v4-org-experiment-instrumentation-summary",
- },
- preferredClickhouseService: "EventsReadOnly",
- clickhouseSettings: {
- skip_unavailable_shards: 1,
- },
- })
- .then((rows) => ({ status: "success" as const, rows }))
- .catch((error: unknown) => {
- logger.warn(
- "Failed to query dataset-run-items POST usage for v4 migration",
- error,
- );
- return {
- status: "error" as const,
- rows: [] as DatasetRunItemsPostUsageByProjectRow[],
- };
- }),
- ]);
-
- const rowsByProjectId = new Map<string, SdkUsageSummaryByProjectRow[]>();
- for (const row of rows) {
- const projectRows = rowsByProjectId.get(row.projectId) ?? [];
- projectRows.push(row);
- rowsByProjectId.set(row.projectId, projectRows);
- }
- const projectsUsingDatasetRunItemsPost = new Set(
- datasetRunItemsPostUsageResult.rows
- .filter((row) => Number(row.count) > 0)
- .map((row) => row.projectId),
- );
-
- return projectIds.map((projectId): SdkUsageSummaryByProjectResultRow => {
- const projectRows = (rowsByProjectId.get(projectId) ?? []).map(
- (row): DecoratedSdkUsageSummaryRow & { eventsCount: number } => {
- const classification = classifyIngestionSdkVersion({
- sdkName: row.sdkName,
- sdkVersion: row.sdkVersion,
- });
- const capabilityStatus = getSdkVersionCapabilityStatus(
- { language: row.sdkName, version: row.sdkVersion },
- "appRootObservations",
- );
-
- return {
- sdkName: row.sdkName,
- sdkVersion: row.sdkVersion,
- publicKey: row.publicKey,
- count: Number(row.count),
- eventsCount: Number(row.eventsCount),
- firstSeen: row.firstSeen,
- lastSeen: row.lastSeen,
- hasDelayedOtelEvents: toNullableBoolean(row.hasDelayedOtelEvents),
- attributionStatus: classifyIngestionSdkAttribution({
- sdkName: row.sdkName,
- sdkVersion: row.sdkVersion,
- }),
- canonicalSdkName: classification.canonicalSdkName,
- upgradeStatus:
- capabilityStatus === "supported"
- ? "current"
- : capabilityStatus === "unsupported" &&
- classification.status === "current"
- ? "outdated_minor"
- : classification.status,
- };
- },
- );
- const sdkUsageSeries = projectRows.map(
- (row): SdkUsageSummaryByProjectSeries => {
- return {
- sdkName: row.sdkName,
- sdkVersion: row.sdkVersion,
- canonicalSdkName: row.canonicalSdkName,
- publicKey: row.publicKey,
- count: row.count,
- eventsCount: row.eventsCount,
- firstSeen: row.firstSeen!,
- lastSeen: row.lastSeen!,
- hasDelayedOtelEvents: row.hasDelayedOtelEvents,
- attributionStatus: row.attributionStatus,
- v4MigrationStatus:
- row.upgradeStatus === "current"
- ? "compatible"
- : row.upgradeStatus === "outdated_minor"
- ? "upgrade_recommended"
- : row.upgradeStatus === "outdated_major"
- ? "upgrade_required"
- : "unknown",
- };
- },
- );
- const usesDatasetRunItemsPost =
- projectsUsingDatasetRunItemsPost.has(projectId);
- const langfuseSdkUsage = projectRows.filter(
- (series) => series.canonicalSdkName !== null,
+ `,
+ params: {
+ projectIds,
+ fromTimestamp: convertDateToClickhouseDateTime(fromTimestamp),
+ toTimestamp: convertDateToClickhouseDateTime(toTimestamp),
+ },
+ tags: { route: "v4-experiment-instrumentation-summary" },
+ preferredClickhouseService: "EventsReadOnly",
+ clickhouseSettings: { skip_unavailable_shards: 1 },
+ })
+ .then((rows) => ({ status: "success" as const, rows }))
+ .catch((error: unknown) => {
+ logger.warn(
+ "Failed to query dataset-run-items POST usage for v4 migration",
+ error,
);
- const hasCurrentExperimentInstrumentation =
- langfuseSdkUsage.length > 0 &&
- langfuseSdkUsage.every(
- (series) =>
- getSdkVersionCapabilityStatus(
- {
- language: series.sdkName,
- version: series.sdkVersion,
- },
- "experimentLinkDeprecation",
- ) === "supported",
- );
- 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")
- );
- },
- );
- const experimentInstrumentationMigration: SdkUsageSummaryByProjectResultRow["experimentInstrumentationMigration"] =
- datasetRunItemsPostUsageResult.status === "error"
- ? { status: "check_failed", upgradePath: null }
- : !usesDatasetRunItemsPost
- ? { status: "not_required", upgradePath: null }
- : hasCurrentExperimentInstrumentation
- ? { status: "not_required", upgradePath: null }
- : hasInconclusiveExperimentSdkUsage
- ? { status: "sdk_usage_inconclusive", upgradePath: "sdk" }
- : { status: "required", upgradePath: "api" };
-
return {
- projectId,
- experimentInstrumentationMigration,
- sdkUsageSeries,
+ status: "error" as const,
+ rows: [] as DatasetRunItemsPostUsageByProjectRow[],
};
- });
- }),
+ }),
+ ]);
- legacyApiUsageSummaryByProject: protectedOrganizationProcedure
- .input(organizationTimeRangeInputSchema)
- .query(async ({ input, ctx }) => {
- const projects = await ctx.prisma.project.findMany({
- where: getAccessibleOrganizationProjectWhere({
- orgId: input.orgId,
- session: ctx.session,
- }),
- select: {
- id: true,
- },
- });
- const projectIds = projects.map((project) => project.id);
+ const rowsByProjectId = new Map<string, SdkUsageSummaryByProjectRow[]>();
+ for (const row of rows) {
+ const projectRows = rowsByProjectId.get(row.projectId) ?? [];
+ projectRows.push(row);
+ rowsByProjectId.set(row.projectId, projectRows);
+ }
+ const projectsUsingDatasetRunItemsPost = new Set(
+ datasetRunItemsPostUsageResult.rows
+ .filter((row) => Number(row.count) > 0)
+ .map((row) => row.projectId),
+ );
- if (projectIds.length === 0) return [];
+ 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,
+ }),
+ );
+ const sdkUsageSeries = projectRows;
+ const langfuseSdkUsage = projectRows.filter(
+ (series) => series.canonicalSdkName !== null,
+ );
+ const hasCurrentExperimentInstrumentation =
+ langfuseSdkUsage.length > 0 &&
+ langfuseSdkUsage.every(
+ (series) =>
+ getSdkVersionCapabilityStatus(
+ { language: series.sdkName, version: series.sdkVersion },
+ "experimentLinkDeprecation",
+ ) === "supported",
+ );
+ 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")
+ );
+ },
+ );
+ 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" };
+
+ return { projectId, experimentInstrumentationMigration, sdkUsageSeries };
+ });
+};
- const rows = await queryClickhouse<LegacyApiUsageSummaryByProjectRow>({
- query: `
+const getLegacyApiUsageSummaries = async ({
+ projectIds,
+ fromTimestamp,
+ toTimestamp,
+}: {
+ projectIds: string[];
+ fromTimestamp: Date;
+ toTimestamp: Date;
+}): Promise<LegacyApiUsageSummaryByProjectResultRow[]> => {
+ if (projectIds.length === 0) return [];
+
+ const rows = await queryClickhouse<LegacyApiUsageSummaryByProjectRow>({
+ query: `
WITH selected AS (
SELECT
JSONExtractString(log_comment, 'projectId') AS project_id,
+ event_time_microseconds,
splitByChar('?', JSONExtractString(log_comment, 'route'))[1] AS route_path
FROM ${systemTableRef("system.query_log")}
WHERE
@@ -790,6 +636,7 @@ WITH selected AS (
classified AS (
SELECT
project_id,
+ event_time_microseconds,
multiIf(
route_path IN (
'GET /api/public/spans',
@@ -840,160 +687,154 @@ classified AS (
SELECT
project_id AS projectId,
concat('publicapi: ', legacy_route) AS entrypoint,
- sum(1.0 / clickhouse_queries_per_api_call) AS count
+ sum(1.0 / clickhouse_queries_per_api_call) AS count,
+ formatDateTime(max(event_time_microseconds), '%Y-%m-%dT%H:%i:%S.%fZ', 'UTC') AS lastSeen
FROM classified
WHERE legacy_route IS NOT NULL
AND clickhouse_queries_per_api_call IS NOT NULL
GROUP BY project_id, legacy_route
ORDER BY project_id ASC, legacy_route ASC
SETTINGS skip_unavailable_shards = 1
- `,
- params: {
- projectIds,
- fromTimestamp: convertDateToClickhouseDateTime(input.fromTimestamp),
- toTimestamp: convertDateToClickhouseDateTime(input.toTimestamp),
- },
- tags: {
- route: "v4-org-legacy-api-usage-summary",
- },
- preferredClickhouseService: "ReadOnly",
- clickhouseSettings: {
- skip_unavailable_shards: 1,
- },
+ `,
+ params: {
+ projectIds,
+ fromTimestamp: convertDateToClickhouseDateTime(fromTimestamp),
+ toTimestamp: convertDateToClickhouseDateTime(toTimestamp),
+ },
+ tags: { route: "v4-legacy-api-usage-summary" },
+ preferredClickhouseService: "ReadOnly",
+ clickhouseSettings: { skip_unavailable_shards: 1 },
+ });
+
+ return rows.map((row) => ({
+ projectId: row.projectId,
+ entrypoint: row.entrypoint,
+ count: Number(row.count),
+ lastSeen: row.lastSeen,
+ }));
+};
+
+export const v4TransitionRouter = createTRPCRouter({
+ forceV3Experience: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .query(({ input }) => isForceV3ExperienceProject(input.projectId)),
+
+ summary: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const [summary] = await getLegacyIntegrationSummaries({
+ prisma: ctx.prisma,
+ projectIds: [input.projectId],
});
+ return summary!;
+ }),
- return rows.map(
- (row): LegacyApiUsageSummaryByProjectResultRow => ({
- projectId: row.projectId,
- entrypoint: row.entrypoint,
- count: Number(row.count),
- }),
- );
+ traceLevelEvalSummary: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const [summary] = await getTraceLevelEvalSummaries({
+ prisma: ctx.prisma,
+ projectIds: [input.projectId],
+ });
+ return summary!;
}),
- timeSeriesByEntrypoint: protectedProjectProcedure
- .input(timelineInputSchema)
- .query(async ({ input }) => {
- const granularity = resolveTimelineGranularity(
- input.fromTimestamp,
- input.toTimestamp,
- );
- const bucketTimeSql = getTimelineBucketSql(
- "event_time_microseconds",
- granularity,
+ summaryByProject: protectedOrganizationProcedure
+ .input(z.object({ orgId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const projects = await getAccessibleOrganizationProjects({
+ prisma: ctx.prisma,
+ orgId: input.orgId,
+ session: ctx.session,
+ });
+ const projectIds = projects.map((project) => project.id);
+
+ if (projectIds.length === 0) {
+ return { projects: [] };
+ }
+ const summaries = await getLegacyIntegrationSummaries({
+ prisma: ctx.prisma,
+ projectIds,
+ });
+ const summaryByProjectId = new Map(
+ summaries.map((summary) => [summary.projectId, summary]),
);
- const rows = await queryClickhouse<LegacyApiUsageRow>({
- query: `
-WITH selected AS (
- SELECT
- ${bucketTimeSql} AS bucket_time,
- event_time_microseconds,
- splitByChar('?', JSONExtractString(log_comment, 'route'))[1] AS route_path
- FROM ${systemTableRef("system.query_log")}
- WHERE
- event_time >= {fromTimestamp: DateTime64(3)}
- AND event_time <= {toTimestamp: DateTime64(3)}
- AND event_date >= toDate({fromTimestamp: DateTime64(3)})
- AND event_date <= toDate({toTimestamp: DateTime64(3)})
- AND type = 'QueryFinish'
- AND JSONExtractString(log_comment, 'tag_schema_version') = '1'
- AND JSONExtractString(log_comment, 'surface') = 'publicapi'
- AND JSONExtractString(log_comment, 'projectId') = {projectId: String}
-),
-classified AS (
- SELECT
- bucket_time,
- event_time_microseconds,
- multiIf(
- route_path IN (
- 'GET /api/public/spans',
- 'GET /api/public/generations',
- 'GET /api/public/traces',
- 'GET /api/public/sessions',
- 'GET /api/public/observations',
- 'GET /api/public/scores',
- 'GET /api/public/v2/scores',
- 'GET /api/public/metrics',
- 'GET /api/public/metrics/daily',
- 'GET /api/public/dataset-run-items'
- ), route_path,
- match(route_path, '^GET /api/public/traces/[^/?#]+$'), 'GET /api/public/traces/{id}',
- match(route_path, '^GET /api/public/sessions/[^/?#]+$'), 'GET /api/public/sessions/{id}',
- match(route_path, '^GET /api/public/observations/[^/?#]+$'), 'GET /api/public/observations/{id}',
- match(route_path, '^GET /api/public/scores/[^/?#]+$'), 'GET /api/public/scores/{id}',
- match(route_path, '^GET /api/public/v2/scores/[^/?#]+$'), 'GET /api/public/v2/scores/{id}',
- match(route_path, '^GET /api/public/datasets/[^/?#]+/runs/[^/?#]+$'), 'GET /api/public/datasets/{datasetName}/runs/{runName}',
- NULL
- ) AS legacy_route,
- multiIf(
- route_path IN (
- 'GET /api/public/spans',
- 'GET /api/public/generations',
- 'GET /api/public/traces',
- 'GET /api/public/observations',
- 'GET /api/public/scores',
- 'GET /api/public/v2/scores',
- 'GET /api/public/metrics/daily',
- 'GET /api/public/dataset-run-items'
- ), 2,
- route_path IN (
- 'GET /api/public/sessions',
- 'GET /api/public/metrics'
- ), 1,
- match(route_path, '^GET /api/public/traces/[^/?#]+$'), 3,
- match(route_path, '^GET /api/public/sessions/[^/?#]+$'), 1,
- match(route_path, '^GET /api/public/observations/[^/?#]+$'), 1,
- match(route_path, '^GET /api/public/scores/[^/?#]+$'), 1,
- match(route_path, '^GET /api/public/v2/scores/[^/?#]+$'), 1,
- match(route_path, '^GET /api/public/datasets/[^/?#]+/runs/[^/?#]+$'), 1,
- NULL
- ) AS clickhouse_queries_per_api_call
- FROM selected
-)
+ return {
+ projects: projects.map((project) => {
+ const summary = summaryByProjectId.get(project.id)!;
+ return {
+ ...summary,
+ projectName: project.name,
+ forceV3Experience: isForceV3ExperienceProject(project.id),
+ };
+ }),
+ };
+ }),
-SELECT
- formatDateTime(bucket_time, '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS time,
- concat('publicapi: ', legacy_route) AS entrypoint,
- sum(1.0 / clickhouse_queries_per_api_call) AS count,
- formatDateTime(max(event_time_microseconds), '%Y-%m-%dT%H:%i:%S.%fZ', 'UTC') AS lastSeen
-FROM classified
-WHERE legacy_route IS NOT NULL
- AND clickhouse_queries_per_api_call IS NOT NULL
-GROUP BY bucket_time, legacy_route
-ORDER BY bucket_time ASC, legacy_route ASC
-SETTINGS skip_unavailable_shards = 1
- `,
- params: {
- projectId: input.projectId,
- fromTimestamp: convertDateToClickhouseDateTime(input.fromTimestamp),
- toTimestamp: convertDateToClickhouseDateTime(input.toTimestamp),
- },
- tags: {
- projectId: input.projectId,
- route: "v4-legacy-api-usage",
- },
- preferredClickhouseService: "ReadOnly",
- clickhouseSettings: {
- skip_unavailable_shards: 1,
- },
+ traceLevelEvalSummaryByProject: protectedOrganizationProcedure
+ .input(z.object({ orgId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const projects = await getAccessibleOrganizationProjects({
+ prisma: ctx.prisma,
+ orgId: input.orgId,
+ session: ctx.session,
+ });
+ const projectIds = projects.map((project) => project.id);
+ return getTraceLevelEvalSummaries({
+ prisma: ctx.prisma,
+ projectIds,
});
+ }),
- const dataRows = rows.map((row) => ({
- time: row.time,
- entrypoint: row.entrypoint,
- count: Number(row.count),
- lastSeen: row.lastSeen,
- }));
-
- return dataRows.length === 0
- ? dataRows
- : getEmptyTimelineBuckets(
- input.fromTimestamp,
- input.toTimestamp,
- granularity,
- )
- .concat(dataRows)
- .sort(compareTimelineRows);
+ sdkUsageSummary: protectedProjectProcedure
+ .input(projectTimeRangeInputSchema)
+ .query(async ({ input }) => {
+ const [summary] = await getSdkUsageSummaries({
+ projectIds: [input.projectId],
+ fromTimestamp: input.fromTimestamp,
+ toTimestamp: input.toTimestamp,
+ });
+ return summary!;
+ }),
+
+ sdkUsageSummaryByProject: protectedOrganizationProcedure
+ .input(organizationTimeRangeInputSchema)
+ .query(async ({ input, ctx }) => {
+ const projects = await getAccessibleOrganizationProjects({
+ prisma: ctx.prisma,
+ orgId: input.orgId,
+ session: ctx.session,
+ });
+ return getSdkUsageSummaries({
+ projectIds: projects.map((project) => project.id),
+ fromTimestamp: input.fromTimestamp,
+ toTimestamp: input.toTimestamp,
+ });
+ }),
+
+ legacyApiUsageSummary: protectedProjectProcedure
+ .input(projectTimeRangeInputSchema)
+ .query(({ input }) =>
+ getLegacyApiUsageSummaries({
+ projectIds: [input.projectId],
+ fromTimestamp: input.fromTimestamp,
+ toTimestamp: input.toTimestamp,
+ }),
+ ),
+
+ legacyApiUsageSummaryByProject: protectedOrganizationProcedure
+ .input(organizationTimeRangeInputSchema)
+ .query(async ({ input, ctx }) => {
+ const projects = await getAccessibleOrganizationProjects({
+ prisma: ctx.prisma,
+ orgId: input.orgId,
+ session: ctx.session,
+ });
+ return getLegacyApiUsageSummaries({
+ projectIds: projects.map((project) => project.id),
+ fromTimestamp: input.fromTimestamp,
+ toTimestamp: input.toTimestamp,
+ });
}),
});