Skip to content

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

fix(web): add the v4 walkthrough video to the migration side panel (#16079)

Trang Nguyen574d26053160
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index 7988f2553c..f48a8c1e6b 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -345,6 +345,7 @@ export const events = {
"section_link_clicked",
"project_keys_copied",
"evals_manual_upgrade_clicked",
+ "walkthrough_video_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/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
index c2ba9fd75c..517aba0630 100644
--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx
@@ -50,6 +50,11 @@ const cleanSdkState = (): V4MigrationSdkState => ({
});
const mocks = vi.hoisted(() => ({
+ // Mutable so tests can flip between Cloud and self-hosted; the component
+ // reads the env at render time.
+ env: { NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: "US" } as {
+ NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: string | undefined;
+ },
routerPush: vi.fn(),
capture: vi.fn(),
openAssistant: vi.fn(),
@@ -92,6 +97,8 @@ const mocks = vi.hoisted(() => ({
createProjectApiKey: vi.fn(),
}));
+vi.mock("@/src/env.mjs", () => ({ env: mocks.env }));
+
vi.mock("next/router", () => ({
useRouter: () => ({
query: { projectId: "project-1" },
@@ -215,6 +222,7 @@ vi.mock("@/src/components/ui/collapsible", () => {
describe("V4MigrationDetailsContent", () => {
beforeEach(() => {
vi.clearAllMocks();
+ mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
mocks.routerPush.mockResolvedValue(true);
mocks.submitAgentMessage.mockResolvedValue(undefined);
mocks.migrationData.evals = { status: "loaded", count: 0 };
@@ -897,6 +905,33 @@ describe("V4MigrationDetailsContent", () => {
).toBeInTheDocument();
});
+ it("links the walkthrough video from the help footer on Cloud", () => {
+ render(<V4MigrationDetailsContent projectId="project-1" />);
+
+ const link = screen.getByRole("link", { name: "Walkthrough video" });
+ // Straight to YouTube in a new tab; the panel never embeds the player,
+ // so no iframe may render before or after the click.
+ expect(link).toHaveAttribute(
+ "href",
+ "https://www.youtube.com/watch?v=g3YbbqVGt4g",
+ );
+ expect(link).toHaveAttribute("target", "_blank");
+ expect(document.querySelector("iframe")).toBeNull();
+
+ fireEvent.click(link);
+ expect(mocks.capture).toHaveBeenCalledWith(
+ "v4_migration:walkthrough_video_clicked",
+ );
+ expect(document.querySelector("iframe")).toBeNull();
+ });
+
+ it("hides the walkthrough video link on self-hosted deployments", () => {
+ mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;
+ render(<V4MigrationDetailsContent projectId="project-1" />);
+
+ expect(screen.queryByText("Walkthrough video")).not.toBeInTheDocument();
+ });
+
it("shows the preview-toggle section only when the session can toggle v4", () => {
const { unmount } = render(
<V4MigrationDetailsContent projectId="project-1" />,
@@ -1079,15 +1114,22 @@ describe("V4MigrationHeaderContent", () => {
}
});
- it("labels the help footer and renders no horizontal separators", () => {
- render(<V4MigrationDetailsContent projectId="project-1" />);
+ it("labels the help footer and groups content with three separators", () => {
+ const { container } = render(
+ <V4MigrationDetailsContent projectId="project-1" />,
+ );
expect(screen.getByText("Need help?")).toBeInTheDocument();
expect(screen.getByRole("link", { name: "Docs" })).toHaveAttribute(
"href",
"https://langfuse.com/docs/v4",
);
- expect(screen.queryByRole("separator")).not.toBeInTheDocument();
+ // One divider above Action items, one above the agent CTA, one above
+ // Need help. Decorative Radix separators render role="none", so query
+ // by data attribute.
+ expect(
+ container.querySelectorAll('[data-orientation="horizontal"]'),
+ ).toHaveLength(3);
});
it("does not create credentials when revealing or copying the prompt", () => {
diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsx
index 473a1e9192..3ee3d40766 100644
--- a/web/src/features/v4-migration/V4MigrationContent.tsx
+++ b/web/src/features/v4-migration/V4MigrationContent.tsx
@@ -10,6 +10,7 @@ import {
Copy,
Info,
} from "lucide-react";
+import { env } from "@/src/env.mjs";
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";
@@ -20,6 +21,7 @@ import {
HoverCardTrigger,
} from "@/src/components/ui/hover-card";
import { RainbowButton } from "@/src/components/magicui/rainbow-button";
+import { Separator } from "@/src/components/ui/separator";
import {
Collapsible,
CollapsibleContent,
@@ -99,6 +101,11 @@ const EXPERIMENT_OTEL_INGESTION_URL =
const SDK_OVERVIEW_URL = "https://langfuse.com/docs/observability/sdk/overview";
const OTEL_INTEGRATION_URL =
"https://langfuse.com/integrations/native/opentelemetry";
+// Hassieb's 2 minute walkthrough of the upgrade steps. Linked (not embedded)
+// from the Need help footer, so the panel stays free of YouTube player
+// chrome and the CSP frame-src stays untouched. Cloud only: the video covers
+// the steps as they apply to Langfuse Cloud projects.
+const WALKTHROUGH_VIDEO_URL = "https://www.youtube.com/watch?v=g3YbbqVGt4g";
// Copies the agent migration prompt to the clipboard with toast + analytics;
// shared by the panel/modal header CTA and the status page.
@@ -1343,6 +1350,8 @@ 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
@@ -1409,6 +1418,8 @@ export function V4MigrationDetailsContent({
</div>
</div>
+ <Separator />
+
<V4MigrationAgentUpgradeSection projectId={projectId} />
{/* The toggle row hides itself when the session cannot toggle v4
@@ -1451,6 +1462,8 @@ export function V4MigrationDetailsContent({
</>
)}
+ <Separator />
+
<div className="flex flex-col gap-2">
<p className="text-base font-bold">Need help?</p>
<div className="text-muted-foreground flex flex-wrap items-center gap-x-2 gap-y-1 text-sm">
@@ -1481,6 +1494,22 @@ export function V4MigrationDetailsContent({
>
Book a call
</a>
+ {env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION && (
+ <>
+ <span>·</span>
+ <a
+ href={WALKTHROUGH_VIDEO_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={() =>
+ capture("v4_migration:walkthrough_video_clicked")
+ }
+ className="underline"
+ >
+ Walkthrough video
+ </a>
+ </>
+ )}
</div>
</div>
{projectId ? (