🪢 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
feat(web): Update V4 migration panel (#15898)
Trang Nguyen586f1ca16ab2
diff --git a/packages/shared/scripts/seeder/scenarios/scored-traces.ts b/packages/shared/scripts/seeder/scenarios/scored-traces.tsindex a473168f29..1cee30ff3e 100644--- a/packages/shared/scripts/seeder/scenarios/scored-traces.ts+++ b/packages/shared/scripts/seeder/scenarios/scored-traces.ts@@ -71,6 +71,17 @@ const TRACE_NAMES = ["classify-intent",] as const;+// Models a production edge: an outdated SDK that only posts scores (e.g. a CI+// eval job) while tracing runs through a current SDK. Detection must flag it,+// but its key renders as plain text in the migration panel — events_core has+// no rows for it, so an events-table evidence link would open an empty result+// (LFE-14859). Applied to the scores of python-current traces below.+const SCORES_ONLY_ATTRIBUTION = {+ key: "python-scores-only",+ ingestion_sdk_name: "python",+ ingestion_sdk_version: "4.5.0",+} as const;+const SDK_ATTRIBUTION_PROFILES = [{key: "python-legacy",@@ -411,8 +422,20 @@ const run = async ();}+ // python-current traces post their scores through the scores-only legacy+ // SDK (see SCORES_ONLY_ATTRIBUTION); every other profile scores through+ // the same SDK that traced.+ const scoreAttribution =+ sdkAttribution.key === "python-current"+ ? {+ ingestion_api_key: `pk-lf-seed-${ctx.idPrefix}-${SCORES_ONLY_ATTRIBUTION.key}`,+ ingestion_sdk_name: SCORES_ONLY_ATTRIBUTION.ingestion_sdk_name,+ ingestion_sdk_version:+ SCORES_ONLY_ATTRIBUTION.ingestion_sdk_version,+ }+ : ingestionAttribution;for (const score of scores.slice(scoreStartIndex)) {- Object.assign(score, ingestionAttribution);+ Object.assign(score, scoreAttribution);}}diff --git a/packages/shared/src/eventsTable.ts b/packages/shared/src/eventsTable.tsindex 2a0a7608ab..4ddd5f169d 100644--- a/packages/shared/src/eventsTable.ts+++ b/packages/shared/src/eventsTable.ts@@ -118,6 +118,27 @@ const eventsTableColsDefinition = [internal: "e.ingestion_api_key",options: [], // to be added at runtime},+ {+ name: "SDK Name",+ id: "ingestionSdkName",+ type: "stringOptions",+ internal: "e.ingestion_sdk_name",+ options: [], // to be added at runtime+ },+ {+ name: "SDK Version",+ id: "ingestionSdkVersion",+ type: "stringOptions",+ internal: "e.ingestion_sdk_version",+ options: [], // to be added at runtime+ },+ {+ name: "Ingestion Source",+ id: "ingestionSource",+ type: "stringOptions",+ internal: "e.source",+ options: [], // to be added at runtime+ },{name: "Version",id: "version",diff --git a/packages/shared/src/server/queries/clickhouse-sql/event-filter-options.ts b/packages/shared/src/server/queries/clickhouse-sql/event-filter-options.tsindex e89e6e3337..acee07d3cd 100644--- a/packages/shared/src/server/queries/clickhouse-sql/event-filter-options.ts+++ b/packages/shared/src/server/queries/clickhouse-sql/event-filter-options.ts@@ -1,4 +1,5 @@import { InvalidRequestError } from "../../../errors";+import { UNKNOWN_INGESTION_SDK_VALUE } from "../../ingestion/ingestionAttribution";import {eventsTableCols,eventsTableHasParentObservationSql,@@ -117,6 +118,27 @@ const EVENTS_FILTER_OPTION_DEFINITIONS = {includeWhen: "length(e.ingestion_api_key) > 0",sort: "countDesc",},+ // The SDK attribution columns default to the 'unknown' placeholder (see+ // clickhouse migration 0042 / UNKNOWN_INGESTION_SDK_VALUE), not '' like+ // ingestion_api_key — exclude it so the facet only offers real SDK values.+ ingestionSdkName: {+ kind: "scalar",+ expression: "e.ingestion_sdk_name",+ includeWhen: `length(e.ingestion_sdk_name) > 0 AND e.ingestion_sdk_name != '${UNKNOWN_INGESTION_SDK_VALUE}'`,+ sort: "countDesc",+ },+ ingestionSdkVersion: {+ kind: "scalar",+ expression: "e.ingestion_sdk_version",+ includeWhen: `length(e.ingestion_sdk_version) > 0 AND e.ingestion_sdk_version != '${UNKNOWN_INGESTION_SDK_VALUE}'`,+ sort: "countDesc",+ },+ ingestionSource: {+ kind: "scalar",+ expression: "e.source",+ includeWhen: "length(e.source) > 0",+ sort: "countDesc",+ },promptName: {kind: "scalar",expression: "e.prompt_name",diff --git a/packages/shared/src/server/tableMappings/mapEventsTable.ts b/packages/shared/src/server/tableMappings/mapEventsTable.tsindex 070b29474b..83abe8a831 100644--- a/packages/shared/src/server/tableMappings/mapEventsTable.ts+++ b/packages/shared/src/server/tableMappings/mapEventsTable.ts@@ -24,6 +24,24 @@ export const eventsTableNativeUiColumnDefinitions: UiColumnMappings = [clickhouseTableName: "events_proto",clickhouseSelect: 'e."ingestion_api_key"',},+ {+ uiTableName: "SDK Name",+ uiTableId: "ingestionSdkName",+ clickhouseTableName: "events_proto",+ clickhouseSelect: 'e."ingestion_sdk_name"',+ },+ {+ uiTableName: "SDK Version",+ uiTableId: "ingestionSdkVersion",+ clickhouseTableName: "events_proto",+ clickhouseSelect: 'e."ingestion_sdk_version"',+ },+ {+ uiTableName: "Ingestion Source",+ uiTableId: "ingestionSource",+ clickhouseTableName: "events_proto",+ clickhouseSelect: 'e."source"',+ },{uiTableName: "Type",uiTableId: "type",diff --git a/web/src/__tests__/server/event-query-builder.servertest.ts b/web/src/__tests__/server/event-query-builder.servertest.tsindex 753135c3b6..472f688295 100644--- a/web/src/__tests__/server/event-query-builder.servertest.ts+++ b/web/src/__tests__/server/event-query-builder.servertest.ts@@ -227,6 +227,38 @@ describe("buildEventsFilterOptionsForColumnsQuery", () => {expect(built.query).not.toContain("FINAL");});+ it.each([+ // The SDK attribution columns default to the 'unknown' placeholder+ // (clickhouse migration 0042), so their facets must exclude it;+ // events_core.source has no such placeholder (plain '' default).+ ["ingestionSdkName", "e.ingestion_sdk_name", true],+ ["ingestionSdkVersion", "e.ingestion_sdk_version", true],+ ["ingestionSource", "e.source", false],+ ] as const)(+ "builds %s filter options from ingestion attribution",+ (column, expression, excludesUnknownPlaceholder) => {+ const built = buildEventsFilterOptionColumnQuery({+ projectId: "test-project",+ filter: [],+ column,+ limit: 10,+ });++ expect(built).not.toBeNull();+ if (!built) throw new Error("expected query");++ expect(built.query).toContain(`'${column}' AS column`);+ expect(built.query).toContain(`toString(${expression}) AS value`);+ expect(built.query).toContain(`length(${expression}) > 0`);+ if (excludesUnknownPlaceholder) {+ expect(built.query).toContain(`${expression} != 'unknown'`);+ } else {+ expect(built.query).not.toContain("!= 'unknown'");+ }+ expect(built.query).not.toContain("FINAL");+ },+ );+it("maps API key filters to the ingestion attribution column", () => {const [filter] = createFilterFromFilterState([@@ -248,6 +280,34 @@ describe("buildEventsFilterOptionsForColumnsQuery", () => {expect(Object.values(applied.params)).toContainEqual(["pk-lf-test"]);});+ it.each([+ ["ingestionSdkName", 'e."ingestion_sdk_name" IN', "python"],+ ["ingestionSdkVersion", 'e."ingestion_sdk_version" IN', "4.7.1"],+ ["ingestionSource", 'e."source" IN', "otel"],+ ] as const)(+ "maps %s filters to the ingestion attribution column",+ (column, expectedClause, value) => {+ const [filter] = createFilterFromFilterState(+ [+ {+ column,+ type: "stringOptions",+ operator: "any of",+ value: [value],+ },+ ],+ eventsTableUiColumnDefinitions,+ eventsTableCols,+ );++ expect(filter).toBeDefined();+ if (!filter) throw new Error("expected filter");+ const applied = filter.apply();+ expect(applied.query).toContain(expectedClause);+ expect(Object.values(applied.params)).toContainEqual([value]);+ },+ );+it("maps release filters to the observation release column", () => {const [filter] = createFilterFromFilterState([diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.tsindex 751bad1499..7c8e47738a 100644--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts@@ -1517,6 +1517,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "3.9.0",publicKey: "pk-lf-python",count: "8",+ eventsCount: "8",firstSeen: "2026-06-24T01:00:00Z",lastSeen: "2026-06-24T02:00:00Z",hasDelayedOtelEvents: "1",@@ -1527,6 +1528,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "4.14.1",publicKey: "pk-lf-python",count: "13",+ eventsCount: "13",firstSeen: "2026-06-24T03:00:00Z",lastSeen: "2026-06-24T04:00:00Z",hasDelayedOtelEvents: "1",@@ -1537,6 +1539,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "4.6.9",publicKey: "pk-lf-pre-v4-python",count: "5",+ eventsCount: "0",firstSeen: "2026-06-24T12:00:00Z",lastSeen: "2026-06-24T13:00:00Z",hasDelayedOtelEvents: "1",@@ -1547,6 +1550,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "4.7.0",publicKey: "pk-lf-current-python",count: "6",+ eventsCount: "6",firstSeen: "2026-06-24T13:30:00Z",lastSeen: "2026-06-24T14:00:00Z",hasDelayedOtelEvents: "1",@@ -1557,6 +1561,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "5.3.9",publicKey: "pk-lf-old-js",count: "5",+ eventsCount: "5",firstSeen: "2026-06-24T01:00:00Z",lastSeen: "2026-06-24T04:00:00Z",hasDelayedOtelEvents: "1",@@ -1567,6 +1572,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "unknown",publicKey: "pk-lf-otel",count: "3",+ eventsCount: "3",firstSeen: "2026-06-24T01:00:00Z",lastSeen: "2026-06-24T04:00:00Z",hasDelayedOtelEvents: "0",@@ -1577,6 +1583,7 @@ describe("v4TransitionRouter", () => {sdkVersion: "1.2.3",publicKey: "pk-lf-custom-otel",count: "2",+ eventsCount: "2",firstSeen: "2026-06-24T02:00:00Z",lastSeen: "2026-06-24T03:00:00Z",hasDelayedOtelEvents: "1",@@ -1614,6 +1621,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: "python",publicKey: "pk-lf-python",count: 8,+ eventsCount: 8,firstSeen: "2026-06-24T01:00:00Z",lastSeen: "2026-06-24T02:00:00Z",hasDelayedOtelEvents: true,@@ -1627,6 +1635,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: "python",publicKey: "pk-lf-python",count: 13,+ eventsCount: 13,firstSeen: "2026-06-24T03:00:00Z",lastSeen: "2026-06-24T04:00:00Z",hasDelayedOtelEvents: true,@@ -1640,6 +1649,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: "python",publicKey: "pk-lf-pre-v4-python",count: 5,+ eventsCount: 0,firstSeen: "2026-06-24T12:00:00Z",lastSeen: "2026-06-24T13:00:00Z",hasDelayedOtelEvents: true,@@ -1653,6 +1663,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: "python",publicKey: "pk-lf-current-python",count: 6,+ eventsCount: 6,firstSeen: "2026-06-24T13:30:00Z",lastSeen: "2026-06-24T14:00:00Z",hasDelayedOtelEvents: true,@@ -1677,6 +1688,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: "javascript",publicKey: "pk-lf-old-js",count: 5,+ eventsCount: 5,firstSeen: "2026-06-24T01:00:00Z",lastSeen: "2026-06-24T04:00:00Z",hasDelayedOtelEvents: true,@@ -1690,6 +1702,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: null,publicKey: "pk-lf-otel",count: 3,+ eventsCount: 3,firstSeen: "2026-06-24T01:00:00Z",lastSeen: "2026-06-24T04:00:00Z",hasDelayedOtelEvents: false,@@ -1703,6 +1716,7 @@ describe("v4TransitionRouter", () => {canonicalSdkName: null,publicKey: "pk-lf-custom-otel",count: 2,+ eventsCount: 2,firstSeen: "2026-06-24T02:00:00Z",lastSeen: "2026-06-24T03:00:00Z",hasDelayedOtelEvents: true,diff --git a/web/src/components/layouts/app-layout/right-drawer/AppContentWithRightDrawer.tsx b/web/src/components/layouts/app-layout/right-drawer/AppContentWithRightDrawer.tsxindex 155bbf2494..4d0f7dc574 100644--- a/web/src/components/layouts/app-layout/right-drawer/AppContentWithRightDrawer.tsx+++ b/web/src/components/layouts/app-layout/right-drawer/AppContentWithRightDrawer.tsx@@ -72,8 +72,10 @@ export function AppContentWithRightDrawer({ children }: PropsWithChildren) {primaryContent={children}secondaryContent={rightDrawerContent}open={supportOpen || migrationOpen}- defaultPrimarySize={70}- defaultSecondarySize={30}+ defaultPrimarySize={supportOpen ? 70 : 60}+ // The migration panel carries denser content than the support drawer,+ // so it opens wider by default.+ defaultSecondarySize={supportOpen ? 30 : 40}minPrimarySize={30}maxSecondarySize={60}keepSecondaryMounted={false}diff --git a/web/src/features/events/components/V4SidebarToggle.tsx b/web/src/features/events/components/V4SidebarToggle.tsxindex c23e9701cf..8724d363bc 100644--- a/web/src/features/events/components/V4SidebarToggle.tsx+++ b/web/src/features/events/components/V4SidebarToggle.tsx@@ -217,7 +217,7 @@ export function V4PreviewToggleRow({ projectId }: { projectId?: string }) {return (<><div className="flex items-center gap-2">- <span className="shrink-0 text-sm">V3</span>+ <span className="text-muted-foreground shrink-0 text-sm">V3</span><Switchid={toggleId}size="sm"@@ -229,10 +229,10 @@ export function V4PreviewToggleRow({ projectId }: { projectId?: string }) {/><LabelhtmlFor={toggleId}- className="block min-w-0 cursor-pointer truncate text-sm font-normal"- title={V4_PREVIEW_LABEL}+ className="text-muted-foreground block min-w-0 cursor-pointer truncate text-sm font-normal"+ title="V4">- {V4_PREVIEW_LABEL}+ V4</Label><span id={descriptionId} className="sr-only">{V4_PREVIEW_DESCRIPTION}diff --git a/web/src/features/events/config/filter-config.ts b/web/src/features/events/config/filter-config.tsindex e7030808ee..b7ec7a137a 100644--- a/web/src/features/events/config/filter-config.ts+++ b/web/src/features/events/config/filter-config.ts@@ -194,6 +194,21 @@ export const observationEventsFilterConfig: FilterConfig = {column: "ingestionApiKey",label: getEventsColumnName("ingestionApiKey"),},+ {+ type: "categorical" as const,+ column: "ingestionSdkName",+ label: getEventsColumnName("ingestionSdkName"),+ },+ {+ type: "categorical" as const,+ column: "ingestionSdkVersion",+ label: getEventsColumnName("ingestionSdkVersion"),+ },+ {+ type: "categorical" as const,+ column: "ingestionSource",+ label: getEventsColumnName("ingestionSource"),+ },{type: "categorical" as const,column: "experimentDatasetId",diff --git a/web/src/features/events/hooks/useEventsFilterOptions.ts b/web/src/features/events/hooks/useEventsFilterOptions.tsindex 34a2164c9f..370ae381d6 100644--- a/web/src/features/events/hooks/useEventsFilterOptions.ts+++ b/web/src/features/events/hooks/useEventsFilterOptions.ts@@ -40,6 +40,9 @@ const ALL_EVENT_FILTER_OPTION_COLUMNS = ["level","environment","ingestionApiKey",+ "ingestionSdkName",+ "ingestionSdkVersion",+ "ingestionSource","experimentDatasetId","experimentId","experimentName",@@ -319,6 +322,9 @@ export function useEventsFilterOptions({return {environment: rawData.environment ?? undefined,ingestionApiKey: rawData.ingestionApiKey ?? undefined,+ ingestionSdkName: rawData.ingestionSdkName ?? undefined,+ ingestionSdkVersion: rawData.ingestionSdkVersion ?? undefined,+ ingestionSource: rawData.ingestionSource ?? undefined,name: rawData.name ?? undefined,type: rawData.type ?? undefined,level: rawData.level ?? undefined,diff --git a/web/src/features/events/server/eventsService.ts b/web/src/features/events/server/eventsService.tsindex bfe2136c41..b580b5fc61 100644--- a/web/src/features/events/server/eventsService.ts+++ b/web/src/features/events/server/eventsService.ts@@ -139,6 +139,9 @@ const EVENT_FILTER_OPTION_COLUMNS = ["level","environment","ingestionApiKey",+ "ingestionSdkName",+ "ingestionSdkVersion",+ "ingestionSource","experimentDatasetId","experimentId","experimentName",diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.tsindex 6f432e034a..b86f44468d 100644--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts@@ -319,8 +319,11 @@ export const events = {"v4_beta_toggled","v4_migration_card_clicked",],+ // Migration-funnel events answer "are people finding the panel, which+ // action items do they engage with, and which CTA do they use?"+ // panel_opened carries the entry surface; panel_checks_loaded carries the+ // amount of work shown (counts only — never keys or SDK payload values).v4_migration: [- "in_app_agent_opened","coding_agent_prompt_viewed","coding_agent_prompt_copied","delay_badge_clicked",@@ -332,8 +335,15 @@ export const events = {"migrate_evals_with_agent_clicked","overview_banner_status_clicked","overview_banner_docs_clicked",- "panel_status_link_clicked","panel_docs_link_clicked",+ "create_project_keys_clicked",+ "panel_opened",+ "panel_checks_loaded",+ "section_expanded",+ "evidence_link_clicked",+ "section_link_clicked",+ "project_keys_copied",+ "evals_manual_upgrade_clicked",],// Filter/search-bar usage analytics (LFE-10781). METADATA ONLY — payloads// never carry a raw filter value, search text, or AI prompt (PII). Onlydiff --git a/web/src/features/search-bar/lib/fields.ts b/web/src/features/search-bar/lib/fields.tsindex 179caf442a..8c1a13acdb 100644--- a/web/src/features/search-bar/lib/fields.ts+++ b/web/src/features/search-bar/lib/fields.ts@@ -61,6 +61,9 @@ export const FIELDS: FieldDef[] = [{ id: "type", aliases: [], kind: "text", syncMode: "exactOption", label: "Type", description: "Observation type" },{ id: "environment", aliases: ["env"], kind: "text", syncMode: "exactOption", label: "Environment", description: "Environment", nullable: true },{ id: "ingestionApiKey", aliases: ["ingestionapikey", "ingestion_api_key", "apikey", "api_key", "publickey", "public_key"], kind: "text", syncMode: "exactOption", label: "Ingestion API key", description: "Public ingestion API key" },+ { id: "ingestionSdkName", aliases: ["ingestionsdkname", "ingestion_sdk_name", "sdkname", "sdk_name"], kind: "text", syncMode: "exactOption", label: "Ingestion SDK name", description: "Ingestion SDK name" },+ { id: "ingestionSdkVersion", aliases: ["ingestionsdkversion", "ingestion_sdk_version", "sdkversion", "sdk_version"], kind: "text", syncMode: "exactOption", label: "Ingestion SDK version", description: "Ingestion SDK version" },+ { id: "ingestionSource", aliases: ["ingestionsource", "ingestion_source", "source"], kind: "text", syncMode: "exactOption", label: "Ingestion source", description: "Ingestion source (API or OTel path)" },{ id: "userId", aliases: ["userid", "user_id", "user"], kind: "text", syncMode: "exactOption", label: "User ID", description: "Trace user id", nullable: true },{ id: "sessionId", aliases: ["sessionid", "session_id", "session"], kind: "text", syncMode: "exactOption", label: "Session ID", description: "Trace session id", nullable: true },{ id: "level", aliases: [], kind: "text", syncMode: "exactOption", label: "Level", description: "Observation level" },diff --git a/web/src/features/search-bar/lib/langQ.clienttest.ts b/web/src/features/search-bar/lib/langQ.clienttest.tsindex 9dfa5e3918..e7b09ff6ec 100644--- a/web/src/features/search-bar/lib/langQ.clienttest.ts+++ b/web/src/features/search-bar/lib/langQ.clienttest.ts@@ -51,6 +51,52 @@ describe("langQ parser", () => {});});+ it("resolves ingestion attribution aliases to canonical field ids", () => {+ const r = parse("sdk_name:python sdkVersion:4.7.1 source:otel");+ expect(r.valid).toBe(true);+ expect(strip(r.ast)).toEqual({+ kind: "and",+ children: [+ {+ kind: "filter",+ key: "ingestionSdkName",+ op: "=",+ values: ["python"],+ },+ {+ kind: "filter",+ key: "ingestionSdkVersion",+ op: "=",+ values: ["4.7.1"],+ },+ {+ kind: "filter",+ key: "ingestionSource",+ op: "=",+ values: ["otel"],+ },+ ],+ });+ // Snake-case and canonical spellings resolve to the same fields.+ const alt = parse(+ "sdkName:js ingestion_sdk_version:3.2.1 ingestionSource:api",+ );+ expect(alt.valid).toBe(true);+ expect(strip(alt.ast)).toEqual({+ kind: "and",+ children: [+ { kind: "filter", key: "ingestionSdkName", op: "=", values: ["js"] },+ {+ kind: "filter",+ key: "ingestionSdkVersion",+ op: "=",+ values: ["3.2.1"],+ },+ { kind: "filter", key: "ingestionSource", op: "=", values: ["api"] },+ ],+ });+ });+it("parses grouped lists, comma lists, comparisons, and quoted values", () => {expect(strip(parse("level:(ERROR OR WARNING)").ast)).toEqual({kind: "filter",diff --git a/web/src/features/v4-migration/EvaluatorMigrationDialog.tsx b/web/src/features/v4-migration/EvaluatorMigrationDialog.tsxindex e367a17787..eaeee7dd81 100644--- a/web/src/features/v4-migration/EvaluatorMigrationDialog.tsx+++ b/web/src/features/v4-migration/EvaluatorMigrationDialog.tsx@@ -14,6 +14,7 @@ import {useCanUseInAppAgent,useInAppAiAgent,} from "@/src/features/in-app-agent/components/InAppAiAgentProvider";+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { useQueryProjectOrOrganization } from "@/src/features/projects/hooks";import { useHasOrganizationAccess } from "@/src/features/rbac/utils/checkOrganizationAccess";@@ -56,6 +57,7 @@ export function EvaluatorMigrationDialog({const isSingleEvaluator = scope.type === "single";const showAssistantOption = canUseAssistant;+ const capture = usePostHogClientCapture();const startAssistant = async () => {const opened = openAssistant("v4_migration");if (!opened) return;@@ -79,10 +81,11 @@ export function EvaluatorMigrationDialog({};const handleManualClick = () => {- if (isSingleEvaluator) {- onManualUpgrade();- return;- }+ // The assistant branch is covered by in_app_agent:new_chat_started+ // (entryPoint "v4_migration"); this event completes the funnel fork.+ capture("v4_migration:evals_manual_upgrade_clicked", {+ scope: isSingleEvaluator ? "single" : "bulk",+ });onManualUpgrade();};diff --git a/web/src/features/v4-migration/V4MigrationBadgeContent.tsx b/web/src/features/v4-migration/V4MigrationBadgeContent.tsxindex 477e6cb556..776e7bf2db 100644--- a/web/src/features/v4-migration/V4MigrationBadgeContent.tsx+++ b/web/src/features/v4-migration/V4MigrationBadgeContent.tsx@@ -1,4 +1,27 @@import { ChevronRight } from "lucide-react";+import { cn } from "@/src/utils/tailwind";++// Status dots shared across the v4-migration surfaces (badge, panel section+// rows, clean summary). This file sits on the no-raw-colors baseline; the raw+// palette values are intentional — the semantic warning/success fills read+// too muted at this size.+export function V4MigrationStatusDot({+ variant,+}: {+ variant: "action" | "done";+}) {+ return (+ <span+ aria-hidden+ className={cn(+ "size-1.75 shrink-0 rounded-full",+ variant === "action"+ ? "bg-orange-400 dark:bg-orange-400"+ : "bg-green-400 dark:bg-green-400",+ )}+ />+ );+}type V4MigrationBadgeContentProps = {onClick: () => void;@@ -29,10 +52,7 @@ export function V4MigrationBadgeContent({onClick={onClick}className="group ring-input hover:bg-muted/50 hover:text-foreground col-start-1 row-start-1 inline-flex w-fit flex-none shrink-0 items-center gap-1.5 justify-self-start rounded-full bg-transparent px-2 py-0.5 text-xs font-bold whitespace-nowrap ring">- <span- aria-hidden- className="size-1.75 shrink-0 rounded-full bg-orange-400 dark:bg-orange-400"- />+ <V4MigrationStatusDot variant="action" /><span className="flex items-center">{title}<span className="flex max-w-0 items-center overflow-hidden transition-[max-width] duration-300 ease-out group-hover:max-w-96 group-focus-visible:max-w-96">diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsxindex d46ca5fb3f..26e38244bf 100644--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx@@ -1,3 +1,4 @@+import React from "react";import {fireEvent,render,@@ -8,6 +9,7 @@ import {import { beforeEach, describe, expect, it, vi } from "vitest";import {+ V4MigrationAgentUpgradeSection,V4MigrationDetailsContent,V4MigrationHeaderContent,} from "./V4MigrationContent";@@ -15,10 +17,42 @@ import {type MigrationActionState,type MigrationCountState,} from "./migrationData";-import { type V4MigrationSdkState } from "./sdkVersionStatus";+import {+ type V4MigrationSdkState,+ type V4MigrationSdkUsageSeries,+} from "./sdkVersionStatus";+import { V4_MIGRATION_LOOKBACK_DAYS } from "./migrationData";+import { TABLE_AGGREGATION_OPTIONS } from "@langfuse/shared";+import { rangeFromString } from "@/src/utils/date-range-utils";++const makeSdkUsageSeries = (+ overrides: Partial<V4MigrationSdkUsageSeries>,+): V4MigrationSdkUsageSeries => ({+ sdkName: "python",+ sdkVersion: "4.7.1",+ canonicalSdkName: "python",+ publicKey: "pk-lf-1234567890abcdef",+ count: 10,+ eventsCount: 10,+ firstSeen: "2026-07-20T10:00:00Z",+ lastSeen: "2026-07-23T10:00:00Z",+ hasDelayedOtelEvents: null,+ attributionStatus: "attributed",+ v4MigrationStatus: "compatible",+ upgradeCompleted: false,+ ...overrides,+});++const cleanSdkState = (): V4MigrationSdkState => ({+ status: "latest",+ sdkUsageSeries: [],+ upgradeRequiredCount: 0,+ delayedOtelIngestionCount: 0,+});const mocks = vi.hoisted(() => ({routerPush: vi.fn(),+ capture: vi.fn(),openAssistant: vi.fn(),submitAgentMessage: vi.fn(),upgradePlan: {@@ -52,6 +86,7 @@ const mocks = vi.hoisted(() => ({legacyIntegrations: ["PostHog", "Mixpanel", "Blob Storage"],},canToggleV4: true,+ isBetaEnabled: true,hasApiKeyCreateAccess: true,canUpdateOrgSettings: true,aiFeaturesEnabled: true,@@ -70,7 +105,7 @@ vi.mock("@/src/features/support-chat/SupportDrawerProvider", () => ({}));vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({- usePostHogClientCapture: () => vi.fn(),+ usePostHogClientCapture: () => mocks.capture,}));vi.mock("@/src/utils/api", () => ({@@ -135,20 +170,48 @@ vi.mock("@/src/features/events/components/V4SidebarToggle", () => ({// The details content reads canToggleV4 to gate the toggle section's copy.vi.mock("@/src/features/events/hooks/useV4Beta", () => ({- useV4Beta: () => ({ canToggleV4: mocks.canToggleV4 }),+ useV4Beta: () => ({+ canToggleV4: mocks.canToggleV4,+ isBetaEnabled: mocks.isBetaEnabled,+ }),}));-vi.mock("@/src/components/ui/collapsible", () => ({- Collapsible: ({ children }: { children: React.ReactNode }) => (- <div>{children}</div>- ),- CollapsibleTrigger: ({ children }: { children: React.ReactNode }) => (- <button>{children}</button>- ),- CollapsibleContent: ({ children }: { children: React.ReactNode }) => (- <div>{children}</div>- ),-}));+// Content stays rendered so section-body assertions need no expanding; the+// trigger toggles like Radix (open ↔ closed, seeded from defaultOpen) so the+// expand-only guard in Section is genuinely exercised.+vi.mock("@/src/components/ui/collapsible", () => {+ const ToggleContext = React.createContext<() => void>(() => {});+ return {+ Collapsible: ({+ children,+ defaultOpen,+ onOpenChange,+ }: {+ children: React.ReactNode;+ defaultOpen?: boolean;+ onOpenChange?: (open: boolean) => void;+ }) => {+ const [isOpen, setIsOpen] = React.useState(defaultOpen ?? false);+ const toggle = () => {+ const next = !isOpen;+ setIsOpen(next);+ onOpenChange?.(next);+ };+ return (+ <ToggleContext.Provider value={toggle}>+ <div>{children}</div>+ </ToggleContext.Provider>+ );+ },+ CollapsibleTrigger: ({ children }: { children: React.ReactNode }) => {+ const toggle = React.useContext(ToggleContext);+ return <button onClick={toggle}>{children}</button>;+ },+ CollapsibleContent: ({ children }: { children: React.ReactNode }) => (+ <div>{children}</div>+ ),+ };+});describe("V4MigrationDetailsContent", () => {beforeEach(() => {@@ -162,9 +225,10 @@ describe("V4MigrationDetailsContent", () => {};mocks.migrationData.experimentInstrumentationUpgradePath = null;mocks.canToggleV4 = true;+ mocks.isBetaEnabled = true;mocks.canUpdateOrgSettings = true;mocks.aiFeaturesEnabled = true;- mocks.migrationData.sdk.status = "latest";+ mocks.migrationData.sdk = cleanSdkState();mocks.migrationData.apis = { status: "loaded", count: 1 };mocks.migrationData.exports = { status: "loaded", count: 3 };mocks.migrationData.apiUsage = [@@ -184,8 +248,8 @@ describe("V4MigrationDetailsContent", () => {it("uses deprecated terminology and links to the migration guides", () => {render(<V4MigrationDetailsContent projectId="project-1" />);- expect(screen.getByText("Deprecated APIs")).toBeInTheDocument();- expect(screen.getByText("Deprecated Integrations")).toBeInTheDocument();+ expect(screen.getByText("Migrate APIs")).toBeInTheDocument();+ expect(screen.getByText("Migrate Integrations")).toBeInTheDocument();expect(screen.queryByText("Legacy APIs")).not.toBeInTheDocument();expect(screen.queryByText("Legacy Integrations")).not.toBeInTheDocument();@@ -223,7 +287,7 @@ describe("V4MigrationDetailsContent", () => {}});- it("uses deprecated terminology in the empty states", () => {+ it("collapses clean sections into one up-to-date summary", () => {mocks.migrationData.apis = { status: "loaded", count: 0 };mocks.migrationData.exports = { status: "loaded", count: 0 };mocks.migrationData.apiUsage = [];@@ -232,17 +296,28 @@ describe("V4MigrationDetailsContent", () => {render(<V4MigrationDetailsContent projectId="project-1" />);expect(- screen.getByText(/No deprecated public API usage detected/),- ).toBeInTheDocument();- expect(- screen.getByText("No deprecated integration exports detected."),+ screen.getByText(+ "Evals, experiments, APIs and integrations are up to date.",+ ),).toBeInTheDocument();+ expect(screen.queryByText("Repoint Evals")).not.toBeInTheDocument();+ expect(screen.queryByText("Experiments")).not.toBeInTheDocument();+ expect(screen.queryByText("Migrate APIs")).not.toBeInTheDocument();+ expect(screen.queryByText("Migrate Integrations")).not.toBeInTheDocument();+ });++ it("keeps affected sections while summarizing the clean ones", () => {+ // Default mock: apis count 1, exports count 3; evals and experiments clean.+ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("Migrate APIs")).toBeInTheDocument();+ expect(screen.getByText("Migrate Integrations")).toBeInTheDocument();expect(- screen.getByText("No deprecated evals detected."),+ screen.getByText("Evals and experiments are up to date."),).toBeInTheDocument();expect(- screen.getByText("No experiment instrumentation updates required."),- ).toBeInTheDocument();+ screen.queryByText("Repoint Evals", { exact: true }),+ ).not.toBeInTheDocument();});it("shows the experiment instrumentation upgrade requirement", () => {@@ -268,7 +343,6 @@ describe("V4MigrationDetailsContent", () => {render(<V4MigrationDetailsContent projectId="project-1" />);fireEvent.click(screen.getByRole("button", { name: /Experiments/ }));- expect(screen.getByText("Needs review")).toBeInTheDocument();expect(screen.getByText(/supports the experiment runner/),).toBeInTheDocument();@@ -289,33 +363,394 @@ describe("V4MigrationDetailsContent", () => {).toBeInTheDocument();});- it("shows no detected ingestion data without asking for SDK review", () => {+ it("hides the tracing sections when no ingestion data was detected", () => {mocks.migrationData.sdk.status = "no_data";render(<V4MigrationDetailsContent projectId="project-1" />);- expect(screen.getByText("No data detected")).toBeInTheDocument();+ expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();expect(- screen.getByText(/No ingestion data was detected in the last 14 days/),- ).toBeInTheDocument();+ screen.queryByText("Update OTel Instrumentation"),+ ).not.toBeInTheDocument();expect(screen.queryByText("Needs review")).not.toBeInTheDocument();});+ it("hides the tracing sections when everything detected is up to date", () => {+ mocks.migrationData.sdk = {+ ...cleanSdkState(),+ sdkUsageSeries: [+ makeSdkUsageSeries({}),+ makeSdkUsageSeries({+ sdkName: "otelcol",+ sdkVersion: "0.98.0",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: false,+ }),+ ],+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();+ expect(+ screen.queryByText("Update OTel Instrumentation"),+ ).not.toBeInTheDocument();+ });++ it("lists every detected SDK series when one needs an upgrade", () => {+ mocks.migrationData.sdk = {+ status: "legacy",+ sdkUsageSeries: [+ makeSdkUsageSeries({+ sdkVersion: "2.60.3",+ v4MigrationStatus: "upgrade_required",+ }),+ makeSdkUsageSeries({ publicKey: "pk-lf-fedcba0987654321" }),+ ],+ upgradeRequiredCount: 1,+ delayedOtelIngestionCount: 0,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("Update SDK")).toBeInTheDocument();+ expect(+ 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(/upgrade required/)).toBeInTheDocument();+ // The public key deep-links to the exact evidence: the events table+ // filtered by this key + SDK name/version over the detection lookback+ // window, so two SDK versions on the same key link to distinct results.+ expect(+ screen.getByRole("link", { name: "pk-lf-123…abcdef" }),+ ).toHaveAttribute(+ "href",+ `/project/project-1/observations?filter=${encodeURIComponent(+ "ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef," ++ "ingestionSdkName;stringOptions;;any of;python," ++ "ingestionSdkVersion;stringOptions;;any of;2.60.3",+ )}&dateRange=14d`,+ );+ expect(+ screen.queryByText("Update OTel Instrumentation"),+ ).not.toBeInTheDocument();+ });++ it("renders the key as plain text when an offender has no observation evidence", () => {+ // A scores-only offender: detection counts score ingestions, but the+ // events table has nothing for this key — a link would open an empty+ // table, so the key must stay plain text (LFE-14859).+ mocks.migrationData.sdk = {+ status: "legacy",+ sdkUsageSeries: [+ makeSdkUsageSeries({+ sdkVersion: "2.60.3",+ v4MigrationStatus: "upgrade_required",+ eventsCount: 0,+ }),+ ],+ upgradeRequiredCount: 1,+ delayedOtelIngestionCount: 0,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("Python 2.60.3")).toBeInTheDocument();+ expect(screen.getByText("pk-lf-123…abcdef")).toBeInTheDocument();+ expect(+ screen.queryByRole("link", { name: "pk-lf-123…abcdef" }),+ ).not.toBeInTheDocument();+ });++ it("captures panel_checks_loaded once when all checks settle", () => {+ const { rerender } = render(+ <V4MigrationDetailsContent projectId="project-1" />,+ );+ rerender(<V4MigrationDetailsContent projectId="project-1" />);++ const loadedCalls = mocks.capture.mock.calls.filter(+ ([name]) => name === "v4_migration:panel_checks_loaded",+ );+ expect(loadedCalls).toHaveLength(1);+ expect(loadedCalls[0]![1]).toEqual({+ readiness: "action-needed",+ sdkStatus: "latest",+ sdkActionableCount: 0,+ delayedOtelCount: 0,+ customInstrumentationCount: 0,+ evalsCount: 0,+ apisCount: 1,+ integrationsCount: 3,+ experimentsResult: "not_required",+ });+ });++ it("holds panel_checks_loaded while a check is still running", () => {+ mocks.migrationData.evals = { status: "loading", count: 0 };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(mocks.capture).not.toHaveBeenCalledWith(+ "v4_migration:panel_checks_loaded",+ expect.anything(),+ );+ });++ it("holds panel_checks_loaded when one check errors while another loads", () => {+ // readiness collapses to "unavailable" on the first error, but the event+ // must wait for the in-flight checks instead of locking in a mid-flight+ // snapshot; errored counts then report null, not a clean-looking zero.+ mocks.migrationData.evals = { status: "error", count: 0 };+ mocks.migrationData.apis = { status: "loading", count: 0 };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(mocks.capture).not.toHaveBeenCalledWith(+ "v4_migration:panel_checks_loaded",+ expect.anything(),+ );++ mocks.migrationData.apis = { status: "loaded", count: 1 };+ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(mocks.capture).toHaveBeenCalledWith(+ "v4_migration:panel_checks_loaded",+ expect.objectContaining({ readiness: "unavailable", evalsCount: null }),+ );+ });++ it("captures section_expanded and evidence_link_clicked in the SDK section", () => {+ mocks.migrationData.sdk = {+ status: "legacy",+ sdkUsageSeries: [+ makeSdkUsageSeries({+ sdkVersion: "2.60.3",+ v4MigrationStatus: "upgrade_required",+ }),+ ],+ upgradeRequiredCount: 1,+ delayedOtelIngestionCount: 0,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ fireEvent.click(screen.getByText("Update SDK").closest("button")!);+ expect(mocks.capture).toHaveBeenCalledWith(+ "v4_migration:section_expanded",+ { section: "sdk" },+ );++ // Collapsing must not count as engagement.+ fireEvent.click(screen.getByText("Update SDK").closest("button")!);+ expect(+ mocks.capture.mock.calls.filter(+ ([name]) => name === "v4_migration:section_expanded",+ ),+ ).toHaveLength(1);++ fireEvent.click(screen.getByRole("link", { name: "pk-lf-123…abcdef" }));+ // Only bounded values: the canonical SDK enum and status enums — never+ // the raw client-supplied sdkName/sdkVersion header strings.+ expect(mocks.capture).toHaveBeenCalledWith(+ "v4_migration:evidence_link_clicked",+ {+ section: "sdk",+ sdkName: "python",+ v4MigrationStatus: "upgrade_required",+ attributionStatus: "attributed",+ },+ );++ fireEvent.click(screen.getByRole("link", { name: "upgrade path" }));+ expect(mocks.capture).toHaveBeenCalledWith(+ "v4_migration:section_link_clicked",+ { section: "sdk", link: "sdk_upgrade_docs" },+ );+ });++ it("shows delayed OTel exporters and hides the clean SDK section", () => {+ mocks.migrationData.sdk = {+ status: "otel_header_required",+ sdkUsageSeries: [+ makeSdkUsageSeries({}),+ makeSdkUsageSeries({+ sdkName: "openlit",+ sdkVersion: "1.35.4",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: true,+ publicKey: "pk-lf-aaaa000011112222",+ }),+ makeSdkUsageSeries({+ sdkName: "otelcol",+ sdkVersion: "0.98.0",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: false,+ publicKey: "pk-lf-bbbb333344445555",+ }),+ ],+ upgradeRequiredCount: 0,+ delayedOtelIngestionCount: 1,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("Update OTel Instrumentation")).toBeInTheDocument();+ expect(+ within(+ screen.getByText("Update OTel Instrumentation").closest("button")!,+ ).getByText("1"),+ ).toBeInTheDocument();+ expect(screen.getByText(/delayed ingestion path/)).toBeInTheDocument();+ expect(screen.getByText("openlit 1.35.4")).toBeInTheDocument();+ expect(screen.getByText("otelcol 0.98.0")).toBeInTheDocument();+ expect(screen.getByText("· delayed")).toBeInTheDocument();+ expect(screen.getByText("· real-time")).toBeInTheDocument();+ expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();+ });++ it("keeps Update SDK visible for a recognized SDK with an unparsable version", () => {+ mocks.migrationData.sdk = {+ status: "unknown",+ sdkUsageSeries: [+ makeSdkUsageSeries({+ sdkVersion: "not-a-version",+ v4MigrationStatus: "unknown",+ }),+ ],+ upgradeRequiredCount: 0,+ delayedOtelIngestionCount: 0,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("Update SDK")).toBeInTheDocument();+ // Badge and sentence share the same count.+ expect(+ within(screen.getByText("Update SDK").closest("button")!).getByText("1"),+ ).toBeInTheDocument();+ expect(+ screen.getByText(/1 detected SDK configuration needs an update/),+ ).toBeInTheDocument();+ expect(screen.getByText("· version not recognized")).toBeInTheDocument();+ });++ it("keeps the evidence-link date range expressible as a table range", () => {+ // The events table resolves ?dateRange= through rangeFromString against+ // TABLE_AGGREGATION_OPTIONS; an unknown abbreviation silently falls back+ // to the page default and unscopes the evidence links.+ expect(+ rangeFromString(+ `${V4_MIGRATION_LOOKBACK_DAYS}d`,+ TABLE_AGGREGATION_OPTIONS,+ "last1Day",+ ),+ ).toEqual({ range: `last${V4_MIGRATION_LOOKBACK_DAYS}Days` });+ });++ it("renders the public key as plain text when the v4 preview is off", () => {+ mocks.isBetaEnabled = false;+ mocks.migrationData.sdk = {+ status: "legacy",+ sdkUsageSeries: [+ makeSdkUsageSeries({+ sdkVersion: "2.60.3",+ v4MigrationStatus: "upgrade_required",+ }),+ ],+ upgradeRequiredCount: 1,+ delayedOtelIngestionCount: 0,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("pk-lf-123…abcdef")).toBeInTheDocument();+ expect(+ screen.queryByRole("link", { name: "pk-lf-123…abcdef" }),+ ).not.toBeInTheDocument();+ });++ it("shows ingestion-API traffic without an SDK header as Upgrade Instrumentation", () => {+ mocks.migrationData.sdk = {+ status: "unknown",+ sdkUsageSeries: [+ makeSdkUsageSeries({+ sdkName: "unknown",+ sdkVersion: "unknown",+ canonicalSdkName: null,+ attributionStatus: "missing_name_and_version",+ v4MigrationStatus: "unknown",+ }),+ ],+ upgradeRequiredCount: 0,+ delayedOtelIngestionCount: 0,+ };++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(screen.getByText("Upgrade Instrumentation")).toBeInTheDocument();+ expect(+ within(+ screen.getByText("Upgrade Instrumentation").closest("button")!,+ ).getByText("1"),+ ).toBeInTheDocument();+ expect(screen.getByText("Custom instrumentation")).toBeInTheDocument();+ // Unattributed series ("unknown" SDK name/version) keep a key-only+ // evidence link — "unknown" is the fallback bucket, not an exact value.+ expect(+ screen.getByRole("link", { name: "pk-lf-123…abcdef" }),+ ).toHaveAttribute(+ "href",+ `/project/project-1/observations?filter=${encodeURIComponent(+ "ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef",+ )}&dateRange=14d`,+ );+ expect(+ screen.getByRole("link", { name: "Python or JS SDK" }),+ ).toHaveAttribute(+ "href",+ "https://langfuse.com/docs/observability/sdk/overview",+ );+ expect(+ screen.getByRole("link", { name: "OpenTelemetry endpoint" }),+ ).toHaveAttribute(+ "href",+ "https://langfuse.com/integrations/native/opentelemetry",+ );+ expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();+ expect(+ screen.queryByText("Update OTel Instrumentation"),+ ).not.toBeInTheDocument();+ });++ it("renders the agent upgrade group with the prompt CTA", () => {+ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(+ screen.getByText(/Paste prompt into Claude Code or other coding agents/),+ ).toBeInTheDocument();+ expect(+ screen.getByRole("button", { name: "Copy prompt" }),+ ).toBeInTheDocument();+ });+it("shows the preview-toggle section only when the session can toggle v4", () => {const { unmount } = render(<V4MigrationDetailsContent projectId="project-1" />,);- expect(screen.getByText("Want to review first?")).toBeInTheDocument();expect(- screen.getByText(/Use this toggle to compare both views/),+ screen.getByText(/Compare traces while you upgrade/),).toBeInTheDocument();unmount();mocks.canToggleV4 = false;render(<V4MigrationDetailsContent projectId="project-1" />);- expect(screen.queryByText("Want to review first?")).not.toBeInTheDocument();expect(- screen.queryByText(/Use this toggle to compare both views/),+ screen.queryByText(/Compare traces while you upgrade/),).not.toBeInTheDocument();});@@ -399,9 +834,7 @@ describe("V4MigrationHeaderContent", () => {it("claims the project needs migrating while checks report action needed", () => {render(<V4MigrationHeaderContent projectId="project-1" />);- expect(- screen.getByText(/This project still uses the previous setup/),- ).toBeInTheDocument();+ expect(screen.getByText(/Your setup is outdated/)).toBeInTheDocument();});it("drops the status claim once every check is clean", () => {@@ -409,7 +842,7 @@ describe("V4MigrationHeaderContent", () => {mocks.migrationData.exports = { status: "loaded", count: 0 };render(<V4MigrationHeaderContent projectId="project-1" />);expect(- screen.queryByText(/This project still uses the previous setup/),+ screen.queryByText(/Your setup is outdated/),).not.toBeInTheDocument();});@@ -417,79 +850,122 @@ describe("V4MigrationHeaderContent", () => {mocks.migrationData.apis = { status: "loading", count: 0 };render(<V4MigrationHeaderContent projectId="project-1" />);expect(- screen.queryByText(/This project still uses the previous setup/),+ screen.queryByText(/Your setup is outdated/),).not.toBeInTheDocument();});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- // right-aligned status link.+ // body's top-right corner; without the gutter it overlaps the title.render(<V4MigrationHeaderContentprojectId="project-1"titleRowClassName="pr-6"/>,);- const link = screen.getByRole("link", { name: "View Org status" });- expect(link).toHaveAttribute("href", "/v4-migration");- expect(link.parentElement).toHaveClass("pr-6");+ expect(screen.getByText("Migrate to v4").parentElement).toHaveClass("pr-6");});- it("creates project API keys when revealing the migration prompt", async () => {- render(<V4MigrationHeaderContent projectId="project-1" />);+ it("links to the docs from the details footer", () => {+ render(<V4MigrationDetailsContent projectId="project-1" />);- fireEvent.click(- screen.getByRole("button", { name: "Update SDK with agents" }),+ expect(screen.getByRole("link", { name: "Docs" })).toHaveAttribute(+ "href",+ "https://langfuse.com/docs/v4",);+ });++ it("does not create credentials when revealing or copying the prompt", () => {+ render(<V4MigrationAgentUpgradeSection projectId="project-1" />);++ fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));expect(screen.getByText("coding-agent-prompt")).toBeInTheDocument();+ expect(mocks.createProjectApiKey).not.toHaveBeenCalled();++ // Second click copies; still no credentials. (jsdom has no clipboard.)+ Object.assign(navigator, { clipboard: { writeText: vi.fn() } });+ fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));+ expect(mocks.createProjectApiKey).not.toHaveBeenCalled();+ });++ it("creates keys only on the explicit create action and shows an env block", async () => {+ render(<V4MigrationAgentUpgradeSection projectId="project-1" />);++ fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));+ const createButton = screen.getByRole("button", {+ name: "Create API keys",+ });++ fireEvent.click(createButton);expect(mocks.createProjectApiKey).toHaveBeenCalledWith({projectId: "project-1",note: "v4-migration-key",});+await waitFor(() =>- expect(screen.getByText("pk-lf-pr…ct-1")).toBeInTheDocument(),+ expect(+ screen.getByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-1/),+ ).toBeInTheDocument(),);+ expect(+ screen.getByText(/LANGFUSE_SECRET_KEY=sk-lf-project-1/),+ ).toBeInTheDocument();+ expect(screen.getByText(/LANGFUSE_BASE_URL=/)).toBeInTheDocument();+ // The secret must never leak into the agent prompt.+ expect(screen.getByText("coding-agent-prompt").textContent).not.toContain(+ "sk-lf-project-1",+ );+ // The create action is consumed; no accidental duplicates.+ expect(+ screen.queryByRole("button", { name: "Create API keys" }),+ ).not.toBeInTheDocument();+ expect(mocks.createProjectApiKey).toHaveBeenCalledTimes(1);});- it("hides API key creation for users without access", () => {+ it("keeps the prompt available but disables key creation without access", () => {mocks.hasApiKeyCreateAccess = false;- const { container } = render(- <V4MigrationHeaderContent projectId="project-1" />,- );-- fireEvent.click(- screen.getByRole("button", { name: "Update SDK with agents" }),- );+ render(<V4MigrationAgentUpgradeSection projectId="project-1" />);+ const promptButton = screen.getByRole("button", { name: "Copy prompt" });+ expect(promptButton).toBeEnabled();+ fireEvent.click(promptButton);expect(screen.getByText("coding-agent-prompt")).toBeInTheDocument();++ const createButton = screen.getByRole("button", {+ name: "Create API keys",+ });+ expect(createButton).toBeDisabled();+ fireEvent.click(createButton);expect(mocks.createProjectApiKey).not.toHaveBeenCalled();- expect(container.querySelector(".lucide-loader-circle")).toBeNull();});- it("refreshes generated keys when the project changes", async () => {+ it("requires a fresh explicit creation when the project changes", async () => {const { rerender } = render(- <V4MigrationHeaderContent key="project-1" projectId="project-1" />,- );- fireEvent.click(- screen.getByRole("button", { name: "Update SDK with agents" }),+ <V4MigrationAgentUpgradeSection key="project-1" projectId="project-1" />,);+ fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));+ fireEvent.click(screen.getByRole("button", { name: "Create API keys" }));await waitFor(() =>- expect(screen.getByText("pk-lf-pr…ct-1")).toBeInTheDocument(),+ expect(+ screen.getByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-1/),+ ).toBeInTheDocument(),);rerender(- <V4MigrationHeaderContent key="project-2" projectId="project-2" />,+ <V4MigrationAgentUpgradeSection key="project-2" projectId="project-2" />,);- expect(screen.queryByText("pk-lf-pr…ct-1")).not.toBeInTheDocument();- fireEvent.click(- screen.getByRole("button", { name: "Update SDK with agents" }),- );+ expect(+ screen.queryByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-1/),+ ).not.toBeInTheDocument();+ fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));+ fireEvent.click(screen.getByRole("button", { name: "Create API keys" }));await waitFor(() =>- expect(screen.getByText("pk-lf-pr…ct-2")).toBeInTheDocument(),+ expect(+ screen.getByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-2/),+ ).toBeInTheDocument(),);expect(mocks.createProjectApiKey).toHaveBeenLastCalledWith({projectId: "project-2",diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsxindex e640bb3528..041899d8eb 100644--- a/web/src/features/v4-migration/V4MigrationContent.tsx+++ b/web/src/features/v4-migration/V4MigrationContent.tsx@@ -1,19 +1,24 @@/* eslint-disable @repo/no-style-props */-import { type ReactNode, useState } from "react";+import { type ReactNode, useEffect, useRef, useState } from "react";import { useRouter } from "next/router";import Link from "next/link";import {+ Bot,BotMessageSquare,+ Check,ChevronRight,Copy,- LibraryBig,- LifeBuoy,- TriangleAlert,+ Info,} from "lucide-react";import { useCanUseInAppAgent } from "@/src/features/in-app-agent/components/InAppAiAgentProvider";import { useSupportDrawer } from "@/src/features/support-chat/SupportDrawerProvider";import { Button } from "@/src/components/ui/button";-import { CodeView } from "@/src/components/ui/CodeJsonViewer";+import {+ HoverCard,+ HoverCardContent,+ HoverCardPortal,+ HoverCardTrigger,+} from "@/src/components/ui/hover-card";import { RainbowButton } from "@/src/components/magicui/rainbow-button";import { Separator } from "@/src/components/ui/separator";import {@@ -23,12 +28,19 @@ import {} from "@/src/components/ui/collapsible";import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { showSuccessToast } from "@/src/features/notifications/showSuccessToast";+import { showErrorToast } from "@/src/features/notifications/showErrorToast";import { cn } from "@/src/utils/tailwind";+import { copyTextToClipboard } from "@/src/utils/clipboard";import {formatSdkUpgradeRequirement,formatSdkVersion,+ getCustomInstrumentationSectionState,+ getOtelSectionState,+ getSdkSectionState,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,@@ -46,7 +58,8 @@ import {V4_CODING_AGENT_PROMPT,} from "@/src/features/v4-migration/useV4UpgradeAssistantSupport";import { useHasProjectAccess } from "@/src/features/rbac/utils/checkProjectAccess";-import { api, reportNonTrpcError } from "@/src/utils/api";+import { api } from "@/src/utils/api";+import { encodeFiltersGeneric, type FilterState } from "@langfuse/shared";import { EvaluatorMigrationDialog } from "@/src/features/v4-migration/EvaluatorMigrationDialog";import { buildDeprecatedEvaluatorsUrl } from "@/src/features/v4-migration/evaluatorMigrationUrls";@@ -54,6 +67,7 @@ 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";+// Consumed by the status page deadline copy.export const V4_MIGRATION_DEADLINE = "Oct 9";const SDK_UPGRADE_URL ="https://langfuse.com/docs/observability/sdk/upgrade-path";@@ -73,6 +87,11 @@ const DEPRECATED_INTEGRATION_MIGRATION_URLS: Record<string, string> = {};const EXPERIMENT_OTEL_INGESTION_URL ="https://langfuse.com/integrations/native/opentelemetry/experiments";+// The docs ship one combined SDK page; Python and JS have no standalone+// landing pages to deep-link.+const SDK_OVERVIEW_URL = "https://langfuse.com/docs/observability/sdk/overview";+const OTEL_INTEGRATION_URL =+ "https://langfuse.com/integrations/native/opentelemetry";// Copies the agent migration prompt to the clipboard with toast + analytics;// shared by the panel/modal header CTA and the status page.@@ -80,8 +99,10 @@ 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");- await navigator.clipboard.writeText(V4_CODING_AGENT_PROMPT);showSuccessToast({title: "Prompt copied",description: "Paste it into Cursor, Codex, or another coding agent.",@@ -89,45 +110,53 @@ export function useCopyMigrationPrompt() {};}-function Chip({- children,- variant,-}: {- children: ReactNode;- variant: "warning" | "success";-}) {- 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",- variant === "warning"- ? "bg-light-yellow text-dark-yellow"- : "bg-light-green text-dark-green",- )}- >- {children}- </span>- );-}-function Section({title,- chip,+ count,+ meta,children,+ defaultOpen,+ analyticsSection,}: {title: string;- chip: ReactNode;+ /** 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;}) {+ const capture = usePostHogClientCapture();return (- <Collapsible>- <CollapsibleTrigger className="group flex w-full items-center gap-2.5 py-1.5 text-left">+ <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">+ {/* 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">+ {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 className="text-muted-foreground h-4 w-4 shrink-0 transition-transform group-data-[state=open]:rotate-90" />- <span className="flex-1 text-sm">{title}</span>- {chip}</CollapsibleTrigger><CollapsibleContent>- <div className="pt-0.5 pb-3.5 pl-6.5">{children}</div>+ <div className="pt-0.5 pb-4 pl-4.25">{children}</div></CollapsibleContent></Collapsible>);@@ -141,214 +170,797 @@ function ExternalLink({href,children,className,+ analytics,}: {href: string;children: ReactNode;className?: string;+ /** Which guidance link in which section — for section_link_clicked. */+ analytics?: { section: string; link: string };}) {+ const capture = usePostHogClientCapture();return (<ahref={href}target="_blank"rel="noopener noreferrer"- className={cn("text-dark-blue hover:underline", className)}+ className={cn("underline", className)}+ onClick={+ analytics+ ? () => capture("v4_migration:section_link_clicked", analytics)+ : undefined+ }>{children}</a>);}-function ApiKeyCopyField({- label,- value,+// Evidence deep-link filter for one SDK usage series: always the exact public+// key, 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-only. The delayed-OTel `source` dimension is+// deliberately not linked either: it is a prefix match, not an exact one.+function buildSdkUsageEvidenceFilter(usage: V4MigrationSdkUsageSeries): string {+ const filters: FilterState = [+ {+ column: "ingestionApiKey",+ type: "stringOptions",+ operator: "any of",+ value: [usage.publicKey],+ },+ ];+ 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,}: {- label: "Public key" | "Secret key";- value: string;+ 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 truncatedValue = `${value.slice(0, 8)}…${value.slice(-4)}`;+ 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="flex min-w-0 items-stretch overflow-hidden rounded-md border">- <div className="bg-muted text-muted-foreground flex w-24 shrink-0 items-center justify-center border-r text-xs font-bold">- {label}+ <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>- <CodeView- content={truncatedValue}- originalContent={value}- className="min-w-0 flex-1 [&>div]:rounded-none [&>div]:border-0"- lineWrap={false}- />+ <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 className="h-3.5 w-3.5" />+ ) : (+ <Copy className="h-3.5 w-3.5" />+ )}+ </Button></div>);}-function MigrationCountChip({- state,- affectedLabel,+function SdkUsageSeriesRows({+ series,+ needsAction,+ suffix,+ unknownSeriesLabel = "OTLP exporter",+ projectId,+ onNavigate,+ analyticsSection,}: {- state: MigrationCountState;- affectedLabel: string;+ 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;+ /** Enables the evidence deep link on the public key. */+ projectId?: string;+ onNavigate?: () => void;+ /** Funnel dimension for the evidence_link_clicked event (snake_case). */+ analyticsSection: string;}) {- if (state.status === "loading") {- return <Chip variant="warning">Checking</Chip>;- }- if (state.status === "error") {- return <Chip variant="warning">Check failed</Chip>;- }- if (state.count === 0) {- return <Chip variant="success">Up to date</Chip>;- }+ const capture = usePostHogClientCapture();+ if (series.length === 0) return null;+return (- <Chip variant="warning">- {state.count} {affectedLabel}- </Chip>- );-}+ <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 =+ usage.publicKey.length > 18+ ? `${usage.publicKey.slice(0, 9)}…${usage.publicKey.slice(-6)}`+ : usage.publicKey || "No API key";-function MigrationActionChip({ state }: { state: MigrationActionState }) {- if (state.status === "loading") {- return <Chip variant="warning">Checking</Chip>;- }- if (state.status === "error") {- return <Chip variant="warning">Check failed</Chip>;- }- return state.result === "required" ? (- <Chip variant="warning">Update required</Chip>- ) : state.result === "sdk_usage_inconclusive" ? (- <Chip variant="warning">Needs review</Chip>- ) : (- <Chip variant="success">Up to date</Chip>+ return (+ <li+ key={`${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">+ {/* Deep link to the exact evidence: the events table filtered by+ this public key (plus SDK name/version when attributed) over+ the same lookback window the detection used; see+ buildSdkUsageEvidenceFilter. Scores-only offenders+ (eventsCount 0) stay plain text — the events table has+ nothing for them and a link would open an empty result. */}+ {projectId && usage.publicKey && usage.eventsCount > 0 ? (+ <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={`/project/${projectId}/observations?filter=${encodeURIComponent(+ buildSdkUsageEvidenceFilter(usage),+ )}&dateRange=${V4_MIGRATION_LOOKBACK_DAYS}d`}+ 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,+ });+ onNavigate?.();+ }}+ className="underline"+ title={usage.publicKey}+ >+ {publicKey}+ </Link>+ ) : (+ <span title={usage.publicKey || undefined}>{publicKey}</span>+ )}+ <span>+ · last seen{" "}+ {formatCompactRelativeTime(new Date(usage.lastSeen))}+ </span>+ </div>+ </li>+ );+ })}+ </ul>);}-function V4MigrationSdkSection({ sdk }: { sdk: V4MigrationSdkState }) {- const detectedSdkSeries = sdk.sdkUsageSeries.filter(- (series) => series.canonicalSdkName !== null,- );- const chip =- sdk.status === "latest" ? (- <Chip variant="success">Up to date</Chip>- ) : sdk.status === "otel_realtime" ? (- <Chip variant="success">OTel real-time</Chip>- ) : sdk.status === "no_data" ? (- <Chip variant="success">No data detected</Chip>- ) : sdk.status === "checking" ? (- <Chip variant="warning">Checking</Chip>- ) : sdk.status === "otel_header_required" ? (- <Chip variant="warning">OTel header required</Chip>- ) : sdk.status === "unknown" ? (- <Chip variant="warning">Needs review</Chip>- ) : sdk.status === "error" ? (- <Chip variant="warning">Check failed</Chip>- ) : (- <Chip variant="warning">{sdk.upgradeRequiredCount} outdated</Chip>- );+// 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,+ onNavigate,+}: {+ sdk: V4MigrationSdkState;+ defaultOpen?: boolean;+ projectId?: string;+ onNavigate?: () => void;+}) {+ 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="Tracing Instrumentation" chip={chip}>+ <Section+ title="Update SDK"+ analyticsSection="sdk"+ count={isTransient ? 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">- {sdk.status === "checking" ? (+ {section.status === "checking" ? ("Checking the latest traces for this project…"- ) : sdk.status === "otel_header_required" ? (- <>- OTel data is arriving through the delayed ingestion path. Set the{" "}- <MonoValue>x-langfuse-ingestion-version</MonoValue> header to{" "}- <MonoValue>4</MonoValue> on the OTLP exporter to use real-time- ingestion.{" "}- <ExternalLink href={OTEL_V4_MIGRATION_URL}>- OpenTelemetry migration guide- </ExternalLink>- .- </>- ) : sdk.status === "otel_realtime" ? (- "OTel data is using real-time ingestion. No ingestion header update is required."- ) : sdk.status === "no_data" ? (- `No ingestion data was detected in the last ${V4_MIGRATION_LOOKBACK_DAYS} days.`- ) : sdk.status === "unknown" ? (- "We could not recognize every detected SDK version. Verify that these SDKs are up to date."- ) : sdk.status === "error" ? (+ ) : section.status === "error" ? ("We could not check the latest traces for this project. Try again later."- ) : sdk.status === "latest" ? (- "All detected Langfuse SDK versions are up to date.") : (<>- {sdk.upgradeRequiredCount} detected SDK{" "}- {sdk.upgradeRequiredCount === 1+ {section.actionableCount} detected SDK{" "}+ {section.actionableCount === 1? "configuration needs": "configurations need"}{" "}- an update.{" "}- <ExternalLink href={SDK_UPGRADE_URL}>Upgrade the SDK</ExternalLink>{" "}- for real-time data and the latest tracing experience.+ an update. See{" "}+ <ExternalLink+ href={SDK_UPGRADE_URL}+ analytics={{ section: "sdk", link: "sdk_upgrade_docs" }}+ >+ upgrade path+ </ExternalLink>+ .</>)}</p>- {detectedSdkSeries.length > 0 && (- <ul className="mt-2 flex flex-col gap-1.5">- {detectedSdkSeries.map((series) => {- const sdkLabel = formatSdkVersion({- language: series.canonicalSdkName ?? series.sdkName,- version: series.sdkVersion,- });- const publicKey =- series.publicKey.length > 18- ? `${series.publicKey.slice(0, 9)}…${series.publicKey.slice(-6)}`- : series.publicKey || "No API key";-- return (- <li- key={`${series.sdkName}:${series.sdkVersion}:${series.publicKey}`}- className="text-muted-foreground flex flex-wrap items-baseline gap-x-1.5 text-xs"+ <SdkUsageSeriesRows+ series={section.series}+ projectId={projectId}+ onNavigate={onNavigate}+ analyticsSection="sdk"+ needsAction={(usage) =>+ (usage.v4MigrationStatus === "upgrade_required" &&+ !usage.upgradeCompleted) ||+ usage.v4MigrationStatus === "unknown"+ }+ suffix={(usage) =>+ usage.v4MigrationStatus === "upgrade_required" &&+ !usage.upgradeCompleted ? (+ <span>· {formatSdkUpgradeRequirement(usage.canonicalSdkName)}</span>+ ) : usage.upgradeCompleted ? (+ <span>· upgrade completed</span>+ ) : usage.v4MigrationStatus === "unknown" ? (+ <span>· version not recognized</span>+ ) : 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,+ onNavigate,+}: {+ sdk: V4MigrationSdkState;+ defaultOpen?: boolean;+ projectId?: string;+ onNavigate?: () => void;+}) {+ 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">+ OTel data is arriving through the delayed ingestion path. Set the{" "}+ <MonoValue>x-langfuse-ingestion-version</MonoValue> header to{" "}+ <MonoValue>4</MonoValue> on the OTLP exporter to use real-time+ ingestion.{" "}+ <ExternalLink+ href={OTEL_V4_MIGRATION_URL}+ analytics={{ section: "otel", link: "otel_migration_docs" }}+ >+ OpenTelemetry migration guide+ </ExternalLink>+ .+ </p>+ <SdkUsageSeriesRows+ series={section.series}+ projectId={projectId}+ onNavigate={onNavigate}+ analyticsSection="otel"+ needsAction={(usage) => usage.hasDelayedOtelEvents === true}+ suffix={(usage) =>+ usage.hasDelayedOtelEvents === true ? (+ <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,+ onNavigate,+}: {+ sdk: V4MigrationSdkState;+ defaultOpen?: boolean;+ projectId?: string;+ onNavigate?: () => void;+}) {+ 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 one of our latest{" "}+ <ExternalLink+ href={SDK_OVERVIEW_URL}+ analytics={{+ section: "custom_instrumentation",+ link: "sdk_overview_docs",+ }}+ >+ Python or JS SDK+ </ExternalLink>{" "}+ versions, 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}+ onNavigate={onNavigate}+ unknownSeriesLabel="Custom instrumentation"+ analyticsSection="custom_instrumentation"+ needsAction={() => true}+ suffix={() => null}+ />+ </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;+ /** Assistant CTA; null hides the button. */+ assistant: { onMigrate: () => void } | null;+ evalsUrl?: string;+ onNavigate?: () => void;+ defaultOpen?: boolean;+}) {+ const capture = usePostHogClientCapture();+ return (+ <Section+ title="Repoint 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. Repoint{" "}+ {state.count === 1 ? "it" : "them"} at observations.+ </p>+ {assistant && (+ <Button variant="outline" size="sm" onClick={assistant.onMigrate}>+ <BotMessageSquare className="mr-1.5 h-4 w-4" />+ Use Assistant+ </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" }}>- <MonoValue>{sdkLabel}</MonoValue>- <span title={series.publicKey || undefined}>{publicKey}</span>- <span>- · last seen{" "}- {formatCompactRelativeTime(new Date(series.lastSeen))}+ 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 }[];+ 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 called these deprecated endpoints in the last{" "}+ {V4_MIGRATION_LOOKBACK_DAYS} days. They stop working soon; the{" "}+ <ExternalLink+ href={DEPRECATED_API_MIGRATION_URL}+ analytics={{ section: "apis", link: "deprecated_api_docs" }}+ >+ migration guide+ </ExternalLink>{" "}+ maps each endpoint to its replacement.+ </p>+ <div className="flex flex-col">+ {usage.map((row) => (+ <div+ key={row.endpoint}+ className="text-muted-foreground flex flex-wrap items-baseline justify-between gap-x-2 py-0.5"+ >+ <ExternalLink+ href={DEPRECATED_API_MIGRATION_URL}+ className="text-sm"+ analytics={{ section: "apis", link: "deprecated_api_docs" }}+ >+ {row.endpoint}+ </ExternalLink>+ <span+ className="text-muted-foreground text-sm whitespace-nowrap"+ title={`Last seen at ${row.lastSeen}`}+ >+ {numberFormatter(row.count, 0, 2)} calls · last seen{" "}+ {formatCompactRelativeTime(new Date(row.lastSeen))}</span>- {series.v4MigrationStatus === "upgrade_required" &&- !series.upgradeCompleted && (- <span className="text-dark-yellow">- · {formatSdkUpgradeRequirement(series.canonicalSdkName)}- </span>- )}- {series.upgradeCompleted && <span>· upgrade completed</span>}- {series.v4MigrationStatus === "unknown" && (- <span className="text-dark-yellow">- · version not recognized- </span>+ </div>+ ))}+ </div>+ </>+ ) : (+ <p className="text-muted-foreground text-sm">+ No deprecated public API usage detected in the last{" "}+ {V4_MIGRATION_LOOKBACK_DAYS} days.+ </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>)}- </li>- );- })}- </ul>+ <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>);}-// Title, description, and the primary agent CTA. The CTA is two-step: the-// first click reveals the prompt so users can see what they hand to their-// agent, the second click copies it.+// Title, status link, and the v4 pitch. The agent CTA lives in+// V4MigrationAgentUpgradeSection, rendered by the details content.export function V4MigrationHeaderContent({projectName,projectId,- onNavigate,titleRowClassName,}: {projectName?: string;projectId?: string;- /** Fires when an internal link is followed so the surface can close. */- onNavigate?: () => void;/** 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 right-aligned status link. */+ * would otherwise overlap the title. */titleRowClassName?: string;}) {- const capture = usePostHogClientCapture();- const handleCopyPrompt = useCopyMigrationPrompt();- const [promptVisible, setPromptVisible] = useState(false);-// 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.@@ -362,6 +974,49 @@ export function V4MigrationHeaderContent({Boolean(projectId) &&getProjectMigrationReadiness(migrationData) === "action-needed";+ return (+ <>+ <div+ className={cn(+ "mb-1.5 flex items-baseline justify-between gap-2",+ titleRowClassName,+ )}+ >+ <p className="min-w-0 text-lg font-bold">+ {projectName ? <>Migrate {projectName} to v4</> : "Migrate to v4"}+ </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>+ </>+ );+}++// The primary agent CTA as its own group. The CTA is two-step: the first+// click reveals the prompt so users can see what they hand to their agent,+// the second click 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 [promptVisible, setPromptVisible] = useState(false);+const [generatedKeys, setGeneratedKeys] = useState<{projectId: string;secretKey: string;@@ -382,13 +1037,19 @@ export function V4MigrationHeaderContent({const handleShowPrompt = () => {capture("v4_migration:coding_agent_prompt_viewed");setPromptVisible(true);+ };++ const handleCreateKeys = () => {+ // Guards double-clicks and re-creation once keys exist for this project.if (!projectId ||!hasApiKeyCreateAccess ||- mutCreateProjectApiKey.isPending+ mutCreateProjectApiKey.isPending ||+ generatedKeysForProject)return;+ capture("v4_migration:create_project_keys_clicked");mutCreateProjectApiKey.mutateAsync({projectId,@@ -402,97 +1063,111 @@ export function V4MigrationHeaderContent({});capture(`project_settings:api_key_create`);})- .catch((error) => reportNonTrpcError(error, "v4-migration"));+ .catch((error) => {+ console.error(error);+ showErrorToast(+ "Could not create API keys",+ "Something went wrong. Please try again.",+ );+ });};+ 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={cn(- "mb-1.5 flex items-baseline justify-between gap-2",- titleRowClassName,- )}- >- <p- className="min-w-0 flex-1 truncate text-lg font-bold"- title={projectName ? `Migrate ${projectName} to v4` : "Migrate to v4"}- >- {projectName ? <>Migrate {projectName} to v4</> : "Migrate to v4"}+ <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+ </div>+ <p className="text-muted-foreground text-sm">+ Paste prompt into Claude Code or other coding agents</p>- <Link- href="/v4-migration"- onClick={() => {- capture("v4_migration:panel_status_link_clicked");- onNavigate?.();- }}- className="shrink-0 text-sm underline"- >- View Org status- </Link></div>- <p className="text-muted-foreground mb-3 text-sm leading-relaxed">- <ExternalLink href={V4_DOCS_URL} className="text-inherit underline">- Langfuse v4- </ExternalLink>{" "}- is here: real-time, up to 165× faster, plus new dashboards, alerting,- sessions, and trace view.- {needsMigration &&- ` This project still uses the previous setup, which stops working on ${V4_MIGRATION_DEADLINE}.`}- </p><div className="flex flex-col gap-2">- {promptVisible && (- <div className="bg-muted/50 max-h-44 overflow-y-auto rounded-md border p-3">- <code className="text-muted-foreground font-mono text-xs leading-5 break-words whitespace-pre-wrap">- {V4_CODING_AGENT_PROMPT}- </code>- </div>- )}<RainbowButtonclassName="w-full"onClick={promptVisible ? handleCopyPrompt : handleShowPrompt}>{promptVisible ? (- <>- <Copy className="mr-1.5 h-4 w-4 shrink-0" />- <span className="min-w-0 truncate" title="Copy prompt">- Copy prompt- </span>- </>+ <Copy className="mr-1.5 h-4 w-4 shrink-0" />) : (- <span className="min-w-0 truncate" title="Update SDK with agents">- Update SDK with agents- </span>+ <Bot className="mr-1.5 h-4 w-4 shrink-0" />)}+ <span className="min-w-0 truncate" title="Copy prompt">+ Copy prompt+ </span></RainbowButton>- {promptVisible &&- projectId &&- hasApiKeyCreateAccess &&- generatedKeysForProject && (- <div className="mt-1 flex flex-col gap-2">- <p className="text-muted-foreground text-sm leading-relaxed">- If you are setting up the Langfuse CLI or skills for the first- time, use these project API keys.+ {promptVisible && (+ <CodeBlockWithCopy+ text={V4_CODING_AGENT_PROMPT}+ copyLabel="Copy prompt to clipboard"+ onCopy={() => capture("v4_migration:coding_agent_prompt_copied")}+ scrollable+ className="my-3"+ />+ )}+ {promptVisible && 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>- <div className="flex flex-col gap-2">- <ApiKeyCopyField- label="Public key"- value={generatedKeysForProject.publicKey}- />- <ApiKeyCopyField- label="Secret key"- value={generatedKeysForProject.secretKey}- />- </div>+ {!envBlock &&+ (missingApiKeyAccess ? (+ // Disabled buttons swallow pointer events, so the hover+ // reason needs a span trigger, same pattern as ActionButton.+ <HoverCard openDelay={200}>+ <HoverCardTrigger asChild>+ <span className="shrink-0">{createKeysButton}</span>+ </HoverCardTrigger>+ <HoverCardPortal>+ <HoverCardContent className="w-80 text-sm">+ Only users with admin access can create project API+ keys. Please contact your admins.+ </HoverCardContent>+ </HoverCardPortal>+ </HoverCard>+ ) : (+ createKeysButton+ ))}</div>- )}+ {envBlock && (+ <CodeBlockWithCopy+ text={envBlock}+ copyLabel="Copy keys"+ onCopy={() => capture("v4_migration:project_keys_copied")}+ />+ )}+ </div>+ )}</div>- </>+ </div>);}-// The "Want to review first?" and "What happens if I don't update" groups.-// onNavigate fires when an internal link is followed so the hosting surface-// (panel or modal) can close itself.+// 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,@@ -515,7 +1190,87 @@ export function V4MigrationDetailsContent({orgId: organization?.id,enabled: Boolean(projectId),});- const { canToggleV4 } = useV4Beta();+ const { canToggleV4, isBetaEnabled } = useV4Beta();+ // 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 = isBetaEnabled ? 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");@@ -549,342 +1304,148 @@ 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+ </div>+ <div>+ <V4MigrationSdkSection+ sdk={migrationData.sdk}+ projectId={evidenceProjectId}+ onNavigate={onNavigate}+ />+ <V4MigrationOtelSection+ sdk={migrationData.sdk}+ projectId={evidenceProjectId}+ onNavigate={onNavigate}+ />+ <V4MigrationCustomInstrumentationSection+ sdk={migrationData.sdk}+ projectId={evidenceProjectId}+ onNavigate={onNavigate}+ />++ {!evalsClean && (+ <V4MigrationEvalsSection+ state={migrationData.evals}+ assistant={+ canUseAssistant+ ? { onMigrate: handleMigrateEvalsWithAgent }+ : 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>+ )}+ </div>+ </div>++ <Separator />++ <V4MigrationAgentUpgradeSection projectId={projectId} />+{/* The toggle row hides itself when the session cannot toggle v4(legacy/events_only write mode, post-rollout auto-enrollment), so thecopy describing it must hide on the same condition. */}{canToggleV4 && (<>- <div className="flex flex-col gap-3">- <div className="flex items-center justify-between gap-2">- <div className="flex items-center gap-2 text-base font-bold">- <LibraryBig className="h-4 w-4 shrink-0" /> Want to review- first?- </div>- <V4PreviewToggleRow projectId={projectId} />- </div>- <p className="text-muted-foreground text-sm">- The latest SDK no longer sets trace input and output; v4{" "}- <ExternalLink- href={OBSERVATIONS_DATA_MODEL_URL}- className="text-inherit underline"- >- infers them from observations- </ExternalLink>- . Use this toggle to compare both views while you upgrade.+ <div className="flex items-center justify-between gap-2">+ <p className="text-muted-foreground flex min-w-0 items-center gap-1.5 text-sm">+ Compare traces while you upgrade+ <HoverCard openDelay={200}>+ <HoverCardTrigger asChild>+ <button+ type="button"+ aria-label="Why compare traces?"+ className="shrink-0"+ >+ <Info className="h-3.5 w-3.5" />+ </button>+ </HoverCardTrigger>+ <HoverCardPortal>+ <HoverCardContent className="w-80 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>+ .+ </HoverCardContent>+ </HoverCardPortal>+ </HoverCard></p>+ <V4PreviewToggleRow projectId={projectId} /></div>-- <Separator /></>)}- <div className="flex flex-col gap-3">- <div className="flex items-center justify-between gap-2">- <div className="flex items-center gap-2 text-base font-bold">- <TriangleAlert className="h-4 w-4 shrink-0" /> What happens if I- don't update?- </div>- <a- href={V4_DOCS_URL}- target="_blank"- rel="noopener noreferrer"- onClick={() => capture("v4_migration:panel_docs_link_clicked")}- className="text-foreground shrink-0 text-sm underline"- >- Documentation- </a>- </div>- <p className="text-muted-foreground text-sm">- Some features will stop working on {V4_MIGRATION_DEADLINE}.- </p>- <div>- <V4MigrationSdkSection sdk={migrationData.sdk} />-- <Section- title="Evals"- chip={- <MigrationCountChip- state={migrationData.evals}- affectedLabel="deprecated"- />- }- >- {migrationData.evals.status === "loading" ? (- <p className="text-muted-foreground text-sm">- Checking configured evals…- </p>- ) : migrationData.evals.status === "error" ? (- <p className="text-muted-foreground text-sm">- We could not check configured evals. Try again later.- </p>- ) : migrationData.evals.count > 0 ? (- <>- <p className="text-muted-foreground mb-2 text-sm">- {migrationData.evals.count} configured{" "}- {migrationData.evals.count === 1- ? "eval targets"- : "evals target"}{" "}- trace input/output, which{" "}- <span className="text-dark-yellow">- {migrationData.evals.count === 1 ? "stops" : "stop"} running- on {V4_MIGRATION_DEADLINE}- </span>- . Repointing {migrationData.evals.count === 1 ? "it" : "them"}{" "}- at observations or experiments requires minimal changes- {canUseAssistant- ? upgradePlan.mode === "evals-ready"- ? " — the assistant can do it for you"- : " — the assistant can help you choose the upgrade order"- : ""}- .- </p>- <div className="flex items-center gap-3">- {canUseAssistant && (- <Button- variant="outline"- size="sm"- onClick={handleMigrateEvalsWithAgent}- >- <BotMessageSquare className="mr-1.5 h-4 w-4" />- Use Assistant- </Button>- )}- {evalsUrl ? (- <Link- href={evalsUrl}- onClick={onNavigate}- className="text-dark-blue text-sm hover:underline"- >- Review deprecated evals- </Link>- ) : null}- </div>- </>- ) : (- <p className="text-muted-foreground text-sm">- No deprecated evals detected.- </p>- )}- </Section>-- <Section- title="Experiments"- chip={<MigrationActionChip state={migrationData.experiments} />}- >- {migrationData.experiments.status === "loading" ? (- <p className="text-muted-foreground text-sm">- Checking experiment instrumentation…- </p>- ) : migrationData.experiments.status === "error" ? (- <p className="text-muted-foreground text-sm">- We could not check experiment instrumentation. Try again later.- </p>- ) : migrationData.experiments.result !== "not_required" ? (- <p className="text-muted-foreground text-sm">- {migrationData.experimentInstrumentationUpgradePath ===- "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}>- OTel experiment instrumentation guide- </ExternalLink>{" "}- for more details.- </>- ) : migrationData.experiments.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}>- 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>-- <Section- title="Deprecated APIs"- chip={- <MigrationCountChip- state={migrationData.apis}- affectedLabel="deprecated"- />- }- >- {migrationData.apis.status === "loading" ? (- <p className="text-muted-foreground text-sm">- Checking public API usage…- </p>- ) : migrationData.apis.status === "error" ? (- <p className="text-muted-foreground text-sm">- We could not check public API usage. Try again later.- </p>- ) : migrationData.apiUsage.length > 0 ? (- <>- <p className="text-muted-foreground mb-2 text-sm">- You've called these deprecated endpoints in the last{" "}- {V4_MIGRATION_LOOKBACK_DAYS} days. They stop working on{" "}- {V4_MIGRATION_DEADLINE}; the{" "}- <ExternalLink href={DEPRECATED_API_MIGRATION_URL}>- migration guide- </ExternalLink>{" "}- maps each endpoint to its replacement.- </p>- <div className="flex flex-col">- {migrationData.apiUsage.map((usage) => (- <div- key={usage.endpoint}- className="flex flex-wrap items-baseline justify-between gap-x-2 py-0.5"- >- <ExternalLink- href={DEPRECATED_API_MIGRATION_URL}- className="text-sm"- >- {usage.endpoint}- </ExternalLink>- <span- className="text-muted-foreground text-xs whitespace-nowrap"- title={`Last seen at ${usage.lastSeen}`}- >- {numberFormatter(usage.count, 0, 2)} calls · last seen{" "}- {formatCompactRelativeTime(new Date(usage.lastSeen))}- </span>- </div>- ))}- </div>- </>- ) : (- <p className="text-muted-foreground text-sm">- No deprecated public API usage detected in the last{" "}- {V4_MIGRATION_LOOKBACK_DAYS} days.- </p>- )}- </Section>-- <Section- title="Deprecated Integrations"- chip={- <MigrationCountChip- state={migrationData.exports}- affectedLabel="deprecated"- />- }- >- {migrationData.exports.status === "loading" ? (- <p className="text-muted-foreground text-sm">- Checking integrations…- </p>- ) : migrationData.exports.status === "error" ? (- <p className="text-muted-foreground text-sm">- We could not check integrations. Try again later.- </p>- ) : migrationData.legacyIntegrations.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">- {migrationData.legacyIntegrations.map((name) => (- <div- key={name}- className="flex items-baseline gap-1.5 py-0.5"- >- {integrationsUrl ? (- <Link- href={integrationsUrl}- onClick={onNavigate}- className="text-dark-blue text-sm hover:underline"- >- {name}- </Link>- ) : (- <span className="text-sm">{name}</span>- )}- <span className="text-muted-foreground text-xs">·</span>- <ExternalLink- href={- DEPRECATED_INTEGRATION_MIGRATION_URLS[name] ??- V4_DOCS_URL- }- className="text-xs"- >- Migration guide- </ExternalLink>- </div>- ))}- </div>- </>- ) : (- <p className="text-muted-foreground text-sm">- No deprecated integration exports detected.- </p>- )}- </Section>- </div>- </div>-<Separator />- <div className="flex flex-col gap-3">- <div className="flex items-center gap-2 text-base font-bold">- <LifeBuoy className="h-4 w-4 shrink-0" /> Contact us- </div>- <p className="text-muted-foreground text-sm">- Need a hand with the update? We're here to help!- </p>- <div className="flex items-center gap-2">- <Button variant="outline" asChild className="min-w-0 flex-1">- <a- href="https://cal.com/team/langfuse/welcome-to-langfuse"- target="_blank"- rel="noopener noreferrer"- onClick={() => capture("v4_migration:contact_book_call_clicked")}- >- <span className="min-w-0 truncate" title="Book a call">- Book a call- </span>- </a>- </Button>- <Button- variant="outline"- className="min-w-0 flex-1"- onClick={handleEmailEngineer}- >- <span className="min-w-0 truncate" title="Email an Engineer">- Email an Engineer- </span>- </Button>- </div>+ <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>{projectId ? (<EvaluatorMigrationDialogdiff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsxnew file mode 100644index 0000000000..48f408c90f--- /dev/null+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx@@ -0,0 +1,198 @@+import { render, screen } from "@testing-library/react";+import { beforeEach, describe, expect, it, vi } from "vitest";++import { V4MigrationDelayBadge } from "./V4MigrationDelayBadge";+import {+ type V4MigrationSdkState,+ type V4MigrationSdkUsageSeries,+} from "./sdkVersionStatus";++const makeSdkUsageSeries = (+ overrides: Partial<V4MigrationSdkUsageSeries>,+): V4MigrationSdkUsageSeries => ({+ sdkName: "python",+ sdkVersion: "4.7.1",+ canonicalSdkName: "python",+ publicKey: "pk-lf-1234567890abcdef",+ count: 10,+ eventsCount: 10,+ firstSeen: "2026-07-20T10:00:00Z",+ lastSeen: "2026-07-23T10:00:00Z",+ hasDelayedOtelEvents: null,+ attributionStatus: "attributed",+ v4MigrationStatus: "compatible",+ upgradeCompleted: false,+ ...overrides,+});++const outdatedSdkSeries = () =>+ makeSdkUsageSeries({+ sdkVersion: "2.60.3",+ v4MigrationStatus: "upgrade_required",+ });++const delayedOtelSeries = () =>+ makeSdkUsageSeries({+ sdkName: "openlit",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: true,+ publicKey: "pk-lf-otel-1234567890",+ });++const customIngestionSeries = () =>+ makeSdkUsageSeries({+ sdkName: "unknown",+ sdkVersion: "unknown",+ canonicalSdkName: null,+ attributionStatus: "missing_name_and_version",+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: null,+ publicKey: "pk-lf-custom-123456789",+ });++const mocks = vi.hoisted(() => ({+ sdk: {+ status: "latest",+ sdkUsageSeries: [],+ upgradeRequiredCount: 0,+ delayedOtelIngestionCount: 0,+ } as V4MigrationSdkState,+ v4UpgradeUiEnabled: true,+ openMigrationPanel: vi.fn(),+}));++vi.mock("@/src/features/v4-migration/useV4UpgradeUiEnabled", () => ({+ useV4UpgradeUiEnabled: () => mocks.v4UpgradeUiEnabled,+}));++vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({+ usePostHogClientCapture: () => vi.fn(),+}));++vi.mock("@/src/features/projects/hooks", () => ({+ useQueryProject: () => ({+ project: { id: "project-1", name: "Project One" },+ organization: { id: "org-1" },+ }),+}));++vi.mock("@/src/features/v4-migration/hooks/useOpenV4MigrationPanel", () => ({+ useOpenV4MigrationPanel: () => mocks.openMigrationPanel,+}));++vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({+ useProjectV4SdkData: () => mocks.sdk,+ useProjectV4EvalData: () => ({ status: "loaded", count: 0 }),+}));++vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({+ useCanUseInAppAgent: () => false,+ useInAppAiAgent: () => ({ setOpen: vi.fn(), submit: vi.fn() }),+}));++vi.mock("@/src/features/v4-migration/useV4UpgradeAssistantSupport", () => ({+ useEvalUpgradeAssistantPlan: () => ({+ canUseAssistant: false,+ mode: "outside",+ showAssistantButton: false,+ assistantPrompt: "",+ }),+}));++const setSdk = (+ status: V4MigrationSdkState["status"],+ series: V4MigrationSdkUsageSeries[],+) => {+ mocks.sdk = {+ status,+ sdkUsageSeries: series,+ upgradeRequiredCount: series.filter(+ (usage) =>+ usage.v4MigrationStatus === "upgrade_required" &&+ !usage.upgradeCompleted,+ ).length,+ delayedOtelIngestionCount: series.filter(+ (usage) =>+ usage.canonicalSdkName === null && usage.hasDelayedOtelEvents === true,+ ).length,+ };+};++describe("V4MigrationDelayBadge", () => {+ beforeEach(() => {+ vi.clearAllMocks();+ mocks.v4UpgradeUiEnabled = true;+ setSdk("latest", [makeSdkUsageSeries({})]);+ });++ it("stays hidden when every ingestion path is clean", () => {+ render(<V4MigrationDelayBadge />);+ expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();+ });++ it("shows SDK copy for outdated SDK traffic", () => {+ setSdk("legacy", [outdatedSdkSeries()]);+ render(<V4MigrationDelayBadge />);+ expect(screen.getAllByText("New data in ~15 min").length).toBeGreaterThan(+ 0,+ );+ expect(+ screen.getAllByText(/Update SDK for real-time data/).length,+ ).toBeGreaterThan(0);+ });++ it("shows OTel copy for delayed OTel exporters", () => {+ setSdk("otel_header_required", [delayedOtelSeries()]);+ render(<V4MigrationDelayBadge />);+ expect(+ screen.getAllByText(/Update OTel instrumentation for real-time data/)+ .length,+ ).toBeGreaterThan(0);+ });++ it("shows instrumentation copy for headerless ingestion traffic", () => {+ setSdk("unknown", [customIngestionSeries()]);+ render(<V4MigrationDelayBadge />);+ expect(+ screen.getAllByText(/Upgrade instrumentation for real-time data/).length,+ ).toBeGreaterThan(0);+ });++ it("shows the generic copy when several delayed paths fire", () => {+ setSdk("legacy", [outdatedSdkSeries(), delayedOtelSeries()]);+ render(<V4MigrationDelayBadge />);+ expect(+ screen.getAllByText(/Upgrade for real-time data/).length,+ ).toBeGreaterThan(0);+ expect(screen.queryAllByText(/Update SDK for real-time data/)).toHaveLength(+ 0,+ );+ });++ it("stays hidden when an SDK version is merely unrecognized", () => {+ // An unparsable version puts the series in the panel's Update SDK+ // section for review, but is no proof of delayed ingestion.+ setSdk("unknown", [+ makeSdkUsageSeries({+ sdkVersion: "not-semver",+ v4MigrationStatus: "unknown",+ }),+ ]);+ render(<V4MigrationDelayBadge />);+ expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();+ });++ it("stays hidden while the check is still running", () => {+ setSdk("checking", []);+ render(<V4MigrationDelayBadge />);+ expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();+ });++ it("stays hidden without the v4 upgrade UI flag", () => {+ mocks.v4UpgradeUiEnabled = false;+ setSdk("legacy", [outdatedSdkSeries()]);+ render(<V4MigrationDelayBadge />);+ expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();+ });+});diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.tsxindex 8ef7bbe2ee..019920a6aa 100644--- a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.tsx@@ -11,6 +11,10 @@ import {import { useEvalUpgradeAssistantPlan } from "@/src/features/v4-migration/useV4UpgradeAssistantSupport";import { useCanUseInAppAgent } from "@/src/features/in-app-agent/components/InAppAiAgentProvider";import { V4MigrationBadgeContent } from "@/src/features/v4-migration/V4MigrationBadgeContent";+import {+ getCustomInstrumentationSectionState,+ getOtelSectionState,+} from "@/src/features/v4-migration/sdkVersionStatus";import { EvaluatorMigrationDialog } from "@/src/features/v4-migration/EvaluatorMigrationDialog";import {buildDeprecatedEvaluatorsUrl,@@ -28,20 +32,48 @@ export function V4MigrationDelayBadge() {enabled: v4UpgradeUiEnabled && Boolean(project),});- if (!v4UpgradeUiEnabled || !project || sdk.status !== "legacy") {+ // Every delayed ingestion path shows the pill, matching the migration+ // panel's per-path offender detectors (LFE-14861) — not just outdated SDKs.+ // Unlike the panel's Update SDK section, the pill states a factual delay,+ // so the SDK path needs a confirmed-outdated series: an unparsable version+ // is grounds for review, not proof the data is delayed.+ const isTransient = sdk.status === "checking" || sdk.status === "error";+ const sdkActionable = !isTransient && sdk.upgradeRequiredCount > 0;+ const otelActionable =+ !isTransient && getOtelSectionState(sdk).delayedCount > 0;+ const customActionable =+ !isTransient && getCustomInstrumentationSectionState(sdk).series.length > 0;+ const actionablePaths = [+ sdkActionable,+ otelActionable,+ customActionable,+ ].filter(Boolean).length;++ if (!v4UpgradeUiEnabled || !project || actionablePaths === 0) {return null;}const handleClick = () => {capture("v4_migration:delay_badge_clicked");- openMigrationPanel({ id: project.id, name: project.name });+ openMigrationPanel({ id: project.id, name: project.name }, "delay_badge");};+ // The hover's action clause echoes the panel section the click opens;+ // multiple delayed paths get the generic clause.+ const description =+ actionablePaths > 1+ ? "Your setup is outdated. Upgrade for real-time data"+ : sdkActionable+ ? "Your setup is outdated. Update SDK for real-time data"+ : otelActionable+ ? "Your setup is outdated. Update OTel instrumentation for real-time data"+ : "Your setup is outdated. Upgrade instrumentation for real-time data";+return (<V4MigrationBadgeContentonClick={handleClick}title="New data in ~15 min"- description="Update your SDK for real-time data"+ description={description}/>);}diff --git a/web/src/features/v4-migration/V4MigrationModal.tsx b/web/src/features/v4-migration/V4MigrationModal.tsxindex bd069cda09..fbf8f32252 100644--- a/web/src/features/v4-migration/V4MigrationModal.tsx+++ b/web/src/features/v4-migration/V4MigrationModal.tsx@@ -5,7 +5,6 @@ import {DialogContent,DialogTitle,} from "@/src/components/ui/dialog";-import { Separator } from "@/src/components/ui/separator";import {V4MigrationHeaderContent,V4MigrationDetailsContent,@@ -62,12 +61,11 @@ function V4MigrationModalContent({<V4MigrationHeaderContentprojectName={project.name}projectId={project.id}- onNavigate={() => setOpen(false)}// Clear the dialog's floating fallback close button (top-right).titleRowClassName="pr-6"/>- <Separator className="my-6" />- <div className="flex flex-col gap-6">+ {/* Details opens with its own separator above Action items. */}+ <div className="mt-6 flex flex-col gap-6"><V4MigrationDetailsContentonNavigate={() => setOpen(false)}projectId={project.id}diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsxindex d5e27aed12..4c9cef27cd 100644--- a/web/src/features/v4-migration/V4MigrationNavItem.tsx+++ b/web/src/features/v4-migration/V4MigrationNavItem.tsx@@ -47,7 +47,10 @@ export function V4MigrationNavItem() {}setTimeout(() => {// push to next tick to avoid flickering when hiding sidebar on mobile- openMigrationPanel({ id: project.id, name: project.name });+ openMigrationPanel(+ { id: project.id, name: project.name },+ "sidebar_card",+ );}, 1);};diff --git a/web/src/features/v4-migration/V4MigrationPanel.tsx b/web/src/features/v4-migration/V4MigrationPanel.tsxindex 1c33744b86..23175615b2 100644--- a/web/src/features/v4-migration/V4MigrationPanel.tsx+++ b/web/src/features/v4-migration/V4MigrationPanel.tsx@@ -1,7 +1,6 @@/* eslint-disable @repo/no-style-props */import { X } from "lucide-react";import { Button } from "@/src/components/ui/button";-import { Separator } from "@/src/components/ui/separator";import { useV4MigrationPanel } from "@/src/features/v4-migration/V4MigrationPanelProvider";import { useQueryProject } from "@/src/features/projects/hooks";import {@@ -36,34 +35,34 @@ export const V4MigrationPanel = ({className,])}>- <div className="bg-background">- <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 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">- <div className="bg-background sticky top-0 z-[1] px-4 pt-4">+ <div className="px-4 pt-4"><V4MigrationHeaderContentkey={project?.id}projectName={project?.name}projectId={project?.id}- onNavigate={() => setOpen(false)}/>- <Separator className="mt-6" /></div><div className="flex flex-col gap-6 px-4 pt-6 pb-16"><V4MigrationDetailsContent+ // Keyed like the header: a project switch while the panel stays+ // open remounts the content, so per-open analytics (the+ // panel_checks_loaded fire-once ref) reset for the new project.+ key={project?.id}onNavigate={() => setOpen(false)}projectId={project?.id}/>diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsxindex eded15a5ac..5e02443d15 100644--- a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx@@ -9,11 +9,16 @@ import {} from "./V4MigrationPanelProvider";const flagState = vi.hoisted(() => ({ enabled: false }));+const captureMock = vi.hoisted(() => vi.fn());vi.mock("./useV4UpgradeUiEnabled", () => ({useV4UpgradeUiEnabled: () => flagState.enabled,}));+vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({+ usePostHogClientCapture: () => captureMock,+}));+const wrapper = ({ children }: { children: React.ReactNode }) => (<V4MigrationPanelProvider>{children}</V4MigrationPanelProvider>);@@ -21,18 +26,23 @@ const wrapper = ({ children }: { children: React.ReactNode }) => (describe("V4MigrationPanelProvider", () => {beforeEach(() => {flagState.enabled = false;+ captureMock.mockClear();});it("refuses to open when the user flag is disabled", () => {const { result } = renderHook(() => useV4MigrationPanel(), { wrapper });act(() =>- result.current.openForProject({ id: "project-id", name: "Project" }),+ result.current.openForProject(+ { id: "project-id", name: "Project" },+ "delay_badge",+ ),);act(() => result.current.setOpen(true));expect(result.current.open).toBe(false);expect(result.current.targetProject).toBeNull();+ expect(captureMock).not.toHaveBeenCalled();});it("opens for a project when the user flag is enabled", () => {@@ -40,7 +50,10 @@ describe("V4MigrationPanelProvider", () => {const { result } = renderHook(() => useV4MigrationPanel(), { wrapper });act(() =>- result.current.openForProject({ id: "project-id", name: "Project" }),+ result.current.openForProject(+ { id: "project-id", name: "Project" },+ "delay_badge",+ ),);expect(result.current.open).toBe(true);@@ -48,5 +61,58 @@ describe("V4MigrationPanelProvider", () => {id: "project-id",name: "Project",});+ expect(captureMock).toHaveBeenCalledExactlyOnceWith(+ "v4_migration:panel_opened",+ { source: "delay_badge" },+ );+ });++ it("reports one panel_opened per closed-to-open transition", () => {+ flagState.enabled = true;+ const { result } = renderHook(() => useV4MigrationPanel(), { wrapper });++ act(() =>+ result.current.openForProject(+ { id: "project-id", name: "Project" },+ "delay_badge",+ ),+ );+ // Redundant open of the SAME project from another surface: no new entry.+ act(() =>+ result.current.openForProject(+ { id: "project-id", name: "Project" },+ "sidebar_card",+ ),+ );++ const openedCalls = captureMock.mock.calls.filter(+ ([name]) => name === "v4_migration:panel_opened",+ );+ expect(openedCalls).toHaveLength(1);++ // Retargeting the open panel to a DIFFERENT project is a new entry.+ act(() =>+ result.current.openForProject(+ { id: "project-2", name: "Other project" },+ "status_page_row",+ ),+ );+ expect(+ captureMock.mock.calls.filter(+ ([name]) => name === "v4_migration:panel_opened",+ ),+ ).toHaveLength(2);++ // Close and reopen: a fresh funnel entry with the new source.+ act(() => result.current.setOpen(false));+ act(() =>+ result.current.openForProject(+ { id: "project-id", name: "Project" },+ "status_page_row",+ ),+ );+ expect(captureMock).toHaveBeenCalledWith("v4_migration:panel_opened", {+ source: "status_page_row",+ });});});diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.tsxindex 0b6c8b21a4..44397ce702 100644--- a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.tsx@@ -4,16 +4,27 @@ import {useState,type PropsWithChildren,} from "react";+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";export type V4MigrationTargetProject = { id: string; name: string };+/** Which surface opened the panel; the funnel's entry dimension. */+export type V4MigrationPanelOpenSource =+ | "delay_badge"+ | "status_page_row"+ | "sidebar_card"+ | "project_chip";+type V4MigrationPanelContextType = {open: boolean;setOpen: (v: boolean) => void;/** Project the panel content is about; set by whichever surface opened it. */targetProject: V4MigrationTargetProject | null;- openForProject: (project: V4MigrationTargetProject) => void;+ openForProject: (+ project: V4MigrationTargetProject,+ source: V4MigrationPanelOpenSource,+ ) => void;};const V4MigrationPanelContext =@@ -29,6 +40,7 @@ export function V4MigrationPanelProvider({defaultOpen = false,}: V4MigrationPanelProviderProps) {const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const capture = usePostHogClientCapture();const [requestedOpen, setRequestedOpen] = useState(defaultOpen);const [targetProject, setTargetProject] =useState<V4MigrationTargetProject | null>(null);@@ -37,8 +49,17 @@ export function V4MigrationPanelProvider({const setOpen = (nextOpen: boolean) => {setRequestedOpen(v4UpgradeUiEnabled && nextOpen);};- const openForProject = (project: V4MigrationTargetProject) => {+ // Every open path goes through here (setOpen callers only ever close), so+ // this is the single funnel-entry event. A redundant open of the same+ // project does not double-count, but retargeting the open panel to a+ // different project is a new funnel entry.+ const openForProject = (+ project: V4MigrationTargetProject,+ source: V4MigrationPanelOpenSource,+ ) => {if (!v4UpgradeUiEnabled) return;+ if (!open || project.id !== targetProject?.id)+ capture("v4_migration:panel_opened", { source });setTargetProject(project);setRequestedOpen(true);};diff --git a/web/src/features/v4-migration/V4MigrationProjectChip.tsx b/web/src/features/v4-migration/V4MigrationProjectChip.tsxindex c895365174..b5bf4279a3 100644--- a/web/src/features/v4-migration/V4MigrationProjectChip.tsx+++ b/web/src/features/v4-migration/V4MigrationProjectChip.tsx@@ -30,7 +30,7 @@ export function V4MigrationProjectChip({const handleClick = () => {capture("v4_migration:project_chip_clicked");- openMigrationPanel(project);+ openMigrationPanel(project, "project_chip");};return (diff --git a/web/src/features/v4-migration/V4MigrationSections.stories.tsx b/web/src/features/v4-migration/V4MigrationSections.stories.tsxnew file mode 100644index 0000000000..e00eb2a9f1--- /dev/null+++ b/web/src/features/v4-migration/V4MigrationSections.stories.tsx@@ -0,0 +1,464 @@+import { fn } from "storybook/test";++import preview from "../../../.storybook/preview";+import {+ V4MigrationApisSection,+ V4MigrationCustomInstrumentationSection,+ V4MigrationEvalsSection,+ V4MigrationExperimentsSection,+ V4MigrationIntegrationsSection,+ V4MigrationOtelSection,+ V4MigrationSdkSection,+} from "./V4MigrationContent";+import {+ type V4MigrationSdkState,+ type V4MigrationSdkUsageSeries,+} from "./sdkVersionStatus";++const HOUR_MS = 60 * 60 * 1000;++const makeSeries = (+ overrides: Partial<V4MigrationSdkUsageSeries>,+): V4MigrationSdkUsageSeries => ({+ sdkName: "python",+ sdkVersion: "4.7.1",+ canonicalSdkName: "python",+ publicKey: "pk-lf-1234567890abcdef",+ count: 10,+ eventsCount: 10,+ firstSeen: new Date(Date.now() - 72 * HOUR_MS).toISOString(),+ lastSeen: new Date(Date.now() - 19 * HOUR_MS).toISOString(),+ hasDelayedOtelEvents: null,+ attributionStatus: "attributed",+ v4MigrationStatus: "compatible",+ upgradeCompleted: false,+ ...overrides,+});++const makeSdkState = (+ overrides: Partial<V4MigrationSdkState>,+): V4MigrationSdkState => ({+ status: "latest",+ sdkUsageSeries: [],+ upgradeRequiredCount: 0,+ delayedOtelIngestionCount: 0,+ ...overrides,+});++const outdatedPython = makeSeries({+ sdkVersion: "2.60.3",+ v4MigrationStatus: "upgrade_required",+});+// Scores-only offender: detection sees its score ingestions but the events+// table has nothing for it, so the key renders as plain text, not a link.+const scoresOnlyPython = makeSeries({+ sdkVersion: "2.44.0",+ v4MigrationStatus: "upgrade_required",+ publicKey: "pk-lf-scores-only-0001",+ eventsCount: 0,+});+const outdatedJavascript = makeSeries({+ sdkName: "javascript",+ sdkVersion: "3.38.5",+ canonicalSdkName: "javascript",+ v4MigrationStatus: "upgrade_required",+ publicKey: "pk-lf-fedcba0987654321",+});+const upgradedPython = makeSeries({+ v4MigrationStatus: "upgrade_required",+ upgradeCompleted: true,+ publicKey: "pk-lf-0000111122223333",+ lastSeen: new Date(Date.now() - 0.25 * HOUR_MS).toISOString(),+});+const unrecognizedSdk = makeSeries({+ sdkName: "my-custom-wrapper",+ sdkVersion: "0.4.0",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ publicKey: "pk-lf-4444555566667777",+});+const delayedOtelExporter = makeSeries({+ sdkName: "openlit",+ sdkVersion: "1.35.4",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: true,+ publicKey: "pk-lf-aaaa000011112222",+ lastSeen: new Date(Date.now() - 0.25 * HOUR_MS).toISOString(),+});+const unnamedDelayedOtelExporter = makeSeries({+ sdkName: "unknown",+ sdkVersion: "unknown",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: true,+ publicKey: "pk-lf-8888999900001111",+});+const realtimeOtelExporter = makeSeries({+ sdkName: "otelcol",+ sdkVersion: "0.98.0",+ canonicalSdkName: null,+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: false,+ publicKey: "pk-lf-bbbb333344445555",+ lastSeen: new Date(Date.now() - 70 * HOUR_MS).toISOString(),+});+// Ingestion-API traffic without a Langfuse SDK header: custom instrumentation+// or an SDK too old to send attribution headers.+const customInstrumentation = makeSeries({+ sdkName: "unknown",+ sdkVersion: "unknown",+ canonicalSdkName: null,+ attributionStatus: "missing_name_and_version",+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: null,+ publicKey: "pk-lf-cccc666677778888",+});++const sdkOutdatedState = makeSdkState({+ status: "legacy",+ sdkUsageSeries: [+ outdatedPython,+ scoresOnlyPython,+ outdatedJavascript,+ upgradedPython,+ ],+ upgradeRequiredCount: 3,+});++// An unrecognized SDK name is custom instrumentation, not an SDK state.+const unrecognizedSdkState = makeSdkState({+ status: "unknown",+ sdkUsageSeries: [makeSeries({}), unrecognizedSdk],+});++const otelHeaderRequiredState = makeSdkState({+ status: "otel_header_required",+ sdkUsageSeries: [+ delayedOtelExporter,+ unnamedDelayedOtelExporter,+ realtimeOtelExporter,+ ],+ delayedOtelIngestionCount: 2,+});++const customInstrumentationState = makeSdkState({+ status: "unknown",+ sdkUsageSeries: [customInstrumentation],+});++const combinedState = makeSdkState({+ status: "legacy",+ sdkUsageSeries: [+ outdatedPython,+ upgradedPython,+ delayedOtelExporter,+ realtimeOtelExporter,+ customInstrumentation,+ ],+ upgradeRequiredCount: 1,+ delayedOtelIngestionCount: 1,+});++const apiUsage = [+ {+ endpoint: "GET /api/public/traces",+ count: 1284,+ lastSeen: new Date(Date.now() - 2 * HOUR_MS).toISOString(),+ },+ {+ endpoint: "POST /api/public/scores",+ count: 42,+ lastSeen: new Date(Date.now() - 26 * HOUR_MS).toISOString(),+ },+];++const integrations = ["PostHog", "Mixpanel", "Blob Storage"];++const meta = preview.meta({+ component: V4MigrationSdkSection,+});++export const SdkOutdated = meta.story({+ args: { sdk: sdkOutdatedState, defaultOpen: true },+});++export const UnrecognizedSdkName = meta.story({+ render: () => (+ <V4MigrationCustomInstrumentationSection+ sdk={unrecognizedSdkState}+ defaultOpen+ />+ ),+});++export const SdkChecking = meta.story({+ args: { sdk: makeSdkState({ status: "checking" }), defaultOpen: true },+});++export const SdkCheckFailed = meta.story({+ args: { sdk: makeSdkState({ status: "error" }), defaultOpen: true },+});++export const OtelHeaderRequired = meta.story({+ render: () => (+ <V4MigrationOtelSection sdk={otelHeaderRequiredState} defaultOpen />+ ),+});++export const UpgradeInstrumentation = meta.story({+ render: () => (+ <V4MigrationCustomInstrumentationSection+ sdk={customInstrumentationState}+ defaultOpen+ />+ ),+});++export const EvalsDeprecated = meta.story({+ render: () => (+ <V4MigrationEvalsSection+ state={{ status: "loaded", count: 3 }}+ assistant={{ onMigrate: fn() }}+ evalsUrl="/project/demo/evals"+ defaultOpen+ />+ ),+});++export const ExperimentsUpdateRequired = meta.story({+ render: () => (+ <V4MigrationExperimentsSection+ state={{ status: "loaded", result: "required" }}+ upgradePath="api"+ defaultOpen+ />+ ),+});++export const ApisDeprecated = meta.story({+ render: () => (+ <V4MigrationApisSection+ state={{ status: "loaded", count: apiUsage.length }}+ usage={apiUsage}+ defaultOpen+ />+ ),+});++export const IntegrationsDeprecated = meta.story({+ render: () => (+ <V4MigrationIntegrationsSection+ state={{ status: "loaded", count: integrations.length }}+ integrations={integrations}+ integrationsUrl="/project/demo/settings/integrations"+ defaultOpen+ />+ ),+});++// All sections hide themselves when nothing needs action; the empty output+// here is the intended state, not a broken story.+export const HiddenWhenClean = meta.story({+ render: () => {+ const sdk = makeSdkState({+ sdkUsageSeries: [makeSeries({}), realtimeOtelExporter],+ });+ return (+ <div>+ <V4MigrationSdkSection sdk={sdk} />+ <V4MigrationOtelSection sdk={sdk} />+ <V4MigrationCustomInstrumentationSection sdk={sdk} />+ </div>+ );+ },+});++export const VariantMatrix = meta.story({+ render: () => (+ <div className="flex max-w-xl flex-col gap-8">+ {(+ [+ [+ "1. SDK outdated (mixed rows)",+ <V4MigrationSdkSection+ key="1"+ sdk={sdkOutdatedState}+ defaultOpen+ />,+ ],+ [+ "2. Unrecognized SDK name (renders as custom instrumentation)",+ <V4MigrationCustomInstrumentationSection+ key="2"+ sdk={unrecognizedSdkState}+ defaultOpen+ />,+ ],+ [+ "3. SDK checking",+ <V4MigrationSdkSection+ key="3"+ sdk={makeSdkState({ status: "checking" })}+ defaultOpen+ />,+ ],+ [+ "4. SDK check failed",+ <V4MigrationSdkSection+ key="4"+ sdk={makeSdkState({ status: "error" })}+ defaultOpen+ />,+ ],+ [+ "5. OTel header required (delayed, unnamed, real-time exporters)",+ <V4MigrationOtelSection+ key="5"+ sdk={otelHeaderRequiredState}+ defaultOpen+ />,+ ],+ [+ "6. Upgrade Instrumentation (ingestion API without SDK header)",+ <V4MigrationCustomInstrumentationSection+ key="6"+ sdk={customInstrumentationState}+ defaultOpen+ />,+ ],+ [+ "7. Evals deprecated (assistant can migrate)",+ <V4MigrationEvalsSection+ key="7"+ state={{ status: "loaded", count: 3 }}+ assistant={{ onMigrate: fn() }}+ evalsUrl="/project/demo/evals"+ defaultOpen+ />,+ ],+ [+ "8. Evals deprecated, single (assistant plans the order, no auto-migrate)",+ <V4MigrationEvalsSection+ key="8"+ state={{ status: "loaded", count: 1 }}+ assistant={{ onMigrate: fn() }}+ evalsUrl="/project/demo/evals"+ defaultOpen+ />,+ ],+ [+ "9. Experiments update required (deprecated API call)",+ <V4MigrationExperimentsSection+ key="9"+ state={{ status: "loaded", result: "required" }}+ upgradePath="api"+ defaultOpen+ />,+ ],+ [+ "10. Experiments update required (outdated SDK)",+ <V4MigrationExperimentsSection+ key="10"+ state={{ status: "loaded", result: "required" }}+ upgradePath="sdk"+ defaultOpen+ />,+ ],+ [+ "11. Experiments needs review (inconclusive SDK usage)",+ <V4MigrationExperimentsSection+ key="11"+ state={{ status: "loaded", result: "sdk_usage_inconclusive" }}+ upgradePath="sdk"+ defaultOpen+ />,+ ],+ [+ "12. Deprecated APIs called",+ <V4MigrationApisSection+ key="12"+ state={{ status: "loaded", count: apiUsage.length }}+ usage={apiUsage}+ defaultOpen+ />,+ ],+ [+ "13. Deprecated integrations exporting",+ <V4MigrationIntegrationsSection+ key="13"+ state={{ status: "loaded", count: integrations.length }}+ integrations={integrations}+ integrationsUrl="/project/demo/settings/integrations"+ defaultOpen+ />,+ ],+ [+ "14. Checker still loading (evals shown; same chip on all checkers)",+ <V4MigrationEvalsSection+ key="14"+ state={{ status: "loading", count: 0 }}+ assistant={null}+ defaultOpen+ />,+ ],+ [+ "15. Checker failed (evals shown; same chip on all checkers)",+ <V4MigrationEvalsSection+ key="15"+ state={{ status: "error", count: 0 }}+ assistant={null}+ defaultOpen+ />,+ ],+ [+ "16. Clean sections collapse into one summary line",+ <p key="16" className="text-muted-foreground py-1.5 text-sm">+ Evals, experiments, APIs and integrations are up to date.+ </p>,+ ],+ [+ "17. Everything at once",+ <div key="17">+ <V4MigrationSdkSection sdk={combinedState} defaultOpen />+ <V4MigrationOtelSection sdk={combinedState} defaultOpen />+ <V4MigrationCustomInstrumentationSection+ sdk={combinedState}+ defaultOpen+ />+ <V4MigrationEvalsSection+ state={{ status: "loaded", count: 2 }}+ assistant={{ onMigrate: fn() }}+ evalsUrl="/project/demo/evals"+ defaultOpen+ />+ <V4MigrationExperimentsSection+ state={{ status: "loaded", result: "required" }}+ upgradePath="api"+ defaultOpen+ />+ <V4MigrationApisSection+ state={{ status: "loaded", count: apiUsage.length }}+ usage={apiUsage}+ defaultOpen+ />+ <V4MigrationIntegrationsSection+ state={{ status: "loaded", count: integrations.length }}+ integrations={integrations}+ integrationsUrl="/project/demo/settings/integrations"+ defaultOpen+ />+ </div>,+ ],+ ] as const+ ).map(([label, node]) => (+ <div key={label} className="flex flex-col gap-2">+ <p className="text-muted-foreground text-xs tracking-wide uppercase">+ {label}+ </p>+ {node}+ </div>+ ))}+ </div>+ ),+});diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsxindex c002a912fa..ad1dc9dcac 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx@@ -130,7 +130,7 @@ describe("V4MigrationStatusPage", () => {render(<V4MigrationStatusPage />);expect(screen.getByText("Migrated")).toBeInTheDocument();- expect(screen.getByText("of 1 projects migrated")).toBeInTheDocument();+ expect(screen.getByText("of 1 projects need action")).toBeInTheDocument();});it("links projects to traces and opens the migration panel", () => {@@ -144,10 +144,10 @@ describe("V4MigrationStatusPage", () => {});fireEvent.click(projectLink);- expect(mocks.openForProject).toHaveBeenCalledWith({- id: "project-1",- name: "Test project",- });+ expect(mocks.openForProject).toHaveBeenCalledWith(+ { id: "project-1", name: "Test project" },+ "status_page_row",+ );expect(mocks.capture).toHaveBeenCalledWith("v4_migration:status_row_clicked",);@@ -163,10 +163,10 @@ describe("V4MigrationStatusPage", () => {fireEvent.click(projectRow!);- expect(mocks.openForProject).toHaveBeenCalledWith({- id: "project-1",- name: "Test project",- });+ expect(mocks.openForProject).toHaveBeenCalledWith(+ { id: "project-1", name: "Test project" },+ "status_page_row",+ );expect(mocks.routerPush).toHaveBeenCalledWith("/project/project-1/traces");});diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsxindex fb3c1c1f5e..c58b15cc1d 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx@@ -172,7 +172,7 @@ function OrgStatusSection({const openProjectMigration = (row: { id: string; name: string }) => {capture("v4_migration:status_row_clicked");- openMigrationPanel({ id: row.id, name: row.name });+ openMigrationPanel({ id: row.id, name: row.name }, "status_page_row");};const handleRowClick = (row: { id: string; name: string }) => {@@ -541,7 +541,14 @@ function V4MigrationStatusPageContent() {return status ? [getProjectMigrationReadiness(status)] : [];}),);- const readyProjects = readiness.filter((state) => state === "ready").length;+ 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;const isChecking =session.status === "loading" ||readiness.some((state) => state === "checking");@@ -570,10 +577,13 @@ function V4MigrationStatusPageContent() {) : (<><span className="text-2xl leading-none font-bold tracking-tight">- {readyProjects}+ {actionNeededProjects}</span><span className="text-muted-foreground text-sm">- of {totalProjects} projects migrated+ of {totalProjects} projects{" "}+ {actionNeededProjects === 1 ? "needs" : "need"} action+ {unavailableProjects > 0 &&+ ` · ${unavailableProjects} could not be checked`}</span></>)}diff --git a/web/src/features/v4-migration/hooks/useOpenV4MigrationPanel.ts b/web/src/features/v4-migration/hooks/useOpenV4MigrationPanel.tsindex e701d82ab9..b8fb7c7be4 100644--- a/web/src/features/v4-migration/hooks/useOpenV4MigrationPanel.ts+++ b/web/src/features/v4-migration/hooks/useOpenV4MigrationPanel.ts@@ -2,6 +2,7 @@ import { useInAppAiAgent } from "@/src/features/in-app-agent/components/InAppAiAimport { useSupportDrawer } from "@/src/features/support-chat/SupportDrawerProvider";import {useV4MigrationPanel,+ type V4MigrationPanelOpenSource,type V4MigrationTargetProject,} from "@/src/features/v4-migration/V4MigrationPanelProvider";@@ -10,9 +11,12 @@ export function useOpenV4MigrationPanel() {const { setOpen: setSupportDrawerOpen } = useSupportDrawer();const { setOpen: setAiAgentOpen } = useInAppAiAgent();- return (project: V4MigrationTargetProject) => {+ return (+ project: V4MigrationTargetProject,+ source: V4MigrationPanelOpenSource,+ ) => {setAiAgentOpen(false);setSupportDrawerOpen(false);- openForProject(project);+ openForProject(project, source);};}diff --git a/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts b/web/src/features/v4-migration/sdkVersionStatus.clienttest.tsindex 956a52d8a9..1dfaabd50b 100644--- a/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts+++ b/web/src/features/v4-migration/sdkVersionStatus.clienttest.ts@@ -13,6 +13,7 @@ const sdkSeries = (canonicalSdkName: "python" as const,publicKey: "pk-lf-python",count: 1,+ eventsCount: 1,firstSeen: "2026-07-23T09:00:00Z",lastSeen: "2026-07-23T10:00:00Z",hasDelayedOtelEvents: false,@@ -112,6 +113,23 @@ describe("v4 migration SDK status", () => {});});+ it("keeps custom-instrumentation traffic action-needed despite a compatible SDK", () => {+ expect(+ getLoadedSdkState(+ sdkSeries(),+ sdkSeries({+ sdkName: "unknown",+ sdkVersion: "unknown",+ canonicalSdkName: null,+ publicKey: "pk-lf-custom",+ attributionStatus: "missing_name_and_version",+ v4MigrationStatus: "unknown",+ hasDelayedOtelEvents: null,+ }),+ ),+ ).toMatchObject({ status: "unknown" });+ });+it("keeps a recognized SDK with an invalid version unknown", () => {expect(getLoadedSdkState(diff --git a/web/src/features/v4-migration/sdkVersionStatus.ts b/web/src/features/v4-migration/sdkVersionStatus.tsindex 82dd603a3c..568f4e6b7e 100644--- a/web/src/features/v4-migration/sdkVersionStatus.ts+++ b/web/src/features/v4-migration/sdkVersionStatus.ts@@ -32,6 +32,15 @@ const requiresOtelIngestionHeader = (): boolean =>series.hasDelayedOtelEvents === true && series.canonicalSdkName === null;+// Ingestion-API series without a recognized Langfuse SDK: custom+// instrumentation against POST /api/public/ingestion, an unrecognized SDK+// name, or an SDK too old to send attribution headers. (hasDelayedOtelEvents+// is null for non-OTel ingestion.)+export const isCustomInstrumentationSeries = (+ series: V4MigrationSdkUsageSeries,+): boolean =>+ series.hasDelayedOtelEvents === null && series.canonicalSdkName === null;+const sortSdkUsageSeries = (rows: V4MigrationSdkUsageSeries[],): V4MigrationSdkUsageSeries[] =>@@ -85,6 +94,12 @@ export const getV4MigrationSdkState = (params: {(series) =>series.canonicalSdkName === null && series.hasDelayedOtelEvents === false,);+ // Custom-instrumentation traffic is always an action item in the panel, so+ // the combined status must not report the project as fully migrated while+ // the Upgrade Instrumentation section is telling the user to act.+ const hasCustomInstrumentation = sdkUsageSeries.some(+ isCustomInstrumentationSeries,+ );return {status:@@ -94,7 +109,7 @@ export const getV4MigrationSdkState = (params: {? "legacy": delayedOtelIngestionCount > 0? "otel_header_required"- : hasUnknownRecognizedSdk+ : hasUnknownRecognizedSdk || hasCustomInstrumentation? "unknown": hasCompatibleSdk? "latest"@@ -107,6 +122,91 @@ export const getV4MigrationSdkState = (params: {};};+// A series is an OTel exporter when it has no recognized Langfuse SDK name but+// arrived through OTel ingestion (hasDelayedOtelEvents is null for non-OTel+// series). Recognized SDKs that ship via OTLP manage their own headers, so+// they stay in the SDK bucket.+export const isOtelExporterSeries = (+ series: V4MigrationSdkUsageSeries,+): boolean =>+ series.canonicalSdkName === null && series.hasDelayedOtelEvents !== null;++// Both section states below implement the offender rule: a section renders+// only while it contains at least one series needing action, but a rendered+// section lists every series detected on its ingestion path.++export const isActionableSdkSeries = (+ series: V4MigrationSdkUsageSeries,+): boolean =>+ (series.v4MigrationStatus === "upgrade_required" &&+ !series.upgradeCompleted) ||+ // A recognized SDK with an unparsable version still needs the user's+ // attention; without it the section would hide while the project-level+ // status keeps reporting action needed.+ series.v4MigrationStatus === "unknown";++export type V4MigrationSdkSectionState = {+ /** "latest" and "no_data" mean no offenders; 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. */+ 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;+};++export const getSdkSectionState = (+ sdk: V4MigrationSdkState,+): V4MigrationSdkSectionState => {+ const series = sdk.sdkUsageSeries.filter(+ (usage) => usage.canonicalSdkName !== null,+ );+ const actionableCount = series.filter(isActionableSdkSeries).length;++ return {+ status:+ sdk.status === "checking" || sdk.status === "error"+ ? sdk.status+ : series.length === 0+ ? "no_data"+ : actionableCount > 0+ ? "legacy"+ : "latest",+ series,+ actionableCount,+ };+};++export type V4MigrationCustomInstrumentationSectionState = {+ /** Every series here is an offender; the section hides when empty. */+ series: V4MigrationSdkUsageSeries[];+};++export const getCustomInstrumentationSectionState = (+ sdk: V4MigrationSdkState,+): V4MigrationCustomInstrumentationSectionState => ({+ series: sdk.sdkUsageSeries.filter(isCustomInstrumentationSeries),+});++export type V4MigrationOtelSectionState = {+ /** All detected OTel exporter series, delayed ones sorted first. */+ series: V4MigrationSdkUsageSeries[];+ delayedCount: number;+};++export const getOtelSectionState = (+ sdk: V4MigrationSdkState,+): V4MigrationOtelSectionState => {+ const series = sdk.sdkUsageSeries.filter(isOtelExporterSeries);+ return {+ series,+ delayedCount: series.filter((usage) => usage.hasDelayedOtelEvents === true)+ .length,+ };+};+export const formatSdkVersion = (sdkVersion: SdkVersionInfo | undefined) => {if (!sdkVersion?.language || !sdkVersion.version) return null;diff --git a/web/src/features/v4/server/v4TransitionRouter.ts b/web/src/features/v4/server/v4TransitionRouter.tsindex b7d9fffde5..0445ce3f01 100644--- a/web/src/features/v4/server/v4TransitionRouter.ts+++ b/web/src/features/v4/server/v4TransitionRouter.ts@@ -169,6 +169,8 @@ type SdkUsageSummaryByProjectRow = {sdkVersion: string;publicKey: string;count: string | number;+ /** Hits from events_core only (count also includes score ingestions). */+ eventsCount: string | number;firstSeen: string;lastSeen: string;hasDelayedOtelEvents: boolean | string | number | null;@@ -180,6 +182,10 @@ type SdkUsageSummaryByProjectSeries = {canonicalSdkName: "python" | "javascript" | null;publicKey: string;count: number;+ /** Hits with observation evidence: rows in events_core, excluding scores.+ Zero means the offender is scores-only and an events-table evidence+ link would open an empty result set. */+ eventsCount: number;firstSeen: string;lastSeen: string;hasDelayedOtelEvents: boolean | null;@@ -936,7 +942,8 @@ ORDER BY ${bucketTimeSql} ASC, sdk_name ASC, sdk_version ASC, public_key ASCif(ingestion_sdk_version = '', 'unknown', ingestion_sdk_version) AS sdk_version,ingestion_api_key AS public_key,false AS is_otel_ingestion,- false AS is_delayed_otel+ false AS is_delayed_otel,+ true AS is_score_ingestionFROM scores FINALWHEREproject_id IN {projectIds: Array(String)}@@ -956,7 +963,8 @@ WITH selected AS (if(ingestion_sdk_version = '', 'unknown', ingestion_sdk_version) AS sdk_version,ingestion_api_key AS public_key,(source = 'otel' OR startsWith(source, 'otel-dual-write')) AS is_otel_ingestion,- startsWith(source, 'otel-dual-write') AS is_delayed_otel+ startsWith(source, 'otel-dual-write') AS is_delayed_otel,+ false AS is_score_ingestionFROM events_coreWHEREproject_id IN {projectIds: Array(String)}@@ -973,6 +981,7 @@ SELECTsdk_version AS sdkVersion,public_key AS publicKey,count() AS count,+ countIf(NOT is_score_ingestion) AS eventsCount,formatDateTime(min(event_time), '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS firstSeen,formatDateTime(max(event_time), '%Y-%m-%dT%H:%i:%SZ', 'UTC') AS lastSeen,if(countIf(is_otel_ingestion) > 0, argMaxIf(is_delayed_otel, event_time, is_otel_ingestion), NULL) AS hasDelayedOtelEvents@@ -1050,7 +1059,7 @@ SETTINGS skip_unavailable_shards = 1return projectIds.map((projectId): SdkUsageSummaryByProjectResultRow => {const projectRows = (rowsByProjectId.get(projectId) ?? []).map(- (row): SdkUsageTimeSeriesResultRow => {+ (row): SdkUsageTimeSeriesResultRow & { eventsCount: number } => {const classification = classifyIngestionSdkVersion({sdkName: row.sdkName,sdkVersion: row.sdkVersion,@@ -1066,6 +1075,7 @@ SETTINGS skip_unavailable_shards = 1sdkVersion: row.sdkVersion,publicKey: row.publicKey,count: Number(row.count),+ eventsCount: Number(row.eventsCount),firstSeen: row.firstSeen,lastSeen: row.lastSeen,hasDelayedOtelEvents: toNullableBoolean(row.hasDelayedOtelEvents),@@ -1099,6 +1109,7 @@ SETTINGS skip_unavailable_shards = 1canonicalSdkName: row.canonicalSdkName,publicKey: row.publicKey,count: row.count,+ eventsCount: row.eventsCount,firstSeen: row.firstSeen!,lastSeen: row.lastSeen!,hasDelayedOtelEvents: row.hasDelayedOtelEvents,