TP : Instrumenter des traces à la main (spans, événements, erreurs, liens, échantillonnage)

Ce que vous allez apprendre dans ce TP

• Créer des spans avec le SDK
• Signaler erreurs, événements et liens
• Interroger avec TraceQL et échantillonner

Introduction #

Ce que vous allez apprendre dans cette section

• Créer des spans avec le SDK
• Signaler erreurs, événements et liens
• Interroger avec TraceQL et échantillonner

Contexte. Le service de commandes n'a aucune bibliothèque auto-instrumentée pour sa logique métier. Vous l'instrumentez à la main pour voir les étapes d'une commande, ses erreurs de paiement et ses traitements par lots.

Prérequis : Docker et Python 3.10 ou plus ; la pile grafana/otel-lgtm (Collector, Tempo, Loki, Prometheus, Pyroscope et Grafana dans un seul conteneur)  ·  Durée estimée : 50 min

Des traces riches et interrogeables, et un échantillonnage maîtrisé.

Mise en place #

Étapes guidées, avec leur correction.

1. 1. Démarrer la pile d'observabilité

   Pourquoi ? Une seule image fournit un Collector OTLP et tous les backends : on se concentre sur le signal.

   Lancez grafana/otel-lgtm, créez un environnement Python et pointez les exportateurs vers le port OTLP/HTTP 4318.

2. 2. Initialiser le SDK

   Pourquoi ? Le TracerProvider porte la ressource et l'exportateur ; le BatchSpanProcessor envoie par lots.

   Installez le SDK et l'exportateur OTLP/HTTP, puis écrivez otel_setup.py qui configure la ressource (service.name, service.version, deployment.environment.name) et l'export.

3. 3. Créer une trace métier

   Pourquoi ? Des spans nommés par étape, avec SpanKind et attributs conformes aux conventions, rendent la trace lisible par tous les outils.

   Écrivez commande.py : un span racine traiter commande et trois enfants (stock en CLIENT avec attributs de base de données, calcul, paiement), un événement, et une erreur de paiement une fois sur trois avec record_exception et statut ERROR.

4. 4. Explorer et interroger avec TraceQL

   Pourquoi ? TraceQL filtre sur la structure et les attributs des spans : on trouve en une requête les traces qui comptent.

   Dans Grafana, ouvrez Explore > Tempo. Exécutez les requêtes ci-dessous, ouvrez une trace en erreur et retrouvez l'événement et l'exception du span payer.

5. 5. Relier un traitement par lots avec des liens

   Pourquoi ? Un lot qui traite des éléments venant de plusieurs traces ne peut pas avoir plusieurs parents : on utilise des liens.

   Écrivez lot.py : trois traces « réception » indépendantes, puis un span facturer lot lié aux trois. Retrouvez les liens dans le détail du span.

6. 6. Échantillonner

   Pourquoi ? L'échantillonnage par ratio réduit le volume ; parentbased garantit qu'une trace est gardée ou jetée en entier.

   Relancez commande.py avec un échantillonnage à 20 % et comparez le nombre de traces reçues ; vérifiez qu'aucune trace n'est partielle. Expliquez pourquoi le tail sampling du Collector serait préférable pour garder toutes les erreurs.

Niveau de difficulté : ●●●○○ (3/5)