---

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.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io

Langfuse Upgrade & Migration

Overview

Guide for upgrading Langfuse SDK versions and handling breaking changes.

Prerequisites

• Existing Langfuse integration
• Access to test environment
• Version control (git)

Instructions

Step 1: Check Current Version and Updates

# Check current version (Node.js)
npm list langfuse
npm outdated langfuse

# Check current version (Python)
pip show langfuse
pip index versions langfuse

# View changelog
open https://github.com/langfuse/langfuse-js/releases
open https://github.com/langfuse/langfuse-python/releases

Step 2: Review Breaking Changes

## Common Breaking Changes by Version

### v2.x -> v3.x (TypeScript)
- `Langfuse.trace()` returns `Trace` instead of `Promise<Trace>`
- `flushAsync()` replaces `flush()` (now async)
- `observeOpenAI()` moved to main package export
- Generation `completionTokens` -> `completionTokens` (was `completion_tokens`)

### v1.x -> v2.x (Python)
- `langfuse.trace()` now returns synchronously
- Decorator `@observe()` replaces `@langfuse.observe()`
- `flush()` is now synchronous, use `shutdown()` for cleanup

Step 3: Update SDK with Testing

# Create upgrade branch
git checkout -b chore/upgrade-langfuse

# Update package (Node.js)
npm install langfuse@latest

# Update package (Python)
pip install --upgrade langfuse

# Run tests
npm test
pytest

# If tests fail, check specific version
npm install langfuse@3.0.0  # Specific version

Step 4: Handle TypeScript API Changes

// BEFORE (v2.x)
import Langfuse from "langfuse";

const langfuse = new Langfuse({
  publicKey: "...",
  secretKey: "...",
});

// Old async pattern
const trace = await langfuse.trace({ name: "test" });
await langfuse.flush();

// AFTER (v3.x)
import { Langfuse } from "langfuse";  // Named export

const langfuse = new Langfuse({
  publicKey: "...",
  secretKey: "...",
});

// New sync pattern (returns immediately, batches in background)
const trace = langfuse.trace({ name: "test" });
await langfuse.flushAsync();  // Renamed method

Step 5: Handle Python API Changes

# BEFORE (v1.x)
from langfuse import Langfuse

langfuse = Langfuse()

@langfuse.observe()  # Old decorator syntax
def my_function():
    pass

langfuse.flush()

# AFTER (v2.x)
from langfuse import Langfuse
from langfuse.decorators import observe, langfuse_context  # New import

langfuse = Langfuse()

@observe()  # New decorator (no langfuse prefix)
def my_function():
    # Access context via langfuse_context
    langfuse_context.update_current_observation(
        metadata={"key": "value"}
    )
    pass

langfuse.flush()

Step 6: Migration Script for Codemod

// scripts/migrate-langfuse.ts
import { Project } from "ts-morph";

const project = new Project({
  tsConfigFilePath: "./tsconfig.json",
});

const sourceFiles = project.getSourceFiles();

for (const sourceFile of sourceFiles) {
  let modified = false;

  // Update imports
  const importDeclarations = sourceFile.getImportDeclarations();
  for (const importDecl of importDeclarations) {
    if (importDecl.getModuleSpecifierValue() === "langfuse") {
      // Change default import to named import
      const defaultImport = importDecl.getDefaultImport();
      if (defaultImport?.getText() === "Langfuse") {
        importDecl.removeDefaultImport();
        importDecl.addNamedImport("Langfuse");
        modified = true;
      }
    }
  }

  // Update flush() to flushAsync()
  sourceFile.forEachDescendant((node) => {
    if (
      node.getKindName() === "CallExpression" &&
      node.getText().includes(".flush()")
    ) {
      node
        .asKind(ts.SyntaxKind.CallExpression)
        ?.getExpression()
        .replaceWithText(
          node
            .getText()
            .replace(".flush()", ".flushAsync()")
        );
      modified = true;
    }
  });

  if (modified) {
    console.log(`Updated: ${sourceFile.getFilePath()}`);
    sourceFile.saveSync();
  }
}

Step 7: Test Migration

// tests/langfuse-migration.test.ts
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { Langfuse } from "langfuse";

describe("Langfuse Migration Tests", () => {
  let langfuse: Langfuse;

  beforeAll(() => {
    langfuse = new Langfuse({
      publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
      secretKey: process.env.LANGFUSE_SECRET_KEY!,
    });
  });

  afterAll(async () => {
    await langfuse.shutdownAsync();
  });

  it("should create trace with new API", () => {
    const trace = langfuse.trace({
      name: "migration-test",
      metadata: { version: "3.x" },
    });

    expect(trace).toBeDefined();
    expect(trace.id).toBeDefined();
  });

  it("should create generation with correct usage format", () => {
    const trace = langfuse.trace({ name: "generation-test" });

    const generation = trace.generation({
      name: "test-gen",
      model: "gpt-4",
      input: [{ role: "user", content: "test" }],
    });

    generation.end({
      output: "response",
      usage: {
        promptTokens: 10,      // New format (camelCase)
        completionTokens: 20,  // New format (camelCase)
      },
    });

    expect(generation.id).toBeDefined();
  });

  it("should flush with new async method", async () => {
    langfuse.trace({ name: "flush-test" });

    // New method name
    await expect(langfuse.flushAsync()).resolves.not.toThrow();
  });
});

Output

• Updated SDK to latest version
• Migrated deprecated API calls
• All tests passing
• No breaking changes in functionality

Version Compatibility Matrix

Feature	v2.x	v3.x	Migration
Default import	import Langfuse	import { Langfuse }	Update imports
trace() return	Promise<Trace>	Trace	Remove await
flush()	Sync	N/A	Use flushAsync()
Usage keys	snake_case	camelCase	Update all usage objects

Error Handling

Error	Cause	Solution
Import error	Changed export	Use named import
Type error on usage	Key name change	Use camelCase keys
flush() not found	Method renamed	Use flushAsync()
Decorator error	New import path	Import from langfuse.decorators

Rollback Plan

# If upgrade fails, rollback
git checkout main
npm install langfuse@2.0.0  # Previous version

# Or with lock file
git checkout HEAD -- package-lock.json
npm ci

Resources

• Langfuse JS Changelog
• Langfuse Python Changelog
• Langfuse Migration Guide
• Langfuse Discord

Next Steps

For CI/CD integration, see langfuse-ci-integration.