Research Langfuse

🚀 Quick Start Langfuse-pack is a Claude Code skill pack covering LLM observability, prompt management, and evaluation. It installs 24 skills focusing on OpenTelemetry (v4+) tracing, rate-limit handling, and production architectures.

🔧 Configuration & Setup Install via CLI using /plugin install langfuse-pack@claude-code-plugins-plus. Always use environment variables LANGFUSE_PUBLIC_KEY (client-safe) and LANGFUSE_SECRET_KEY (server-side only) to configure access. Check for swapped keys at startup to prevent auth failures.

📦 Dependencies Target the modern v4+ SDK using @langfuse/client, @langfuse/tracing, @langfuse/otel, and @opentelemetry/sdk-node. Legacy v3 (langfuse) is in maintenance mode.

💡 Patterns & Best Practices

• Singleton SDK: Instantiate Langfuse clients once per application lifecycle. Combine with AsyncLocalStorage for cross-request context propagation.
• Ergonomic Tracing: Use the observe() wrapper to auto-create spans for existing functions. For inline nested traces, implement startActiveObservation.
• Error-Safe Execution: Tracing failures must never break the main app. Wrap tracing blocks in try/catch handlers that log telemetry errors but gracefully return the original function output.
• Rate Limits & Backoff: Tune OTel span processors using maxExportBatchSize and exportIntervalMillis. Implement exponential backoff with jitter and p-queue concurrency caps for 429 Too Many Requests errors.
• Data Minimization: Truncate large payloads and buffers before sending trace data. Use Regex patterns to scrub PII (emails, API keys, SSNs) prior to trace submission.
• Graceful Shutdown: Bind sdk.shutdown() to SIGTERM and SIGINT process events. This guarantees the trace queue flushes before the container terminates.
• Environment Scoping: Separate projects for dev, staging, and production. Utilize scoped API keys with least-privilege roles to protect write paths.

🚨 Anti-patterns & Gotchas

• Per-Request Instantiation: NEVER call new Langfuse() or new LangfuseClient() inside request handlers. This causes memory leaks and duplicates traces.
• Blocking Flushes: Do not await trace flushes in the hot path. Let the SDK handle asynchronous background batching.
• Missing Span Termination (v3): Failing to call .end() leaves traces stuck “in progress” indefinitely. Use try/finally blocks to guarantee span closure.
• Missing Token Usage: Streaming generations omit tokens unless explicitly instructed. Always set stream_options: { include_usage: true } in OpenAI calls to track costs.
• Swapped Keys: Passing pk-lf- instead of sk-lf- throws immediate 401s. Validate prefixes on app startup to prevent silent failures.

🔍 Research & References

• Plugin Hub: https://tonsofskills.com/learn/langfuse/
• Repository: https://github.com/jeremylongshore/claude-code-plugins-plus-skills
• Target Scope: Supports Claude Code, Codex, and OpenClaw agents.