Observability

Warum Observability integriert ist

Agenten lassen sich durch das Lesen von Logs nur schwer debuggen: Das interessante Verhalten steckt in verschachtelten LLM-Aufrufen, Tool-Aufrufen und Datenbank-Roundtrips. Agent-Lab behandelt Observability als Framework-Feature, nicht als nachträglichen Zusatz – jeder HTTP-Request, jeder Modellaufruf, jede SQL-Abfrage und jeder ausgehende HTTP-Hop wird zu einem Span, exportiert über den Industriestandard OpenTelemetry (mit den semantischen Konventionen von OpenLLMetry und OpenInference).

Da durchgängig OTLP verwendet wird, funktioniert jedes Collector-kompatible Backend – der Grafana-Stack, Elastic, Langfuse, LangWatch oder das bestehende APM Ihres Unternehmens.

Was instrumentiert wird

Das Setup befindet sich in agent_lab/infrastructure/metrics/tracer.py. Wenn OTEL_EXPORTER_OTLP_ENDPOINT gesetzt ist, wird Folgendes automatisch getraced:

Die Ressourcenidentität ergibt sich aus SERVICE_NAME (Standard Agent-Lab) und SERVICE_VERSION (Standard snapshot). Rauschpfade (/status/*, /docs, /openapi.json, Favicons) werden von einem benutzerdefinierten Sampler verworfen.

Aktivierung

Keine Codeänderungen – nur ein Endpoint. Wenn OTEL_EXPORTER_OTLP_ENDPOINT gesetzt ist, fließen Spans über OTLP/HTTP an <endpoint>/v1/traces, /v1/metrics und /v1/logs. Ist die Variable nicht gesetzt, ist das Tracing deaktiviert.

# Point the app at any OTLP/HTTP collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 uvicorn agent_lab.main:app --reload

Für die lokale Entwicklung übernehmen zwei vorkonfigurierte Stacks die gesamte Verdrahtung für Sie (aus dem Framework-Repository):

docker compose -f compose-grafana.yml up --build      # collector + Prometheus + Tempo + Loki + Grafana
docker compose -f compose-opensearch.yml up --build   # collector + Data Prepper + OpenSearch + Dashboards

Jeder Stack bringt seine eigene OpenTelemetry-Collector-Konfiguration unter otel/grafana/ bzw. otel/opensearch/ mit – diese Dateien sind die Referenz dafür, wie Traces, Metriken und Logs geroutet werden. Produktionstopologien finden Sie im Deployment-Guide.

Backends für LLM-Observability

Über reines OTel hinaus lässt sich Agent-Lab an spezialisierte LLM-Observability-Plattformen anbinden – über eine TracingBackend-Abstraktion (als DI-Provider in agent_lab/core/container.py verdrahtet). Beide mitgelieferten Backends werden ausschließlich über Umgebungsvariablen aktiviert und deaktivieren sich stillschweigend, wenn ihre Variablen fehlen, sodass die Anwendung immer startet.

Langfuse

Setzen Sie die drei Variablen aus Ihrem Langfuse-Projekt, und jeder Trace wird an den OTLP-Endpoint von Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) gespiegelt – mit langfuse.trace.*-Attributen: Prompts, Completions, Token-Verbrauch und Kosten, bereit für die Simulationsexperimente:

LangWatch

LangWatch zeichnet pro Nachricht einen langwatch.trace()-Span auf; auf diese Weise protokollieren die Simulations-Suites die Judge-Bewertungen zu den Experimenten.

Referenz-Dashboards

Beide Guides enthalten Demo-Aufzeichnungen der Dashboards im Einsatz.

Erweiterung: Ihr eigenes Backend

TracingBackend ist Teil der öffentlichen API. Leiten Sie davon ab, um Spans an Ihre eigene Plattform weiterzuleiten, und registrieren Sie die Klasse in Ihrem Container:

from agent_lab import Container, TracingBackend


class MyBackend(TracingBackend):
    ...  # export spans wherever your platform needs them


class MyContainer(Container):
    # replace or extend the shipped tracing_backends provider list
    ...

Die Konfigurationsreferenz listet alle Observability-bezogenen Variablen in einer Tabelle auf.