Skip to content

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

fix(web): show only actionable projects on the v4 migration status page (#16073)

Max Deichmann65fc9c3c5094
diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsx
index 187eaa908f..473a1e9192 100644
--- a/web/src/features/v4-migration/V4MigrationContent.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.tsx
@@ -970,6 +970,34 @@ export function V4MigrationIntegrationsSection({
);
}
+// Docs link and deadline note are shared by the panel/modal header and the
+// account-level status page so both surfaces read the same.
+export function V4MigrationDocsLink() {
+ return (
+ <ExternalLink
+ href={V4_DOCS_URL}
+ analytics={{ section: "header", link: "v4_docs" }}
+ >
+ See docs.
+ </ExternalLink>
+ );
+}
+
+export function V4MigrationDeadlineNote() {
+ return (
+ <p>
+ After{" "}
+ <ExternalLink
+ href={V4_TIMELINE_URL}
+ analytics={{ section: "header", link: "v4_timeline" }}
+ >
+ {V4_MIGRATION_DEADLINE}
+ </ExternalLink>{" "}
+ some features may stop working without a v4 upgrade.
+ </p>
+ );
+}
+
// Title, status link, and the v4 pitch. The agent CTA lives in
// V4MigrationAgentUpgradeSection, rendered by the details content.
export function V4MigrationHeaderContent({
@@ -1001,25 +1029,9 @@ export function V4MigrationHeaderContent({
{actionNeeded
? "Langfuse v4 is here: real-time ingestion and up to 165× faster queries. Complete the action items below to switch this project over. "
: "Langfuse v4 is here: real-time ingestion and up to 165× faster queries. "}
- <ExternalLink
- href={V4_DOCS_URL}
- analytics={{ section: "header", link: "v4_docs" }}
- >
- See docs.
- </ExternalLink>
+ <V4MigrationDocsLink />
</p>
- {actionNeeded && (
- <p>
- After{" "}
- <ExternalLink
- href={V4_TIMELINE_URL}
- analytics={{ section: "header", link: "v4_timeline" }}
- >
- {V4_MIGRATION_DEADLINE}
- </ExternalLink>{" "}
- some features may stop working without a v4 upgrade.
- </p>
- )}
+ {actionNeeded && <V4MigrationDeadlineNote />}
</div>
</>
);
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
index 7d260ef383..3949ce6d9c 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
@@ -19,6 +19,9 @@ const mocks = vi.hoisted(() => ({
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
},
+ // Evals are the simplest way to keep the single test project on the table:
+ // ready projects are hidden, so most cases need one open action item.
+ evalCount: 1,
}));
vi.mock("next/router", () => ({
@@ -70,6 +73,17 @@ vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({
vi.mock("@/src/features/v4-migration/V4MigrationContent", () => ({
V4_MIGRATION_DEADLINE: "November 16, 2026",
useCopyMigrationPrompt: () => vi.fn(),
+ // Stand-ins for the shared sidebar copy: the real components are covered in
+ // V4MigrationContent.clienttest.tsx, here we only assert they are rendered.
+ V4MigrationDocsLink: () => (
+ <a href="https://langfuse.com/docs/v4">See docs.</a>
+ ),
+ V4MigrationDeadlineNote: () => (
+ <p>
+ After November 16, 2026 some features may stop working without a v4
+ upgrade.
+ </p>
+ ),
}));
vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({
@@ -87,7 +101,7 @@ vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({
"project-1",
{
sdk: mocks.sdk,
- evals: { status: "loaded", count: 0 },
+ evals: { status: "loaded", count: mocks.evalCount },
experiments: { status: "loaded", result: "not_required" },
apis: { status: "loaded", count: 0 },
exports: { status: "loaded", count: 0 },
@@ -118,6 +132,7 @@ describe("V4MigrationStatusPage", () => {
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
};
+ mocks.evalCount = 1;
});
it("keeps the project table readable through horizontal scrolling", () => {
@@ -132,7 +147,61 @@ describe("V4MigrationStatusPage", () => {
render(<V4MigrationStatusPage />);
expect(screen.queryByText("Migrated")).not.toBeInTheDocument();
+ expect(screen.getByText("of 1 projects needs action")).toBeInTheDocument();
+ });
+
+ it("lists only the projects that still need action", () => {
+ mocks.evalCount = 0;
+
+ render(<V4MigrationStatusPage />);
+
+ expect(screen.queryByRole("table")).not.toBeInTheDocument();
+ expect(screen.queryByText("Test project")).not.toBeInTheDocument();
expect(screen.getByText("of 1 projects need action")).toBeInTheDocument();
+ expect(
+ screen.getByText("All projects are up to date. Nothing to do here."),
+ ).toBeInTheDocument();
+ });
+
+ it("keeps projects whose checks are still running or failed", () => {
+ mocks.evalCount = 0;
+ mocks.sdk = {
+ status: "checking",
+ sdkUsageSeries: [],
+ upgradeRequiredCount: 0,
+ delayedOtelIngestionCount: 0,
+ };
+
+ render(<V4MigrationStatusPage />);
+
+ expect(screen.getByText("Test project")).toBeInTheDocument();
+ expect(
+ screen.queryByText("All projects are up to date. Nothing to do here."),
+ ).not.toBeInTheDocument();
+ });
+
+ it("opens the summary card with a link to the v4 docs", () => {
+ render(<V4MigrationStatusPage />);
+
+ expect(screen.getByText("Upgrade to v4")).toBeInTheDocument();
+ expect(screen.getByRole("link", { name: "See docs." })).toHaveAttribute(
+ "href",
+ "https://langfuse.com/docs/v4",
+ );
+ expect(
+ screen.getByText(/some features may stop working/),
+ ).toBeInTheDocument();
+ });
+
+ it("drops the deadline warning once nothing needs action", () => {
+ mocks.evalCount = 0;
+
+ render(<V4MigrationStatusPage />);
+
+ expect(screen.getByRole("link", { name: "See docs." })).toBeInTheDocument();
+ expect(
+ screen.queryByText(/some features may stop working/),
+ ).not.toBeInTheDocument();
});
it("uses the November 16, 2026 deadline throughout the FAQ", () => {
@@ -144,10 +213,7 @@ describe("V4MigrationStatusPage", () => {
});
it("only shows the status pill when action is required", () => {
- const { unmount } = render(<V4MigrationStatusPage />);
- expect(screen.queryByText("Action needed")).not.toBeInTheDocument();
- unmount();
-
+ mocks.evalCount = 0;
mocks.sdk = {
status: "checking",
sdkUsageSeries: [],
@@ -155,6 +221,7 @@ describe("V4MigrationStatusPage", () => {
delayedOtelIngestionCount: 0,
};
const checking = render(<V4MigrationStatusPage />);
+ expect(screen.queryByText("Action needed")).not.toBeInTheDocument();
expect(
screen.queryByText("Checking", { exact: true }),
).not.toBeInTheDocument();
@@ -182,7 +249,7 @@ describe("V4MigrationStatusPage", () => {
fireEvent.click(projectLink);
expect(mocks.openForProject).toHaveBeenCalledWith(
- { id: "project-1", name: "Test project", readiness: "ready" },
+ { id: "project-1", name: "Test project", readiness: "action-needed" },
"status_page_row",
);
expect(mocks.capture).toHaveBeenCalledWith(
@@ -201,7 +268,7 @@ describe("V4MigrationStatusPage", () => {
fireEvent.click(projectRow!);
expect(mocks.openForProject).toHaveBeenCalledWith(
- { id: "project-1", name: "Test project", readiness: "ready" },
+ { id: "project-1", name: "Test project", readiness: "action-needed" },
"status_page_row",
);
expect(mocks.routerPush).toHaveBeenCalledWith("/project/project-1/traces");
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
index a4e416faa5..6b88e654cb 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
@@ -15,11 +15,14 @@ import {
} from "@/src/components/ui/table";
import {
useCopyMigrationPrompt,
+ V4MigrationDeadlineNote,
+ V4MigrationDocsLink,
V4_MIGRATION_DEADLINE,
} from "@/src/features/v4-migration/V4MigrationContent";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { api } from "@/src/utils/api";
import { formatCompactRelativeTime } from "@/src/utils/dates";
+import { V4MigrationStatusDot } from "@/src/features/v4-migration/V4MigrationBadgeContent";
import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
import {
@@ -183,11 +186,11 @@ function OrgStatusSection({
};
const handleRowClick = (
- row: { id: string; name: string; status?: ProjectMigrationStatus },
+ row: { id: string; name: string; status: ProjectMigrationStatus },
readiness: ProjectMigrationReadiness,
) => {
// Forced-v3 projects have no migration panel — just navigate to the project.
- if (!row.status?.forceV3Experience) {
+ if (!row.status.forceV3Experience) {
openProjectMigration(row, readiness);
}
router.push(`/project/${row.id}/traces`);
@@ -209,19 +212,28 @@ function OrgStatusSection({
setOrderBy(next);
};
- const rows = org.projects.map((project) => {
+ // The page is a work list: projects with nothing left to do drop out of the
+ // table. The summary card still counts them.
+ const rows = org.projects.flatMap((project) => {
+ const status = statusByProjectId.get(project.id);
+ if (!status) return [];
+ const readiness = getProjectMigrationReadiness(status);
+ if (readiness === "ready") return [];
const lastTraceAt = lastTraceTimes?.find(
(trace) => trace.projectId === project.id,
)?.lastTraceAt;
- return {
- id: project.id,
- name: project.name,
- status: statusByProjectId.get(project.id),
- lastTraceLabel: lastTraceAt
- ? formatCompactRelativeTime(new Date(lastTraceAt))
- : "—",
- lastTraceSort: lastTraceAt ? new Date(lastTraceAt).getTime() : -1,
- };
+ return [
+ {
+ id: project.id,
+ name: project.name,
+ status,
+ readiness,
+ lastTraceLabel: lastTraceAt
+ ? formatCompactRelativeTime(new Date(lastTraceAt))
+ : "—",
+ lastTraceSort: lastTraceAt ? new Date(lastTraceAt).getTime() : -1,
+ },
+ ];
});
const sortValue = (
@@ -232,43 +244,41 @@ function OrgStatusSection({
case "name":
return row.name.toLowerCase();
case "status":
- return row.status
- ? {
- unavailable: 0,
- checking: 1,
- "action-needed": 2,
- ready: 3,
- "partner-managed": 4,
- }[getProjectMigrationReadiness(row.status)]
- : 0;
+ return {
+ unavailable: 0,
+ checking: 1,
+ "action-needed": 2,
+ ready: 3,
+ "partner-managed": 4,
+ }[row.readiness];
case "sdk":
- return row.status?.sdk.status === "latest"
+ return row.status.sdk.status === "latest"
? 5
- : row.status?.sdk.status === "otel_realtime"
+ : row.status.sdk.status === "otel_realtime"
? 5
- : row.status?.sdk.status === "no_data"
+ : row.status.sdk.status === "no_data"
? 5
- : row.status?.sdk.status === "legacy"
+ : row.status.sdk.status === "legacy"
? 4
- : row.status?.sdk.status === "otel_header_required"
+ : row.status.sdk.status === "otel_header_required"
? 3
- : row.status?.sdk.status === "unknown"
+ : row.status.sdk.status === "unknown"
? 2
- : row.status?.sdk.status === "checking"
+ : row.status.sdk.status === "checking"
? 1
: 0;
case "evals":
- return row.status?.evals.count ?? 0;
+ return row.status.evals.count;
case "experiments":
- return row.status?.experiments.result === "required"
+ return row.status.experiments.result === "required"
? 2
- : row.status?.experiments.result === "sdk_usage_inconclusive"
+ : row.status.experiments.result === "sdk_usage_inconclusive"
? 1
: 0;
case "apis":
- return row.status?.apis.count ?? 0;
+ return row.status.apis.count;
case "exports":
- return row.status?.exports.count ?? 0;
+ return row.status.exports.count;
case "lastTrace":
return row.lastTraceSort;
}
@@ -351,8 +361,7 @@ function OrgStatusSection({
</TableHeader>
<TableBody>
{sortedRows.map((row) => {
- if (!row.status) return null;
- const readiness = getProjectMigrationReadiness(row.status);
+ const { readiness } = row;
return (
<TableRow
key={row.id}
@@ -367,7 +376,7 @@ function OrgStatusSection({
onClick={(event) => {
event.stopPropagation();
// Forced-v3 projects have no migration panel.
- if (!row.status?.forceV3Experience) {
+ if (!row.status.forceV3Experience) {
openProjectMigration(row, readiness);
}
}}
@@ -566,6 +575,9 @@ function V4MigrationStatusPageContent() {
const unavailableProjects = readiness.filter(
(state) => state === "unavailable",
).length;
+ // Ready projects are hidden from the org tables, so the page needs its own
+ // "nothing left to do" state once every project drops out.
+ const listedProjects = readiness.filter((state) => state !== "ready").length;
const isChecking =
session.status === "loading" ||
readiness.some((state) => state === "checking");
@@ -577,34 +589,39 @@ function V4MigrationStatusPageContent() {
}}
>
<div className="flex flex-col gap-6 pt-2 pb-24">
- <Card className="flex flex-wrap items-center justify-between gap-x-6 gap-y-4 p-6">
- <div className="flex min-w-0 flex-col gap-2.5">
- <p className="text-base font-bold">
- Langfuse v4 is here. Real-time and up to 165× faster
+ <Card className="flex min-w-0 flex-col gap-2.5 p-6">
+ <p className="text-base font-bold">Upgrade to v4</p>
+ <div className="text-muted-foreground flex flex-col gap-2 text-sm leading-relaxed">
+ <p>
+ {actionNeededProjects > 0
+ ? "Langfuse v4 is here: real-time ingestion and up to 165× faster queries. Complete the action items on each project below to switch over. "
+ : "Langfuse v4 is here: real-time ingestion and up to 165× faster queries. "}
+ <V4MigrationDocsLink />
</p>
- <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
- {isChecking ? (
- <span className="text-muted-foreground text-sm">
- Checking project status…
+ {actionNeededProjects > 0 && <V4MigrationDeadlineNote />}
+ </div>
+ <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+ {isChecking ? (
+ <span className="text-muted-foreground text-sm">
+ Checking project status…
+ </span>
+ ) : totalProjects === 0 ? (
+ <span className="text-muted-foreground text-sm">
+ No active projects
+ </span>
+ ) : (
+ <>
+ <span className="text-2xl leading-none font-bold tracking-tight">
+ {actionNeededProjects}
</span>
- ) : totalProjects === 0 ? (
<span className="text-muted-foreground text-sm">
- No active projects
+ of {totalProjects} projects{" "}
+ {actionNeededProjects === 1 ? "needs" : "need"} action
+ {unavailableProjects > 0 &&
+ ` · ${unavailableProjects} could not be checked`}
</span>
- ) : (
- <>
- <span className="text-2xl leading-none font-bold tracking-tight">
- {actionNeededProjects}
- </span>
- <span className="text-muted-foreground text-sm">
- of {totalProjects} projects{" "}
- {actionNeededProjects === 1 ? "needs" : "need"} action
- {unavailableProjects > 0 &&
- ` · ${unavailableProjects} could not be checked`}
- </span>
- </>
- )}
- </div>
+ </>
+ )}
</div>
</Card>
@@ -616,6 +633,13 @@ function V4MigrationStatusPageContent() {
/>
))}
+ {!isChecking && totalProjects > 0 && listedProjects === 0 && (
+ <p className="text-muted-foreground flex items-center gap-2.5 text-sm">
+ <V4MigrationStatusDot variant="done" />
+ All projects are up to date. Nothing to do here.
+ </p>
+ )}
+
<div className="mt-6">
<p className="text-base font-bold">What&apos;s new in v4</p>
<div className="flex flex-col gap-6 pt-4">