Skip to content

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

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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>
<Switch
id={toggleId}
size="sm"
@@ -229,10 +229,10 @@ export function V4PreviewToggleRow({ projectId }: { projectId?: string }) {
/>
<Label
htmlFor={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.ts
index 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.ts
index 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.ts
index 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.ts
index 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). Only
diff --git a/web/src/features/search-bar/lib/fields.ts b/web/src/features/search-bar/lib/fields.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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(
<V4MigrationHeaderContent
projectId="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.tsx
index 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 (
<a
href={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&apos;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>
- )}
<RainbowButton
className="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 the
copy 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&apos;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&apos;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&apos;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 ? (
<EvaluatorMigrationDialog
diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx
new file mode 100644
index 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.tsx
index 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 (
<V4MigrationBadgeContent
onClick={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.tsx
index 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({
<V4MigrationHeaderContent
projectName={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">
<V4MigrationDetailsContent
onNavigate={() => setOpen(false)}
projectId={project.id}
diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsx
index 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.tsx
index 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">
<V4MigrationHeaderContent
key={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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
index 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/InAppAiA
import { 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.ts
index 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.ts
index 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.ts
index 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 ASC
if(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_ingestion
FROM scores FINAL
WHERE
project_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_ingestion
FROM events_core
WHERE
project_id IN {projectIds: Array(String)}
@@ -973,6 +981,7 @@ SELECT
sdk_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 = 1
return 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 = 1
sdkVersion: 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 = 1
canonicalSdkName: row.canonicalSdkName,
publicKey: row.publicKey,
count: row.count,
+ eventsCount: row.eventsCount,
firstSeen: row.firstSeen!,
lastSeen: row.lastSeen!,
hasDelayedOtelEvents: row.hasDelayedOtelEvents,