Skip to main content Install and configure Langfuse SDK authentication for LLM observability.
Use when setting up a new Langfuse integration, configuring API keys,
or initializing Langfuse tracing in your project.
Trigger with phrases like "install langfuse", "setup langfuse",
"langfuse auth", "configure langfuse API key", "langfuse tracing setup".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill langfuse-install-auth ai automation claude-code devops mcp ai-agents
Langfuse Install & Auth
Overview
Install the Langfuse SDK and configure authentication for LLM observability. Covers both the legacy langfuse package (v3) and the modern modular SDK (v4+/v5) built on OpenTelemetry.
Prerequisites
Node.js 18+ or Python 3.9+
Package manager (npm, pnpm, or pip)
Langfuse account (cloud at https://cloud.langfuse.com or self-hosted)
Public Key (pk-lf-...) and Secret Key (sk-lf-...) from project settings
Instructions
Step 1: Install SDK
TypeScript/JavaScript (v4+ modular SDK -- recommended):
set -euo pipefail
# Core client for prompt management, datasets, scores
npm install @langfuse/client
# Tracing (observe, startActiveObservation)
npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node
# OpenAI integration (drop-in wrapper)
npm install @langfuse/openai
# LangChain integration
npm install @langfuse/langchain
TypeScript/JavaScript (v3 legacy -- single package):
Step 2: Get API Keys
Open Langfuse dashboard (https://cloud.langfuse.com or your self-hosted URL)
Go to Settings > API Keys
Click Create new API key pair
Copy both keys:
Public Key : pk-lf-... (identifies your project)Secret Key : sk-lf-... (grants write access -- keep secret)
Note the host URL (cloud default: https://cloud.langfuse.com)
Step 3: Configure Environment Variables # Set environment variables
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"
# Or create .env file
cat >> .env << 'EOF'
LANGFUSE_PUBLIC_KEY=pk-lf-your-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-secret-key
LANGFUSE_BASE_URL=https://cloud.langfuse.com
EOF
Note: v4+ uses LANGFUSE_BASE_URL. Legacy v3 uses LANGFUSE_HOST or LANGFUSE_BASEURL.
Step 4: Initialize and Verify (v4+ Modular SDK) // src/lib/langfuse.ts
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation } from "@langfuse/tracing";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
// 1. Register the OpenTelemetry span processor (once at app startup)
const sdk = new NodeSDK({
spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();
// 2. Create the Langfuse client for prompt/dataset/score operations
export const langfuse = new LangfuseClient({
publicKey: process.env.LANGFUSE_PUBLIC_KEY,
secretKey: process.env.LANGFUSE_SECRET_KEY,
baseUrl: process.env.LANGFUSE_BASE_URL,
});
// 3. Verify connection
async function verify() {
await startActiveObservation("connection-test", async (span) => {
span.update({ input: { test: true } });
span.update({ output: { status: "connected" } });
});
console.log("Langfuse connection verified. Check dashboard for trace.");
}
verify();
Step 5: Initialize and Verify (v3 Legacy SDK) import { Langfuse } from "langfuse";
const langfuse = new Langfuse({
publicKey: process.env.LANGFUSE_PUBLIC_KEY,
secretKey: process.env.LANGFUSE_SECRET_KEY,
baseUrl: process.env.LANGFUSE_HOST,
});
// Verify with a test trace
const trace = langfuse.trace({
name: "connection-test",
metadata: { test: true },
});
await langfuse.flushAsync();
console.log("Connected. Trace URL:", trace.getTraceUrl());
// Clean shutdown
process.on("beforeExit", async () => {
await langfuse.shutdownAsync();
});
Step 6: Python Verification from langfuse import Langfuse
import os
langfuse = Langfuse(
public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
secret_key=os.environ["LANGFUSE_SECRET_KEY"],
host=os.environ.get("LANGFUSE_HOST", "https://cloud.langfuse.com"),
)
# Test trace
trace = langfuse.trace(name="connection-test", metadata={"test": True})
langfuse.flush()
print(f"Connected. Trace: {trace.get_trace_url()}")
SDK Version Comparison Feature v3 (langfuse) v4+ (@langfuse/*) Package Single langfuse Modular: @langfuse/client, @langfuse/tracing, @langfuse/otel Base URL env var LANGFUSE_HOSTLANGFUSE_BASE_URLTracing langfuse.trace()startActiveObservation() / observe()Client class LangfuseLangfuseClientOpenAI wrapper observeOpenAI() from langfuseobserveOpenAI() from @langfuse/openaiFoundation Custom OpenTelemetry
Error Handling Error Cause Solution 401 UnauthorizedInvalid or expired API key Re-check keys in Langfuse dashboard Settings > API Keys ECONNREFUSEDWrong host URL or server down Verify LANGFUSE_BASE_URL / LANGFUSE_HOST Missing required configurationEnv vars not loaded Ensure dotenv/config imported at entry point Module not foundPackage not installed Run npm install or pip install again Using pk- key as secret Keys swapped Public key starts pk-lf-, secret starts sk-lf-
Resources
Next Steps After auth is working, proceed to langfuse-hello-world for your first traced LLM call.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
