Observability¶

Agentlab integriert sich für Flow-Tracing und Observability mit Langfuse. So lassen sich Flow-Ausführungen beobachten, Engpässe erkennen und Fehler diagnostizieren.

Was getraced wird¶

Bei einem Flow-Run erfasst Langfuse:

Flow-Execution-Spans — der Gesamtlauf des Flows mit Timing und Status.
Komponenten-Spans — einzelne Komponentenausführungen innerhalb des Flows.
LLM-Calls — Modellaufrufe inklusive Prompts, Completions, Token-Nutzung und Latenz.

Prometheus-Metriken¶

Unabhängig von Langfuse kann jede Instanz LLM- und Flow-Nutzung als Prometheus-Metriken bereitstellen. Das funktioniert mit und ohne konfiguriertes Langfuse — beides ist voneinander unabhängig.

Aktivierung über LANGFLOW_PROMETHEUS_ENABLED=true. Die Metriken werden auf LANGFLOW_PROMETHEUS_PORT (Standard 9090) unter /metrics ausgeliefert.

Was bereitgestellt wird¶

Metrik	Typ	Labels
`karli_llm_tokens_total`	Counter	`model`, `kind` (`input`/`output`), `flow_id`
`karli_llm_calls_total`	Counter	`model`, `status` (`ok`/`error`), `flow_id`
`karli_llm_call_duration_seconds`	Histogram	`model`, `flow_id`
`karli_flow_runs_total`	Counter	`flow_id`, `status` (`ok`/`error`)
`karli_flow_duration_seconds`	Histogram	`flow_id`
`karli_flow_info`	Gauge	`flow_id`, `flow_name`

Die Suffixe _total und _seconds werden vom Prometheus-Exporter angehängt — die Metriken also genau unter den oben genannten Namen abfragen. Die Dauer-Histogramme nutzen für LLM-Latenzen passende Buckets (0,1 s bis 120 s) statt der OpenTelemetry-Standardwerte.

model ist die angefragte Modell-ID (zum Beispiel karli/KARLI-MoE-latest), nicht der normalisierte Name, den das Gateway zurückgibt. Ist das Modell nicht ermittelbar, wird unknown erfasst, statt den Datenpunkt zu verwerfen.

Token-Counter werden nur geschrieben, wenn der Provider tatsächlich Usage meldet. Ein Call ohne Usage-Block erhöht dennoch karli_llm_calls_total. Eine Differenz zwischen Call- und Token-Zahlen bedeutet also, dass der Provider nichts gemeldet hat — nicht, dass der Call kostenlos war. Fehlgeschlagene Calls werden mit status="error" gezählt und tragen keine Tokens bei, da für sie keine belastbare Usage vorliegt.

Labels wie session_id, user_id, trace_id oder Labels pro Komponente fehlen bewusst (Kardinalität). Erfasst werden ausschließlich Tokens — keine Kosten oder Preise; die Bepreisung erfolgt zentral zum Auslesezeitpunkt.

Flow-Namen¶

Die Nutzungs-Counter tragen ausschließlich das Label flow_id. Flow-Namen kommen über eine separate info-Metrik, die für den aktuellen Namen eines Flows immer den Wert 1 hat:

karli_flow_info{flow_id="…", flow_name="Support Triage"} 1

Beim Abfragen wird sie auf die Counter gejoint:

sum by (flow_name) (
  increase(karli_llm_tokens_total{kind="output"}[24h])
  * on(flow_id) group_left(flow_name) (karli_flow_info == 1)
)

Das == 1 ist wichtig: Bei einer Umbenennung wird der alte Name auf 0 gesetzt und nicht entfernt. Sind beide Serien aktiv, schlägt group_left mit „multiple matches for labels“ fehl — also immer filtern.

Namen gehören bewusst nicht auf die Counter. Ein Label-Wert ist Teil der Identität einer Zeitreihe: Stünde der Name dort, würde eine Umbenennung eine völlig neue Serie beginnen, die alte auf ihrem letzten Wert zurücklassen und jede Abfrage über den Umbenennungszeitpunkt hinweg verfälschen. Da die Counter über die unveränderliche flow_id geführt werden, wandert bei einer Umbenennung nur die info-Serie — historische Graphen erscheinen sofort unter dem neuen Namen.

Ein Flow erscheint in karli_flow_info, sobald er im aktuellen Prozess gelaufen ist.

Instanz-Identität¶

Die Metriken enthalten keinerlei Instanz-Identität. Es gibt kein Client- oder Instanz-Label. Die zentrale Prometheus-Instanz ergänzt die Identität über ihre Scrape-Konfiguration auf Basis des Deployments-API-Inventars. In der Anwendung darf ein solches Label nicht ergänzt werden.

Einschränkungen¶

Ein Worker. OpenTelemetry-Metriken gelten pro Prozess, und nur ein Worker kann den Metrics-Port binden. Bei LANGFLOW_WORKERS größer als 1 werden nur die Counter eines Workers gescrapt, alle anderen bleiben unsichtbar. Instanzen mit aktivierten Metriken daher auf einen Worker beschränken, solange keine Aggregation über einen Collector existiert.
Usage-Metering wird bewusst nicht von LANGFLOW_DEACTIVATE_TRACING abgeschaltet. Diese Einstellung deaktiviert den Trace-Export an Langfuse und andere Provider; die Metriken laufen weiter.

Traces einsehen¶

Traces sind über das Langfuse-Dashboard des jeweiligen Karli-Studio-Deployments zugänglich.

Tip

Wenn ein Flow unerwartete Ergebnisse liefert, zuerst den Langfuse-Trace der Konversation prüfen. Die Komponenten-Spans zeigen exakt, was jede Komponente empfangen und produziert hat.