AI-Agenten lokal monitoren: Langfuse + OpenTelemetry, ganz ohne Cloud-Account

Dein Agent läuft in der Demo einwandfrei. Du bringst ihn live. Dann geht in Produktion irgendwas schief, und du hast nichts, woran du dich orientieren kannst — kein Protokoll, welche Tools er aufgerufen hat, was dabei rauskam, wo in der Kette es tatsächlich gebrochen ist.

Langfuse, ein Open-Source-LLM-Monitoring-Tool, löst das — und du kannst das Ganze komplett lokal mit Docker betreiben, kein Cloud-Account nötig, um loszulegen.

Die OpenTelemetry-Basics, die du wirklich brauchst#

Langfuse baut auf OpenTelemetry auf, einem offenen Standard zur Instrumentierung verteilter Systeme — eine Sammlung von APIs, SDKs und Tools zum Sammeln von Metriken, Logs und Traces, gebaut für Produktionseinsatz über Sprachen hinweg. Drei Begriffe sind hier wichtig:

Span — eine Arbeitseinheit.
Trace — der gesamte Lebenszyklus einer Anfrage, Anfang bis Ende. Bei einem Agenten also vom Moment, in dem du einen Prompt schickst, bis zur finalen Antwort.
Span Processor — sammelt die Spans und lässt dich sie inspizieren oder verändern, bevor sie rausgeschickt werden.

Ein Tradeoff, den du kennen solltest, bevor du irgendeinen Beispielcode kopierst: es gibt zwei Span Processors, simple und batch. Simple verarbeitet Spans einzeln — gut fürs lokale Debuggen, wo du jeden sofort sehen willst. Unter echter Produktionslast willst du stattdessen batch, das Spans zusammenfasst statt sie einzeln zu verschicken. Simple in Dev, vor dem Go-Live auf batch wechseln.

Der Exporter nimmt die gesammelten Spans, verpackt sie ins OpenTelemetry-Standardformat und schickt sie an deinen Provider — hier Langfuse.

Im Video#

00:35 — Was OpenTelemetry eigentlich ist: Spans, Traces, Span Processors
04:33 — Langfuse lokal mit Docker und Docker Compose aufsetzen
07:27 — Account, Organisation, Projekt anlegen und die API-Keys holen
10:23 — Der Instrumentierungs-Code: Instrumentor importieren, Tracer Provider verdrahten
13:00 — Den Agenten laufen lassen und den ersten Trace im Dashboard sehen

Lokal aufsetzen#

Du brauchst Docker und Docker Compose installiert. Klon das Langfuse-Repo — dort liegt die docker-compose.yml — und führ aus:

bash

docker compose up

Das startet jeden Service, den Langfuse braucht: ClickHouse, Redis, die Langfuse-Web-App und den Worker. Sobald die Container laufen, geh auf localhost:3000, meld dich an und durchlauf den Setup-Wizard: Organisation anlegen, dann ein Projekt. Am Ende bekommst du einen Secret Key (sk-...) und einen Public Key (pk-...) zurück — die zwei Dinge, die du wirklich brauchst.

In deinen Agenten verdrahten#

Secret- und Public-Key zusammen Base64-encodieren, und zwei Umgebungsvariablen setzen:

bash

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3000/api/public/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64-encoded-keys>"

(Endpoint gegen https://cloud.langfuse.com/... oder das US-Region-Äquivalent tauschen, falls du die Managed-Version statt Self-Hosting nutzt.)

Dann, im Code — das Beispiel hier nutzt smolagents, aber das Pattern gilt für jedes Framework mit OpenTelemetry-Support:

python

from smolagents import SmolagentsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 
trace_provider = TracerProvider()
trace_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter()))
 
SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)

Das war's. Keine manuellen Logging-Statements, verstreut über deinen Agenten-Code — eine gute Framework-Integration wrapped die relevanten Methoden automatisch, sobald du instrument() aufrufst.

Den ersten Trace anschauen#

Agent laufen lassen, dann im Langfuse-Dashboard unter Traces nachschauen. In den Run reinklicken, und du siehst den kompletten Lebenszyklus: jeden Tool-Call, jeden Zwischenschritt, in Reihenfolge, vom eingehenden Prompt bis zur finalen Antwort.

Worum es eigentlich geht#

Das ist kein Debugging-Tool nur für den Moment, wenn schon was kaputt ist. Setz es auf, bevor du live gehst, und du bekommst in Produktion denselben Einblick, den du beim lokalen Bauen hattest — welches Tool aufgerufen wurde, was zurückkam, und genau wo ein Run entgleist ist, statt eines Support-Tickets und einer Vermutung.