Osservabilità

Perché l'osservabilità è integrata

Fare il debug degli agenti leggendo i log è difficile: il comportamento interessante si nasconde nelle chiamate LLM annidate, nelle invocazioni dei tool e nei round-trip verso il database. Agent-Lab tratta l'osservabilità come una funzionalità del framework, non come un'aggiunta successiva: ogni richiesta HTTP, chiamata al modello, query SQL e chiamata HTTP in uscita diventa uno span, esportato tramite lo standard di settore OpenTelemetry (con le convenzioni semantiche di OpenLLMetry e OpenInference).

Poiché è OTLP end-to-end, funziona con qualsiasi backend compatibile con un collector: stack Grafana, Elastic, Langfuse, LangWatch o l'APM già in uso nella tua azienda.

Cosa viene strumentato

La configurazione si trova in agent_lab/infrastructure/metrics/tracer.py. Con OTEL_EXPORTER_OTLP_ENDPOINT impostata, vengono tracciati automaticamente:

L'identità della risorsa deriva da SERVICE_NAME (predefinito Agent-Lab) e SERVICE_VERSION (predefinito snapshot). I path di disturbo (/status/*, /docs, /openapi.json, favicon) vengono scartati da un sampler personalizzato.

Attivarla

Nessuna modifica al codice: basta un endpoint. Quando OTEL_EXPORTER_OTLP_ENDPOINT è impostata, gli span vengono inviati a <endpoint>/v1/traces, /v1/metrics e /v1/logs tramite OTLP/HTTP. Quando non è impostata, il tracing è disattivato.

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

Per lo sviluppo locale, due stack preconfigurati si occupano di tutti i collegamenti al posto tuo (dal repository del framework):

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

Ogni stack include la propria configurazione dell'OpenTelemetry Collector, rispettivamente in otel/grafana/ e otel/opensearch/: questi file sono il riferimento per capire come vengono instradati trace, metriche e log. Consulta la guida al deployment per le topologie di produzione.

Backend di osservabilità per LLM

Oltre a OTel di base, Agent-Lab si integra con piattaforme di osservabilità per LLM dedicate tramite un'astrazione TracingBackend (collegata come provider DI in agent_lab/core/container.py). Entrambi i backend inclusi si abilitano esclusivamente tramite variabili d'ambiente e si disabilitano silenziosamente quando le variabili mancano, così l'app si avvia sempre.

Langfuse

Imposta le tre variabili del tuo progetto Langfuse e ogni trace verrà replicata sull'endpoint OTLP di Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) con gli attributi langfuse.trace.*: prompt, completion, utilizzo dei token e costi, pronti per gli esperimenti di simulazione:

LangWatch

LangWatch registra uno span langwatch.trace() per ogni messaggio: è così che le suite di simulazione registrano i punteggi del giudice rispetto agli esperimenti.

Dashboard di riferimento

Entrambe le guide includono registrazioni dimostrative delle dashboard in azione.

Estensione: un backend personalizzato

TracingBackend fa parte dell'API pubblica. Crea una sottoclasse per inoltrare gli span alla tua piattaforma e registrala nel tuo 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
    ...

Il Riferimento della configurazione elenca in un'unica tabella tutte le variabili relative all'osservabilità.