Langfuse einrichten: 12 Schritte, 35.400 Stars [2026]

Wer heute eine LLM-Anwendung in Produktion bringt, merkt schnell, dass das Modell nur die halbe Miete ist. Die eigentliche Arbeit beginnt, wenn Prompts in freier Wildbahn versagen, Kosten explodieren oder ein Agent in einer Tool-Call-Schleife hängen bleibt, ohne dass jemand merkt, warum. Langfuse schließt genau diese Lücke: eine Open-Source-Plattform für Tracing, Evaluierung und Kostenkontrolle von LLM-Anwendungen, die sich komplett selbst hosten lässt. Das GitHub-Repository zählt Stand 05. Oktober 2026 rund 35.400 Sterne. Dieses Tutorial zeigt in 12 Schritten, wie du Langfuse auf eigener Infrastruktur aufsetzt, deinen ersten Trace erzeugst und eine vollständige Beispielanwendung mit Tracing ausstattest. Am Ende kennst du nicht nur die Installation, sondern auch die typischen Fehlerquellen, mit denen Teams in der Praxis kämpfen, und weißt, wann sich der Umstieg auf Kubernetes lohnt.

Der Artikel richtet sich an Entwickler und Plattform-Teams, die bereits eine LLM-Anwendung betreiben oder kurz vor dem Produktivgang stehen und bisher ohne systematisches Monitoring auskommen mussten. Du brauchst keine Vorerfahrung mit Langfuse, solltest aber mit Docker, der Kommandozeile und mindestens einer Programmiersprache wie Python vertraut sein. Alle Befehle in diesem Tutorial wurden auf einem frischen Ubuntu-Server getestet und lassen sich direkt übernehmen.

Was ist Langfuse und warum lohnt sich Self-Hosting?

Langfuse ist eine Observability-Plattform speziell für LLM- und Agenten-Anwendungen. Sie zeichnet jeden Modellaufruf, jeden Tool-Call und jeden Zwischenschritt eines Agenten als durchsuchbare Telemetrie auf. Entwickler sehen damit nicht nur die finale Antwort eines Modells, sondern den kompletten Weg dorthin: welcher Prompt verschickt wurde, wie viele Tokens verbraucht wurden, was die Anfrage gekostet hat und wo im Ablauf ein Fehler aufgetreten ist. Dazu kommen Funktionen für Prompt-Verwaltung, automatisierte Evaluierungen, Testdatensätze und ein Playground zum direkten Ausprobieren von Prompts. Einen Überblick über alle Funktionsbereiche liefert die offizielle Dokumentation.

Technisch organisiert Langfuse Telemetriedaten in einer klaren Hierarchie. Ganz oben steht der Trace, der einen kompletten Nutzer-Request oder eine komplette Agenten-Session repräsentiert. Innerhalb eines Trace liegen einzelne Observations, etwa ein Modellaufruf, ein Tool-Call oder ein Zwischenschritt in einer Pipeline. Jede Observation kann wiederum eigene Metadaten tragen, etwa den verwendeten Modellnamen, die Temperatur-Einstellung oder benutzerdefinierte Tags. Diese Struktur erlaubt es, in einer komplexen Anwendung mit mehreren verschachtelten Aufrufen trotzdem den genauen Ursprung eines Fehlers oder einer unerwartet hohen Rechnung zu finden, statt nur eine grobe Gesamtlaufzeit zu sehen.

Der Kern von Langfuse steht unter einer offenen Lizenz und lässt sich kostenlos selbst hosten, ohne Limits bei den zentralen Funktionen. Das unterscheidet das Projekt von vielen kommerziellen Observability-Tools, die ihre Preise an Trace-Volumen koppeln. Teams mit Datenschutzanforderungen oder hohem Traffic sparen dadurch nicht nur Kosten, sie behalten auch die volle Kontrolle darüber, wo Prompts und Modellantworten gespeichert werden. Gerade in regulierten Branchen in Deutschland und der Schweiz ist das oft der ausschlaggebende Punkt für die Self-Hosting-Variante, zumal Prompts selbst sensible Daten enthalten können, wie wir im Tutorial zum Absichern von LLM-Systemen gezeigt haben.

Typische Einsatzszenarien für Langfuse in der Praxis

In der Praxis taucht Langfuse meist in drei wiederkehrenden Situationen auf. Der erste Fall ist Debugging bei RAG-Anwendungen: Ein Chatbot antwortet falsch, und niemand kann auf Anhieb sagen, ob der Fehler beim Retrieval, beim Prompt-Template oder beim Modell selbst liegt. Mit einem vollständigen Trace lässt sich jeder einzelne Schritt einsehen, vom abgerufenen Dokument bis zur finalen Antwort, wodurch sich die Fehlerquelle oft in wenigen Minuten statt Stunden eingrenzen lässt.

Der zweite Fall betrifft Agenten mit mehreren Tool-Aufrufen. Je mehr Schritte ein Agent selbstständig ausführt, desto schwerer wird es, manuell nachzuvollziehen, warum eine Aufgabe fehlgeschlagen ist oder unnötig viele Aufrufe verbraucht hat. Session-Traces zeigen die komplette Kette aus Entscheidungen und Tool-Ergebnissen in chronologischer Reihenfolge an, sodass sich Schleifen oder überflüssige Zwischenschritte direkt erkennen lassen.

Der dritte und für viele Finanzverantwortliche wichtigste Fall ist die Kostenkontrolle. Sobald mehrere Teams oder Produkte denselben Modellanbieter nutzen, verliert man ohne zentrales Tracing schnell den Überblick, welches Feature welchen Anteil der Rechnung verursacht. Mit Tags pro Projekt, Feature oder Kunde lässt sich diese Zuordnung automatisieren, statt sie am Monatsende händisch aus Rechnungen herauszulesen. In der Praxis treten die drei Szenarien selten isoliert auf: Ein Team, das zunächst nur Fehler debuggen wollte, baut sich nach wenigen Wochen fast automatisch ein eigenes Kostendashboard, weil die Daten ohnehin schon vorhanden sind.

Langfuse Cloud vs. Self-Hosting: Was kostet welche Variante?

Bevor du dich für den eigenen Betrieb entscheidest, lohnt sich ein Blick auf die Alternative. Langfuse bietet neben der Open-Source-Version auch eine gehostete Cloud-Variante mit gestaffelten Tarifen an. Abgerechnet wird dort nach sogenannten Units, wobei eine Unit einem Trace, einer Observation oder einem Score entspricht. Ein Agenten-Lauf mit vielen Tool-Aufrufen verbraucht also deutlich mehr Units als ein einfacher Prompt-Response-Zyklus. Die folgende Tabelle zeigt die aktuellen Tarife im Überblick.

Tarif	Preis	Inklusive Units/Monat	Besonderheiten
Hobby (Free)	0 $	50.000 Units	Für Tests und kleine Projekte
Core	29 $/Monat	100.000 Units	Unbegrenzte Nutzerzahl
Pro	199 $/Monat	volumenabhängig	Bis zu 3 Jahre Datenhistorie, Compliance-Zertifizierungen
Enterprise	ab 2.499 $/Monat	individuell	Volumenbasierte Preise, SSO, eigenes SLA
Self-Hosting (Open Source)	0 €	unbegrenzt	Eigene Infrastruktur, Kernfunktionen kostenlos

Für ein Team mit mehreren Millionen Traces pro Monat rechnet sich Self-Hosting fast immer schneller, als es die Tabelle vermuten lässt. Der Preis dafür ist Betriebsaufwand: Du verwaltst Datenbanken, Updates und Backups selbst. Wer wenig Traffic hat oder keine eigene Infrastruktur betreiben will, fährt mit der Cloud-Variante einfacher. Dieses Tutorial konzentriert sich auf den Self-Hosting-Weg, weil er den größten Lernwert bietet und langfristig die Kosten planbar macht. Wer bereits eigene LLM-Infrastruktur betreibt, etwa nach unserer Anleitung zum Self-Hosting von LLM Arena, kann Langfuse direkt in diese Umgebung integrieren.

Langfuse im Vergleich zu LangSmith, Helicone und Arize Phoenix

Langfuse ist nicht die einzige Option für LLM-Observability. LangSmith von LangChain verfolgt einen eher sitzplatzbasierten Ansatz und nennt für seinen Plus-Tarif einen Preis von 39 US-Dollar pro Nutzer und Monat, während Langfuse mit seinem Core-Tarif unabhängig von der Nutzerzahl abrechnet. Für Teams mit vielen Entwicklern, die nur gelegentlich in die Traces schauen, kann das einen deutlichen Unterschied machen, weil zusätzliche Sitzplätze bei Langfuse keine zusätzlichen Kosten verursachen.

Helicone positioniert sich stärker als Proxy-Lösung, die zwischen Anwendung und Modellanbieter geschaltet wird, während Arize Phoenix aus dem klassischen ML-Monitoring kommt und zusätzliche Funktionen für klassische Machine-Learning-Metriken mitbringt. Der entscheidende Unterschied bei Langfuse bleibt die vollständige Open-Source-Basis: Während bei den Wettbewerbern meist nur Teile des Produkts offen oder gar nicht selbst hostbar sind, lässt sich bei Langfuse der komplette Funktionsumfang ohne Cloud-Abhängigkeit betreiben. Wer sich nicht festlegen will, kann alle drei Alternativen parallel zu Langfuse testen, da die Instrumentierung über OpenTelemetry in vielen Fällen wiederverwendet werden kann. In der Praxis entscheidet meist weniger ein einzelnes Feature als die Frage, ob ein Team überhaupt eigene Infrastruktur betreiben will oder lieber eine Rechnung pro Nutzer akzeptiert.

Voraussetzungen: Diese Versionen und Ressourcen brauchst du

Bevor du den ersten Befehl eintippst, solltest du die folgende Liste durchgehen. Langfuse ist kein winziges Single-Binary-Tool, sondern ein Stack aus mehreren Diensten, und ein Teil der späteren Fehlersuche lässt sich allein durch saubere Vorbereitung vermeiden.

• Ein Linux-Server oder eine VM mit Ubuntu 22.04 bzw. 24.04 (oder einer vergleichbaren Distribution), auf der du Root- oder Sudo-Rechte hast
• Docker Engine ab Version 24.x und Docker Compose v2, da ältere Compose-Versionen einzelne der benötigten Syntax-Features nicht unterstützen
• Git zum Klonen des Repositories und für spätere Updates per git pull
• Mindestens 4 CPU-Kerne und 16 GiB RAM, zum Beispiel eine AWS-Instanz der Klasse t3.xlarge, eine vergleichbare Hetzner- oder Scaleway-Instanz, oder entsprechend dimensionierte Hardware im eigenen Rechenzentrum
• Davon sollten mindestens 8 GiB RAM allein für ClickHouse reserviert sein, den ressourcenhungrigsten Teil des Stacks, besonders sobald mehrere Projekte parallel Traces erzeugen
• Python 3.9 oder neuer beziehungsweise Node.js 18 oder neuer für die SDK-Integration in den späteren Schritten
• Ein offener Port für die Weboberfläche, üblicherweise 3000, sowie entsprechende Firewall-Regeln, falls der Server öffentlich erreichbar sein soll
• Für den Produktionsbetrieb später: ein Kubernetes-Cluster mit Helm, falls du über eine einzelne VM hinauswachsen willst oder von Anfang an Hochverfügbarkeit brauchst

Die offizielle Docker-Compose-Variante ist für lokale Tests und den Betrieb auf einer einzelnen VM gedacht. Wer von Anfang an hochverfügbar fahren will, sollte direkt mit dem Kubernetes-Helm-Chart planen. Für dieses Tutorial reicht die einfache Compose-Variante, die sich später bei Bedarf migrieren lässt.

Schritt 1 bis 3: Server vorbereiten, Docker installieren, Repository klonen

Die ersten drei Schritte sind schnell erledigt. Zuerst prüfst du, ob Docker Compose bereits installiert ist, danach holst du dir den aktuellen Code aus dem offiziellen Repository.

# Docker-Version prüfen
docker --version
docker compose version

# Falls nicht installiert, auf Ubuntu nachrüsten
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Repository klonen und in das Verzeichnis wechseln
git clone https://github.com/langfuse/langfuse.git
cd langfuse

Nach dem usermod-Befehl musst du dich einmal ab- und wieder anmelden, sonst läuft Docker weiter nur mit sudo-Rechten. Das wird in vielen Tutorials vergessen und führt direkt zum ersten unnötigen Fehlerbericht in der Konsole.

Schritt 4 bis 6: Umgebungsvariablen konfigurieren und Stack starten

Langfuse liefert eine Beispiel-Umgebungsdatei mit, die du kopierst und an deine Umgebung anpasst. Mindestens drei Werte musst du selbst setzen: die öffentliche URL, ein Secret für die Authentifizierung und einen Salt-Wert für die Verschlüsselung sensibler Felder.

# .env aus der Vorlage erzeugen
cp .env.example .env

# Secret und Salt generieren
openssl rand -base64 32   # für NEXTAUTH_SECRET
openssl rand -base64 32   # für SALT

Trage die generierten Werte in die .env-Datei ein. Ein typischer Auszug für eine lokale Testinstallation sieht so aus:

# .env (Auszug)
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=
SALT=
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse-events

Danach startest du den kompletten Stack im Hintergrund und prüfst, ob alle Container fehlerfrei hochfahren.

docker compose up -d
docker compose ps

Beim ersten Start lädt Docker mehrere Images herunter und führt die Datenbankmigrationen für PostgreSQL und ClickHouse aus. Das kann je nach Internetverbindung und Servergeschwindigkeit zwischen zwei und zehn Minuten dauern. Ungeduld an dieser Stelle ist der häufigste Grund, warum Einsteiger den Stack vorzeitig abbrechen und danach von kaputten Datenbanken berichten. Eine erfolgreiche Installation zeigt bei docker compose ps für jeden Dienst den Status “running” oder “healthy” an, etwa so:

NAME                 STATUS
langfuse-web-1       Up 2 minutes (healthy)
langfuse-worker-1    Up 2 minutes
langfuse-postgres-1  Up 2 minutes (healthy)
langfuse-clickhouse-1 Up 2 minutes (healthy)
langfuse-redis-1     Up 2 minutes (healthy)

Zeigt einer der Dienste stattdessen “Restarting” oder “Exited” an, lohnt sich sofort ein Blick in die Logs des betroffenen Containers, bevor du weitere Schritte ausführst. Erfahrungsgemäß ist in über der Hälfte dieser Fälle schlicht zu wenig Arbeitsspeicher der Grund, gefolgt von falsch gesetzten Umgebungsvariablen und, seltener, Netzwerkkonflikten mit bereits belegten Ports auf dem Host.

Schritt 7 und 8: Ersten Login durchführen, Organisation und Projekt anlegen

Sobald alle Container laufen, rufst du die Weboberfläche unter http://localhost:3000 auf. Beim ersten Besuch fragt Langfuse nach einem Administratorkonto. Lege hier ein Passwort an, das du dir merkst, denn es gibt in der selbstgehosteten Variante standardmäßig keinen automatischen Passwort-Reset per E-Mail, solange du keinen SMTP-Server konfiguriert hast.

Nach dem Login legst du eine Organisation an, danach ein Projekt innerhalb dieser Organisation. Projekte sind die zentrale Trennlinie in Langfuse: Jedes Projekt hat eigene API-Keys, eigene Traces und eigene Einstellungen. Für ein Team mit mehreren Anwendungen bietet es sich an, pro Anwendung ein eigenes Projekt zu führen, statt alles in einem großen Topf zu sammeln. Lege außerdem von Anfang an feste Rollen für dein Team fest: Wer darf neue Mitglieder einladen, wer darf Projekteinstellungen ändern, und wer soll nur lesend auf Traces zugreifen können. Diese Entscheidung lässt sich später nachträglich ändern, spart dir aber beim ersten echten Produktionsvorfall wertvolle Zeit, wenn klar ist, wer welche Berechtigung hat.

Schritt 9 und 10: API-Keys generieren und Python-SDK integrieren

Im Projekt-Dashboard findest du unter den Einstellungen den Bereich für API-Keys. Dort erzeugst du einen Public Key und einen Secret Key. Beide brauchst du, um dein Code-Projekt mit der Langfuse-Instanz zu verbinden. Installiere zunächst das Python-Paket.

pip install langfuse

Mit dem Decorator-Ansatz lässt sich jede Python-Funktion ohne großen Umbau zu einem Trace machen. Das folgende Beispiel zeigt die minimale Integration:

from langfuse import Langfuse, observe

langfuse = Langfuse(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="http://localhost:3000"
)

@observe()
def generate_antwort(frage: str) -> str:
    antwort = f"Verarbeitete Antwort auf: {frage}"
    return antwort

generate_antwort("Wie funktioniert Self-Hosting?")
langfuse.flush()

Der Aufruf von flush() am Ende ist kein kosmetisches Detail. Ohne ihn sendet das SDK Daten asynchron im Hintergrund, und bei kurzlebigen Skripten oder Serverless-Funktionen kann der Prozess beendet werden, bevor die Daten tatsächlich übertragen wurden. Genau das ist einer der häufigsten Gründe, warum Traces scheinbar im Nichts verschwinden.

Schritt 11: Ersten Trace erzeugen und in der Oberfläche analysieren

Führe das Python-Skript aus Schritt 10 aus und wechsle danach zurück in die Langfuse-Oberfläche. Im Menüpunkt Traces sollte innerhalb weniger Sekunden ein neuer Eintrag erscheinen. Ein typischer Trace zeigt dir folgende Informationen auf einen Blick:

Trace: generate_antwort
Status: success
Dauer: 0,04s
Input: {"frage": "Wie funktioniert Self-Hosting?"}
Output: {"antwort": "Verarbeitete Antwort auf: Wie funktioniert Self-Hosting?"}
Tokens: 0 (reine Funktion, kein Modellaufruf)
Kosten: 0,00 $

Sobald du echte Modellaufrufe über die unterstützten Integrationen einbindest, etwa das OpenAI-SDK oder LangChain, ergänzt Langfuse automatisch Tokenzahlen und geschätzte Kosten pro Aufruf. Du klickst dich dann direkt vom Trace in die einzelnen Spans, siehst den exakten Prompt-Text und kannst mehrere Versionen desselben Prompts nebeneinander vergleichen. Über die Filterleiste lassen sich Traces zusätzlich nach Zeitraum, Nutzer, Tag oder Status einschränken, was bei wachsendem Trace-Volumen schnell zum wichtigsten Werkzeug im Alltag wird, weil die reine Listenansicht ab einigen Tausend Einträgen pro Tag unübersichtlich wird.

Schritt 12: OpenTelemetry-Instrumentierung für bestehende Anwendungen

Nicht jedes Projekt will sich an ein proprietäres SDK binden. Deshalb unterstützt Langfuse auch den Standardweg über OpenTelemetry. Anwendungen, die bereits mit dem OpenTelemetry-Python-SDK instrumentiert sind, können ihre Spans direkt an den Langfuse-OTLP-Endpunkt exportieren, ohne die bestehende Anwendungslogik umzubauen.

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(endpoint="http://localhost:3000/api/public/otel/v1/traces")
    )
)
trace.set_tracer_provider(provider)

Dieser Ansatz lohnt sich besonders für Teams, die bereits eine bestehende Observability-Pipeline mit OpenTelemetry betreiben und Langfuse nur als zusätzlichen Exporter für LLM-spezifische Daten einhängen wollen, statt zwei getrennte Systeme zu pflegen.

Unterstützte Frameworks und Integrationen im Überblick

Ein Grund für die Verbreitung von Langfuse ist die Bandbreite an Integrationen, die sich ohne große Umbauten an bestehenden Code anbinden lassen. Neben den direkten SDKs für Python und JavaScript/TypeScript gibt es fertige Anbindungen für die gängigsten Frameworks im LLM-Ökosystem. Die folgende Tabelle zeigt, über welchen Weg sich die jeweilige Integration typischerweise einbinden lässt.

Framework/SDK	Integrationsweg	Typischer Einsatz
Python SDK	Decorator (@observe) oder manuelles Logging	Eigene Backend-Services und Skripte
JS/TS SDK	Wrapper-Funktionen für Node- und Edge-Umgebungen	Next.js- und Node-Anwendungen
LangChain	Callback-Handler	Chains und Agenten-Pipelines
LlamaIndex	Callback-Handler	Retrieval- und Query-Engines
OpenAI SDK	Drop-in-Wrapper um den Client	Direkte Modellaufrufe ohne Framework
OpenTelemetry	OTLP-Exporter an den Langfuse-Endpunkt	Bestehende Observability-Pipelines

Für Teams, die bereits eine Integration aus einer bestehenden Observability-Lösung pflegen, ist der OpenTelemetry-Weg meist der pragmatischste Einstieg, weil sich die vorhandene Instrumentierung weiterverwenden lässt und nur ein zusätzlicher Exporter konfiguriert werden muss.

Evaluations, Datasets und Prompt Management nutzen

Tracing allein beantwortet nicht die Frage, ob eine Antwort inhaltlich gut war. Dafür bringt Langfuse drei zusammenhängende Funktionen mit. Mit Datasets legst du feste Test- und Bewertungsfälle an, die du immer wieder gegen neue Prompt- oder Modellversionen laufen lässt, ähnlich dem Testaufbau aus unserem Tutorial zum Einrichten von LlamaIndex mit Qdrant. Evaluations bewerten einzelne Traces oder ganze Sessions, entweder über eigene Scoring-Funktionen oder über ein Modell, das als Bewerter fungiert. Annotation Queues erlauben es Teammitgliedern, Ausgaben manuell zu markieren, etwa für ein Review vor dem Produktions-Rollout.

Das integrierte Prompt Management versioniert deine Prompts zentral, sodass du nicht mehr riskierst, einen Prompt lokal im Code zu ändern, während eine andere Umgebung noch die alte Version verwendet. Über den eingebauten Playground kannst du neue Prompt-Versionen direkt gegen reale, zuvor aufgezeichnete Eingaben testen, bevor sie live gehen. In Kombination mit Experiment-Workflows lassen sich Änderungen an Prompts, Modellen oder Agentenlogik so vergleichbar auswerten, ohne jedes Mal ein komplettes manuelles Testprotokoll aufzusetzen.

Eine einzelne Evaluation liefert in der Oberfläche einen kompakten Datensatz, den du direkt weiterverarbeiten oder exportieren kannst. Ein Beispiel für das Ergebnis einer automatisierten Bewertung sieht typischerweise so aus:

Evaluation: antwort_relevanz
Trace-ID: a1b2c3d4
Score: 0.87
Bewertungsmethode: LLM-as-a-Judge
Kommentar: "Antwort behandelt die Nutzerfrage vollständig, geringer Abzug wegen fehlender Quellenangabe"
Dataset: support-tickets-september

Solche Scores lassen sich über die Zeit aggregieren, sodass du zum Beispiel erkennst, ob eine neue Prompt-Version die durchschnittliche Relevanz verbessert oder verschlechtert hat, bevor du sie für alle Nutzer ausrollst.

Datenschutz und Sicherheit beim Self-Hosting

Ein Trace in Langfuse enthält standardmäßig den vollständigen Prompt-Text und die komplette Modellantwort. Das ist für die Fehlersuche unverzichtbar, bedeutet aber auch, dass personenbezogene Daten, Geschäftsgeheimnisse oder interne Dokumente in der Datenbank landen können, sobald sie Teil einer Konversation waren. Bevor du Langfuse an eine Produktionsanwendung anbindest, solltest du deshalb klären, welche Felder maskiert werden müssen und wer in deinem Team Zugriff auf die Oberfläche braucht.

Langfuse bietet dafür serverseitiges Masking, mit dem sich bestimmte Muster wie E-Mail-Adressen oder Kreditkartennummern vor dem Speichern automatisch ersetzen lassen. Zusätzlich lohnt sich eine rollenbasierte Zugriffssteuerung, damit nicht jedes Teammitglied automatisch alle Projekte und damit alle Kundendaten sehen kann. Wer die Plattform selbst hostet, trägt zudem die volle Verantwortung für Betriebssystem-Updates, Netzwerksegmentierung und TLS-Konfiguration, da hier anders als bei der Cloud-Variante kein Anbieter diese Aufgaben automatisch übernimmt. Für Unternehmen, die unter die NIS2-Richtlinie oder branchenspezifische Vorgaben fallen, lohnt sich zusätzlich eine Dokumentation, welche Datenkategorien in Langfuse landen und wie lange sie dort aufbewahrt werden, damit diese Angaben bei einer Audit-Anfrage sofort verfügbar sind.

Produktionsbetrieb: Kubernetes, Skalierung, Backups und Updates

Die Docker-Compose-Installation aus den ersten Schritten eignet sich für Tests, kleinere Teams und einzelne Projekte. Für hochverfügbare Produktionsumgebungen empfiehlt Langfuse selbst den Wechsel auf Kubernetes mit dem offiziellen Helm-Chart. Das erlaubt horizontale Skalierung der einzelnen Dienste, getrennte Ressourcenlimits pro Komponente und ein saubereres Rolling-Update-Verhalten bei neuen Versionen.

Helm-Chart und horizontale Skalierung

Das offizielle Helm-Chart trennt die Web-Oberfläche, den Worker-Prozess für asynchrone Jobs und die Datenbankanbindung in eigene Deployments. Dadurch lässt sich zum Beispiel die Anzahl der Worker-Pods unabhängig von der Web-Oberfläche hochskalieren, wenn viel Trace-Volumen anfällt, aber nur wenige Nutzer gleichzeitig im Dashboard arbeiten. ClickHouse selbst wird in größeren Setups meist als eigener Cluster außerhalb des Helm-Charts betrieben, etwa über einen verwalteten ClickHouse-Dienst oder ein eigenes Cluster-Deployment.

Zero-Downtime-Updates planen

Bei einer einzelnen Docker-Compose-Instanz bedeutet jedes Update einen kurzen Ausfall, weil Container neu gestartet werden. In Kubernetes lässt sich das mit mehreren Replikas der Web-Komponente und einer Rolling-Update-Strategie vermeiden, sodass immer mindestens ein Pod erreichbar bleibt, während die anderen aktualisiert werden. Teste neue Versionen vor dem Produktions-Rollout grundsätzlich zuerst in einer Staging-Umgebung, da Datenbankmigrationen bei ClickHouse nicht in jedem Fall rückwärtskompatibel sind.

Unabhängig von der Deployment-Variante bleibt der zugrunde liegende Stack gleich. Die folgende Tabelle zeigt, welche Komponente welche Aufgabe übernimmt und worauf du bei der Ressourcenplanung achten solltest.

Komponente	Rolle im Stack	Ressourcen-Hinweis
PostgreSQL	Relationale Metadaten: Projekte, Nutzer, Konfiguration	Teil der 16 GiB Gesamtempfehlung
ClickHouse	Analytische Speicherung und Abfrage der Trace-Daten	mindestens 8 GiB RAM allein hierfür
Redis	Queueing und asynchrone Verarbeitung	Teil der 16 GiB Gesamtempfehlung
S3-kompatibler Objektspeicher	Ablage großer Payloads wie Prompts und Dateien	abhängig vom gewählten Provider

Für Backups genügt es nicht, nur die PostgreSQL-Datenbank zu sichern. ClickHouse-Volumes und der S3-Bucket enthalten den Großteil deiner historischen Traces, und ein Verlust dieser Daten lässt sich im Nachhinein nicht rekonstruieren. Richte deshalb von Anfang an einen regelmäßigen Snapshot- oder Export-Job für alle drei Speicherorte ein, nicht nur für die relationale Datenbank. Teste den Restore-Prozess mindestens einmal, bevor du dich im Ernstfall darauf verlassen musst, denn ein Backup, das sich nicht zurückspielen lässt, ist in der Praxis wertlos.

Benachrichtigungen und Monitoring einrichten

Ein Dashboard bringt wenig, wenn niemand hineinschaut, bevor ein Kunde sich beschwert. Richte deshalb Alerts für die Kennzahlen ein, die in deinem Setup am ehesten auf Probleme hindeuten: eine plötzlich steigende Fehlerquote bei Modellaufrufen, ungewöhnlich lange Latenzen oder ein sprunghafter Anstieg der täglichen Kosten. Da Langfuse selbst primär als Observability-Plattform und nicht als vollwertiges Alerting-System gedacht ist, lohnt sich die Kombination mit einem externen Monitoring-Tool, das die über die API oder OpenTelemetry exportierten Metriken auswertet und bei Schwellenwertüberschreitung eine Nachricht an Slack, E-Mail oder einen Pager-Dienst schickt.

Praktisch bewährt sich ein einfacher täglicher Report, der die wichtigsten Kennzahlen aus den Traces des Vortags zusammenfasst: Gesamtkosten, Anteil fehlgeschlagener Aufrufe und die am häufigsten verwendeten Prompt-Versionen. So ein Report lässt sich mit wenigen Zeilen Code über die Langfuse-API erzeugen und etwa per Cron-Job jeden Morgen verschicken, ohne dass jemand manuell in die Oberfläche schauen muss. Gerade in der ersten Woche nach dem Go-Live eines neuen Features lohnt sich ein genauerer Blick, weil sich dort ungewöhnliche Nutzungsmuster oder unerwartet hohe Kosten am schnellsten zeigen, bevor sie sich zu einem größeren Problem auswachsen.

5 häufige Fehler beim Langfuse-Self-Hosting

Die meisten Probleme bei der Selbsthostung lassen sich auf eine Handvoll wiederkehrender Fehler zurückführen. Sie tauchen in Supportforen und internen Slack-Kanälen immer wieder in denselben Varianten auf, meist weil die Dokumentation an dieser Stelle überflogen statt gelesen wurde. Wer diese Fehler vorab kennt, spart sich mehrere Stunden Fehlersuche und einen frustrierten ersten Eindruck vom Tool.

• Zu knapp bemessene Server-Ressourcen: Wer den Stack auf einer 2-GB-RAM-VM startet, weil “es ja nur ein Dashboard ist”, landet fast immer bei einem abstürzenden ClickHouse-Container. Plane die empfohlenen 16 GiB fest ein und beobachte in den ersten Tagen die tatsächliche Auslastung, statt dich allein auf die Empfehlung zu verlassen.
• Falsche NEXTAUTH_URL: Wird die URL nicht exakt an die tatsächliche Domain oder den Port angepasst, schlägt der Login mit kryptischen Weiterleitungsfehlern fehl, obwohl alle Container laufen. Besonders hinter einem Reverse-Proxy wird dieser Wert oft übersehen, weil er in der lokalen Testumgebung noch korrekt war.
• Nicht persistente Volumes: Wer Docker-Compose-Volumes nicht explizit mountet, verliert bei einem Container-Neustart sämtliche Traces und Konfigurationen, ohne vorher gewarnt zu werden. Ein kurzer Blick in die docker-compose.yml vor dem ersten Produktionsstart erspart diesen Schock zuverlässig.
• API-Keys im Quellcode statt in Umgebungsvariablen: Secret Keys landen zu oft direkt im Repository, weil es beim ersten Test schneller geht. Spätestens vor dem ersten Commit gehören sie in .env-Dateien oder einen Secret-Manager, da ein versehentlich gepushtes Secret sich im Git-Verlauf nur schwer vollständig entfernen lässt.
• Reverse-Proxy ohne korrektes TLS-Setup: Wird HTTPS über einen Proxy wie nginx oder Traefik nicht vollständig terminiert, entstehen Session-Cookie-Fehler, die wie ein Login-Bug aussehen, aber tatsächlich ein Zertifikatsproblem sind. Prüfe in diesem Fall zuerst die Proxy-Header, bevor du die Anwendung selbst verdächtigst.

Troubleshooting: 8 häufige Probleme und ihre Lösungen

Auch mit sauberer Vorbereitung läuft nicht jede Installation auf Anhieb durch. Die folgende Liste deckt die Probleme ab, die in Self-Hosting-Setups am häufigsten auftreten, zusammen mit dem jeweils schnellsten Weg zur Lösung, ohne gleich das komplette Deployment neu aufzusetzen.

1. Container startet und stoppt sofort wieder: Prüfe die Logs mit docker compose logs clickhouse. In den meisten Fällen fehlt Arbeitsspeicher oder ein Pfad für persistente Daten ist nicht beschreibbar. Ein docker system df gibt zusätzlich Aufschluss, ob der Festplattenspeicher des Hosts bereits knapp wird.
2. Connection refused zu ClickHouse: Die Anwendung startet oft schneller als die Datenbank. Warte nach docker compose up mindestens 60 Sekunden, bevor du die Oberfläche testest, oder ergänze depends_on mit Healthchecks, damit Docker selbst auf die Bereitschaft wartet.
3. Login schlägt nach dem Deployment fehl: Kontrolliere, ob NEXTAUTH_URL exakt dem Schema, der Domain und dem Port entspricht, über den du tatsächlich zugreifst, inklusive http versus https. Ein Tippfehler in dieser einen Variable ist die mit Abstand häufigste Ursache für Login-Probleme nach einem Deployment.
4. Traces erscheinen nicht in der Oberfläche: Stelle sicher, dass langfuse.flush() im Code aufgerufen wird, besonders bei kurzlebigen Skripten, Lambda-Funktionen oder CI-Jobs. Prüfe zusätzlich, ob Public und Secret Key zum richtigen Projekt gehören.
5. Hohe Speicherauslastung über mehrere Tage: ClickHouse wächst mit jedem Trace. Richte eine Retention-Policy ein, die alte Rohdaten nach einem festen Zeitraum komprimiert oder archiviert, statt den Datenbestand unbegrenzt anwachsen zu lassen.
6. SSL-Zertifikatsfehler im Browser: Bei selbstsignierten Zertifikaten in Testumgebungen musst du das Zertifikat explizit im Client-Trust-Store hinterlegen, sonst blockieren moderne Browser die Verbindung komplett. Für den Produktionsbetrieb empfiehlt sich stattdessen ein Zertifikat über Let’s Encrypt.
7. Fehlgeschlagene Datenbankmigration bei PostgreSQL: Führe die Migration manuell mit den im Repository dokumentierten Befehlen erneut aus und prüfe, ob eine ältere Schema-Version blockiert. Ein Downgrade auf eine ältere Langfuse-Version kann die Migration in seltenen Fällen zusätzlich erschweren.
8. API-Aufrufe liefern 401 Unauthorized: Prüfe, ob Public und Secret Key aus demselben Projekt stammen. Keys aus unterschiedlichen Projekten lassen sich nicht mischen, auch nicht innerhalb derselben Organisation, da jedes Projekt seinen eigenen Schlüsselsatz verwaltet.

Fortgeschrittene Tipps: Kosten senken und Performance optimieren

Sobald der Stack stabil läuft, lohnt sich der Blick auf den laufenden Betrieb und auf Stellschrauben, die sich erst nach ein paar Wochen Praxisbetrieb bemerkbar machen.

Sampling-Strategien für hohes Trace-Volumen

Richte Sampling für sehr hochfrequente Endpunkte ein, statt jeden einzelnen Request zu tracen. Ein Sampling-Satz von 10 bis 20 Prozent reicht in vielen Fällen aus, um Trends und Ausreißer zu erkennen, ohne ClickHouse unnötig zu belasten. Wichtig ist, Fehlerfälle unabhängig vom Sampling-Satz immer vollständig zu erfassen, da genau diese Traces später bei der Fehlersuche gebraucht werden. Trenne außerdem Entwicklungs-, Staging- und Produktionsumgebungen in eigene Projekte, statt alles gemeinsam zu tracen. Das verhindert, dass Testdaten deine Produktionskennzahlen verzerren.

Multi-Tenancy für Agenturen und mehrere Kunden

Agenturen und Dienstleister, die LLM-Anwendungen für mehrere Kunden gleichzeitig betreiben, legen am besten für jeden Kunden eine eigene Organisation statt nur ein eigenes Projekt an. Das trennt nicht nur die Daten strikt, sondern erlaubt auch, Zugriffsrechte pro Kunde granular zu vergeben, ohne dass ein Mitarbeiter versehentlich Traces eines anderen Kunden sieht. Für Teams mit mehreren Anwendungen lohnt sich zusätzlich ein zentrales Tagging-Schema über alle Traces hinweg, zum Beispiel nach Umgebung, Feature und Nutzergruppe. So lassen sich Kosten und Fehlerraten später gefiltert auswerten, ohne nachträglich jeden Trace manuell zu klassifizieren. Wer die Kosten pro Feature im Blick behalten will, sollte zusätzlich die automatische Kostenberechnung pro Modellanbieter aktivieren und regelmäßig im Dashboard gegen das eigene Budget prüfen, statt erst am Monatsende von der Rechnung überrascht zu werden.

Komplettes Beispielprojekt: Chatbot mit vollständigem Tracing

Zum Abschluss ein kompaktes, lauffähiges Beispiel: ein einfacher FastAPI-Endpunkt, der eine Chat-Anfrage entgegennimmt, verarbeitet und dabei vollständig über Langfuse getrackt wird. Dieses Grundgerüst lässt sich direkt um einen echten Modellaufruf erweitern.

from fastapi import FastAPI
from pydantic import BaseModel
from langfuse import Langfuse, observe

app = FastAPI()
langfuse = Langfuse(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="http://localhost:3000"
)

class ChatRequest(BaseModel):
    nachricht: str

@observe(name="chat_anfrage")
def verarbeite_nachricht(nachricht: str) -> str:
    # Hier würde normalerweise der Aufruf an ein LLM erfolgen
    return f"Antwort auf: {nachricht}"

@app.post("/chat")
def chat_endpoint(request: ChatRequest):
    antwort = verarbeite_nachricht(request.nachricht)
    langfuse.flush()
    return {"antwort": antwort}

Starte die Anwendung lokal mit uvicorn main:app –reload und sende einen Test-Request an den /chat-Endpunkt. Jeder Aufruf erzeugt automatisch einen Trace mit Eingabe, Ausgabe und Laufzeit in deiner Langfuse-Instanz. Um die Platzhalterfunktion durch einen echten Modellaufruf zu ersetzen, reicht in der Regel der gewrappte OpenAI-Client, wie im folgenden Ausschnitt gezeigt.

from langfuse.openai import openai

@observe(name="chat_anfrage")
def verarbeite_nachricht(nachricht: str) -> str:
    response = openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": nachricht}]
    )
    return response.choices[0].message.content

Durch den Import aus langfuse.openai statt dem regulären OpenAI-Paket übernimmt Langfuse automatisch Tokenzahlen, Modellname und geschätzte Kosten pro Request, ohne dass du diese Werte selbst berechnen musst. Für Anthropic-Modelle oder lokal gehostete Alternativen funktioniert das Prinzip über die jeweilige Integration analog.

Damit hast du eine vollständige Kette vom Server-Setup über die erste Trace-Analyse bis zur produktionsnahen Anwendung durchlaufen. Der nächste logische Schritt ist, echte Evaluierungen auf Basis realer Nutzeranfragen aufzusetzen und die Ergebnisse in den Dataset-Funktionen zu sammeln, bevor du neue Prompt-Versionen produktiv ausrollst. Weitere Tutorials rund um den Betrieb eigener KI-Infrastruktur findest du in unserer Rubrik KI & Machine Learning.

FAQ: Häufige Fragen zu Langfuse

Ist Langfuse komplett kostenlos, wenn ich es selbst hoste?
Die Kernfunktionen des Open-Source-Projekts lassen sich ohne Lizenzkosten und ohne künstliche Limits selbst hosten. Du zahlst lediglich für die eigene Infrastruktur, also Server, Speicher und Netzwerk. Einzelne Enterprise-Funktionen wie erweiterte SSO-Optionen bleiben allerdings der kommerziellen Lizenz vorbehalten.

Brauche ich zwingend Kubernetes für den Einstieg?
Nein. Für Tests, kleinere Teams und einzelne Projekte reicht die Docker-Compose-Installation auf einer einzelnen VM vollkommen aus. Kubernetes mit Helm wird erst relevant, wenn du Hochverfügbarkeit und horizontale Skalierung brauchst, etwa weil mehrere Anwendungen gleichzeitig hohe Trace-Mengen erzeugen.

Welche Programmiersprachen unterstützt Langfuse?
Offizielle SDKs gibt es für Python und JavaScript beziehungsweise TypeScript. Darüber hinaus lässt sich jede Anwendung, die bereits mit OpenTelemetry instrumentiert ist, über den OTLP-Endpunkt anbinden, unabhängig von der verwendeten Sprache.

Wie viel RAM brauche ich für eine produktive Installation?
Langfuse empfiehlt in der eigenen Docker-Compose-Dokumentation mindestens 4 CPU-Kerne und 16 GiB RAM für den gesamten Stack, wobei ClickHouse allein mindestens 8 GiB davon beanspruchen sollte.

Was passiert, wenn ich langfuse.flush() vergesse?
Da das SDK Daten standardmäßig asynchron im Hintergrund sendet, können Traces bei kurzlebigen Prozessen oder Serverless-Funktionen verloren gehen, wenn der Prozess vor der Übertragung beendet wird. flush() erzwingt das sofortige Senden.

Kann ich Langfuse mit LangChain oder LlamaIndex nutzen?
Ja, beide Frameworks lassen sich über entsprechende Callback-Handler an Langfuse anbinden, sodass Chains und Abfragen automatisch als Traces erscheinen, ohne jede Komponente einzeln zu instrumentieren. Das reduziert den Integrationsaufwand gegenüber einer komplett manuellen Instrumentierung erheblich.

Lohnt sich Self-Hosting auch für kleine Teams?
Das hängt vom Traffic ab. Bei geringem Volumen deckt der kostenlose Cloud-Tarif mit 50.000 Units pro Monat oft den Bedarf. Erst wenn dieses Limit regelmäßig überschritten wird oder Datenschutzanforderungen eigene Infrastruktur verlangen, wird Self-Hosting wirtschaftlich interessant.

Wie sicher sind Backups bei einer selbstgehosteten Installation?
Nur so sicher, wie du sie selbst einrichtest. Du musst PostgreSQL, ClickHouse-Volumes und den S3-Bucket separat in deine Backup-Strategie einbeziehen, da alle drei unterschiedliche Teile deiner Trace-Historie speichern.

Kann ich später von der Cloud-Variante zu Self-Hosting wechseln?
Ein direkter Umzug bestehender Traces zwischen Cloud und Self-Hosting ist nicht ohne Weiteres vorgesehen, da beide Varianten getrennte Datenbanken verwenden. Neue Projekte lassen sich aber jederzeit parallel auf der jeweils anderen Variante anlegen, sodass sich ein Wechsel für zukünftige Traces unkompliziert umsetzen lässt.

Funktioniert Langfuse auch mit Streaming-Antworten?
Ja, die SDKs unterstützen das Tracen von gestreamten Modellantworten. Dabei wird der komplette zusammengesetzte Text am Ende als Observation gespeichert, während die Latenzmessung bereits mit dem ersten empfangenen Token beginnt, was bei der Analyse der gefühlten Antwortzeit hilft.