Langfuse Install AuthCAUTION

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: langfuse-install-auth
description: '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".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(pnpm:*), Grep
version: 1.17.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- langfuse
- api
- observability
- llm
compatibility: Designed for Claude Code
---
# 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-` |

## Output

Produce a connection-verification receipt with SDK version, configured host, project
identifier, and a trace URL or identifier. Record only whether each credential is set;
never print key values, headers

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

cat >> .env << 'EOF'

Gates applied: no_behavioural_pass.