Observabilidad

Por qué la observabilidad viene integrada

Los agentes son difíciles de depurar leyendo logs: el comportamiento interesante está en las llamadas anidadas al LLM, las invocaciones de herramientas y los viajes de ida y vuelta a la base de datos. Agent-Lab trata la observabilidad como una funcionalidad del framework, no como un añadido: cada petición HTTP, llamada al modelo, consulta SQL y salto HTTP saliente se convierte en un span, exportado mediante el estándar del sector OpenTelemetry (con las convenciones semánticas de OpenLLMetry y OpenInference).

Como es OTLP de extremo a extremo, funciona cualquier backend compatible con el colector: el stack de Grafana, Elastic, Langfuse, LangWatch o el APM que ya utilice tu empresa.

Qué se instrumenta

La configuración se encuentra en agent_lab/infrastructure/metrics/tracer.py. Con OTEL_EXPORTER_OTLP_ENDPOINT definida, se trazan automáticamente los siguientes elementos:

La identidad del recurso procede de SERVICE_NAME (por defecto Agent-Lab) y SERVICE_VERSION (por defecto snapshot). Un sampler personalizado descarta las rutas de ruido (/status/*, /docs, /openapi.json, favicons).

Cómo activarla

Sin cambios en el código: solo hace falta un endpoint. Cuando OTEL_EXPORTER_OTLP_ENDPOINT está definida, los spans fluyen hacia <endpoint>/v1/traces, /v1/metrics y /v1/logs mediante OTLP/HTTP. Cuando no está definida, la trazabilidad está desactivada.

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

Para el desarrollo local, dos stacks preconfigurados se encargan de todo el cableado por ti (desde el repositorio 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

Cada stack incluye su propia configuración del OpenTelemetry Collector en otel/grafana/ y otel/opensearch/, respectivamente; esos archivos son la referencia de cómo se enrutan las trazas, las métricas y los logs. Consulta la Guía de despliegue para conocer las topologías de producción.

Backends de observabilidad de LLM

Más allá de OTel puro, Agent-Lab se conecta a plataformas de observabilidad de LLM especializadas mediante una abstracción TracingBackend (conectada como proveedores de DI en agent_lab/core/container.py). Los dos backends incluidos se habilitan únicamente mediante variables de entorno y se desactivan solos sin avisar cuando faltan sus variables, de modo que la aplicación siempre arranca.

Langfuse

Define las tres variables de tu proyecto de Langfuse y cada traza se replicará en el endpoint OTLP de Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) con atributos langfuse.trace.*: prompts, respuestas, uso de tokens y costes, listos para los experimentos de simulación:

LangWatch

LangWatch registra un span langwatch.trace() por mensaje, que es la forma en que las baterías de simulación registran las puntuaciones del juez en los experimentos.

Paneles de referencia

Ambas guías incluyen grabaciones de demostración de los paneles en funcionamiento.

Ampliación: tu propio backend

TracingBackend forma parte de la API pública. Crea una subclase para reenviar los spans a tu propia plataforma y regístrala en tu 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
    ...

La Referencia de configuración recoge en una sola tabla todas las variables relacionadas con la observabilidad.