Agent skill

langfuse-install-auth

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".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/langfuse-pack/skills/langfuse-install-auth

SKILL.md

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):

bash
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):

bash
npm install langfuse

Python:

bash
pip install langfuse

Step 2: Get API Keys

  1. Open Langfuse dashboard (https://cloud.langfuse.com or your self-hosted URL)
  2. Go to Settings > API Keys
  3. Click Create new API key pair
  4. Copy both keys:
    • Public Key: pk-lf-... (identifies your project)
    • Secret Key: sk-lf-... (grants write access -- keep secret)
  5. Note the host URL (cloud default: https://cloud.langfuse.com)

Step 3: Configure Environment Variables

bash
# 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)

typescript
// 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)

typescript
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

python
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_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.

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results