Langfuse Deploy Integration
Overview
Deploy Langfuse LLM observability alongside your application. Covers integrating the SDK for serverless (Vercel/Lambda), Docker, Cloud Run, and self-hosting the Langfuse server itself.
Prerequisites
- Langfuse API keys (cloud or self-hosted)
- Application using Langfuse SDK
- Target platform CLI installed
Instructions
Step 1: Vercel / Next.js Deployment
set -euo pipefail
vercel env add LANGFUSE_PUBLIC_KEY production
vercel env add LANGFUSE_SECRET_KEY production
vercel env add LANGFUSE_BASE_URL production
import { NextRequest, NextResponse } from "next/server";
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
import OpenAI from "openai";
const langfuse = new LangfuseClient();
const openai = new OpenAI();
export async function POST(req: NextRequest) {
const { messages } = await req.json();
const response = await startActiveObservation(
{ name: "chat-api", asType: "generation" },
async () => {
updateActiveObservation({
model: "gpt-4o",
input: messages,
metadata: { endpoint: "/api/chat" },
});
const result = await openai.chat.completions.create({
model: "gpt-4o",
messages,
});
updateActiveObservation({
output: result.choices[0].message,
usage: {
promptTokens: result.usage?.prompt_tokens,
completionTokens: result.usage?.completion_tokens,
},
});
return result.choices[0].message;
}
);
return NextResponse.json(response);
}
Serverless note: Langfuse SDK v4+ uses OTel which handles flushing asynchronously. For v3, always call await langfuse.flushAsync() before the response returns -- serverless functions may freeze after response.
Step 2: AWS Lambda / Serverless
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
const sdk = new NodeSDK({
spanProcessors: [
new LangfuseSpanProcessor({
exportIntervalMillis: 1000,
}),
],
});
sdk.start();
export const handler = async (event: any) => {
return await startActiveObservation("lambda-handler", async () => {
updateActiveObservation({ input: event });
const result = await processRequest(event);
updateActiveObservation({ output: result });
await sdk.shutdown();
return { statusCode: 200, : .(result) };
});
};
Step 3: Self-Hosted Langfuse Server (Docker)
services:
langfuse:
image: langfuse/langfuse:latest
ports:
- "3000:3000"
environment:
- DATABASE_URL=postgresql://langfuse:${DB_PASSWORD}@postgres:5432/langfuse
- NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
- NEXTAUTH_URL=https://langfuse.your-domain.com
- SALT=${SALT}
- ENCRYPTION_KEY=${ENCRYPTION_KEY}
- AUTH_DISABLE_SIGNUP=true
- LANGFUSE_DEFAULT_PROJECT_ROLE=VIEWER
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
environment:
POSTGRES_USER: langfuse
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: langfuse
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U langfuse"]
interval: 5s
timeout: 5s
retries: 5
set -euo pipefail
export DB_PASSWORD=$(openssl rand -hex 16)
export NEXTAUTH_SECRET=$(openssl rand -hex 32)
export SALT=$(openssl rand -hex 16)
export ENCRYPTION_KEY=$(openssl rand -hex 32)
docker compose up -d
sleep 10
curl -s http://localhost:3000/api/public/health
Step 4: Google Cloud Run
set -euo pipefail
gcloud builds submit --tag gcr.io/$PROJECT_ID/my-llm-app
gcloud run deploy my-llm-app \
--image gcr.io/$PROJECT_ID/my-llm-app \
--set-secrets="LANGFUSE_PUBLIC_KEY=langfuse-public-key:latest" \
--set-secrets="LANGFUSE_SECRET_KEY=langfuse-secret-key:latest" \
--set-env-vars="LANGFUSE_BASE_URL=https://cloud.langfuse.com"
Step 5: Health Check Endpoint
import { LangfuseClient } from "@langfuse/client";
const langfuse = new LangfuseClient();
export async function GET() {
try {
await langfuse.prompt.get("__health__").catch(() => {});
return Response.json({ status: "healthy", tracing: "enabled" });
} catch {
return Response.json(
{ status: "degraded", tracing: "disabled" },
{ status: 503 }
);
}
}
Platform-Specific Considerations
| Platform | Key Concern | Solution |
|---|
| Vercel/Edge | Function timeout | Flush before response; use v4+ |
| AWS Lambda | Cold starts | Initialize SDK outside handler |
| Cloud Run | Concurrency | Singleton client, shared OTel SDK |
| Docker | Self-hosted networking | Ensure app can reach Langfuse host |
| Kubernetes | Pod lifecycle | Shutdown hook on SIGTERM |
Error Handling
| Issue | Cause | Solution |
|---|
| Traces missing in serverless | Not flushed before freeze | sdk.shutdown() before response |
| Auth error after deploy | Wrong env for environment | Verify secrets match deployment |
| Self-hosted 502 | DB not ready | Add healthcheck + depends_on |
| High latency in prod | Small batch size | Increase flushAt / maxExportBatchSize |
Resources
