Aller au contenu

TechniquePratique5 min de lecture

Lab 1 : instrumenter une application LLM

Brancher OpenTelemetry sur une petite application qui appelle un LLM local : initialiser le SDK, poser les attributs GenAI, créer les métriques standard, puis vérifier que les données arrivent dans VictoriaMetrics et Tempo.

Pour : ingénieurs et SREPrérequis : Avoir lu les modules 1 et 2 du parcours, savoir utiliser Docker et lire du Python.

Durée : 1 h 45. Prérequis : modules 1 et 2, Docker, Python 3.10 ou plus récent, 16 Go de mémoire conseillés.

Une application qui appelle un LLM sans instrumentation est muette : impossible de savoir combien de jetons elle consomme, combien de temps prend chaque appel ou pour quel client elle travaille. Le script de ce lab pose des questions à un modèle local et il est déjà instrumenté. Vous allez lire ce code, le lancer, le modifier, puis vérifier que chaque appel laisse une trace consultable dans Grafana et alimente des métriques découpées par modèle, client et fonctionnalité. Pour finir, vous provoquerez une panne pour voir à quoi elle ressemble.

La première commande démarre la stack du kit. Les deux suivantes téléchargent les modèles locaux : Mistral 7B répond aux questions, tandis que nomic-embed-text est un modèle d’embeddings qui transforme un texte en vecteur de nombres (il servira au lab 2).

Fenêtre de terminal
cd labs/llm-observability
docker compose up -d
# Modèles locaux (5 à 10 minutes au premier lancement)
docker exec -it mttl-ollama ollama pull mistral:7b
docker exec -it mttl-ollama ollama pull nomic-embed-text
cd app && pip install -r requirements.txt
ServiceAdresseNature
Grafanahttp://localhost:3000interface (admin / admin)
VictoriaMetricshttp://localhost:8428/vmuiinterface de requête
Tempohttp://localhost:3200API HTTP, sans interface : on explore les traces depuis Grafana
Phoenixhttp://localhost:6006interface

Versions des images du kit : Collector contrib 0.108.0, VictoriaMetrics v1.110.0, Tempo 2.6.0, Grafana 11.2.0, Phoenix version-5.9.1, Qdrant v1.12.0, Ollama 0.3.12. Elles sont épinglées dans docker-compose.yml ; les dépendances Python le sont dans app/requirements.txt.

Ouvrez app/lab1_llm_app.py. Quatre éléments sont à repérer.

La fonction init_telemetry() met en place la tuyauterie : les fournisseurs de traces et de métriques (les objets du SDK OpenTelemetry qui fabriquent spans et mesures) et les exportateurs OTLP, qui les envoient au Collector. Vient ensuite le span manuel ouvert autour de l’appel au modèle, puis les attributs gen_ai.* posés sur ce span. Enfin, la fonction create_genai_metrics() crée les instruments, c’est-à-dire les compteurs et histogrammes : jetons et durée (standard), coût et erreurs (extensions mttl.*). Le lab 1 n’émet pas de coût : le coût en euros n’est calculé qu’au lab 4, à partir d’une grille de prix que vous fournissez.

Le cœur de l’instrumentation tient en quelques lignes :

labels = {
GEN_AI_PROVIDER_NAME: Provider.OLLAMA, # gen_ai.provider.name
GEN_AI_OPERATION_NAME: Operation.CHAT,
GEN_AI_REQUEST_MODEL: MODEL,
MTTL_TENANT_ID: tenant, # extension maison : mttl.tenant.id
MTTL_FEATURE: feature, # extension maison : mttl.feature
}
with tracer.start_as_current_span(f"chat {MODEL}", attributes={**labels, ...}) as span:
try:
response = get_ollama().chat(model=MODEL, messages=[...], options={...})
input_tokens = response.get("prompt_eval_count", 0)
output_tokens = response.get("eval_count", 0)
span.set_attribute(GEN_AI_USAGE_INPUT_TOKENS, input_tokens)
span.set_attribute(GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens)
metrics["duration"].record(time.time() - start, labels)
metrics["tokens"].record(input_tokens, {**labels, GEN_AI_TOKEN_TYPE: "input"})
metrics["tokens"].record(output_tokens, {**labels, GEN_AI_TOKEN_TYPE: "output"})
except Exception as e:
err = {**labels, ERROR_TYPE: type(e).__name__}
span.record_exception(e)
span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
metrics["duration"].record(time.time() - start, err)
metrics["errors"].add(1, err)
raise

Les constantes (GEN_AI_PROVIDER_NAME, MTTL_TENANT_ID…) sont définies dans app/shared/conventions.py. Quand la convention évolue, on ne modifie qu’un fichier. Les noms standard restent dans gen_ai.*, les extensions du kit vont dans mttl.*.

Un détail vous évitera de chercher longtemps un panneau vide : dans VictoriaMetrics, l’exportateur du Collector ajoute aux noms les suffixes d’unité et de type. La durée devient gen_ai_client_operation_duration_seconds_bucket, le compteur d’erreurs mttl_client_errors_total et l’attribut mttl.tenant.id devient le label mttl_tenant_id. Ce sont ces noms qu’interrogent les tableaux de bord et les alertes.

Fenêtre de terminal
python lab1_llm_app.py

Dans Grafana, ouvrez Explore avec la source Tempo, cherchez le service lab1-llm-app et ouvrez une trace. Vérifiez que les attributs de fournisseur, de modèle et d’usage sont présents. Ouvrez ensuite le tableau de bord LLM Overview : jetons et latence doivent apparaître.

  1. Ajoutez l’attribut gen_ai.request.top_p sur le span.
  2. Faites varier la température de 0.0 à 1.0 et observez la dispersion de la latence.
  3. Ajoutez un événement de span pour le prompt : span.add_event("prompt", {...}). Cette capture est acceptable dans ce lab local. En production, elle reste désactivée par défaut, ne s’active que par un choix explicite (opt-in) et s’accompagne d’un masquage des données sensibles (voir le module 2 et le §2 de l’article Observer un système LLM).

Étape 4 : plusieurs clients et fonctionnalités (25 min)

Section intitulée « Étape 4 : plusieurs clients et fonctionnalités (25 min) »

Le script envoie cinq requêtes réparties entre deux clients (acme-corp, client-test) et trois fonctionnalités (support, search, summary). À vous de jouer : ajoutez dans la liste PROMPTS un troisième client (globex-energy) et une quatrième fonctionnalité (translation), relancez, puis vérifiez sur le tableau de bord LLM Overview que les métriques se découpent par client et par fonctionnalité (panneaux « Jetons par client » et « Jetons par fonctionnalité », variables model et tenant en haut du tableau de bord).

On coupe le modèle pour voir comment une vraie panne apparaît dans les données.

Fenêtre de terminal
docker stop mttl-ollama
python lab1_llm_app.py

Observez les spans en erreur dans Tempo (avec l’attribut error.type), l’incrément du compteur mttl_client_errors_total et l’absence de jetons consommés. Relancez ensuite docker start mttl-ollama.

NotionCe que le lab montre
Tracesdans ce lab, un appel LLM produit un span ; les spans enfants par étape arrivent au lab 2
Métriquestoujours labellisées par modèle, client et fonctionnalité
Erreursspan.set_status(StatusCode.ERROR) plus un compteur d’erreurs dédié
Coûtsuivi ici en jetons ; en euros au lab 4 seulement, avec votre grille de prix versionnée et datée

Ne mettez pas les prompts complets dans les attributs : ils sont volumineux et peuvent contenir des données personnelles. Méfiez-vous d’un identifiant client laissé libre si vous en avez des milliers : chaque valeur ouvre de nouvelles séries et la cardinalité explose.

Pensez enfin à l’auto-instrumentation, une bibliothèque qui produit les spans à votre place pour les clients courants. Le paquet officiel du projet OpenTelemetry pour le client OpenAI est opentelemetry-instrumentation-openai-v2 ; opentelemetry-instrumentation-openai, sans suffixe, est celui du projet OpenLLMetry de Traceloop.

Révisé le 2 octobre 2026 : encadré sur l’état du kit, gen_ai.system remplacé par gen_ai.provider.name, extensions du kit déplacées de gen_ai.* vers mttl.*, noms de métriques avec les suffixes ajoutés par l’exportateur, Tempo présenté comme une API, exercice aligné sur le code (deux clients, trois fonctionnalités), paquet officiel opentelemetry-instrumentation-openai-v2 précisé ; plus de coût nul émis pour le modèle local, le coût en euros n’étant calculé qu’avec une grille de prix fournie.