Genkitx Langfuse Digest

🚀 Quick Start The genkitx-langfuse plugin maps Firebase Genkit telemetry (OpenTelemetry) directly to Langfuse. Install using the correct NPM name, as the official README contains typos.

npm install genkitx-langfuse langfuse @opentelemetry/api

import { genkit } from "genkit"
import { langfuse } from "genkitx-langfuse" // Anti-pattern: README says 'genkit-langfuse'
 
const ai = genkit({
  plugins: [
    langfuse({
      secretKey: process.env.LANGFUSE_SECRET_KEY!,
      publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
      forceDevExport: process.env.NODE_ENV !== "production", // Critical for local dev
    }),
  ],
})

🔧 Configuration Required environment variables are LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY. Pass them directly into the plugin constructor.

Option	Type	Default	Description
baseUrl	string	https://cloud.langfuse.com	Override for self-hosted Langfuse instances.
debug	boolean	false	Enables verbose HTTP and span lifecycle logging.
forceDevExport	boolean	false	Bypasses production batching to flush traces immediately.
flushAt	number	20 (Prod)	Batch threshold. Defaults to 1 in dev environments.
flushInterval	number	10000 (Prod)	Export interval in ms. Defaults to 1000 in dev.
calculateCost	function	-	Callback to inject custom LLM cost calculation metrics.
spanFilter	function	-	Callback returning true to selectively export spans.

📦 Dependencies

• Core Exporter: Under the hood, this relies on langfuse and @opentelemetry/core.
• Peer Dependencies: Requires genkit version ^1.16.1 or higher.

💡 Best Practices / Patterns

• Cost Calculation Strategy: Implement the calculateCost(modelName, usage) callback with a local rate dictionary to accurately track spend. Genkit does not automatically map per-token pricing to Langfuse.
• Session Tracking: Use Genkit’s native chat structures like ai.chat({ sessionId: 'user-123' }). The plugin automatically parses the genkit:sessionId and genkit:threadName OpenTelemetry attributes to link chats in Langfuse.
• Standalone Telemetry Initialization: For complex backend OpenTelemetry setups, use await enableLangfuseTelemetry({...}). Call this before Genkit initialization to hijack the global trace exporter directly.
• User Context Mapping: The plugin parses genkit:userId from OpenTelemetry span attributes. Inject this attribute into your root Genkit flows to enable Langfuse user analytics.

🚨 Gotchas / Anti-Patterns

• The NPM Naming Typo: The official package README incorrectly documents installation and imports as genkit-langfuse. You must exclusively use genkitx-langfuse or the module will fail to resolve.
• Silent Failures in Local Dev: Traces will appear to fail or drop entirely when running locally. You must explicitly pass forceDevExport: true to bypass the 10-second production batching interval.
• Implicit Authentication Failure: Unlike some official Genkit plugins, this plugin does not auto-discover process environment variables. You must explicitly map process.env.LANGFUSE_SECRET_KEY into the plugin constructor.

🔍 Research / References

• NPM Registry: genkitx-langfuse
• Source Repository: marcelfolaron/genkitx-langfuse