Observabilidad

Por qué la observabilidad viene integrada

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

Como usa OTLP de principio a fin, funciona cualquier backend compatible con un collector: el stack de Grafana, Elastic, Langfuse, LangWatch o el APM que ya use tu empresa.

Qué se instrumenta

La configuración se encuentra en agent_lab/infrastructure/metrics/tracer.py. Con OTEL_EXPORTER_OTLP_ENDPOINT definida, se rastrea automáticamente lo siguiente:

La identidad del recurso proviene de SERVICE_NAME (valor predeterminado Agent-Lab) y de SERVICE_VERSION (valor predeterminado snapshot). Las rutas que solo generan ruido (/status/*, /docs, /openapi.json, favicons) se descartan mediante un sampler personalizado.

Cómo activarla

Sin cambios de código: solo 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, el rastreo está desactivado.

# 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 hacen todas las conexiones 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 implementación para conocer las topologías de producción.

Backends de observabilidad de LLM

Más allá de OTel puro, Agent-Lab se conecta con 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 deshabilitan sin aviso cuando faltan sus variables, por lo que la aplicación siempre se inicia.

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, completions, uso de tokens y costos, listos para los experimentos de simulación:

LangWatch

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

Dashboards de referencia

Ambas guías incluyen grabaciones de demostración de los dashboards en acción.

Extensió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 reúne en una sola tabla todas las variables relacionadas con la observabilidad.