langfuse-upgrade-migration

Langfuse Upgrade & Migration

Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Guide for upgrading Langfuse SDK versions, handling breaking changes between v2 and v3 (TypeScript) or v1 and v2 (Python), with automated codemod support.

Prerequisites

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

Instructions

Step 1: Check Current Version

Run npm list langfuse (Node) or pip show langfuse (Python) and review changelogs.

Step 2: Review Breaking Changes

Key v3 changes: named exports, sync trace(), flushAsync() replaces flush(), camelCase usage keys.

Step 3: Create Upgrade Branch and Update

Create chore/upgrade-langfuse branch. Run npm install langfuse@latest. Run tests.

Step 4: Apply TypeScript API Changes

Change import Langfuse to import { Langfuse }. Remove await from trace(). Replace flush() with flushAsync().

Step 5: Apply Python API Changes

Update decorator from @langfuse.observe() to @observe(). Import from langfuse.decorators.

Step 6: Run Migration Codemod

Use ts-morph script to auto-update imports and flush calls across the codebase.

Step 7: Verify with Migration Tests

Run tests verifying trace creation, generation usage format, and flush behavior.

See detailed implementation for advanced patterns.

Output

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

Error Handling

Error	Cause	Solution
Import error	Changed export	Use named import { Langfuse }
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

Examples

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

Resources

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