🪢 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, @repo/component-file-structure, react/no-unstable-nested-components */
/* eslint-disable @repo/no-style-props, @repo/no-null-render */
import { showSuccessToast } from "@/src/features/notifications/showSuccessToast";
import { showErrorToast } from "@/src/features/notifications/showErrorToast";
import { type ReactNode, useEffect, useRef, useState } from "react";
import { useRouter } from "next/router";
import Link from "next/link";
import {
BotMessageSquare,
Check,
ChevronRight,
Copy,
Info,
} from "@langfuse/icons";
import { env } from "@/src/env.mjs";
import { useIsInAppAgentLauncherVisible } from "@/src/features/in-app-agent/components/InAppAiAgentProvider";
import { useLangfuseCloudRegion } from "@/src/features/organizations/hooks";
import { useSupportDrawer } from "@/src/features/support-chat/SupportDrawerProvider";
import { Button } from "@/src/components/ui/button";
import { HoverCard } from "@/src/components/design-system/HoverCard/HoverCard";
import { RainbowButton } from "@/src/components/magicui/RainbowButton";
import { Separator } from "@/src/components/ui/separator";
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from "@/src/components/ui/collapsible";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { cn } from "@/src/utils/tailwind";
import { copyTextToClipboard } from "@/src/utils/clipboard";
import {
formatSdkUpgradeRequirement,
formatSdkVersion,
getAvailableSdkMajorUpgrade,
getCustomInstrumentationSectionState,
getDetectedInstrumentationSeries,
getOtelSectionState,
getSdkSectionState,
isActionableSdkSeries,
type V4MigrationSdkState,
type V4MigrationSdkUsageSeries,
} from "@/src/features/v4-migration/sdkVersionStatus";
import { V4MigrationStatusDot } from "@/src/features/v4-migration/V4MigrationBadgeContent";
import { useProjectV4MigrationData } from "@/src/features/v4-migration/hooks/useV4MigrationData";
import {
getProjectMigrationReadiness,
V4_MIGRATION_LOOKBACK_DAYS,
type MigrationActionState,
type MigrationCountState,
type ProjectMigrationReadiness,
} from "@/src/features/v4-migration/migrationData";
import { useReadPath } from "@/src/features/events/hooks/useReadPath";
import { V4PreviewToggleRow } from "@/src/features/events/components/V4SidebarToggle";
import { numberFormatter } from "@/src/utils/numbers";
import { formatCompactRelativeTime } from "@/src/utils/dates";
import { useQueryProjectOrOrganization } from "@/src/features/projects/hooks";
import {
useEvalUpgradeAssistantPlan,
V4_CODING_AGENT_PROMPT,
} from "@/src/features/v4-migration/useV4UpgradeAssistantSupport";
import { useHasProjectAccess } from "@/src/features/rbac/utils/checkProjectAccess";
import { api } from "@/src/utils/api";
import { classifyTrpcToastError } from "@/src/utils/trpcErrorClassification";
import { encodeFiltersGeneric, type FilterState } from "@langfuse/shared";
import { EvaluatorMigrationDialog } from "@/src/features/v4-migration/EvaluatorMigrationDialog";
import { buildDeprecatedRulesUrl } from "@/src/features/v4-migration/evaluatorMigrationUrls";
import {
getApiMigrationGuidance,
getCodingAgentName,
type MigrationSdkName,
} from "@/src/features/v4-migration/apiMigrationGuidance";
// Single source of truth for the v4-migration copy and content. Both surfaces
// (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 = "November 16, 2026";
// Headline form of the deadline; the year is noise in a title.
const V4_MIGRATION_DEADLINE_SHORT = "November 16";
const SDK_UPGRADE_URL =
"https://langfuse.com/docs/observability/sdk/upgrade-path";
const OTEL_V4_MIGRATION_URL =
"https://langfuse.com/integrations/native/opentelemetry/migration-to-v4";
const DEPRECATED_API_MIGRATION_URL =
"https://langfuse.com/faq/all/deprecated-api-migration";
const OBSERVATIONS_DATA_MODEL_URL =
"https://langfuse.com/docs/observability/data-model#observations-and-traces";
const DEPRECATED_INTEGRATION_MIGRATION_URLS: Record<string, string> = {
PostHog:
"https://langfuse.com/integrations/analytics/posthog#migrate-export-source",
Mixpanel:
"https://langfuse.com/integrations/analytics/mixpanel#migrate-export-source",
"Blob Storage":
"https://langfuse.com/docs/api-and-data-platform/features/export-to-blob-storage#upgrade-path",
};
const EXPERIMENT_OTEL_INGESTION_URL =
"https://langfuse.com/integrations/native/opentelemetry/experiments";
// The docs ship one combined SDK page, which is also the right target for
// language-agnostic guidance: the upgrade applies to every Langfuse SDK, not
// just the two most common ones.
const SDK_OVERVIEW_URL = "https://langfuse.com/docs/observability/sdk/overview";
const OTEL_INTEGRATION_URL =
"https://langfuse.com/integrations/native/opentelemetry";
// v4 feature docs linked from the upgrade header pitch.
const FULL_TEXT_SEARCH_URL =
"https://langfuse.com/docs/observability/features/full-text-search";
const FILTER_SEARCH_BAR_URL =
"https://langfuse.com/docs/observability/features/filter-search-bar";
const ALERTS_URL = "https://langfuse.com/docs/metrics/features/alerts";
const CODE_EVALUATORS_URL =
"https://langfuse.com/docs/evaluation/evaluation-methods/code-evaluators";
const LANGFUSE_ASSISTANT_URL = "https://langfuse.com/docs/langfuse-assistant";
// Hassieb's 2 minute walkthrough of the upgrade steps. Linked (not embedded)
// from the Need help footer, so the panel stays free of YouTube player
// chrome and the CSP frame-src stays untouched. Cloud only: the video covers
// the steps as they apply to Langfuse Cloud projects.
const WALKTHROUGH_VIDEO_URL = "https://www.youtube.com/watch?v=g3YbbqVGt4g";
// Copies the agent migration prompt to the clipboard with toast + analytics;
// shared by the panel/modal header CTA and the status page.
export function useCopyMigrationPrompt() {
const capture = usePostHogClientCapture();
return async () => {
// Falls back to a hidden textarea on non-secure contexts (plain-HTTP
// self-hosted) where navigator.clipboard is unavailable.
await copyTextToClipboard(V4_CODING_AGENT_PROMPT);
capture("v4_migration:coding_agent_prompt_copied");
showSuccessToast({
operation: "prompt.copy",
title: "Prompt copied",
description: "Paste it into Cursor, Codex, or another coding agent.",
});
};
}
function Section({
title,
count,
meta,
children,
defaultOpen,
analyticsSection,
statusVariant = "action",
tone = "default",
}: {
title: string;
/** Number of affected items, shown muted after the title. */
count?: number;
/** Right-aligned muted text for transient states (checking, failed). */
meta?: ReactNode;
children: ReactNode;
defaultOpen?: boolean;
/** Funnel dimension for the section_expanded event (snake_case). */
analyticsSection: string;
statusVariant?: "action" | "done";
/** "muted" recesses the trigger to match the settled-checks summary line, so
* a section that needs no action does not read as an action item. */
tone?: "default" | "muted";
}) {
const capture = usePostHogClientCapture();
return (
<Collapsible
defaultOpen={defaultOpen}
onOpenChange={(isOpen) => {
// User expansions only — defaultOpen does not fire onOpenChange.
if (isOpen)
capture("v4_migration:section_expanded", {
section: analyticsSection,
});
}}
>
<CollapsibleTrigger className="group flex w-full items-center gap-2.5 py-2.5 text-left">
<V4MigrationStatusDot variant={statusVariant} />
<span
className={cn(
"flex items-center gap-1.5 text-sm",
tone === "muted"
? "text-muted-foreground"
: "text-foreground font-bold",
)}
>
{title}
{typeof count === "number" && (
// Same count-badge recipe as the "My Views" table button.
<span className="bg-input rounded-sm px-1 text-xs">{count}</span>
)}
</span>
<span className="flex-1" />
{meta && <span className="text-muted-foreground text-xs">{meta}</span>}
<ChevronRight
size="base"
color="tertiary"
__rawClassName="transition-transform group-data-[state=open]:rotate-90"
/>
</CollapsibleTrigger>
<CollapsibleContent>
<div className="pt-0.5 pb-4 pl-4.25">{children}</div>
</CollapsibleContent>
</Collapsible>
);
}
function MonoValue({ children }: { children: ReactNode }) {
return <span className="text-foreground font-bold">{children}</span>;
}
function ExternalLink({
href,
children,
className,
analytics,
ariaLabel,
}: {
href: string;
children: ReactNode;
className?: string;
/** Which guidance link in which section — for section_link_clicked. */
analytics?: { section: string; link: string };
ariaLabel?: string;
}) {
const capture = usePostHogClientCapture();
return (
<a
href={href}
target="_blank"
rel="noopener noreferrer"
className={cn("underline", className)}
aria-label={ariaLabel}
onClick={
analytics
? () => capture("v4_migration:section_link_clicked", analytics)
: undefined
}
>
{children}
</a>
);
}
// Evidence deep-link filter for one SDK usage series: always the exact public
// key (including the empty value used by raw OTel ingestion), source, plus the
// ingestion SDK name/version when the series carries exact values — so two SDK
// versions on the same key link to distinct result sets.
// "unknown" is the attribution fallback bucket, not an exact value, so those
// dimensions fall back to key + source.
function buildSdkUsageEvidenceFilter(usage: V4MigrationSdkUsageSeries): string {
const filters: FilterState = [
{
column: "ingestionApiKey",
type: "stringOptions",
operator: "any of",
value: [usage.publicKey],
},
{
column: "ingestionSource",
type: "stringOptions",
operator: "any of",
value: [usage.source],
},
];
if (usage.sdkName !== "unknown") {
filters.push({
column: "ingestionSdkName",
type: "stringOptions",
operator: "any of",
value: [usage.sdkName],
});
}
if (usage.sdkVersion !== "unknown") {
filters.push({
column: "ingestionSdkVersion",
type: "stringOptions",
operator: "any of",
value: [usage.sdkVersion],
});
}
return encodeFiltersGeneric(filters);
}
// Bordered code block with a corner copy button that swaps to a check for 2s
// as inline feedback. The agent prompt and the generated .env block both
// render through this so the copy affordance stays consistent.
function CodeBlockWithCopy({
text,
copyLabel,
onCopy,
scrollable,
className,
}: {
text: string;
/** Accessible label for the corner button, e.g. "Copy keys". */
copyLabel: string;
/** Fired after a successful copy (analytics). */
onCopy?: () => void;
scrollable?: boolean;
className?: string;
}) {
const [copied, setCopied] = useState(false);
const copiedTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
// The timeout is an external system: clear it so a panel closed right
// after copying cannot fire a state update on an unmounted component.
useEffect(
() => () => {
if (copiedTimeout.current) clearTimeout(copiedTimeout.current);
},
[],
);
return (
<div className={cn("bg-muted/50 relative rounded-md border", className)}>
{/* The button anchors to the outer wrapper so it stays in the corner
while the content scrolls. */}
<div className={cn("p-3", scrollable && "max-h-32 overflow-y-auto")}>
<code className="text-muted-foreground font-mono text-[10px] leading-4 break-words whitespace-pre-wrap">
{text}
</code>
</div>
<Button
variant="ghost"
size="icon"
onClick={async () => {
// Falls back to a hidden textarea on non-secure contexts
// (plain-HTTP self-hosted) where navigator.clipboard is
// unavailable.
await copyTextToClipboard(text);
onCopy?.();
setCopied(true);
if (copiedTimeout.current) clearTimeout(copiedTimeout.current);
copiedTimeout.current = setTimeout(() => setCopied(false), 2000);
}}
aria-label={copied ? "Copied" : copyLabel}
title={copied ? "Copied" : copyLabel}
className="text-muted-foreground absolute top-1 right-1 h-6 w-6"
>
{copied ? (
<Check size="base" color="default" />
) : (
<Copy size="base" color="default" />
)}
</Button>
</div>
);
}
function SdkUsageSeriesRows({
series,
needsAction,
suffix,
unknownSeriesLabel = "Custom instrumentation",
hideMissingApiKey = false,
projectId,
analyticsSection,
}: {
series: V4MigrationSdkUsageSeries[];
/** Drives the per-row status emoji; the suffix carries the text meaning. */
needsAction: (series: V4MigrationSdkUsageSeries) => boolean;
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). */
analyticsSection: string;
}) {
const capture = usePostHogClientCapture();
if (series.length === 0) return null;
return (
<ul className="mt-2 flex flex-col gap-2">
{series.map((usage) => {
const sdkLabel =
usage.canonicalSdkName === null && usage.sdkName === "unknown"
? unknownSeriesLabel
: formatSdkVersion({
language: usage.canonicalSdkName ?? usage.sdkName,
version: usage.sdkVersion,
});
const publicKey = (() => {
if (usage.publicKey) {
if (usage.publicKey.length > 18) {
return `${usage.publicKey.slice(0, 9)}…${usage.publicKey.slice(-6)}`;
}
return usage.publicKey;
}
if (hideMissingApiKey) {
return null;
}
return "No API key";
})();
const evidenceHref =
projectId && usage.eventCount > 0
? `/project/${projectId}/observations?filter=${encodeURIComponent(
buildSdkUsageEvidenceFilter(usage),
)}&dateRange=${V4_MIGRATION_LOOKBACK_DAYS}d`
: null;
return (
<li
key={`${usage.source}:${usage.sdkName}:${usage.sdkVersion}:${usage.publicKey}`}
// Message-box style: soft fill + a thicker left edge to group the
// two lines of one item.
className="bg-muted/50 border-border rounded-md border-l-4 p-2 text-sm"
>
{/* Action line: what it is and what to do about it. */}
<div className="text-muted-foreground flex items-center gap-1.5">
<span aria-hidden="true">{needsAction(usage) ? "⚠️" : "✅"}</span>
<MonoValue>{sdkLabel}</MonoValue>
{suffix(usage)}
</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">
{publicKey ? (
<span title={usage.publicKey || undefined}>{publicKey}</span>
) : null}
<span>
{publicKey ? "· " : ""}last seen{" "}
{formatCompactRelativeTime(new Date(usage.lastSeen))}
</span>
{/* Deep link to the exact evidence: the events table filtered by
this public key, plus SDK name and version when attributed,
over the detection lookback. An empty public key is an exact
filter value for raw OTel ingestion. */}
{evidenceHref ? (
<>
<span aria-hidden="true">·</span>
<Link
// The events page's `filter` param carries the semicolon
// filter encoding (column;type;key;operator;value), not the
// search-bar grammar; the bar re-derives its text from it.
href={evidenceHref}
target="_blank"
rel="noopener noreferrer"
onClick={() => {
// Bounded values only: raw sdkName/sdkVersion are
// client-supplied ingestion headers (user-controlled,
// unbounded cardinality) and must not reach PostHog.
capture("v4_migration:evidence_link_clicked", {
section: analyticsSection,
sdkName: usage.canonicalSdkName ?? "other",
v4MigrationStatus: usage.v4MigrationStatus,
attributionStatus: usage.attributionStatus,
});
}}
className="underline"
>
View observations
</Link>
</>
) : null}
</div>
</li>
);
})}
</ul>
);
}
// Renders only while there is at least one recognized SDK with a pending
// upgrade (unrecognized SDKs live in the custom instrumentation section).
// Also carries the transient
// checking/error states so they are not silently lost.
// Exported for the state-gallery story.
export function V4MigrationSdkSection({
sdk,
defaultOpen,
projectId,
}: {
sdk: V4MigrationSdkState;
defaultOpen?: boolean;
projectId?: string;
}) {
const section = getSdkSectionState(sdk);
if (section.status === "latest" || section.status === "no_data") return null;
const isTransient =
section.status === "checking" || section.status === "error";
return (
<Section
title="Update SDK"
analyticsSection="sdk"
count={
isTransient || section.actionableCount === 0
? undefined
: section.actionableCount
}
meta={
section.status === "checking"
? "Checking…"
: section.status === "error"
? "Check failed"
: undefined
}
defaultOpen={defaultOpen}
>
<p className="text-muted-foreground text-sm leading-relaxed">
{section.status === "checking" ? (
"Checking the latest traces for this project…"
) : section.status === "error" ? (
"We could not check the latest traces for this project. Try again later."
) : (
<>
{section.actionableCount} detected SDK{" "}
{section.actionableCount === 1
? "configuration needs"
: "configurations need"}{" "}
an update, based on ingestion seen in the last{" "}
{V4_MIGRATION_LOOKBACK_DAYS} days. See{" "}
<ExternalLink
href={SDK_UPGRADE_URL}
analytics={{ section: "sdk", link: "sdk_upgrade_docs" }}
>
upgrade path
</ExternalLink>
.
</>
)}
</p>
<SdkUsageSeriesRows
series={section.series}
projectId={projectId}
analyticsSection="sdk"
needsAction={isActionableSdkSeries}
suffix={(usage) => {
if (usage.v4MigrationStatus === "upgrade_required") {
return <span>· {formatSdkUpgradeRequirement(usage)}</span>;
}
if (usage.v4MigrationStatus === "unknown") {
return <span>· version not recognized</span>;
}
return null;
}}
/>
</Section>
);
}
// Renders only while at least one OTel exporter still ingests through the
// delayed path; the SDK section above owns the checking/error states.
// Exported for the state-gallery story.
export function V4MigrationOtelSection({
sdk,
defaultOpen,
projectId,
}: {
sdk: V4MigrationSdkState;
defaultOpen?: boolean;
projectId?: string;
}) {
const section = getOtelSectionState(sdk);
if (
sdk.status === "checking" ||
sdk.status === "error" ||
section.delayedCount === 0
)
return null;
return (
<Section
title="Update OTel Instrumentation"
analyticsSection="otel"
count={section.delayedCount}
defaultOpen={defaultOpen}
>
<p className="text-muted-foreground text-sm leading-relaxed">
Your OpenTelemetry data is using delayed ingestion. For real-time
ingestion, upgrade your integration or, if you use OpenTelemetry
directly, set <MonoValue>x-langfuse-ingestion-version: 4</MonoValue> on
your OTLP exporter.{" "}
<ExternalLink
href={OTEL_V4_MIGRATION_URL}
analytics={{ section: "otel", link: "otel_migration_docs" }}
>
Migration guide
</ExternalLink>
.
</p>
<SdkUsageSeriesRows
series={section.series}
projectId={projectId}
analyticsSection="otel"
needsAction={(usage) => usage.actionLevel === "required"}
suffix={(usage) =>
usage.deliveryMode === "delayed" ? (
<span>· delayed</span>
) : (
<span>· real-time</span>
)
}
/>
</Section>
);
}
// Renders only while ingestion-API traffic without a Langfuse SDK header is
// detected: custom instrumentation against POST /api/public/ingestion, or an
// SDK too old to send attribution headers. Exported for the gallery story.
export function V4MigrationCustomInstrumentationSection({
sdk,
defaultOpen,
projectId,
}: {
sdk: V4MigrationSdkState;
defaultOpen?: boolean;
projectId?: string;
}) {
const section = getCustomInstrumentationSectionState(sdk);
if (
sdk.status === "checking" ||
sdk.status === "error" ||
section.series.length === 0
)
return null;
return (
<Section
title="Upgrade Instrumentation"
analyticsSection="custom_instrumentation"
count={section.series.length}
defaultOpen={defaultOpen}
>
<p className="text-muted-foreground text-sm leading-relaxed">
Data is arriving through the ingestion API without a Langfuse SDK
header, so this looks like custom instrumentation or a very old SDK
version. Please upgrade to the latest version of{" "}
<ExternalLink
href={SDK_OVERVIEW_URL}
analytics={{
section: "custom_instrumentation",
link: "sdk_overview_docs",
}}
>
any Langfuse SDK
</ExternalLink>
, or use the{" "}
<ExternalLink
href={OTEL_INTEGRATION_URL}
analytics={{
section: "custom_instrumentation",
link: "otel_integration_docs",
}}
>
OpenTelemetry endpoint
</ExternalLink>
.
</p>
<SdkUsageSeriesRows
series={section.series}
projectId={projectId}
unknownSeriesLabel="Custom instrumentation"
hideMissingApiKey
analyticsSection="custom_instrumentation"
needsAction={() => true}
suffix={() => null}
/>
</Section>
);
}
export function V4MigrationDetectedInstrumentationSection({
sdk,
projectId,
}: {
sdk: V4MigrationSdkState;
projectId?: string;
}) {
const series = getDetectedInstrumentationSeries(sdk);
if (series.length === 0) return null;
return (
<Section
title="Detected V4-compatible instrumentation"
analyticsSection="detected_instrumentation"
count={series.length}
statusVariant="done"
tone="muted"
>
<p className="text-muted-foreground text-sm leading-relaxed">
These configurations are on a V4-compatible SDK major or use real-time
OTel ingestion.
</p>
<SdkUsageSeriesRows
series={series}
projectId={projectId}
analyticsSection="detected_instrumentation"
needsAction={() => false}
suffix={(usage) => {
if (usage.remediationType !== "update_sdk") {
return <span>· real-time</span>;
}
const majorUpgrade = getAvailableSdkMajorUpgrade(usage);
if (!majorUpgrade) return <span>· up to date</span>;
return (
<span>
· {majorUpgrade.label} is available ·{" "}
<ExternalLink
href={majorUpgrade.upgradeGuideUrl}
analytics={{
section: "detected_instrumentation",
link: "sdk_major_upgrade_docs",
}}
>
Upgrade guide
</ExternalLink>
</span>
);
}}
/>
</Section>
);
}
// The four checker sections below are presentational (data via props) so the
// state gallery story can render every variant without tRPC or router mocks.
export function V4MigrationEvalsSection({
state,
assistant,
evalsUrl,
onNavigate,
defaultOpen,
}: {
state: MigrationCountState;
/** Upgrade CTA; null hides the button. Assistant branding only while AI
* features are on — otherwise the dialog opens on its choice screen, so
* the button must not promise the assistant. */
assistant: { onMigrate: () => void; aiFeaturesEnabled?: boolean } | null;
evalsUrl?: string;
onNavigate?: () => void;
defaultOpen?: boolean;
}) {
const capture = usePostHogClientCapture();
return (
<Section
title="Update Evals"
analyticsSection="evals"
count={state.status === "loaded" ? state.count : undefined}
meta={
state.status === "loading"
? "Checking…"
: state.status === "error"
? "Check failed"
: undefined
}
defaultOpen={defaultOpen}
>
{state.status === "loading" ? (
<p className="text-muted-foreground text-sm">
Checking configured evals…
</p>
) : state.status === "error" ? (
<p className="text-muted-foreground text-sm">
We could not check configured evals. Try again later.
</p>
) : state.count > 0 ? (
<>
<p className="text-muted-foreground mb-2 text-sm">
{evalsUrl ? (
<Link
href={evalsUrl}
onClick={() => {
capture("v4_migration:section_link_clicked", {
section: "evals",
link: "evals_table",
});
onNavigate?.();
}}
className="underline"
>
{state.count}{" "}
{state.count === 1 ? "eval targets" : "evals target"} trace
input/output
</Link>
) : (
<>
{state.count}{" "}
{state.count === 1 ? "eval targets" : "evals target"} trace
input/output
</>
)}
, which v4 no longer sets. Update{" "}
{state.count === 1 ? "it" : "them"} to target observations.
</p>
{assistant && (
<Button variant="outline" size="sm" onClick={assistant.onMigrate}>
{assistant.aiFeaturesEnabled !== false ? (
<>
<BotMessageSquare
size="base"
color="default"
__rawClassName="mr-1.5"
/>
Use Halo
</>
) : (
"Update evals"
)}
</Button>
)}
</>
) : (
<p className="text-muted-foreground text-sm">
No deprecated evals detected.
</p>
)}
</Section>
);
}
export function V4MigrationExperimentsSection({
state,
upgradePath,
defaultOpen,
}: {
state: MigrationActionState;
upgradePath: "sdk" | "api" | null;
defaultOpen?: boolean;
}) {
return (
<Section
title="Update Experiments"
analyticsSection="experiments"
meta={
state.status === "loading"
? "Checking…"
: state.status === "error"
? "Check failed"
: undefined
}
defaultOpen={defaultOpen}
>
{state.status === "loading" ? (
<p className="text-muted-foreground text-sm">
Checking experiment instrumentation…
</p>
) : state.status === "error" ? (
<p className="text-muted-foreground text-sm">
We could not check experiment instrumentation. Try again later.
</p>
) : state.result !== "not_required" ? (
<p className="text-muted-foreground text-sm">
{upgradePath === "api" ? (
<>
This project called the deprecated{" "}
<MonoValue>POST /dataset-run-items</MonoValue>. Replace this
direct API call with OTel experiment instrumentation. See the{" "}
<ExternalLink
href={EXPERIMENT_OTEL_INGESTION_URL}
analytics={{
section: "experiments",
link: "experiments_otel_docs",
}}
>
OTel experiment instrumentation guide
</ExternalLink>{" "}
for more details.
</>
) : state.result === "sdk_usage_inconclusive" ? (
<>
This project called <MonoValue>POST /dataset-run-items</MonoValue>{" "}
with an SDK version that supports the experiment runner. Review
that you are using the experiment runner SDK and not the
deprecated{" "}
<>
<>
<code className="bg-muted px-1 font-mono text-sm">
.link()
</code>{" "}
method. This warning will{" "}
</>
disappear once you{" "}
</>
upgrade to latest SDK version.
</>
) : (
<>
This project called <MonoValue>POST /dataset-run-items</MonoValue>{" "}
with an outdated SDK.{" "}
<ExternalLink
href={SDK_UPGRADE_URL}
analytics={{ section: "experiments", link: "sdk_upgrade_docs" }}
>
Upgrade the SDK
</ExternalLink>{" "}
and use the experiment runner method.
</>
)}
</p>
) : (
<p className="text-muted-foreground text-sm">
No experiment instrumentation updates required.
</p>
)}
</Section>
);
}
export function V4MigrationApisSection({
state,
usage,
defaultOpen,
}: {
state: MigrationCountState;
usage: {
endpoint: string;
count: number;
lastSeen: string;
callers?: {
sdkName?: MigrationSdkName;
sdkVersion?: string;
userAgent?: string;
isOther?: true;
count: number;
lastSeen: string;
}[];
}[];
defaultOpen?: boolean;
}) {
return (
<Section
title="Migrate APIs"
analyticsSection="apis"
count={state.status === "loaded" ? state.count : undefined}
meta={
state.status === "loading"
? "Checking…"
: state.status === "error"
? "Check failed"
: undefined
}
defaultOpen={defaultOpen}
>
{state.status === "loading" ? (
<p className="text-muted-foreground text-sm">
Checking public API usage…
</p>
) : state.status === "error" ? (
<p className="text-muted-foreground text-sm">
We could not check public API usage. Try again later.
</p>
) : usage.length > 0 ? (
<>
<p className="text-muted-foreground mb-2 text-sm">
You've recently called deprecated endpoints that will stop
working after the migration deadline. Please check the{" "}
<ExternalLink
href={DEPRECATED_API_MIGRATION_URL}
analytics={{ section: "apis", link: "deprecated_api_docs" }}
>
migration guide
</ExternalLink>
</p>
<div className="flex flex-col gap-3">
{usage.map((row) => {
const roundedCount = Math.max(1, Math.round(row.count));
const callers = row.callers ?? [];
const hasKnownCallers = callers.some((caller) => !caller.isOther);
const publicApiPrefix = "/api/public/";
const publicApiPrefixStart =
row.endpoint.indexOf(publicApiPrefix);
const publicApiPrefixEnd =
publicApiPrefixStart < 0
? 0
: publicApiPrefixStart + publicApiPrefix.length;
return (
<div key={row.endpoint} className="rounded-md border p-3">
<div className="flex flex-wrap items-baseline justify-between gap-x-2">
<ExternalLink
href={DEPRECATED_API_MIGRATION_URL}
className="text-sm"
analytics={{
section: "apis",
link: "deprecated_api_docs",
}}
ariaLabel={row.endpoint}
>
{row.endpoint.slice(0, publicApiPrefixEnd)}
<span className="font-bold">
{row.endpoint.slice(publicApiPrefixEnd)}
</span>
</ExternalLink>
{!hasKnownCallers ? (
<span
className="text-muted-foreground text-sm whitespace-nowrap"
title={`Last seen at ${row.lastSeen}`}
>
{numberFormatter(roundedCount, 0)}{" "}
{roundedCount === 1 ? "call" : "calls"} · last seen{" "}
{formatCompactRelativeTime(new Date(row.lastSeen))}
</span>
) : null}
</div>
{hasKnownCallers ? (
<ul className="mt-2 flex flex-col gap-2">
{callers.map((caller, index) => {
const codingAgent = getCodingAgentName(
caller.userAgent,
);
const guidance = getApiMigrationGuidance(
row.endpoint,
caller.sdkName,
caller.sdkVersion,
);
const callerName = (() => {
if (caller.isOther) {
return "Unknown callers";
}
if (caller.sdkName) {
return `Langfuse ${caller.sdkName === "python" ? "Python" : "JavaScript"} SDK${caller.sdkVersion ? ` ${caller.sdkVersion}` : ""}`;
}
if (codingAgent) {
return codingAgent;
}
return caller.userAgent || "Unknown caller";
})();
const callerCount = Math.max(
1,
Math.round(caller.count),
);
return (
<li
key={`${callerName}-${index}`}
className="bg-muted/50 border-border rounded-md border-l-4 p-2 text-sm"
>
<div className="flex flex-wrap items-baseline justify-between gap-x-2">
<div className="text-muted-foreground flex items-center gap-1.5">
<span aria-hidden="true">⚠️</span>
<MonoValue>{callerName}</MonoValue>
</div>
<div className="text-muted-foreground flex flex-wrap items-baseline gap-x-1.5 pl-5 sm:pl-0">
<span>
{numberFormatter(callerCount, 0)}{" "}
{callerCount === 1 ? "call" : "calls"} · last
seen{" "}
{formatCompactRelativeTime(
new Date(caller.lastSeen),
)}
</span>
</div>
</div>
{codingAgent && !caller.sdkName ? (
<p className="text-muted-foreground mt-1 pl-5 text-xs">
This looks like traffic from a coding agent. If
the call was only exploratory and is not part of
a running service, you may not need to migrate
application code.{" "}
<ExternalLink
href={DEPRECATED_API_MIGRATION_URL}
analytics={{
section: "apis",
link: "deprecated_api_caller_docs",
}}
>
See docs.
</ExternalLink>
</p>
) : guidance.currentMethod &&
guidance.replacementMethod ? (
<p className="text-muted-foreground mt-1 pl-5 text-xs">
{guidance.currentMethod ===
guidance.replacementMethod ? (
<>
Upgrade to SDK v{guidance.latestMajor},
where{" "}
<MonoValue>
{guidance.replacementMethod}
</MonoValue>{" "}
calls the new API
</>
) : (
<>
Replace{" "}
<MonoValue>
{guidance.currentMethod}
</MonoValue>{" "}
with{" "}
<MonoValue>
{guidance.replacementMethod}
</MonoValue>
{guidance.previousMajorReplacementMethod
? ` (SDK v${guidance.latestMajor})`
: null}
</>
)}
{guidance.previousMajorReplacementMethod &&
guidance.minimumVersion &&
guidance.latestMajor ? (
<>
. On{" "}
<MonoValue>
{guidance.minimumVersion}–
{guidance.latestMajor - 1}.x
</MonoValue>
, use{" "}
<MonoValue>
{guidance.previousMajorReplacementMethod}
</MonoValue>
</>
) : guidance.requiresUpgrade &&
guidance.minimumVersion ? (
<>
. First upgrade to SDK v
{guidance.latestMajor} (
<MonoValue>
{guidance.minimumVersion} or newer
</MonoValue>{" "}
also works)
</>
) : null}
.{" "}
<ExternalLink
href={DEPRECATED_API_MIGRATION_URL}
analytics={{
section: "apis",
link: "deprecated_api_caller_docs",
}}
>
See docs.
</ExternalLink>
</p>
) : (
<p className="text-muted-foreground mt-1 pl-5 text-xs">
Migrate calls to{" "}
<MonoValue>{guidance.replacement}</MonoValue>.{" "}
<ExternalLink
href={DEPRECATED_API_MIGRATION_URL}
analytics={{
section: "apis",
link: "deprecated_api_caller_docs",
}}
>
See docs.
</ExternalLink>
</p>
)}
</li>
);
})}
</ul>
) : null}
</div>
);
})}
</div>
</>
) : (
<p className="text-muted-foreground text-sm">
No deprecated public API usage detected in the last{" "}
{V4_MIGRATION_LOOKBACK_DAYS} days. This check refreshes about every 15
minutes.
</p>
)}
</Section>
);
}
export function V4MigrationIntegrationsSection({
state,
integrations,
integrationsUrl,
onNavigate,
defaultOpen,
}: {
state: MigrationCountState;
integrations: string[];
integrationsUrl?: string;
onNavigate?: () => void;
defaultOpen?: boolean;
}) {
const capture = usePostHogClientCapture();
return (
<Section
title="Migrate Integrations"
analyticsSection="integrations"
count={state.status === "loaded" ? state.count : undefined}
meta={
state.status === "loading"
? "Checking…"
: state.status === "error"
? "Check failed"
: undefined
}
defaultOpen={defaultOpen}
>
{state.status === "loading" ? (
<p className="text-muted-foreground text-sm">Checking integrations…</p>
) : state.status === "error" ? (
<p className="text-muted-foreground text-sm">
We could not check integrations. Try again later.
</p>
) : integrations.length > 0 ? (
<>
<p className="text-muted-foreground mb-2 text-sm">
These exports still read from the old data source. Switching them
over can change what downstream consumers receive, so worth a quick
check.
</p>
<div className="flex flex-col">
{integrations.map((name) => (
<div
key={name}
className="text-muted-foreground flex items-baseline gap-1.5 py-0.5"
>
{integrationsUrl ? (
<Link
href={integrationsUrl}
onClick={() => {
capture("v4_migration:section_link_clicked", {
section: "integrations",
link: "integrations_settings",
});
onNavigate?.();
}}
className="text-sm underline"
>
{name}
</Link>
) : (
<span className="text-sm">{name}</span>
)}
<span className="text-muted-foreground text-sm">·</span>
<ExternalLink
href={
DEPRECATED_INTEGRATION_MIGRATION_URLS[name] ?? V4_DOCS_URL
}
className="text-sm"
analytics={{
section: "integrations",
link: "integration_migration_docs",
}}
>
Migration guide
</ExternalLink>
</div>
))}
</div>
</>
) : (
<p className="text-muted-foreground text-sm">
No deprecated integration exports detected.
</p>
)}
</Section>
);
}
/**
* Whether this deployment is bound by the dated v3 sunset.
*
* `V4_MIGRATION_DEADLINE` is a Langfuse Cloud commitment. On a self-hosted
* deployment nothing happens on that date — the legacy surfaces keep working
* until the operator moves the write mode off `dual`, so quoting a date would
* be plainly wrong. The Fern deprecation messages scope the same date to Cloud
* for the same reason (see `deprecations.ts`).
*/
export function useHasV4MigrationDeadline(): boolean {
return useLangfuseCloudRegion().isLangfuseCloud;
}
// Docs link and deadline note are shared by the panel/modal header and the
// account-level status page so both surfaces read the same.
export function V4MigrationDocsLink() {
return (
<ExternalLink
href={V4_DOCS_URL}
analytics={{ section: "header", link: "v4_docs" }}
>
See docs.
</ExternalLink>
);
}
/**
* Headline for the migration surfaces. It names the compatibility deadline
* rather than a version: the app shell already shows a v4 build number, so a
* "upgrade to v4" title reads as a contradiction to users whose integrations,
* not their deployment, are the thing left to update.
*/
export function useV4MigrationTitle(): string {
return useHasV4MigrationDeadline()
? `Ensure compatibility after ${V4_MIGRATION_DEADLINE_SHORT}`
: "Ensure compatibility";
}
export function V4MigrationDeadlineNote() {
const hasDeadline = useHasV4MigrationDeadline();
if (!hasDeadline) {
return (
<p>
Some features may stop working if you don't update integrations
before your administrator disables the legacy mode.
</p>
);
}
return (
<p>
After{" "}
<ExternalLink
href={V4_TIMELINE_URL}
analytics={{ section: "header", link: "v4_timeline" }}
>
{V4_MIGRATION_DEADLINE}
</ExternalLink>{" "}
some features may stop working if you don't update integrations.
</p>
);
}
// Title, status link, and the v4 pitch. The agent CTA lives in
// V4MigrationAgentUpgradeSection, rendered by the details content.
export function V4MigrationHeaderContent({
titleRowClassName,
readiness,
}: {
/** 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;
}) {
const actionNeeded = readiness === "action-needed";
const title = useV4MigrationTitle();
return (
<>
<div
className={cn(
"mb-1.5 flex items-baseline justify-between gap-2",
titleRowClassName,
)}
>
<p className="min-w-0 text-lg font-bold">{title}</p>
</div>
<div className="text-muted-foreground flex flex-col gap-2 text-sm leading-relaxed">
<p>
Langfuse v4 is live: a re-architecture of our data model and database
tables. It is up to 165× more performant in UI and on APIs. It also
enables new features such as{" "}
<ExternalLink
href={FULL_TEXT_SEARCH_URL}
analytics={{ section: "header", link: "full_text_search_docs" }}
>
full-text search
</ExternalLink>
, a{" "}
<ExternalLink
href={FILTER_SEARCH_BAR_URL}
analytics={{ section: "header", link: "filter_search_bar_docs" }}
>
new filter search bar
</ExternalLink>
,{" "}
<ExternalLink
href={ALERTS_URL}
analytics={{ section: "header", link: "alerts_docs" }}
>
alerts
</ExternalLink>
,{" "}
<ExternalLink
href={CODE_EVALUATORS_URL}
analytics={{ section: "header", link: "code_evaluators_docs" }}
>
code evaluators
</ExternalLink>
, and the{" "}
<ExternalLink
href={LANGFUSE_ASSISTANT_URL}
analytics={{ section: "header", link: "langfuse_assistant_docs" }}
>
Langfuse Halo
</ExternalLink>
.
{actionNeeded
? " Complete the action items below to avoid disruption."
: ""}{" "}
<V4MigrationDocsLink />
</p>
{actionNeeded && <V4MigrationDeadlineNote />}
</div>
</>
);
}
// The primary agent CTA as its own group. The prompt is always visible so a
// single click on the CTA (or the code block's corner button) copies it.
// Project API keys are NOT created as a side effect: credentials only exist
// after an explicit click on the separate "Create keys for project access"
// action, and secrets never enter the agent prompt.
export function V4MigrationAgentUpgradeSection({
projectId,
}: {
projectId?: string;
}) {
const capture = usePostHogClientCapture();
const handleCopyPrompt = useCopyMigrationPrompt();
const [generatedKeys, setGeneratedKeys] = useState<{
projectId: string;
secretKey: string;
publicKey: string;
} | null>(null);
const generatedKeysForProject =
generatedKeys?.projectId === projectId ? generatedKeys : null;
const utils = api.useUtils();
const mutCreateProjectApiKey = api.projectApiKeys.create.useMutation({
onSuccess: () => utils.projectApiKeys.invalidate(),
});
const hasApiKeyCreateAccess = useHasProjectAccess({
projectId,
scope: "apiKeys:CUD",
});
const handleCreateKeys = () => {
// Guards double-clicks and re-creation once keys exist for this project.
if (
!projectId ||
!hasApiKeyCreateAccess ||
mutCreateProjectApiKey.isPending ||
generatedKeysForProject
)
return;
capture("v4_migration:create_project_keys_clicked");
mutCreateProjectApiKey
.mutateAsync({
projectId,
name: "v4-migration-key",
})
.then(({ secretKey, publicKey }) => {
setGeneratedKeys({
projectId,
secretKey,
publicKey,
});
capture(`project_settings:api_key_create`);
})
.catch((error) => {
console.error(error);
showErrorToast(
"Could not create API keys",
"Something went wrong. Please try again.",
classifyTrpcToastError(error, "project_api_key.create"),
);
});
};
const missingApiKeyAccess = Boolean(projectId) && !hasApiKeyCreateAccess;
const createKeysButton = (
<Button
variant="outline"
size="sm"
className="w-fit"
disabled={missingApiKeyAccess || mutCreateProjectApiKey.isPending}
onClick={handleCreateKeys}
>
Create API keys
</Button>
);
const envBlock = generatedKeysForProject
? [
`LANGFUSE_BASE_URL=${typeof window === "undefined" ? "" : window.location.origin}`,
`LANGFUSE_PUBLIC_KEY=${generatedKeysForProject.publicKey}`,
`LANGFUSE_SECRET_KEY=${generatedKeysForProject.secretKey}`,
].join("\n")
: null;
return (
<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">
Upgrade using coding agents
</div>
<p className="text-muted-foreground text-sm">
Paste prompt into Claude Code or other coding agents
</p>
</div>
<div className="flex flex-col gap-2">
<RainbowButton className="w-full" onClick={handleCopyPrompt}>
<Copy size="base" __rawClassName="mr-1.5" />
<span className="min-w-0 truncate" title="Copy prompt">
Copy prompt
</span>
</RainbowButton>
<CodeBlockWithCopy
text={V4_CODING_AGENT_PROMPT}
copyLabel="Copy prompt to clipboard"
onCopy={() => capture("v4_migration:coding_agent_prompt_copied")}
scrollable
className="my-3"
/>
{projectId && (
<div className="flex flex-col gap-2">
<div className="flex items-center justify-between gap-2">
<p className="text-muted-foreground min-w-0 text-sm leading-relaxed">
Create project API keys to give your agent access
</p>
{!envBlock &&
(missingApiKeyAccess ? (
// Disabled buttons swallow pointer events, so the hover
// reason needs a span trigger, same pattern as ActionButton.
<HoverCard
openDelay={200}
content={
<div className="w-80 p-3 text-sm">
Only users with admin access can create project API
keys. Please contact your admins.
</div>
}
>
{({ getTriggerProps }) => (
<span
className="shrink-0"
tabIndex={0}
{...getTriggerProps()}
>
{createKeysButton}
</span>
)}
</HoverCard>
) : (
createKeysButton
))}
</div>
{envBlock && (
<CodeBlockWithCopy
text={envBlock}
copyLabel="Copy keys"
onCopy={() => capture("v4_migration:project_keys_copied")}
/>
)}
</div>
)}
</div>
</div>
);
}
// The migration checklist sections, agent CTA, compare-traces toggle row, and
// footer links. onNavigate fires when an internal link is followed so the
// hosting surface (panel or modal) can close itself.
export function V4MigrationDetailsContent({
onNavigate,
projectId: projectIdProp,
}: {
onNavigate?: () => void;
/** Project the content links point at; falls back to the route project. */
projectId?: string;
}) {
const router = useRouter();
const capture = usePostHogClientCapture();
const { openWithMode: openSupportDrawerWithMode } = useSupportDrawer();
const routeProjectId = router.query.projectId;
const projectId =
projectIdProp ??
(typeof routeProjectId === "string" ? routeProjectId : undefined);
const migrationData = useProjectV4MigrationData({
projectId,
enabled: Boolean(projectId),
});
const { canToggleV4, isV4 } = useReadPath();
// Evidence links target the v4 events table; with the v4 preview off the
// route renders the v3 observations table, which cannot express the
// ingestionApiKey filter — the link would open an unfiltered table. Keep
// the key as plain text there instead of a misleading link.
const evidenceProjectId = isV4 ? projectId : undefined;
// PostHog is the external system here: the panel's checks resolve
// asynchronously after open, so the "how much work was shown" event can
// only fire once they settle; the ref guards refetch-driven re-settles.
// Settled means no check is still in flight — readiness alone would report
// "unavailable" the moment one check errors while others are loading, and
// the event would lock in a mid-flight snapshot.
const readiness = getProjectMigrationReadiness(migrationData);
const checksSettled =
migrationData.sdk.status !== "checking" &&
migrationData.experiments.status !== "loading" &&
migrationData.evals.status !== "loading" &&
migrationData.apis.status !== "loading" &&
migrationData.exports.status !== "loading";
const checksLoadedCaptured = useRef(false);
useEffect(() => {
if (checksLoadedCaptured.current || !checksSettled) return;
checksLoadedCaptured.current = true;
const sdkSection = getSdkSectionState(migrationData.sdk);
const otelSection = getOtelSectionState(migrationData.sdk);
const customSection = getCustomInstrumentationSectionState(
migrationData.sdk,
);
// Counts only — never keys, versions, or other row contents. Errored
// checks report null so they stay distinguishable from a clean zero.
capture("v4_migration:panel_checks_loaded", {
readiness,
sdkStatus: migrationData.sdk.status,
sdkActionableCount: sdkSection.actionableCount,
delayedOtelCount: otelSection.delayedCount,
customInstrumentationCount: customSection.series.length,
evalsCount:
migrationData.evals.status === "loaded"
? migrationData.evals.count
: null,
apisCount:
migrationData.apis.status === "loaded"
? migrationData.apis.count
: null,
integrationsCount:
migrationData.exports.status === "loaded"
? migrationData.exports.count
: null,
experimentsResult:
migrationData.experiments.status === "loaded"
? migrationData.experiments.result
: migrationData.experiments.status,
});
}, [checksSettled, readiness, migrationData, capture]);
// Sections in a good state collapse into one summary sentence instead of
// rendering their own (green) rows. Loading and error states keep the row.
const evalsClean =
migrationData.evals.status === "loaded" && migrationData.evals.count === 0;
const experimentsClean =
migrationData.experiments.status === "loaded" &&
migrationData.experiments.result === "not_required";
const apisClean =
migrationData.apis.status === "loaded" && migrationData.apis.count === 0;
const exportsClean =
migrationData.exports.status === "loaded" &&
migrationData.exports.count === 0;
const cleanSectionLabels = [
evalsClean ? "evals" : null,
experimentsClean ? "experiments" : null,
apisClean ? "APIs" : null,
exportsClean ? "integrations" : null,
].filter((label): label is string => label !== null);
const joinedCleanLabels =
cleanSectionLabels.length > 1
? `${cleanSectionLabels.slice(0, -1).join(", ")} and ${cleanSectionLabels[cleanSectionLabels.length - 1]}`
: cleanSectionLabels[0];
const cleanSummary = joinedCleanLabels
? `${joinedCleanLabels.charAt(0).toUpperCase()}${joinedCleanLabels.slice(1)} are up to date.`
: null;
const handleEmailEngineer = () => {
capture("v4_migration:contact_support_clicked");
onNavigate?.();
openSupportDrawerWithMode("form", { topic: "V4 Migration" });
};
const isInAppAgentLauncherVisible = useIsInAppAgentLauncherVisible();
// Same org source as EvaluatorMigrationDialog's gating, so the button
// branding and the dialog's preselect can't disagree.
const { organization: routeOrganization } = useQueryProjectOrOrganization();
const aiFeaturesEnabled = Boolean(routeOrganization?.aiFeaturesEnabled);
const [evalMigrationDialogOpen, setEvalMigrationDialogOpen] = useState(false);
const upgradePlan = useEvalUpgradeAssistantPlan({
projectId,
enabled: Boolean(projectId),
});
const evalsUrl =
typeof projectId === "string"
? buildDeprecatedRulesUrl(projectId)
: undefined;
const handleMigrateEvalsWithAgent = () => {
capture("v4_migration:migrate_evals_with_agent_clicked");
setEvalMigrationDialogOpen(true);
};
const handleManualEvalUpgrade = () => {
setEvalMigrationDialogOpen(false);
onNavigate?.();
if (evalsUrl) router.push(evalsUrl);
};
const integrationsUrl =
typeof projectId === "string"
? `/project/${projectId}/settings/integrations`
: undefined;
return (
<>
<Separator />
<div className="flex flex-col gap-1">
<div className="flex items-center gap-2 text-base font-bold">
Action items
</div>
<p className="text-muted-foreground text-sm">
SDK, instrumentation, experiment, and API checks cover activity from
the last {V4_MIGRATION_LOOKBACK_DAYS} days. API and experiment usage
counts refresh about every 15 minutes, so recent calls may not appear
yet.
</p>
<div>
<V4MigrationSdkSection
sdk={migrationData.sdk}
projectId={evidenceProjectId}
/>
<V4MigrationOtelSection
sdk={migrationData.sdk}
projectId={evidenceProjectId}
/>
<V4MigrationCustomInstrumentationSection
sdk={migrationData.sdk}
projectId={evidenceProjectId}
/>
{!evalsClean && (
<V4MigrationEvalsSection
state={migrationData.evals}
assistant={
isInAppAgentLauncherVisible
? {
onMigrate: handleMigrateEvalsWithAgent,
aiFeaturesEnabled,
}
: null
}
evalsUrl={evalsUrl}
onNavigate={onNavigate}
/>
)}
{!experimentsClean && (
<V4MigrationExperimentsSection
state={migrationData.experiments}
upgradePath={migrationData.experimentInstrumentationUpgradePath}
/>
)}
{!apisClean && (
<V4MigrationApisSection
state={migrationData.apis}
usage={migrationData.apiUsage}
/>
)}
{!exportsClean && (
<V4MigrationIntegrationsSection
state={migrationData.exports}
integrations={migrationData.legacyIntegrations}
integrationsUrl={integrationsUrl}
onNavigate={onNavigate}
/>
)}
{cleanSummary && (
<p className="text-muted-foreground flex items-center gap-2.5 py-2.5 text-sm">
<V4MigrationStatusDot variant="done" />
{cleanSummary}
</p>
)}
<V4MigrationDetectedInstrumentationSection
sdk={migrationData.sdk}
projectId={evidenceProjectId}
/>
{/* Always the last checklist row. Hides itself when the session
cannot toggle v4 (legacy/events_only write mode, post-rollout
auto-enrollment). Neutral dot + muted text: an optional helper
in the settled-summary style, not pending work. */}
{canToggleV4 && (
<div className="flex w-full items-center gap-2.5 py-2.5">
<V4MigrationStatusDot variant="neutral" />
<span className="text-muted-foreground flex min-w-0 items-center gap-1.5 text-sm">
Compare traces while you upgrade
<HoverCard
openDelay={200}
content={
<div className="w-80 p-3 text-sm">
The latest SDK no longer sets trace input and output;{" "}
<ExternalLink
href={OBSERVATIONS_DATA_MODEL_URL}
analytics={{
section: "compare_row",
link: "observations_data_model_docs",
}}
>
v4 infers them from observations
</ExternalLink>
.
</div>
}
>
{({ getTriggerProps }) => (
<button
type="button"
aria-label="Why compare traces?"
className="shrink-0"
{...getTriggerProps()}
>
<Info size="base" />
</button>
)}
</HoverCard>
</span>
<span className="flex-1" />
<V4PreviewToggleRow projectId={projectId} />
</div>
)}
</div>
</div>
<Separator />
<V4MigrationAgentUpgradeSection projectId={projectId} />
<Separator />
<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>
{env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION && (
<>
<span>·</span>
<a
href={WALKTHROUGH_VIDEO_URL}
target="_blank"
rel="noopener noreferrer"
onClick={() =>
capture("v4_migration:walkthrough_video_clicked")
}
className="underline"
>
Walkthrough video
</a>
</>
)}
</div>
</div>
{projectId ? (
<EvaluatorMigrationDialog
open={evalMigrationDialogOpen}
onOpenChange={setEvalMigrationDialogOpen}
scope={{ type: "all" }}
initialAction="assistant"
assistantPrompt={upgradePlan.assistantPrompt}
onManualUpgrade={handleManualEvalUpgrade}
onAssistantStarted={() => onNavigate?.()}
/>
) : null}
</>
);
}