🪢 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
/* eslint-disable no-nested-ternary, react/no-unstable-nested-components */
/* eslint-disable @repo/no-null-render */
import { useState, type ReactNode } from "react";
import Link from "next/link";
import { useRouter } from "next/router";
import { useSession } from "next-auth/react";
import { ArrowRight } from "@langfuse/icons";
import ContainerPage from "@/src/components/layouts/ContainerPage";
import { Card } from "@/src/components/ui/card";
import { Table } from "@/src/components/design-system/table/Table";
import { type LangfuseColumnDef } from "@/src/components/table/types";
import { createTextTableColumn } from "@/src/components/design-system/table/columns/createTextTableColumn";
import {
useCopyMigrationPrompt,
useHasV4MigrationDeadline,
useV4MigrationTitle,
V4MigrationDeadlineNote,
V4MigrationDocsLink,
V4_MIGRATION_DEADLINE,
} from "@/src/features/v4-migration/V4MigrationContent";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { api } from "@/src/utils/api";
import { formatCompactRelativeTime } from "@/src/utils/dates";
import { V4MigrationStatusDot } from "@/src/features/v4-migration/V4MigrationBadgeContent";
import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";
import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";
import {
useAccountV4MigrationData,
type V4MigrationOrganization,
} from "@/src/features/v4-migration/hooks/useV4MigrationData";
import {
getProjectMigrationReadiness,
type MigrationActionState,
type MigrationCountState,
type ProjectMigrationReadiness,
type ProjectMigrationStatus,
} from "@/src/features/v4-migration/migrationData";
import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";
import { V4MigrationLoadingState } from "@/src/features/v4-migration/V4MigrationLoadingState";
import { useReadPath } from "@/src/features/events/hooks/useReadPath";
import { V4PreviewToggleRow } from "@/src/features/events/components/V4SidebarToggle";
const V4_DOCS_URL = "https://langfuse.com/docs/v4";
const SDK_UPGRADE_URL =
"https://langfuse.com/docs/observability/sdk/upgrade-path";
const DATA_MODEL_URL = "https://langfuse.com/docs/observability/data-model";
const OBSERVATIONS_FAQ_URL =
"https://langfuse.com/faq/all/explore-observations-in-v4";
const API_REFERENCE_URL = "https://api.reference.langfuse.com";
function FaqLink({ href, children }: { href: string; children: ReactNode }) {
return (
<a
href={href}
target="_blank"
rel="noopener noreferrer"
className="text-dark-blue hover:underline"
>
{children}
</a>
);
}
function AffectedCell({ count }: { count: MigrationCountState }) {
if (count.status === "loading") {
return <span className="text-foreground-tertiary">Checking…</span>;
}
if (count.status === "error") {
return <span className="text-foreground-tertiary">Unavailable</span>;
}
if (count.count === 0) {
return <span className="text-foreground-tertiary">0</span>;
}
return <span>{count.count}</span>;
}
function MigrationActionCell({ state }: { state: MigrationActionState }) {
if (state.status === "loading") {
return <span className="text-foreground-tertiary">Checking…</span>;
}
if (state.status === "error") {
return <span className="text-foreground-tertiary">Unavailable</span>;
}
if (state.result === "required") {
return <span>Update required</span>;
}
if (state.result === "sdk_usage_inconclusive") {
return <span>Needs review</span>;
}
return <span className="text-foreground-tertiary">Up to date</span>;
}
function StatusPill({ readiness }: { readiness: ProjectMigrationReadiness }) {
// Forced-v3 projects are managed by their integration partner — link the pill
// straight to the FAQ instead of showing a migration action state.
if (readiness === "partner-managed") {
return (
<a
data-row-click-ignore
href={PARTNER_INTEGRATION_FAQ_URL}
target="_blank"
rel="noopener noreferrer"
className="bg-muted text-muted-foreground inline-flex w-fit shrink-0 items-center rounded-full px-2 py-0.5 text-xs font-bold whitespace-nowrap hover:underline"
title="Upgrade is handled by your integration partner"
>
Integration partner
</a>
);
}
if (readiness !== "action-needed") return null;
return (
<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>
);
}
type SortKey =
| "name"
| "status"
| "sdk"
| "evals"
| "experiments"
| "apis"
| "exports"
| "lastTrace";
type OrderBy = { column: SortKey; order: "ASC" | "DESC" } | null;
// Header styling and none → DESC → ASC → none sort cycle copied from the
// trace table (DataTable); sorting here is client-side over the static rows.
function SortableHeader({
label,
column,
orderBy,
onSort,
}: {
label: string;
column: SortKey;
orderBy: OrderBy;
onSort: (column: SortKey) => void;
}) {
return (
<div
className="-mx-2 flex h-10 w-[calc(100%+1rem)] items-center px-2"
onClick={() => onSort(column)}
>
<div className="flex items-center select-none">
<span className="truncate leading-normal" title={label}>
{label}
</span>
{orderBy?.column === column && (
<span className="ml-1" title="Sort by this column">
{orderBy.order === "ASC" ? "â–²" : "â–¼"}
</span>
)}
</div>
</div>
);
}
function OrgStatusSection({
org,
statusByProjectId,
lastTraceTimes,
}: {
org: V4MigrationOrganization;
statusByProjectId: Map<string, ProjectMigrationStatus>;
lastTraceTimes: { projectId: string; lastTraceAt: Date }[];
}) {
const router = useRouter();
const capture = usePostHogClientCapture();
const openMigrationPanel = useOpenV4MigrationPanel();
const openProjectMigration = (
row: { id: string; name: string },
readiness: ProjectMigrationReadiness,
) => {
capture("v4_migration:status_row_clicked");
openMigrationPanel(
{ id: row.id, name: row.name, readiness },
"status_page_row",
);
};
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, readiness);
}
router.push(`/project/${row.id}/traces`);
};
const [orderBy, setOrderBy] = useState<OrderBy>(null);
const handleSort = (column: SortKey) => {
const next: OrderBy =
orderBy?.column === column
? orderBy.order === "DESC"
? { column, order: "ASC" }
: null
: { column, order: "DESC" };
capture("table:column_sorting_header_click", {
column,
order: next ? next.order : "Disabled",
});
setOrderBy(next);
};
// The page is a work list: projects with nothing left to do drop out of the
// table. The summary card still counts them.
const rows = org.projects.flatMap((project) => {
const status = statusByProjectId.get(project.id);
if (!status) return [];
const readiness = getProjectMigrationReadiness(status);
if (readiness === "ready") return [];
const lastTraceAt = lastTraceTimes?.find(
(trace) => trace.projectId === project.id,
)?.lastTraceAt;
return [
{
id: project.id,
name: project.name,
status,
readiness,
lastTraceLabel: lastTraceAt
? formatCompactRelativeTime(new Date(lastTraceAt))
: "—",
lastTraceSort: lastTraceAt ? new Date(lastTraceAt).getTime() : -1,
},
];
});
const sortValue = (
row: (typeof rows)[number],
column: SortKey,
): string | number => {
switch (column) {
case "name":
return row.name.toLowerCase();
case "status":
return {
unavailable: 0,
checking: 1,
"action-needed": 2,
ready: 3,
"partner-managed": 4,
}[row.readiness];
case "sdk":
if (row.status.sdk.status === "latest") {
return 5;
}
if (row.status.sdk.status === "otel_realtime") {
return 5;
}
if (row.status.sdk.status === "no_data") {
return 5;
}
if (row.status.sdk.status === "legacy") {
return 4;
}
if (row.status.sdk.status === "otel_header_required") {
return 3;
}
if (row.status.sdk.status === "unknown") {
return 2;
}
if (row.status.sdk.status === "checking") {
return 1;
}
return 0;
case "evals":
return row.status.evals.count;
case "experiments":
if (row.status.experiments.result === "required") {
return 2;
}
if (row.status.experiments.result === "sdk_usage_inconclusive") {
return 1;
}
return 0;
case "apis":
return row.status.apis.count;
case "exports":
return row.status.exports.count;
case "lastTrace":
return row.lastTraceSort;
}
};
const sortedRows = orderBy
? [...rows].sort((a, b) => {
const va = sortValue(a, orderBy.column);
const vb = sortValue(b, orderBy.column);
const cmp =
typeof va === "string"
? va.localeCompare(vb as string)
: va - (vb as number);
return orderBy.order === "ASC" ? cmp : -cmp;
})
: rows;
const sortableHeader = (label: string, column: SortKey) => (
<SortableHeader
label={label}
column={column}
orderBy={orderBy}
onSort={handleSort}
/>
);
const columnOptions = {
cellPadding: "comfortable" as const,
};
const columns: LangfuseColumnDef<(typeof rows)[number]>[] = [
{
...columnOptions,
accessorKey: "name",
size: 192,
header: () => sortableHeader("Project", "name"),
cell: ({ row }) => (
<Link
data-row-click-ignore
href={`/project/${row.original.id}/traces`}
className="block truncate font-bold hover:underline"
title={row.original.name}
onClick={() => {
if (!row.original.status.forceV3Experience) {
openProjectMigration(row.original, row.original.readiness);
}
}}
>
{row.original.name}
</Link>
),
},
{
...columnOptions,
accessorKey: "readiness",
header: () => sortableHeader("Status", "status"),
cell: ({ row }) => <StatusPill readiness={row.original.readiness} />,
},
{
...columnOptions,
accessorKey: "sdk",
header: () => sortableHeader("SDK", "sdk"),
cell: ({ row }) => {
if (row.original.status.sdk.status === "latest") {
return <span className="text-foreground-tertiary">Latest</span>;
}
if (row.original.status.sdk.status === "otel_realtime") {
return (
<span className="text-foreground-tertiary">OTel real-time</span>
);
}
if (row.original.status.sdk.status === "no_data") {
return (
<span className="text-foreground-tertiary">No data detected</span>
);
}
if (row.original.status.sdk.status === "checking") {
return <span className="text-foreground-tertiary">Checking…</span>;
}
if (row.original.status.sdk.status === "unknown") {
return <span className="text-foreground-tertiary">Unknown</span>;
}
if (row.original.status.sdk.status === "otel_header_required") {
return (
<span>
{row.original.status.sdk.delayedOtelIngestionCount} OTel header{" "}
{row.original.status.sdk.delayedOtelIngestionCount === 1
? "required"
: "issues"}
</span>
);
}
if (row.original.status.sdk.status === "error") {
return <span className="text-foreground-tertiary">Unavailable</span>;
}
return (
<span>{row.original.status.sdk.upgradeRequiredCount} outdated</span>
);
},
},
{
...columnOptions,
accessorKey: "evals",
header: () => sortableHeader("Affected Evals", "evals"),
cell: ({ row }) => <AffectedCell count={row.original.status.evals} />,
},
{
...columnOptions,
accessorKey: "experiments",
header: () => sortableHeader("Affected Experiments", "experiments"),
cell: ({ row }) => (
<MigrationActionCell state={row.original.status.experiments} />
),
},
{
...columnOptions,
accessorKey: "apis",
header: () => sortableHeader("Affected APIs", "apis"),
cell: ({ row }) => <AffectedCell count={row.original.status.apis} />,
},
{
...columnOptions,
accessorKey: "exports",
header: () => sortableHeader("Affected Exports", "exports"),
cell: ({ row }) => <AffectedCell count={row.original.status.exports} />,
},
createTextTableColumn<(typeof rows)[number]>({
...columnOptions,
accessorKey: "lastTraceLabel",
header: () => sortableHeader("Last trace", "lastTrace"),
}),
{
accessorKey: "id",
header: "",
size: 96,
cellPadding: "comfortable",
cell: () => (
<span className="text-dark-blue flex items-center justify-end gap-1 whitespace-nowrap opacity-0 transition-opacity group-hover/row:opacity-100">
Review <ArrowRight size="sm" />
</span>
),
},
];
if (rows.length === 0) return null;
return (
<div className="flex flex-col gap-2">
<h3 className="text-muted-foreground truncate text-sm" title={org.name}>
{org.name}
</h3>
<Card className="overflow-hidden">
<div className="overflow-x-auto">
<div className="min-w-[60rem]">
<Table
tableName={`${org.name} migration status`}
columns={columns}
data={{ status: "success", data: sortedRows }}
noResultsMessage={null}
topBorder={false}
onRowClick={(row) => handleRowClick(row, row.readiness)}
getRowLabel={(row) => `Review ${row.name}`}
/>
</div>
</div>
</Card>
</div>
);
}
export default function V4MigrationStatusPage() {
const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();
if (!v4UpgradeUiEnabled) {
return null;
}
return <V4MigrationStatusPageContent />;
}
function V4MigrationStatusPageContent() {
const session = useSession();
const handleCopyPrompt = useCopyMigrationPrompt();
const hasDeadline = useHasV4MigrationDeadline();
const title = useV4MigrationTitle();
const orgs: V4MigrationOrganization[] =
session.data?.user?.organizations?.map((org) => ({
id: org.id,
name: org.name,
projects: org.projects
.filter((project) => !project.deletedAt)
.map((project) => ({ id: project.id, name: project.name })),
})) ?? [];
const statusByProjectId = useAccountV4MigrationData({
organizations: orgs,
enabled: true,
});
// Start the table's remaining data alongside the migration checks. Keeping
// these queries in the page lets one loading boundary wait for the complete
// snapshot instead of mounting each organization table with placeholder
// values that update after its rows become visible.
const lastTraceQueries = api.useQueries((t) =>
orgs.map((org) =>
t.organizations.lastTraceByProject(
{ orgId: org.id },
{ enabled: org.projects.length > 0 },
),
),
);
const faqItems: { q: string; a: ReactNode }[] = [
{
q: "Why is this happening?",
a: (
<>
We rebuilt the tracing and evaluation engine around{" "}
<FaqLink href={DATA_MODEL_URL}>observations</FaqLink>. The new engine
is real-time and holds up much better at scale.
</>
),
},
{
q: "What's in it for me?",
a: (
<>
Your{" "}
<FaqLink href={OBSERVATIONS_FAQ_URL}>data shows up instantly</FaqLink>
, everything loads faster, and you get{" "}
<FaqLink href={V4_DOCS_URL}>
features we could not build on the old engine
</FaqLink>
, like full-text search, alerting, and observation-level evals.
</>
),
},
{
q: "Do I have to do this?",
a: (
<>
Yes, eventually. The{" "}
<FaqLink href={SDK_UPGRADE_URL}>old SDKs</FaqLink>, trace-level evals,
and APIs are frozen and stop working{" "}
<span className="underline">
{hasDeadline
? `on ${V4_MIGRATION_DEADLINE}`
: "once your administrator disables the legacy mode"}
</span>
. They keep running until then, but we're no longer fixing bugs
in them.
</>
),
},
{
q: "How much work is it?",
a: (
<>
Less than you'd think. For most projects it's{" "}
<button
type="button"
onClick={handleCopyPrompt}
className="text-dark-blue hover:underline"
>
one prompt
</button>
: the agent updates your SDK and evals, and migrates your API calls,
checking with you before it changes anything.
</>
),
},
{
q: "What if I do nothing?",
a: (
<>
<span className="underline">
{hasDeadline
? `On ${V4_MIGRATION_DEADLINE}`
: "Once your administrator disables the legacy mode"}
</span>
, old SDKs stop sending data, and the{" "}
<FaqLink href={API_REFERENCE_URL}>
deprecated evals and endpoints
</FaqLink>{" "}
start returning errors.
</>
),
},
];
const totalProjects = orgs.reduce(
(total, org) => total + org.projects.length,
0,
);
const readiness = orgs.flatMap((org) =>
org.projects.flatMap((project) => {
const status = statusByProjectId.get(project.id);
return status ? [getProjectMigrationReadiness(status)] : [];
}),
);
const actionNeededProjects = readiness.filter(
(state) => state === "action-needed",
).length;
// Projects whose checks failed are neither clean nor counted as needing
// action; surface them instead of silently finalizing the count.
const unavailableProjects = readiness.filter(
(state) => state === "unavailable",
).length;
// Ready projects are hidden from the org tables, so the page needs its own
// "nothing left to do" state once every project drops out.
const listedProjects = readiness.filter((state) => state !== "ready").length;
const isLoading =
session.status === "loading" ||
readiness.some((state) => state === "checking") ||
orgs.some(
(org, index) =>
org.projects.length > 0 &&
lastTraceQueries[index]?.data === undefined &&
!lastTraceQueries[index]?.isError,
);
if (isLoading) {
return (
<ContainerPage headerProps={{ title: "Migration status" }}>
<V4MigrationLoadingState />
</ContainerPage>
);
}
return (
<ContainerPage
headerProps={{
title: "Migration status",
}}
>
<div className="flex flex-col gap-6 pt-2 pb-24">
<Card className="flex min-w-0 flex-col gap-2.5 p-6">
<p className="text-base font-bold">{title}</p>
<div className="text-muted-foreground flex flex-col gap-2 text-sm leading-relaxed">
<p>
{actionNeededProjects > 0
? "Langfuse v4 is here: real-time ingestion and up to 165× faster queries. Complete the action items on each project below to avoid disruption. "
: "Langfuse v4 is here: real-time ingestion and up to 165× faster queries. "}
<V4MigrationDocsLink />
</p>
{actionNeededProjects > 0 && <V4MigrationDeadlineNote />}
</div>
<div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
{totalProjects === 0 ? (
<span className="text-muted-foreground text-sm">
No active projects
</span>
) : (
<>
<span className="text-2xl leading-none font-bold tracking-tight">
{actionNeededProjects}
</span>
<span className="text-muted-foreground text-sm">
of {totalProjects} projects{" "}
{actionNeededProjects === 1 ? "needs" : "need"} action
{unavailableProjects > 0 &&
` · ${unavailableProjects} could not be checked`}
</span>
</>
)}
</div>
</Card>
{orgs.map((org, index) => (
<OrgStatusSection
key={org.id}
org={org}
statusByProjectId={statusByProjectId}
lastTraceTimes={lastTraceQueries[index]?.data ?? []}
/>
))}
{totalProjects > 0 && listedProjects === 0 && (
<p className="text-muted-foreground flex items-center gap-2.5 text-sm">
<V4MigrationStatusDot variant="done" />
All projects are up to date. Nothing to do here.
</p>
)}
<div className="mt-6">
<p className="text-base font-bold">What's new in v4</p>
<div className="flex flex-col gap-6 pt-4">
<div className="divide-y">
{faqItems.map(({ q, a }) => (
<div key={q} className="py-3">
<p className="text-sm font-bold">{q}</p>
<p className="text-muted-foreground mt-1 text-sm leading-relaxed">
{a}
</p>
</div>
))}
</div>
</div>
</div>
<SwitchBackSection />
</div>
</ContainerPage>
);
}
// User-level v3/v4 UI toggle, the same one the migration side panel shows.
// Hides itself when the session cannot toggle v4 (legacy/events_only write
// mode, post-rollout auto-enrollment).
function SwitchBackSection() {
const { canToggleV4, isV4 } = useReadPath();
const hasDeadline = useHasV4MigrationDeadline();
if (!canToggleV4) {
return null;
}
return (
<div className="mt-6">
<p className="text-base font-bold">
{isV4
? "Need to switch back to the legacy UI (v3)?"
: "Switch back to the latest UI (v4)"}
</p>
<div className="flex flex-col gap-4 pt-4">
{isV4 && (
<p className="text-muted-foreground text-sm leading-relaxed">
The features powering the legacy v3 UI will be sunset{" "}
{hasDeadline
? `on ${V4_MIGRATION_DEADLINE}`
: "once your administrator disables the legacy mode"}
. We strongly recommend switching to the latest UI (v4) before then.
</p>
)}
<V4PreviewToggleRow />
</div>
</div>
);
}