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
npm install @langfuse/client
npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node
npm install @langfuse/openai
npm install @langfuse/langchain
TypeScript/JavaScript (v3 legacy -- single package):
npm install langfuse
Python:
pip install langfuse
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
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"
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)
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation } from "@langfuse/tracing";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
const sdk = new NodeSDK({
spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();
export const langfuse = new LangfuseClient({
publicKey: process.env.LANGFUSE_PUBLIC_KEY,
secretKey: process.env.LANGFUSE_SECRET_KEY,
baseUrl: process.env.LANGFUSE_BASE_URL,
});
async function verify() {
await startActiveObservation("connection-test", async (span) => {
span.update({ : { : } });
span.({ : { : } });
});
.();
}
();
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,
});
const trace = langfuse.trace({
name: "connection-test",
metadata: { test: true },
});
await langfuse.flushAsync();
console.log("Connected. Trace URL:", trace.getTraceUrl());
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"),
)
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_HOST | LANGFUSE_BASE_URL |
| Tracing | langfuse.trace() | startActiveObservation() / observe() |
| Client class | Langfuse | LangfuseClient |
| OpenAI wrapper | observeOpenAI() from langfuse | observeOpenAI() from @langfuse/openai |
| Foundation | Custom | OpenTelemetry |
Error Handling
| Error | Cause | Solution |
|---|
401 Unauthorized | Invalid or expired API key | Re-check keys in Langfuse dashboard Settings > API Keys |
ECONNREFUSED | Wrong host URL or server down | Verify LANGFUSE_BASE_URL / LANGFUSE_HOST |
Missing required configuration | Env vars not loaded | Ensure dotenv/config imported at entry point |
Module not found | Package 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.
