Observabilité

Pourquoi l'observabilité est intégrée

Les agents sont difficiles à déboguer en lisant des logs : le comportement intéressant se cache dans des appels LLM imbriqués, des invocations d'outils et des allers-retours avec la base de données. Agent-Lab traite l'observabilité comme une fonctionnalité du framework, et non comme un ajout après coup — chaque requête HTTP, appel de modèle, requête SQL et saut HTTP sortant devient un span, exporté via le standard du secteur OpenTelemetry (avec les conventions sémantiques d'OpenLLMetry et d'OpenInference).

Comme tout passe par OTLP de bout en bout, n'importe quel backend compatible avec un collecteur fonctionne — stack Grafana, Elastic, Langfuse, LangWatch ou l'APM déjà en place dans votre entreprise.

Ce qui est instrumenté

La mise en place se trouve dans agent_lab/infrastructure/metrics/tracer.py. Lorsque OTEL_EXPORTER_OTLP_ENDPOINT est défini, les éléments suivants sont tracés automatiquement :

L'identité de la ressource provient de SERVICE_NAME (par défaut Agent-Lab) et de SERVICE_VERSION (par défaut snapshot). Les chemins sans intérêt (/status/*, /docs, /openapi.json, favicons) sont écartés par un sampler personnalisé.

Activer l'observabilité

Aucune modification de code — seulement un point de terminaison. Lorsque OTEL_EXPORTER_OTLP_ENDPOINT est défini, les spans sont envoyés vers <endpoint>/v1/traces, /v1/metrics et /v1/logs via OTLP/HTTP. Lorsqu'il n'est pas défini, le traçage est désactivé.

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

Pour le développement local, deux stacks préconfigurées se chargent de toute l'intégration à votre place (depuis le dépôt du 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

Chaque stack embarque sa propre configuration de l'OpenTelemetry Collector, respectivement sous otel/grafana/ et otel/opensearch/ — ces fichiers servent de référence pour l'acheminement des traces, des métriques et des logs. Consultez le guide de déploiement pour les topologies de production.

Backends d'observabilité LLM

Au-delà d'OTel brut, Agent-Lab s'intègre à des plateformes d'observabilité LLM dédiées grâce à une abstraction TracingBackend (câblée sous forme de providers DI dans agent_lab/core/container.py). Les deux backends fournis s'activent uniquement via des variables d'environnement et se désactivent silencieusement lorsque leurs variables sont absentes, de sorte que l'application démarre toujours.

Langfuse

Définissez les trois variables issues de votre projet Langfuse et chaque trace est répliquée vers le point de terminaison OTLP de Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) avec les attributs langfuse.trace.* — prompts, complétions, consommation de jetons et coûts, prêts pour les expériences de simulation :

LangWatch

LangWatch enregistre un span langwatch.trace() par message, ce qui permet aux suites de simulation de consigner les scores du juge pour chaque expérience.

Tableaux de bord de référence

Les deux guides incluent des enregistrements de démonstration des tableaux de bord en action.

Extension : votre propre backend

TracingBackend fait partie de l'API publique. Créez-en une sous-classe pour transférer les spans vers votre propre plateforme, puis enregistrez-la dans votre 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 Référence de configuration répertorie toutes les variables liées à l'observabilité dans un seul tableau.