Lab 7 — Traces manuelles & échantillonnage

L’instrumentation automatique (Lab 2) trace les frontières techniques (HTTP, SQL). Pour tracer la logique métier, on crée des spans manuels. Dans ce lab : un span manuel via annotation, la propagation de contexte vers un autre service, le bagage, puis la maîtrise du volume avec le tail sampling.

Prérequis

• Labs 1 à 6 terminés, agent Java actif sur review-service.
• Les accès ouverts (./scripts/open-ui.sh).
• Les variables de la formation chargées dans votre shell : . ./scripts/env.sh. Elles donnent le port du review-service ($APP_PORT, accès direct au service, pas via le frontend-proxy) et $PF_HOST, le nom par lequel vous le joignez.

Étapes

Partie 1 — Spans manuels & propagation

1. Lire l’instrumentation manuelle dans ProductCatalogClient.java :

@WithSpan("product-catalog.lookup")
public void checkProductExists(@SpanAttribute("app.product.id") String productId) {
    ...
    Span.current().setAttribute("app.product.found", true);

et dans ReviewController.java (le bagage) :

Baggage baggage = Baggage.current().toBuilder()
        .put("app.review.channel", "web")
        .build();
try (Scope ignored = baggage.makeCurrent()) { ... }

Trois mécanismes du chapitre s’y trouvent — lesquels ?

💡 Ce que fait l’agent, ce que vous faites. L’agent Java n’est pas un bloc unique : c’est une collection d’une centaine de modules d’instrumentation, un par bibliothèque connue — Tomcat, JDBC, Hibernate, Spring Data, les clients HTTP… Au démarrage de la JVM, il réécrit le bytecode de ces bibliothèques pour ouvrir un span à l’entrée d’une méthode et le refermer à la sortie. Un span « automatique », c’est donc très concrètement un appel à une méthode d’une bibliothèque reconnue — et sa durée est celle de cet appel.

Deux conséquences valent d’être retenues :

• Ce que l’agent ne reconnaît pas n’existe pas dans la trace. Votre logique métier — la validation d’une note, un calcul de score — n’appartient à aucune bibliothèque connue : elle ne produit aucun span et apparaîtrait dans Jaeger comme un trou inexpliqué entre deux spans. C’est précisément ce manque que @WithSpan comble : l’agent couvre la plomberie, vous nommez ce qui a du sens pour votre métier.
• @WithSpan est lui aussi traité par l’agent. L’annotation ne fait rien par elle-même : c’est un module de l’agent qui la reconnaît et crée le span. Retirez le -javaagent du Lab 2, et votre span manuel disparaît en même temps que les spans automatiques.

Chaque span porte d’ailleurs la signature du module qui l’a produit, dans l’attribut otel.scope.name : io.opentelemetry.tomcat-10.0 pour le span serveur, io.opentelemetry.jdbc pour l’INSERT, io.opentelemetry.spring-data-1.8 pour ReviewRepository.save, et …instrumentation-annotations-1.16 pour le vôtre. Dépliez n’importe quel span dans Jaeger pour le vérifier.

Les identifiants, eux, ne se « déterminent » pas : à la création de chaque span, le SDK tire 8 octets au hasard pour le spanId (16 au span racine pour le traceId). Aucune sémantique — toute l’information est dans le nom, les attributs, et le lien vers le span parent.

2. Générer une trace multi-services :

. ./scripts/env.sh   # si ce n'est pas déjà fait dans ce terminal
curl -X POST http://$PF_HOST:$APP_PORT/api/reviews \
  -H "Content-Type: application/json" \
  -d '{"productId": "OLJCESPC7Z", "rating": 5, "comment": "Trace me!", "userEmail": "ada.lovelace@example.com", "userName": "Ada Lovelace"}'

3. Analyser la trace dans Jaeger (service review-service, opération POST /api/reviews) :

POST /api/reviews                          (review-service, span serveur)
├── product-catalog.lookup                 (review-service, votre span manuel @WithSpan)
│   └── GET                                (review-service, span client HTTP)
│       └── GET /api/products/{productId}  (frontend ! propagation inter-services)
│           └── …                          (spans du frontend, puis de product-catalog)
└── ReviewRepository.save                  (review-service, Spring Data)
    └── …                                  (spans Hibernate)
        └── INSERT otel                    (review-service, span JDBC)

GET                                (review-service — celui qui appelle)
└── GET /api/products/{productId}  (frontend — celui qui répond)

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             │  │                                │                └─ flags (01 = trace échantillonnée)
             │  │                                └─ span-id de l'appelant, qui devient le parent
             │  └─ trace-id : le même pour les trois services
             └─ version du format

💡 Le span INSERT otel est un span client (côté review-service) : vous ne trouverez aucun span côté PostgreSQL. La base n’est pas instrumentée et le protocole SQL ne transporte pas traceparent — la trace s’arrête à la base, qui est une feuille. La propagation ne marche qu’entre services instrumentés (ici review-service → frontend → product-catalog).

4. Prouver la propagation. Jusqu’ici le contexte naissait dans review-service : votre curl arrivait sans en-tête, l’agent n’avait donc rien à reprendre. Imposez-le vous-même, comme le ferait un service appelant :

. ./scripts/env.sh   # si ce n'est pas déjà fait dans ce terminal
curl -s -o /dev/null -X POST http://$PF_HOST:$APP_PORT/api/reviews \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d '{"productId": "OLJCESPC7Z", "rating": 5, "comment": "w3c", "userEmail": "a@b.c", "userName": "A"}'

Cherchez 4bf92f3577b34da6a3ce929d0e0e4736 dans le champ Trace ID de Jaeger, en haut à droite du bandeau. Que trouvez-vous — et qu’est-ce que cela prouve ?

Partie 2 — Tail sampling

5. Le problème : en production, tracer 100 % du trafic coûte cher. Mais échantillonner à la source (head sampling) jette des traces avant de savoir si elles sont intéressantes. Le tail sampling décide après coup, dans le collecteur : on garde les erreurs et les requêtes lentes, on échantillonne le reste.

Écrivez la politique dans manifests/70-otel-traces-values.yaml : 100 % des traces en erreur, 100 % des traces > 1 s, 25 % du reste.

Trois politiques à combiner, une par ligne de l’énoncé.

Pour démarrer, le billet officiel sur le tail sampling donne un exemple court : deux politiques, dont deux des trois qui vous sont demandées. La documentation du processor liste ensuite tous les types et leurs paramètres — c’est là que vous trouverez la troisième, latency. Et le concept lui-même, head vs tail, est résumé dans la doc OpenTelemetry sur l’échantillonnage.

⚠️ Les exemples officiels écrivent les politiques en ligne, avec des accolades ({name: …, type: …}), et le README enchaîne 23 politiques nommées test-policy-1, test-policy-2… ne cherchez pas de sens à ces noms, c’est un fichier de test. Le YAML du lab utilise l’indentation classique : les deux écritures sont strictement équivalentes, choisissez celle que vous lisez le mieux.

cp content/1_Labs/70-otel-traces-values.yaml manifests/

opentelemetry-collector:
  config:
    processors:
      tail_sampling:
        # Une trace arrive en morceaux, souvent depuis plusieurs services. Le
        # collecteur les met de côté pendant ce délai avant de trancher : trop
        # court, il décide sur une trace incomplète et rate l'erreur qui arrive
        # en retard ; trop long, tout ce qui patiente occupe la mémoire.
        # Défaut du processor : 30 s.
        decision_wait: 5s
        policies:
          # Les politiques sont évaluées en OU : la trace est gardée dès que
          # l'une d'elles la retient.
          - name: keep-errors
            type: status_code
            status_code:
              status_codes: [ERROR]
          - name: keep-slow
            # Durée de la trace entière (du premier au dernier span), et non
            # celle d'un span pris isolément.
            type: latency
            latency:
              threshold_ms: 1000
          - name: sample-the-rest
            type: probabilistic
            probabilistic:
              sampling_percentage: 25
    service:
      pipelines:
        traces:
          # tail_sampling doit précéder batch : il raisonne trace par trace,
          # quand batch ne fait que regrouper des spans pour les expédier.
          processors: [memory_limiter, resourcedetection, resource, transform, tail_sampling, batch]

💡 Pourquoi votre tail sampling fonctionne — et pourquoi il casserait en production.

Le collecteur de la démo est un DaemonSet : une instance par nœud. Votre cluster kind n’en a qu’un, donc l’unique collecteur voit tous les spans de chaque trace. C’est la condition sans laquelle rien de ce que vous venez d’écrire ne tient : pour décider si une trace est en erreur ou lente, il faut la posséder en entier.

Ajoutez un second nœud, et les spans d’une même trace se répartissent entre deux collecteurs qui ne se parlent pas. Chacun tranche sur la moitié qu’il voit : celui qui n’a pas reçu le span en erreur traite la trace comme ordinaire et l’échantillonne à 25 %. Vous récoltez alors des traces amputées — plus trompeuses qu’une trace absente, puisqu’elles ont l’air complètes.

La parade tient en deux étages. Les collecteurs de nœud n’échantillonnent plus : ils transmettent à un étage gateway (mode gateway, un Deployment de quelques instances), dont l’exporter loadbalancing route par traceId. Tous les spans d’une même trace atterrissent ainsi sur la même instance de gateway — la seule à porter le tail_sampling.

Ce n’est pas une bizarrerie du tail sampling, mais un cas particulier d’un principe que la documentation officielle sur la montée en charge énonce ainsi : « les composants comme le tail sampling processor ne se répartissent pas facilement, car ils conservent en mémoire l’état nécessaire à leur fonctionnement ». Tout processor à état pose la même question : qui voit quoi, et est-ce suffisant pour décider ?

6. Appliquer (les values des labs précédents restent empilées) :

helm upgrade otel-demo open-telemetry/opentelemetry-demo \
  --version 0.40.9 -n otel-demo \
  -f manifests/values-training.yaml \
  -f manifests/30-otel-collector-values.yaml \
  -f manifests/60-otel-metrics-values.yaml \
  -f manifests/70-otel-traces-values.yaml
kubectl rollout status daemonset/otel-collector-agent -n otel-demo

7. Vérifier la politique :

# ~20 requêtes OK (25 % devraient survivre) :
for i in $(seq 1 20); do curl -s http://$PF_HOST:$APP_PORT/api/reviews > /dev/null; done
# 3 erreurs (100 % doivent survivre) :
for i in $(seq 1 3); do
  curl -s -o /dev/null -X POST http://$PF_HOST:$APP_PORT/api/reviews \
    -H "Content-Type: application/json" \
    -d '{"productId": "DOESNOTEXIST", "rating": 5, "comment": "?", "userEmail": "x@example.com", "userName": "X"}'
done

Dans Jaeger, faites deux recherches distinctes — ce ne sont pas les mêmes opérations :

• Operation GET /api/reviews : comptez les traces récentes. Vous en avez envoyé 20, il doit en rester nettement moins — c’est sample-the-rest à l’œuvre, et le compte exact varie d’un tirage à l’autre.
• Operation POST /api/reviews, avec Tags error=true : les 3 doivent être là, toutes marquées 🔴. keep-errors ne laisse rien passer, quel que soit le pourcentage de la politique probabiliste.

C’est le contraste entre ces deux comptes qui prouve que la politique fonctionne : le trafic ordinaire est réduit, les erreurs sont intégralement conservées.

Et si compter à la main vous laisse dubitatif, le processor tient ses propres comptes, que le collecteur exporte comme n’importe quelle métrique. Commencez par la décision finale :

sum by (sampled) (otelcol_processor_tail_sampling_global_count_traces_sampled_total)

sampled="true"    581     ← traces conservées
sampled="false"  1349

Puis le détail, politique par politique :

sum by (policy, sampled) (otelcol_processor_tail_sampling_count_traces_sampled_total)

policy="keep-errors"       sampled="true"      8    sampled="false"  1922
policy="keep-slow"         sampled="true"    153    sampled="false"  1777
policy="sample-the-rest"   sampled="true"    468    sampled="false"  1462

⚠️ Ce second compteur se lit de travers si l’on n’y prend pas garde. Il enregistre un vote par politique et par trace : keep-errors / sampled="false" = 1922 ne signifie pas que 1922 traces en erreur ont été jetées, mais que 1922 fois, keep-errors a examiné une trace et n’y a trouvé aucune erreur à retenir. Vos erreurs, ce sont les 8 votes true — et elles sont toutes conservées.

La preuve tient dans les totaux : 8 + 1922, 153 + 1777, 468 + 1462 donnent tous 1930, le nombre de traces évaluées. Chaque politique voit chaque trace, et se prononce.

Deux lectures valent le détour :

• 468 / (468 + 1462) = 24,2 % — la politique probabiliste tient sa promesse, chiffre à l’appui, sans que vous ayez à compter des lignes à l’écran ;
• 8 + 153 + 468 = 629, alors que la décision finale n’en retient que 581. L’écart, ce sont les traces retenues par plusieurs politiques à la fois — une trace lente que le tirage aurait de toute façon gardée. Le OU ne les compte qu’une fois.

sum(rate(traces_span_metrics_calls_total[5m]))

11:25   17.8  #################
11:30   17.3  #################
11:35   15.2  ###############
11:40    5.7  #####            ← le tail sampling entre en action
11:45    7.1  #######

Pour aller plus loin

• Lab 7 bonus — Voir le bagage, et s’en servir — rendre visible ce que ce lab ne fait qu’affirmer, puis garder 100 % des traces d’un client donné avec une quatrième politique de tail sampling.

Livrable

Une trace multi-services (review-service → frontend → product-catalog) analysée, et la politique de tail sampling active (3/3 erreurs conservées, ~25 % du reste).