Observabilité d'une application IA avec OpenTelemetry, Prometheus et Grafana

Ondine Télécom (opérateur fictif, 350 conseillers) a mis en service un assistant IA pour son support client : une route qui répond aux questions fréquentes avec Gemini et un cache, et un agent ADK qui diagnostique la ligne d'un client. Un lundi matin, les réponses passent de deux à six secondes et la facture de la semaine a pris 40 %. La supervision en place voit des réponses HTTP 200. Personne ne peut dire si le modèle ralentit, si le cache ne sert plus ou si l'agent boucle.

Ce projet construit l'observabilité qui répond en cinq minutes : chaque appel au modèle mesuré selon les conventions OpenTelemetry gen_ai (durée, tokens, erreurs), le coût et le taux de cache en métriques applicatives, des traces qui montrent chaque étape de l'agent, des journaux reliés à ces traces, un tableau de bord et trois alertes provisionnés en code. Puis le même code exporté vers Google Cloud en changeant un seul fichier.

Capture réelle du 2026-10-16, pendant une charge de cinq minutes sur Vertex AI (gemini-3.5-flash-lite). Les losanges du graphe de latence ouvrent la trace de l'appel mesuré.

Ce que vous livrez

Architecture

flowchart LR
  subgraph APP["Service assistant-support (FastAPI, port 8088)"]
    Q["/question<br/>cache + Gemini"]
    A["/agent<br/>agent ADK + outil"]
    SDK["SDK OpenTelemetry<br/>traces, métriques gen_ai, journaux"]
  end
  CH["Charge de test<br/>(loi de Zipf)"] --> Q
  CH --> A
  Q --> GEM["Gemini<br/>(clé API ou Vertex AI)"]
  A --> GEM
  Q --> SDK
  A --> SDK
  SDK -->|"OTLP/HTTP"| COL["Collecteur OTel<br/>memory_limiter, filtre, batch"]
  subgraph LAB["docker compose -p lab-otel"]
    COL --> PROM[("Prometheus")]
    COL --> TEMPO[("Tempo")]
    COL --> LOKI[("Loki")]
    GRAF["Grafana<br/>tableau de bord + alertes en code"]
  end
  GRAF --> PROM
  GRAF --> TEMPO
  GRAF --> LOKI
  COL -.->|"leçon 6 : collector-gcp.yaml"| GCP["Cloud Monitoring<br/>Cloud Trace, Cloud Logging"]

Stack et coût

Coût mesuré : make e2e (100 requêtes, 29 appels au modèle) a coûté 0,0039 USD le 2026-10-16 sur Vertex AI. make test et make demo-alerte utilisent un faux modèle et ne coûtent rien. La pile tourne en local ; aucune ressource Google Cloud n'est créée.

Prérequis

• Docker 24+ avec Compose v2, 2 Go de RAM libres, ports 3100, 3200, 3300, 4317, 4318, 8088 et 9095 disponibles.
• Python 3.10+, make, openssl.
• Pour les appels réels : une clé API Gemini, ou un projet Google Cloud avec Vertex AI (gcloud auth application-default login). Sans l'un ni l'autre, FAUX_MODELE=1 fait tout fonctionner sauf l'agent.
• Avoir déjà écrit une API FastAPI et un agent ADK simple ; connaître les bases de PromQL aide pour le module 3.

Programme

Le code complet est dans files/ : commencez par le README.