Skip to content

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

fix(web): simplify v4 migration sidebar (#16060)

Hassieb Pakzade2be9001c76d
diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
index 980e82b211..55ffcc2448 100644
--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts
@@ -1196,7 +1196,7 @@ describe("v4TransitionRouter", () => {
lastSeen: "2026-06-24T13:00:00Z",
hasDelayedOtelEvents: true,
attributionStatus: "attributed",
- v4MigrationStatus: "upgrade_required",
+ v4MigrationStatus: "upgrade_recommended",
},
{
sdkName: "python",
@@ -1231,7 +1231,7 @@ describe("v4TransitionRouter", () => {
lastSeen: "2026-06-24T04:00:00Z",
hasDelayedOtelEvents: true,
attributionStatus: "attributed",
- v4MigrationStatus: "upgrade_required",
+ v4MigrationStatus: "upgrade_recommended",
},
{
sdkName: "unknown",
diff --git a/web/src/components/layouts/app-layout/right-drawer/MobileRightDrawer.tsx b/web/src/components/layouts/app-layout/right-drawer/MobileRightDrawer.tsx
index 8c0935f838..6013e52c28 100644
--- a/web/src/components/layouts/app-layout/right-drawer/MobileRightDrawer.tsx
+++ b/web/src/components/layouts/app-layout/right-drawer/MobileRightDrawer.tsx
@@ -71,7 +71,7 @@ export function MobileRightDrawer({ children }: PropsWithChildren) {
<div className="bg-muted h-2 w-20 rounded-full" />
</div>
{/* sr-only for screen readers and accessibility */}
- <DrawerTitle className="sr-only">Migrate to v4</DrawerTitle>
+ <DrawerTitle className="sr-only">Upgrade to v4</DrawerTitle>
<DrawerDescription className="sr-only">
Information about migrating to Langfuse v4 and upcoming
deprecations.
diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
index 3e24579867..a67bdb9f86 100644
--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
@@ -248,6 +248,7 @@ describe("V4MigrationDetailsContent", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Migrate APIs")).toBeInTheDocument();
+ expect(screen.getByText("Migrate APIs")).toHaveClass("font-bold");
expect(screen.getByText("Migrate Integrations")).toBeInTheDocument();
expect(screen.queryByText("Legacy APIs")).not.toBeInTheDocument();
expect(screen.queryByText("Legacy Integrations")).not.toBeInTheDocument();
@@ -299,7 +300,7 @@ describe("V4MigrationDetailsContent", () => {
"Evals, experiments, APIs and integrations are up to date.",
),
).toBeInTheDocument();
- expect(screen.queryByText("Repoint Evals")).not.toBeInTheDocument();
+ expect(screen.queryByText("Retarget Evals")).not.toBeInTheDocument();
expect(screen.queryByText("Experiments")).not.toBeInTheDocument();
expect(screen.queryByText("Migrate APIs")).not.toBeInTheDocument();
expect(screen.queryByText("Migrate Integrations")).not.toBeInTheDocument();
@@ -315,10 +316,22 @@ describe("V4MigrationDetailsContent", () => {
screen.getByText("Evals and experiments are up to date."),
).toBeInTheDocument();
expect(
- screen.queryByText("Repoint Evals", { exact: true }),
+ screen.queryByText("Retarget Evals", { exact: true }),
).not.toBeInTheDocument();
});
+ it("uses Retarget consistently for affected evals", () => {
+ mocks.migrationData.evals = { status: "loaded", count: 2 };
+
+ render(<V4MigrationDetailsContent projectId="project-1" />);
+
+ fireEvent.click(screen.getByRole("button", { name: /Retarget Evals/ }));
+ expect(
+ screen.getByText(/Retarget them at observations/),
+ ).toBeInTheDocument();
+ expect(screen.queryByText(/Repoint them/)).not.toBeInTheDocument();
+ });
+
it("shows the experiment instrumentation upgrade requirement", () => {
mocks.migrationData.experiments = { status: "loaded", result: "required" };
mocks.migrationData.experimentInstrumentationUpgradePath = "sdk";
@@ -405,7 +418,11 @@ describe("V4MigrationDetailsContent", () => {
sdkVersion: "2.60.3",
v4MigrationStatus: "upgrade_required",
}),
- makeSdkUsageSeries({ publicKey: "pk-lf-fedcba0987654321" }),
+ makeSdkUsageSeries({
+ sdkVersion: "4.6.9",
+ publicKey: "pk-lf-fedcba0987654321",
+ v4MigrationStatus: "upgrade_recommended",
+ }),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 0,
@@ -418,8 +435,11 @@ 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("Python 4.6.9")).toBeInTheDocument();
expect(screen.getByText(/upgrade required/)).toBeInTheDocument();
+ expect(
+ screen.getByText("· recommended to upgrade to >= 4.7.0"),
+ ).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")!;
@@ -446,6 +466,29 @@ describe("V4MigrationDetailsContent", () => {
).not.toBeInTheDocument();
});
+ it("hides Update SDK when current-major SDKs only need a recommended bump", () => {
+ mocks.migrationData.sdk = {
+ status: "latest",
+ sdkUsageSeries: [
+ makeSdkUsageSeries({
+ sdkVersion: "4.6.9",
+ v4MigrationStatus: "upgrade_recommended",
+ }),
+ ],
+ upgradeRequiredCount: 0,
+ delayedOtelIngestionCount: 0,
+ };
+
+ 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();
+ });
+
it("keeps outdated SDK usage surfaced when a newer version later used the same key", () => {
// The check reports what it observed in the lookback window: a newer SDK
// ingesting later on the same public key is not evidence that the
@@ -817,9 +860,34 @@ describe("V4MigrationDetailsContent", () => {
).not.toBeInTheDocument();
});
+ it("omits a missing API key from custom instrumentation rows", () => {
+ mocks.migrationData.sdk = {
+ status: "unknown",
+ sdkUsageSeries: [
+ makeSdkUsageSeries({
+ sdkName: "unknown",
+ sdkVersion: "unknown",
+ canonicalSdkName: null,
+ publicKey: "",
+ attributionStatus: "missing_name_and_version",
+ v4MigrationStatus: "unknown",
+ }),
+ ],
+ upgradeRequiredCount: 0,
+ delayedOtelIngestionCount: 0,
+ };
+
+ render(<V4MigrationDetailsContent projectId="project-1" />);
+
+ const row = screen.getByText("Custom instrumentation").closest("li")!;
+ expect(within(row).queryByText("No API key")).not.toBeInTheDocument();
+ expect(within(row).getByText(/last seen/)).toBeInTheDocument();
+ });
+
it("renders the agent upgrade group with the prompt CTA", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
+ expect(screen.getByText("Upgrade using coding agents")).toBeInTheDocument();
expect(
screen.getByText(/Paste prompt into Claude Code or other coding agents/),
).toBeInTheDocument();
@@ -922,47 +990,70 @@ describe("V4MigrationHeaderContent", () => {
);
});
- it("claims the project needs migrating while checks report action needed", () => {
- render(<V4MigrationHeaderContent projectId="project-1" />);
- expect(screen.getByText(/Your setup is outdated/)).toBeInTheDocument();
- });
+ it("uses the project-independent upgrade title and requested description", () => {
+ render(<V4MigrationHeaderContent readiness="action-needed" />);
- it("drops the status claim once every check is clean", () => {
- mocks.migrationData.apis = { status: "loaded", count: 0 };
- mocks.migrationData.exports = { status: "loaded", count: 0 };
- render(<V4MigrationHeaderContent projectId="project-1" />);
+ expect(screen.getByText("Upgrade to v4")).toBeInTheDocument();
+ expect(screen.queryByText(/Project 1/)).not.toBeInTheDocument();
expect(
- screen.queryByText(/Your setup is outdated/),
- ).not.toBeInTheDocument();
- });
-
- it("drops the status claim while checks are still loading", () => {
- mocks.migrationData.apis = { status: "loading", count: 0 };
- render(<V4MigrationHeaderContent projectId="project-1" />);
+ screen.getByText(/Your project setup is outdated/),
+ ).toHaveTextContent(
+ "Your project setup is outdated. Upgrade to v4 now for real-time ingestion and up to 165x faster queries. See docs.",
+ );
+ expect(screen.getByRole("link", { name: "See docs." })).toHaveAttribute(
+ "href",
+ "https://langfuse.com/docs/v4",
+ );
expect(
- screen.queryByText(/Your setup is outdated/),
- ).not.toBeInTheDocument();
+ screen.getByText(/some features may stop working/),
+ ).toHaveTextContent(
+ "After November 16, 2026 some features may stop working without a v4 upgrade.",
+ );
+ expect(
+ screen.getByRole("link", { name: "November 16, 2026" }),
+ ).toHaveAttribute("href", "https://langfuse.com/docs/v4#timeline");
});
it("reserves a close-button gutter on the title row when the host asks", () => {
// The modal host floats the dialog's fallback close button over the
// body's top-right corner; without the gutter it overlaps the title.
- render(
- <V4MigrationHeaderContent
- projectId="project-1"
- titleRowClassName="pr-6"
- />,
- );
- expect(screen.getByText("Migrate to v4").parentElement).toHaveClass("pr-6");
+ render(<V4MigrationHeaderContent titleRowClassName="pr-6" />);
+ expect(screen.getByText("Upgrade to v4").parentElement).toHaveClass("pr-6");
+ });
+
+ it("does not call ready or unresolved projects outdated", () => {
+ for (const readiness of [
+ "ready",
+ "checking",
+ "unavailable",
+ undefined,
+ ] as const) {
+ const { unmount } = render(
+ <V4MigrationHeaderContent readiness={readiness} />,
+ );
+
+ expect(
+ screen.queryByText(/Your project setup is outdated/),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.getByText(/Langfuse v4 offers real-time ingestion/),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByText(/some features may stop working/),
+ ).not.toBeInTheDocument();
+ unmount();
+ }
});
- it("links to the docs from the details footer", () => {
+ it("labels the help footer and renders no horizontal separators", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
+ expect(screen.getByText("Need help?")).toBeInTheDocument();
expect(screen.getByRole("link", { name: "Docs" })).toHaveAttribute(
"href",
"https://langfuse.com/docs/v4",
);
+ expect(screen.queryByRole("separator")).not.toBeInTheDocument();
});
it("does not create credentials when revealing or copying the prompt", () => {
diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsx
index a2fcef1758..5a104f682f 100644
--- a/web/src/features/v4-migration/V4MigrationContent.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.tsx
@@ -20,7 +20,6 @@ import {
HoverCardTrigger,
} from "@/src/components/ui/hover-card";
import { RainbowButton } from "@/src/components/magicui/rainbow-button";
-import { Separator } from "@/src/components/ui/separator";
import {
Collapsible,
CollapsibleContent,
@@ -33,6 +32,7 @@ import { cn } from "@/src/utils/tailwind";
import { copyTextToClipboard } from "@/src/utils/clipboard";
import {
formatSdkUpgradeRequirement,
+ formatSdkUpgradeRecommendation,
formatSdkVersion,
getCustomInstrumentationSectionState,
getOtelSectionState,
@@ -48,6 +48,7 @@ import {
V4_MIGRATION_LOOKBACK_DAYS,
type MigrationActionState,
type MigrationCountState,
+ type ProjectMigrationReadiness,
} from "@/src/features/v4-migration/migrationData";
import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";
import { numberFormatter } from "@/src/utils/numbers";
@@ -68,8 +69,9 @@ import { buildDeprecatedEvaluatorsUrl } from "@/src/features/v4-migration/evalua
// (side panel and modal) render these components — edit copy here only.
const V4_DOCS_URL = "https://langfuse.com/docs/v4";
+const V4_TIMELINE_URL = `${V4_DOCS_URL}#timeline`;
// Consumed by the status page deadline copy.
-export const V4_MIGRATION_DEADLINE = "Nov 15";
+export const V4_MIGRATION_DEADLINE = "November 16, 2026";
const SDK_UPGRADE_URL =
"https://langfuse.com/docs/observability/sdk/upgrade-path";
const OTEL_V4_MIGRATION_URL =
@@ -143,10 +145,8 @@ function Section({
}}
>
<CollapsibleTrigger className="group flex w-full items-center gap-2.5 py-2.5 text-left">
- {/* A rendered section always needs the user to act (clean ones hide
- themselves); same dot as the action-required badge. */}
<V4MigrationStatusDot variant="action" />
- <span className="text-muted-foreground flex items-center gap-1.5 text-sm">
+ <span className="text-foreground flex items-center gap-1.5 text-sm font-bold">
{title}
{typeof count === "number" && (
// Same count-badge recipe as the "My Views" table button.
@@ -303,6 +303,7 @@ function SdkUsageSeriesRows({
needsAction,
suffix,
unknownSeriesLabel = "OTLP exporter",
+ hideMissingApiKey = false,
projectId,
analyticsSection,
}: {
@@ -312,6 +313,8 @@ function SdkUsageSeriesRows({
suffix: (series: V4MigrationSdkUsageSeries) => ReactNode;
/** Row label when the series carries no usable SDK name. */
unknownSeriesLabel?: string;
+ /** Omits the empty-key fallback when it is not useful to the user. */
+ hideMissingApiKey?: boolean;
/** Enables the evidence deep link. */
projectId?: string;
/** Funnel dimension for the evidence_link_clicked event (snake_case). */
@@ -330,10 +333,13 @@ function SdkUsageSeriesRows({
language: usage.canonicalSdkName ?? usage.sdkName,
version: usage.sdkVersion,
});
- const publicKey =
- usage.publicKey.length > 18
+ const publicKey = usage.publicKey
+ ? usage.publicKey.length > 18
? `${usage.publicKey.slice(0, 9)}…${usage.publicKey.slice(-6)}`
- : usage.publicKey || "No API key";
+ : usage.publicKey
+ : hideMissingApiKey
+ ? null
+ : "No API key";
const evidenceHref =
projectId && usage.eventsCount > 0
? `/project/${projectId}/observations?filter=${encodeURIComponent(
@@ -356,9 +362,11 @@ function SdkUsageSeriesRows({
</div>
{/* Metadata line, indented under the label (emoji + gap). */}
<div className="text-muted-foreground flex flex-wrap items-baseline gap-x-1.5 pl-5">
- <span title={usage.publicKey || undefined}>{publicKey}</span>
+ {publicKey ? (
+ <span title={usage.publicKey || undefined}>{publicKey}</span>
+ ) : null}
<span>
- · last seen{" "}
+ {publicKey ? "· " : ""}last seen{" "}
{formatCompactRelativeTime(new Date(usage.lastSeen))}
</span>
{/* Deep link to the exact evidence: the events table filtered by
@@ -416,7 +424,12 @@ export function V4MigrationSdkSection({
projectId?: string;
}) {
const section = getSdkSectionState(sdk);
- if (section.status === "latest" || section.status === "no_data") return null;
+ if (
+ section.status === "latest" ||
+ section.status === "recommended" ||
+ section.status === "no_data"
+ )
+ return null;
const isTransient =
section.status === "checking" || section.status === "error";
@@ -425,7 +438,11 @@ export function V4MigrationSdkSection({
<Section
title="Update SDK"
analyticsSection="sdk"
- count={isTransient ? undefined : section.actionableCount}
+ count={
+ isTransient || section.actionableCount === 0
+ ? undefined
+ : section.actionableCount
+ }
meta={
section.status === "checking"
? "Checking…"
@@ -466,6 +483,10 @@ export function V4MigrationSdkSection({
suffix={(usage) =>
usage.v4MigrationStatus === "upgrade_required" ? (
<span>· {formatSdkUpgradeRequirement(usage.canonicalSdkName)}</span>
+ ) : usage.v4MigrationStatus === "upgrade_recommended" ? (
+ <span>
+ · {formatSdkUpgradeRecommendation(usage.canonicalSdkName)}
+ </span>
) : usage.v4MigrationStatus === "unknown" ? (
<span>· version not recognized</span>
) : null
@@ -588,6 +609,7 @@ export function V4MigrationCustomInstrumentationSection({
series={section.series}
projectId={projectId}
unknownSeriesLabel="Custom instrumentation"
+ hideMissingApiKey
analyticsSection="custom_instrumentation"
needsAction={() => true}
suffix={() => null}
@@ -616,7 +638,7 @@ export function V4MigrationEvalsSection({
const capture = usePostHogClientCapture();
return (
<Section
- title="Repoint Evals"
+ title="Retarget Evals"
analyticsSection="evals"
count={state.status === "loaded" ? state.count : undefined}
meta={
@@ -662,7 +684,7 @@ export function V4MigrationEvalsSection({
input/output
</>
)}
- , which v4 no longer sets. Repoint{" "}
+ , which v4 no longer sets. Retarget{" "}
{state.count === 1 ? "it" : "them"} at observations.
</p>
{assistant && (
@@ -940,30 +962,18 @@ export function V4MigrationIntegrationsSection({
// Title, status link, and the v4 pitch. The agent CTA lives in
// V4MigrationAgentUpgradeSection, rendered by the details content.
export function V4MigrationHeaderContent({
- projectName,
- projectId,
titleRowClassName,
+ readiness,
}: {
- projectName?: string;
- projectId?: string;
/** Extra classes on the title row. The modal host passes a right gutter:
* its dialog floats a fallback close button over the body's top-right
* corner (the title is sr-only, so there is no DialogHeader row), which
* would otherwise overlap the title. */
titleRowClassName?: string;
+ /** Known readiness from the organization status page or an action-only entry point. */
+ readiness?: ProjectMigrationReadiness;
}) {
- // Same queries as V4MigrationDetailsContent below, so react-query dedupes
- // them. Only claim the project needs migrating once the checks confirm it —
- // a fully migrated project shows the v4 value prop without a status claim.
- const { organization } = useProject(projectId ?? null);
- const migrationData = useProjectV4MigrationData({
- projectId,
- orgId: organization?.id,
- enabled: Boolean(projectId),
- });
- const needsMigration =
- Boolean(projectId) &&
- getProjectMigrationReadiness(migrationData) === "action-needed";
+ const actionNeeded = readiness === "action-needed";
return (
<>
@@ -973,22 +983,33 @@ export function V4MigrationHeaderContent({
titleRowClassName,
)}
>
- <p className="min-w-0 text-lg font-bold">
- {projectName ? <>Migrate {projectName} to v4</> : "Migrate to v4"}
+ <p className="min-w-0 text-lg font-bold">Upgrade to v4</p>
+ </div>
+ <div className="text-muted-foreground flex flex-col gap-2 text-sm leading-relaxed">
+ <p>
+ {actionNeeded
+ ? "Your project setup is outdated. Upgrade to v4 now for real-time ingestion and up to 165x faster queries. "
+ : "Langfuse v4 offers real-time ingestion and up to 165x faster queries. "}
+ <ExternalLink
+ href={V4_DOCS_URL}
+ analytics={{ section: "header", link: "v4_docs" }}
+ >
+ See docs.
+ </ExternalLink>
</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>
+ )}
</div>
- <p className="text-muted-foreground text-sm leading-relaxed">
- {/* Only claim the setup is outdated once the checks confirm it. */}
- {needsMigration && "Your setup is outdated. "}
- Upgrade to Langfuse v4 for{" "}
- <ExternalLink
- href={V4_DOCS_URL}
- analytics={{ section: "header", link: "v4_docs" }}
- >
- real-time ingestion
- </ExternalLink>{" "}
- and up to 165× faster queries.
- </p>
</>
);
}
@@ -1088,7 +1109,7 @@ export function V4MigrationAgentUpgradeSection({
<div className="flex flex-col gap-6">
<div className="flex flex-col gap-1">
<div className="flex items-center gap-2 text-base font-bold">
- Auto-upgrade with agents
+ Upgrade using coding agents
</div>
<p className="text-muted-foreground text-sm">
Paste prompt into Claude Code or other coding agents
@@ -1295,8 +1316,6 @@ export function V4MigrationDetailsContent({
return (
<>
- <Separator />
-
<div className="flex flex-col gap-1">
<div className="flex items-center gap-2 text-base font-bold">
Action items
@@ -1360,8 +1379,6 @@ export function V4MigrationDetailsContent({
</div>
</div>
- <Separator />
-
<V4MigrationAgentUpgradeSection projectId={projectId} />
{/* The toggle row hides itself when the session cannot toggle v4
@@ -1404,36 +1421,37 @@ export function V4MigrationDetailsContent({
</>
)}
- <Separator />
-
- <div className="text-muted-foreground flex flex-wrap items-center gap-x-2 gap-y-1 text-sm">
- <a
- href={V4_DOCS_URL}
- target="_blank"
- rel="noopener noreferrer"
- onClick={() => capture("v4_migration:panel_docs_link_clicked")}
- className="underline"
- >
- Docs
- </a>
- <span>·</span>
- <button
- type="button"
- onClick={handleEmailEngineer}
- className="underline"
- >
- Email an engineer
- </button>
- <span>·</span>
- <a
- href="https://cal.com/team/langfuse/v4-upgrade"
- target="_blank"
- rel="noopener noreferrer"
- onClick={() => capture("v4_migration:contact_book_call_clicked")}
- className="underline"
- >
- Book a call
- </a>
+ <div className="flex flex-col gap-2">
+ <p className="text-base font-bold">Need help?</p>
+ <div className="text-muted-foreground flex flex-wrap items-center gap-x-2 gap-y-1 text-sm">
+ <a
+ href={V4_DOCS_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={() => capture("v4_migration:panel_docs_link_clicked")}
+ className="underline"
+ >
+ Docs
+ </a>
+ <span>·</span>
+ <button
+ type="button"
+ onClick={handleEmailEngineer}
+ className="underline"
+ >
+ Email an engineer
+ </button>
+ <span>·</span>
+ <a
+ href="https://cal.com/team/langfuse/v4-upgrade"
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={() => capture("v4_migration:contact_book_call_clicked")}
+ className="underline"
+ >
+ Book a call
+ </a>
+ </div>
</div>
{projectId ? (
<EvaluatorMigrationDialog
diff --git a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx
index 36a10754d4..90229c6109 100644
--- a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx
@@ -103,4 +103,25 @@ describe("v4 migration entry points", () => {
expect(screen.getByText("Update")).toBeInTheDocument();
expect(screen.getByText("Action required")).toBeInTheDocument();
});
+
+ it("hides both entry points while checks are pending or unavailable", () => {
+ for (const status of [
+ migrationStatus({ evals: { status: "loading", count: 0 } }),
+ migrationStatus({ evals: { status: "error", count: 0 } }),
+ ]) {
+ mocks.migrationData = status;
+ const { unmount } = render(
+ <>
+ <V4MigrationProjectChip
+ project={{ id: "project-1", name: "Project 1" }}
+ status={status}
+ />
+ <V4MigrationNavItem />
+ </>,
+ );
+
+ expect(screen.queryByRole("button")).not.toBeInTheDocument();
+ unmount();
+ }
+ });
});
diff --git a/web/src/features/v4-migration/V4MigrationModal.tsx b/web/src/features/v4-migration/V4MigrationModal.tsx
index c96a756670..15a3f6fbd5 100644
--- a/web/src/features/v4-migration/V4MigrationModal.tsx
+++ b/web/src/features/v4-migration/V4MigrationModal.tsx
@@ -54,17 +54,13 @@ function V4MigrationModalContent({
overlayClassName="backdrop-blur-sm"
closeOnInteractionOutside
>
- <DialogTitle className="sr-only">
- {`Upgrade ${project.name} to v4`}
- </DialogTitle>
+ <DialogTitle className="sr-only">Upgrade to v4</DialogTitle>
<DialogBody className="gap-0 p-4">
<V4MigrationHeaderContent
- projectName={project.name}
- projectId={project.id}
// Clear the dialog's floating fallback close button (top-right).
titleRowClassName="pr-6"
+ readiness="action-needed"
/>
- {/* Details opens with its own separator above Action items. */}
<div className="mt-6 flex flex-col gap-6">
<V4MigrationDetailsContent
onNavigate={() => setOpen(false)}
diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsx
index 7af397b721..a0d61b789e 100644
--- a/web/src/features/v4-migration/V4MigrationNavItem.tsx
+++ b/web/src/features/v4-migration/V4MigrationNavItem.tsx
@@ -30,16 +30,10 @@ export function V4MigrationNavItem() {
exports: migrationData.exports,
forceV3Experience: migrationData.forceV3Experience,
});
- if (readiness === "ready") {
+ if (readiness !== "action-needed") {
return null;
}
-
- const label =
- readiness === "checking"
- ? "Checking"
- : readiness === "unavailable"
- ? "Check status"
- : "Action required";
+ const label = "Action required";
const handleClick = () => {
capture("sidebar:v4_migration_card_clicked");
diff --git a/web/src/features/v4-migration/V4MigrationPanel.clienttest.tsx b/web/src/features/v4-migration/V4MigrationPanel.clienttest.tsx
new file mode 100644
index 0000000000..9321690233
--- /dev/null
+++ b/web/src/features/v4-migration/V4MigrationPanel.clienttest.tsx
@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { vi } from "vitest";
+
+import { V4MigrationPanel } from "./V4MigrationPanel";
+import type { ProjectMigrationStatus } from "./migrationData";
+
+const mocks = vi.hoisted(() => ({
+ migrationData: {
+ sdk: {
+ status: "checking" as const,
+ sdkUsageSeries: [],
+ upgradeRequiredCount: 0,
+ delayedOtelIngestionCount: 0,
+ },
+ evals: { status: "loading" as const, count: 0 },
+ experiments: { status: "loading" as const, result: null },
+ apis: { status: "loading" as const, count: 0 },
+ exports: { status: "loading" as const, count: 0 },
+ forceV3Experience: false,
+ } as ProjectMigrationStatus,
+}));
+
+vi.mock("@/src/features/v4-migration/V4MigrationPanelProvider", () => ({
+ useV4MigrationPanel: () => ({
+ open: true,
+ setOpen: vi.fn(),
+ targetProject: {
+ id: "project-id",
+ name: "Project",
+ readiness: "checking",
+ },
+ }),
+}));
+
+vi.mock("@/src/features/projects/hooks", () => ({
+ useQueryProject: () => ({ project: null }),
+ useProject: () => ({ organization: { id: "org-id" } }),
+}));
+
+vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({
+ useProjectV4MigrationData: () => mocks.migrationData,
+}));
+
+vi.mock("@/src/features/v4-migration/V4MigrationContent", () => ({
+ V4MigrationHeaderContent: ({ readiness }: { readiness?: string }) => (
+ <div data-testid="readiness">{readiness ?? "unknown"}</div>
+ ),
+ V4MigrationDetailsContent: () => <div>Details</div>,
+}));
+
+describe("V4MigrationPanel", () => {
+ it("refreshes header readiness when pending checks become actionable", () => {
+ const { rerender } = render(<V4MigrationPanel />);
+ expect(screen.getByTestId("readiness")).toHaveTextContent("checking");
+
+ mocks.migrationData = {
+ ...mocks.migrationData,
+ sdk: {
+ ...mocks.migrationData.sdk,
+ status: "latest",
+ },
+ evals: { status: "loaded", count: 1 },
+ experiments: { status: "loaded", result: "not_required" },
+ apis: { status: "loaded", count: 0 },
+ exports: { status: "loaded", count: 0 },
+ };
+ rerender(<V4MigrationPanel />);
+
+ expect(screen.getByTestId("readiness")).toHaveTextContent("action-needed");
+ });
+});
diff --git a/web/src/features/v4-migration/V4MigrationPanel.tsx b/web/src/features/v4-migration/V4MigrationPanel.tsx
index 23175615b2..c31135acb5 100644
--- a/web/src/features/v4-migration/V4MigrationPanel.tsx
+++ b/web/src/features/v4-migration/V4MigrationPanel.tsx
@@ -2,11 +2,13 @@
import { X } from "lucide-react";
import { Button } from "@/src/components/ui/button";
import { useV4MigrationPanel } from "@/src/features/v4-migration/V4MigrationPanelProvider";
-import { useQueryProject } from "@/src/features/projects/hooks";
+import { useProject, useQueryProject } from "@/src/features/projects/hooks";
import {
V4MigrationHeaderContent,
V4MigrationDetailsContent,
} from "@/src/features/v4-migration/V4MigrationContent";
+import { useProjectV4MigrationData } from "@/src/features/v4-migration/hooks/useV4MigrationData";
+import { getProjectMigrationReadiness } from "@/src/features/v4-migration/migrationData";
import { cn } from "@/src/utils/tailwind";
export const V4MigrationPanel = ({
@@ -19,41 +21,60 @@ export const V4MigrationPanel = ({
const { open, setOpen, targetProject } = useV4MigrationPanel();
const { project: routeProject } = useQueryProject();
- if (!open) return null;
-
// Prefer the route's project so the panel follows navigation while open;
// targetProject only decides on project-less routes (home, status page),
// where it carries the project the opening surface was about.
const project = routeProject
- ? { id: routeProject.id, name: routeProject.name }
+ ? {
+ id: routeProject.id,
+ name: routeProject.name,
+ readiness:
+ targetProject?.id === routeProject.id
+ ? targetProject.readiness
+ : 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);
+ // Keep a known entry-point state while the panel queries are unresolved,
+ // then derive readiness from the live results so the header cannot retain a
+ // stale status-page snapshot after checks finish.
+ const readiness =
+ liveReadiness === "checking" || liveReadiness === "unavailable"
+ ? project?.readiness
+ : liveReadiness;
+
+ if (!open) return null;
return (
<div
className={cn([
- "bg-background flex h-full w-full min-w-0 flex-col",
+ "bg-background relative flex h-full w-full min-w-0 flex-col",
className,
])}
>
- <div className="flex min-h-11 w-full items-center justify-between gap-1 px-4 py-1">
- <span className="text-sm font-bold">Update</span>
- {showCloseButton && (
- <Button
- variant="ghost"
- size="icon"
- onClick={() => setOpen(false)}
- aria-label="Close"
- >
- <X className="h-4 w-4" />
- </Button>
- )}
- </div>
- <div className="flex-1 overflow-y-auto border-t">
+ {showCloseButton && (
+ <Button
+ variant="ghost"
+ size="icon"
+ className="absolute top-2 right-2"
+ onClick={() => setOpen(false)}
+ aria-label="Close"
+ >
+ <X className="h-4 w-4" />
+ </Button>
+ )}
+ <div className="flex-1 overflow-y-auto">
<div className="px-4 pt-4">
<V4MigrationHeaderContent
key={project?.id}
- projectName={project?.name}
- projectId={project?.id}
+ titleRowClassName={showCloseButton ? "pr-10" : undefined}
+ readiness={readiness}
/>
</div>
diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx
index 67aa893c90..8246024577 100644
--- a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx
@@ -64,6 +64,7 @@ describe("V4MigrationPanelProvider", () => {
expect(result.current.targetProject).toEqual({
id: "project-id",
name: "Project",
+ readiness: "action-needed",
});
expect(captureMock).toHaveBeenCalledExactlyOnceWith(
"v4_migration:panel_opened",
diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.tsx
index 1ca0fc9a15..b8156b81fc 100644
--- a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx
+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.tsx
@@ -6,9 +6,14 @@ import {
} from "react";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
+import type { ProjectMigrationReadiness } from "@/src/features/v4-migration/migrationData";
import { useQueryProject } from "@/src/features/projects/hooks";
-export type V4MigrationTargetProject = { id: string; name: string };
+export type V4MigrationTargetProject = {
+ id: string;
+ name: string;
+ readiness?: ProjectMigrationReadiness;
+};
/** Which surface opened the panel; the funnel's entry dimension. */
export type V4MigrationPanelOpenSource =
@@ -62,7 +67,13 @@ export function V4MigrationPanelProvider({
if (!v4UpgradeUiEnabled) return;
if (!open || project.id !== targetProject?.id)
capture("v4_migration:panel_opened", { source });
- setTargetProject(project);
+ // Entry points that only appear for actionable projects may omit readiness.
+ // Normalize them here so a later route change can distinguish that known
+ // state from an unrelated project whose readiness has not been loaded.
+ setTargetProject({
+ ...project,
+ readiness: project.readiness ?? "action-needed",
+ });
setRequestedOpen(true);
};
diff --git a/web/src/features/v4-migration/V4MigrationProjectChip.tsx b/web/src/features/v4-migration/V4MigrationProjectChip.tsx
index e049e1aeea..fc34c9af25 100644
--- a/web/src/features/v4-migration/V4MigrationProjectChip.tsx
+++ b/web/src/features/v4-migration/V4MigrationProjectChip.tsx
@@ -18,7 +18,6 @@ export function V4MigrationProjectChip({
const capture = usePostHogClientCapture();
const readiness = status ? getProjectMigrationReadiness(status) : "checking";
-
// Forced-v3 projects show no migration action — the upgrade is handled by
// their integration partner. Point them at the FAQ instead.
if (readiness === "partner-managed") {
@@ -39,17 +38,10 @@ export function V4MigrationProjectChip({
);
}
- if (readiness === "ready") {
+ if (readiness !== "action-needed") {
return null;
}
- const label =
- readiness === "checking"
- ? "Checking"
- : readiness === "unavailable"
- ? "Check status"
- : "Update";
-
const handleClick = () => {
capture("v4_migration:project_chip_clicked");
openMigrationPanel(project, "project_chip");
@@ -65,7 +57,7 @@ export function V4MigrationProjectChip({
aria-hidden
className="size-1.75 shrink-0 rounded-full bg-orange-400 dark:bg-orange-400"
></span>
- {label}
+ Update
</button>
);
}
diff --git a/web/src/features/v4-migration/V4MigrationSections.stories.tsx b/web/src/features/v4-migration/V4MigrationSections.stories.tsx
index 793b87775f..7b54f552e8 100644
--- a/web/src/features/v4-migration/V4MigrationSections.stories.tsx
+++ b/web/src/features/v4-migration/V4MigrationSections.stories.tsx
@@ -63,6 +63,12 @@ const outdatedJavascript = makeSeries({
v4MigrationStatus: "upgrade_required",
publicKey: "pk-lf-fedcba0987654321",
});
+const recommendedPython = makeSeries({
+ sdkVersion: "4.6.9",
+ v4MigrationStatus: "upgrade_recommended",
+ publicKey: "pk-lf-recommended-0001",
+ lastSeen: new Date(Date.now() - 2 * HOUR_MS).toISOString(),
+});
const unrecognizedSdk = makeSeries({
sdkName: "my-custom-wrapper",
sdkVersion: "0.4.0",
@@ -110,7 +116,12 @@ const customInstrumentation = makeSeries({
const sdkOutdatedState = makeSdkState({
status: "legacy",
- sdkUsageSeries: [outdatedPython, scoresOnlyPython, outdatedJavascript],
+ sdkUsageSeries: [
+ recommendedPython,
+ outdatedPython,
+ scoresOnlyPython,
+ outdatedJavascript,
+ ],
upgradeRequiredCount: 3,
});
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
index 95b3caca9b..7d260ef383 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx
@@ -13,7 +13,8 @@ const mocks = vi.hoisted(() => ({
| "legacy"
| "otel_realtime"
| "otel_header_required"
- | "no_data",
+ | "no_data"
+ | "checking",
sdkUsageSeries: [],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
@@ -67,7 +68,7 @@ vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({
}));
vi.mock("@/src/features/v4-migration/V4MigrationContent", () => ({
- V4_MIGRATION_DEADLINE: "Nov 15",
+ V4_MIGRATION_DEADLINE: "November 16, 2026",
useCopyMigrationPrompt: () => vi.fn(),
}));
@@ -130,10 +131,45 @@ describe("V4MigrationStatusPage", () => {
it("shows migration readiness to project members", () => {
render(<V4MigrationStatusPage />);
- expect(screen.getByText("Migrated")).toBeInTheDocument();
+ expect(screen.queryByText("Migrated")).not.toBeInTheDocument();
expect(screen.getByText("of 1 projects need action")).toBeInTheDocument();
});
+ it("uses the November 16, 2026 deadline throughout the FAQ", () => {
+ render(<V4MigrationStatusPage />);
+
+ expect(screen.getByText("on November 16, 2026")).toBeInTheDocument();
+ expect(screen.getByText("On November 16, 2026")).toBeInTheDocument();
+ expect(screen.queryByText(/Oct 9/)).not.toBeInTheDocument();
+ });
+
+ it("only shows the status pill when action is required", () => {
+ const { unmount } = render(<V4MigrationStatusPage />);
+ expect(screen.queryByText("Action needed")).not.toBeInTheDocument();
+ unmount();
+
+ mocks.sdk = {
+ status: "checking",
+ sdkUsageSeries: [],
+ upgradeRequiredCount: 0,
+ delayedOtelIngestionCount: 0,
+ };
+ const checking = render(<V4MigrationStatusPage />);
+ expect(
+ screen.queryByText("Checking", { exact: true }),
+ ).not.toBeInTheDocument();
+ checking.unmount();
+
+ mocks.sdk = {
+ status: "legacy",
+ sdkUsageSeries: [],
+ upgradeRequiredCount: 1,
+ delayedOtelIngestionCount: 0,
+ };
+ render(<V4MigrationStatusPage />);
+ expect(screen.getByText("Action needed")).toBeInTheDocument();
+ });
+
it("links projects to traces and opens the migration panel", () => {
render(<V4MigrationStatusPage />);
@@ -146,7 +182,7 @@ describe("V4MigrationStatusPage", () => {
fireEvent.click(projectLink);
expect(mocks.openForProject).toHaveBeenCalledWith(
- { id: "project-1", name: "Test project" },
+ { id: "project-1", name: "Test project", readiness: "ready" },
"status_page_row",
);
expect(mocks.capture).toHaveBeenCalledWith(
@@ -165,7 +201,7 @@ describe("V4MigrationStatusPage", () => {
fireEvent.click(projectRow!);
expect(mocks.openForProject).toHaveBeenCalledWith(
- { id: "project-1", name: "Test project" },
+ { id: "project-1", name: "Test project", readiness: "ready" },
"status_page_row",
);
expect(mocks.routerPush).toHaveBeenCalledWith("/project/project-1/traces");
@@ -208,7 +244,7 @@ describe("V4MigrationStatusPage", () => {
render(<V4MigrationStatusPage />);
- expect(screen.getByText("Migrated")).toBeInTheDocument();
+ expect(screen.queryByText("Migrated")).not.toBeInTheDocument();
expect(screen.getByText("OTel real-time")).toBeInTheDocument();
expect(screen.queryByText("Latest")).not.toBeInTheDocument();
});
@@ -223,7 +259,7 @@ describe("V4MigrationStatusPage", () => {
render(<V4MigrationStatusPage />);
- expect(screen.getByText("Migrated")).toBeInTheDocument();
+ expect(screen.queryByText("Migrated")).not.toBeInTheDocument();
expect(screen.getByText("No data detected")).toBeInTheDocument();
});
});
diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
index fc2d833c4c..78405c0659 100644
--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx
+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx
@@ -20,7 +20,6 @@ import {
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { api } from "@/src/utils/api";
import { formatCompactRelativeTime } from "@/src/utils/dates";
-import { cn } from "@/src/utils/tailwind";
import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
import {
@@ -104,27 +103,11 @@ function StatusPill({ readiness }: { readiness: ProjectMigrationReadiness }) {
);
}
- const label =
- readiness === "ready"
- ? "Migrated"
- : readiness === "checking"
- ? "Checking"
- : readiness === "unavailable"
- ? "Unavailable"
- : "Action needed";
+ if (readiness !== "action-needed") return null;
return (
- <span
- className={cn(
- "inline-flex w-fit shrink-0 items-center rounded-full px-2 py-0.5 text-xs font-bold whitespace-nowrap",
- readiness === "ready"
- ? "bg-light-green text-dark-green"
- : readiness === "checking" || readiness === "unavailable"
- ? "bg-muted text-muted-foreground"
- : "bg-light-yellow text-dark-yellow",
- )}
- >
- {label}
+ <span className="bg-light-yellow text-dark-yellow inline-flex w-fit shrink-0 items-center rounded-full px-2 py-0.5 text-xs font-bold whitespace-nowrap">
+ Action needed
</span>
);
}
@@ -188,19 +171,24 @@ function OrgStatusSection({
{ enabled: org.projects.length > 0 },
);
- const openProjectMigration = (row: { id: string; name: string }) => {
+ const openProjectMigration = (
+ row: { id: string; name: string },
+ readiness: ProjectMigrationReadiness,
+ ) => {
capture("v4_migration:status_row_clicked");
- openMigrationPanel({ id: row.id, name: row.name }, "status_page_row");
+ openMigrationPanel(
+ { id: row.id, name: row.name, readiness },
+ "status_page_row",
+ );
};
- const handleRowClick = (row: {
- id: string;
- name: string;
- status?: ProjectMigrationStatus;
- }) => {
+ const handleRowClick = (
+ 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) {
- openProjectMigration(row);
+ openProjectMigration(row, readiness);
}
router.push(`/project/${row.id}/traces`);
};
@@ -369,7 +357,7 @@ function OrgStatusSection({
<TableRow
key={row.id}
className="group/row cursor-pointer"
- onClick={() => handleRowClick(row)}
+ onClick={() => handleRowClick(row, readiness)}
>
<TableCell density="comfortable" className="max-w-48">
<Link
@@ -380,7 +368,7 @@ function OrgStatusSection({
event.stopPropagation();
// Forced-v3 projects have no migration panel.
if (!row.status?.forceV3Experience) {
- openProjectMigration(row);
+ openProjectMigration(row, readiness);
}
}}
>
diff --git a/web/src/features/v4-migration/migrationData.clienttest.ts b/web/src/features/v4-migration/migrationData.clienttest.ts
index 6531b594c0..502d8ee6cd 100644
--- a/web/src/features/v4-migration/migrationData.clienttest.ts
+++ b/web/src/features/v4-migration/migrationData.clienttest.ts
@@ -128,7 +128,7 @@ describe("v4 migration data", () => {
).toBe("unavailable");
});
- it("aggregates real API usage by normalized endpoint", () => {
+ it("aggregates real API usage by normalized endpoint and sorts most recent first", () => {
expect(
aggregateLegacyApiUsage([
{
@@ -149,6 +149,12 @@ describe("v4 migration data", () => {
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([
{
@@ -156,6 +162,11 @@ describe("v4 migration data", () => {
count: 5,
lastSeen: "2026-07-23T10:37:00Z",
},
+ {
+ endpoint: "GET /api/public/sessions",
+ count: 20,
+ lastSeen: "2026-07-23T08:37:00Z",
+ },
]);
});
diff --git a/web/src/features/v4-migration/migrationData.ts b/web/src/features/v4-migration/migrationData.ts
index 8332d86b45..9adb232c20 100644
--- a/web/src/features/v4-migration/migrationData.ts
+++ b/web/src/features/v4-migration/migrationData.ts
@@ -169,7 +169,8 @@ export const aggregateLegacyApiUsage = (
...usage,
})).sort(
(left, right) =>
- right.count - left.count || left.endpoint.localeCompare(right.endpoint),
+ right.lastSeen.localeCompare(left.lastSeen) ||
+ left.endpoint.localeCompare(right.endpoint),
);
};
diff --git a/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts b/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts
index 12385f7ba2..c7b0dcbef8 100644
--- a/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts
+++ b/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts
@@ -1,5 +1,7 @@
import {
formatSdkUpgradeRequirement,
+ formatSdkUpgradeRecommendation,
+ getSdkSectionState,
formatSdkVersion,
getV4MigrationSdkState,
type V4MigrationSdkUsageSeries,
@@ -53,6 +55,45 @@ describe("v4 migration SDK status", () => {
});
});
+ it("treats the current major below the recommended minor as functional", () => {
+ const state = getLoadedSdkState(
+ sdkSeries({
+ sdkVersion: "4.6.9",
+ v4MigrationStatus: "upgrade_recommended",
+ }),
+ );
+
+ expect(state).toMatchObject({
+ status: "latest",
+ upgradeRequiredCount: 0,
+ });
+ expect(getSdkSectionState(state)).toMatchObject({
+ status: "recommended",
+ actionableCount: 0,
+ recommendedCount: 1,
+ });
+ });
+
+ it("orders SDK usage by most recent last seen", () => {
+ const state = getLoadedSdkState(
+ sdkSeries({
+ sdkVersion: "4.6.9",
+ publicKey: "pk-lf-older-outdated",
+ lastSeen: "2026-07-22T10:00:00Z",
+ v4MigrationStatus: "upgrade_required",
+ }),
+ sdkSeries({
+ publicKey: "pk-lf-newer-compatible",
+ lastSeen: "2026-07-23T10:00:00Z",
+ }),
+ );
+
+ expect(state.sdkUsageSeries.map((series) => series.publicKey)).toEqual([
+ "pk-lf-newer-compatible",
+ "pk-lf-older-outdated",
+ ]);
+ });
+
it("does not require action for raw OTel already using real-time ingestion", () => {
expect(
getLoadedSdkState(
@@ -163,8 +204,8 @@ describe("v4 migration SDK status", () => {
});
it.each([
- ["javascript", "upgrade required to >= 5.4.0"],
- ["python", "upgrade required to >= 4.7.0"],
+ ["javascript", "upgrade required to >= 5.0.0"],
+ ["python", "upgrade required to >= 4.0.0"],
[null, "upgrade required"],
] as const)(
"formats %s upgrade guidance with its minimum compatible version",
@@ -172,4 +213,15 @@ describe("v4 migration SDK status", () => {
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);
+ },
+ );
});
diff --git a/web/src/features/v4-migration/sdkVersionStatus.ts b/web/src/features/v4-migration/sdkVersionStatus.ts
index bbe4ddef71..583ebfdda5 100644
--- a/web/src/features/v4-migration/sdkVersionStatus.ts
+++ b/web/src/features/v4-migration/sdkVersionStatus.ts
@@ -44,16 +44,7 @@ export const isCustomInstrumentationSeries = (
const sortSdkUsageSeries = (
rows: V4MigrationSdkUsageSeries[],
): V4MigrationSdkUsageSeries[] =>
- [...rows].sort(
- (left, right) =>
- Number(right.v4MigrationStatus === "upgrade_required") -
- Number(left.v4MigrationStatus === "upgrade_required") ||
- Number(requiresOtelIngestionHeader(right)) -
- Number(requiresOtelIngestionHeader(left)) ||
- Number(right.v4MigrationStatus === "unknown") -
- Number(left.v4MigrationStatus === "unknown") ||
- left.lastSeen.localeCompare(right.lastSeen),
- );
+ [...rows].sort((left, right) => right.lastSeen.localeCompare(left.lastSeen));
export const getV4MigrationSdkState = (params: {
summary: SdkUsageSummary | undefined;
@@ -86,7 +77,9 @@ export const getV4MigrationSdkState = (params: {
series.v4MigrationStatus === "unknown",
);
const hasCompatibleSdk = sdkUsageSeries.some(
- (series) => series.v4MigrationStatus === "compatible",
+ (series) =>
+ series.v4MigrationStatus === "compatible" ||
+ series.v4MigrationStatus === "upgrade_recommended",
);
const hasRealtimeOtelIngestion = sdkUsageSeries.some(
(series) =>
@@ -143,15 +136,23 @@ export const isActionableSdkSeries = (
series.v4MigrationStatus === "unknown";
export type V4MigrationSdkSectionState = {
- /** "latest" and "no_data" mean no offenders; the section hides itself.
+ /** "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" | "latest" | "no_data";
- /** All detected recognized-SDK series, offenders sorted first. */
+ status:
+ | "checking"
+ | "error"
+ | "legacy"
+ | "recommended"
+ | "latest"
+ | "no_data";
+ /** All detected recognized-SDK series, 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 = (
@@ -161,6 +162,9 @@ export const getSdkSectionState = (
(usage) => usage.canonicalSdkName !== null,
);
const actionableCount = series.filter(isActionableSdkSeries).length;
+ const recommendedCount = series.filter(
+ (usage) => usage.v4MigrationStatus === "upgrade_recommended",
+ ).length;
return {
status:
@@ -170,9 +174,12 @@ export const getSdkSectionState = (
? "no_data"
: actionableCount > 0
? "legacy"
- : "latest",
+ : recommendedCount > 0
+ ? "recommended"
+ : "latest",
series,
actionableCount,
+ recommendedCount,
};
};
@@ -188,7 +195,7 @@ export const getCustomInstrumentationSectionState = (
});
export type V4MigrationOtelSectionState = {
- /** All detected OTel exporter series, delayed ones sorted first. */
+ /** All detected OTel exporter series, most recently seen first. */
series: V4MigrationSdkUsageSeries[];
delayedCount: number;
};
@@ -224,7 +231,21 @@ export const formatSdkUpgradeRequirement = (
"appRootObservations",
);
- return minimumVersion
- ? `upgrade required to >= ${minimumVersion}`
+ const requiredMajor = minimumVersion?.split(".")[0];
+ return requiredMajor
+ ? `upgrade required to >= ${requiredMajor}.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/server/v4TransitionRouter.ts b/web/src/features/v4/server/v4TransitionRouter.ts
index f56bdbedce..b28fbcecd5 100644
--- a/web/src/features/v4/server/v4TransitionRouter.ts
+++ b/web/src/features/v4/server/v4TransitionRouter.ts
@@ -128,7 +128,7 @@ type DecoratedSdkUsageSummaryRow = {
hasDelayedOtelEvents: boolean | null;
attributionStatus: IngestionSdkAttributionStatus;
canonicalSdkName: "python" | "javascript" | null;
- upgradeStatus: IngestionSdkUpgradeStatus;
+ upgradeStatus: IngestionSdkUpgradeStatus | "outdated_minor";
};
type SdkUsageSummaryByProjectRow = {
@@ -158,7 +158,11 @@ type SdkUsageSummaryByProjectSeries = {
lastSeen: string;
hasDelayedOtelEvents: boolean | null;
attributionStatus: IngestionSdkAttributionStatus;
- v4MigrationStatus: "compatible" | "upgrade_required" | "unknown";
+ v4MigrationStatus:
+ | "compatible"
+ | "upgrade_recommended"
+ | "upgrade_required"
+ | "unknown";
};
// Counts stay out of this row on purpose: the client derives every displayed
@@ -659,8 +663,9 @@ SETTINGS skip_unavailable_shards = 1
upgradeStatus:
capabilityStatus === "supported"
? "current"
- : capabilityStatus === "unsupported"
- ? "outdated_major"
+ : capabilityStatus === "unsupported" &&
+ classification.status === "current"
+ ? "outdated_minor"
: classification.status,
};
},
@@ -681,9 +686,11 @@ SETTINGS skip_unavailable_shards = 1
v4MigrationStatus:
row.upgradeStatus === "current"
? "compatible"
- : row.upgradeStatus === "outdated_major"
- ? "upgrade_required"
- : "unknown",
+ : row.upgradeStatus === "outdated_minor"
+ ? "upgrade_recommended"
+ : row.upgradeStatus === "outdated_major"
+ ? "upgrade_required"
+ : "unknown",
};
},
);