langfuse-upgrade-migration

Upgrade Langfuse SDK versions and migrate between API changes. Use when upgrading Langfuse SDK, handling breaking changes, or migrating between Langfuse versions. Trigger with phrases like "upgrade langfuse", "langfuse migration", "update langfuse SDK", "langfuse breaking changes", "langfuse version".

Jump to install

Repository: jeremylongshore/tons-of-skills-marketplace
Last source activity: August 19, 2026 at 12:13
Detected SKILL.md language: English
Stars: 2,677
Forks: 392

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	langfuse-upgrade-migration
description	Upgrade Langfuse SDK versions and migrate between API changes. Use when upgrading Langfuse SDK, handling breaking changes, or migrating between Langfuse versions. Trigger with phrases like "upgrade langfuse", "langfuse migration", "update langfuse SDK", "langfuse breaking changes", "langfuse version".
allowed-tools	Read, Write, Edit, Bash(npm:), Bash(pip:)
version	1.12.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","langfuse","api","migration"]
compatibility	Designed for Claude Code

Langfuse Upgrade & Migration

Current State

!npm list langfuse @langfuse/client @langfuse/tracing @langfuse/otel 2>/dev/null | head -10 || echo 'No langfuse packages found' !pip show langfuse 2>/dev/null | grep -E "Name|Version" || echo 'Python langfuse not installed'

Overview

Step-by-step guide for upgrading the Langfuse SDK across major versions. Covers v3 to v4 (OTel rewrite), v4 to v5, breaking changes, and automated codemods.

Prerequisites

Existing Langfuse integration
Test suite covering traced operations
Git branch for the upgrade

Version Roadmap

SDK	Package	Architecture	Status
v3	`langfuse` (single)	Custom, `Langfuse` class	Legacy
v4	`@langfuse/client`, `@langfuse/tracing`, `@langfuse/otel`	OpenTelemetry-based	Stable
v5	`@langfuse/client`, `@langfuse/tracing`, `@langfuse/otel`	OpenTelemetry + improvements	Latest

Instructions

Step 1: Check Current Version and Plan

set -euo pipefail
# Check what you have
npm list langfuse @langfuse/client @langfuse/tracing 2>/dev/null

# Check latest available
npm info @langfuse/client version
npm info @langfuse/tracing version
npm info langfuse version

# Python
pip show langfuse 2>/dev/null | grep Version
pip index versions langfuse 2>/dev/null | head -3

Step 2: v3 to v4 Migration (TypeScript)

This is the biggest migration -- v4 rewrites tracing on OpenTelemetry.

2a. Install new packages:

set -euo pipefail
# Install v4+ packages
npm install @langfuse/client @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

# Keep langfuse v3 temporarily for comparison
# Remove after migration: npm uninstall langfuse

// BEFORE (v3):
import { Langfuse } from "langfuse";
const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: process.env.LANGFUSE_HOST,
});

// AFTER (v4+):
import { LangfuseClient } from "@langfuse/client";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

// OTel setup (once at entry point)
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();

// Client for prompts, datasets, scores
const langfuse = new LangfuseClient();

// BEFORE (v3): Manual trace/span/generation
const trace = langfuse.trace({ name: "my-op", input: data });
const span = trace.span({ name: "step-1", input: data });
await doWork();
span.end({ output: result });
const gen = trace.generation({ name: "llm", model: "gpt-4o" });
gen.end({ output: response, usage: { promptTokens: 10 } });
await langfuse.flushAsync();

// AFTER (v4+): startActiveObservation with auto-nesting
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";

await startActiveObservation("my-op", async () => {
  updateActiveObservation({ input: data });

  await startActiveObservation("step-1", async () => {
    updateActiveObservation({ input: data });
    const result = await doWork();
    updateActiveObservation({ output: result });
  });

  await startActiveObservation({ name: "llm", asType: "generation" }, async () => {
    updateActiveObservation({ model: "gpt-4o" });
    const response = await callLLM();
    updateActiveObservation({ output: response, usage: { promptTokens: 10 } });
  });
});

// BEFORE (v3):
import { observeOpenAI } from "langfuse";

// AFTER (v4+):
import { observeOpenAI } from "@langfuse/openai";
// npm install @langfuse/openai

# BEFORE: LANGFUSE_HOST or LANGFUSE_BASEURL
# AFTER:  LANGFUSE_BASE_URL (LANGFUSE_BASEURL still works in v4 but not v5)

// BEFORE (v3):
const prompt = await langfuse.getPrompt("my-prompt", 2); // version as positional arg

// AFTER (v4+):
const prompt = await langfuse.prompt.get("my-prompt", {
  version: 2, // version in options object
  type: "text", // explicit type
});

// BEFORE (v3):
await langfuse.shutdownAsync();

// AFTER (v4+):
await sdk.shutdown(); // Shuts down OTel SDK + flushes spans

# BEFORE (v2):
from langfuse import Langfuse
langfuse = Langfuse()

@langfuse.observe()
def my_function():
    pass

# AFTER (v3):
from langfuse.decorators import observe, langfuse_context

@observe()
def my_function():
    langfuse_context.update_current_observation(
        metadata={"key": "value"}
    )

set -euo pipefail
# Run existing test suite
npm test

# Verify traces appear in dashboard
node -e "
  const { startActiveObservation, updateActiveObservation } = require('@langfuse/tracing');
  startActiveObservation('upgrade-verify', async () => {
    updateActiveObservation({ input: { test: true }, output: { migrated: true } });
  }).then(() => console.log('Migration verified'));
"

set -euo pipefail
# After all tests pass
npm uninstall langfuse

# Verify no lingering imports
grep -rn "from ['\"]langfuse['\"]" src/ || echo "No old imports found"

Change	v3	v4+
Package	`langfuse`	`@langfuse/client` + `@langfuse/tracing` + `@langfuse/otel`
Client class	`Langfuse`	`LangfuseClient`
Base URL env	`LANGFUSE_HOST`	`LANGFUSE_BASE_URL`
Tracing	`langfuse.trace()` / `.span()` / `.generation()`	`startActiveObservation()` / `observe()`
Flush	`langfuse.flushAsync()`	`sdk.shutdown()`
Prompt version	`getPrompt(name, version)`	`prompt.get(name, { version })`
OpenAI	`import { observeOpenAI } from "langfuse"`	`import { observeOpenAI } from "@langfuse/openai"`

Error	Cause	Solution
`Cannot find module '@langfuse/tracing'`	Package not installed	`npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node`
`langfuse.trace is not a function`	Using v4 `LangfuseClient` for tracing	Use `startActiveObservation` from `@langfuse/tracing`
Flat traces (no nesting)	OTel SDK not started	Register `LangfuseSpanProcessor` with `NodeSDK`
`LANGFUSE_HOST` ignored	v5 dropped legacy env var	Rename to `LANGFUSE_BASE_URL`