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

Next Steps

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