langfuse-upgrade-migration

# 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 ```bash # 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 ```markdown ## Common Breaking Changes by Version ### v2.x -> v3.x (TypeScript) - `Langfuse.trace()` returns `Trace` instead of `Promise` - `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 ```bash # 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 ```typescript // 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 ```python # 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 ```typescript // 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 ```typescript // 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` | 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 ```bash # 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](https://github.com/langfuse/langfuse-js/releases) - [Langfuse Python Changelog](https://github.com/langfuse/langfuse-python/releases) - [Langfuse Migration Guide](https://langfuse.com/docs/sdk) - [Langfuse Discord](https://langfuse.com/discord) ## Next Steps For CI/CD integration, see `langfuse-ci-integration`.