🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
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.tsindex 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.tsxindex 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 upcomingdeprecations.diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsxindex 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.tsxindex 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({<Sectiontitle="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"+ hideMissingApiKeyanalyticsSection="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 ? (<EvaluatorMigrationDialogdiff --git a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsxindex 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.tsxindex 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"><V4MigrationDetailsContentonNavigate={() => setOpen(false)}diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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 (<divclassName={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"><V4MigrationHeaderContentkey={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.tsxindex 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.tsxindex 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.tsxindex 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-hiddenclassName="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.tsxindex 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.tsxindex 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.tsxindex 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({<TableRowkey={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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 = 1upgradeStatus:capabilityStatus === "supported"? "current"- : capabilityStatus === "unsupported"- ? "outdated_major"+ : capabilityStatus === "unsupported" &&+ classification.status === "current"+ ? "outdated_minor": classification.status,};},@@ -681,9 +686,11 @@ SETTINGS skip_unavailable_shards = 1v4MigrationStatus:row.upgradeStatus === "current"? "compatible"- : row.upgradeStatus === "outdated_major"- ? "upgrade_required"- : "unknown",+ : row.upgradeStatus === "outdated_minor"+ ? "upgrade_recommended"+ : row.upgradeStatus === "outdated_major"+ ? "upgrade_required"+ : "unknown",};},);