Le traçage distribué en bref : spans, identifiants parents et W3C Trace Context

Ce que c'est

Une trace enregistre une requête pendant qu'elle traverse plusieurs services. C'est un arbre de spans. La documentation d'OpenTelemetry énumère ce que contient un span : un nom, un identifiant de span parent (vide pour le span racine), des horodatages de début et de fin, un contexte de span (identifiant de trace et identifiant de span), des attributs, des événements, des liens et un statut. Chaque span possède en outre un type (Client, Server, Internal, Producer ou Consumer), qui indique au backend comment reconstituer l'arbre : le parent d'un span Server est souvent un span Client distant.

L'arbre ne se forme que si les identifiants franchissent les frontières de processus. La recommandation W3C Trace Context définit pour cela l'en-tête HTTP traceparent : version-trace-id-parent-id-trace-flags, où l'identifiant de trace compte 32 caractères hexadécimaux en minuscules (16 octets), l'identifiant parent 16 caractères hexadécimaux (l'identifiant de span de l'appelant) et l'octet de drapeaux porte actuellement un bit, sampled. Un second en-tête, tracestate, accueille des données propres à chaque fournisseur. La recommandation distingue deux niveaux : un outil doit au minimum retransmettre les deux en-têtes pour que les traces ne se rompent pas, ou peut participer en créant son propre span et en réécrivant l'identifiant parent. La page d'OpenTelemetry sur la propagation de contexte décrit le même mécanisme : l'appelant transmet l'identifiant de trace et l'identifiant de span, l'appelé crée un span enfant ayant pour parent le span de l'appelant.

Pourquoi c'est important

Des journaux provenant de dix services décrivent dix événements séparés ; une trace montre lesquels appartiennent à une même requête, dans quel ordre, et où le temps a été passé. Sans propagation, chaque service démarre son propre span racine, et le backend affiche des fragments impossibles à relier.

Comment l'appliquer

• Créer un span Server pour chaque requête entrante, et un span Client pour chaque appel sortant, chaque message publié et chaque requête à une base de données ; les bibliothèques d'instrumentation des frameworks le font automatiquement.
• Propager à travers tout, pas seulement en HTTP : placer traceparent dans les en-têtes des messages pour les files d'attente et dans la charge utile des jobs en arrière-plan, et le restaurer côté consommateur.
• Écrire l'identifiant de trace dans chaque ligne de journal de la requête, afin de pouvoir relier journaux et traces.
• Choisir des noms de span avec peu de variantes possibles (GET /users/{id}, et non l'adresse concrète) ; placer les parties variables dans des attributs.
• Les services dépourvus de SDK de traçage retransmettent traceparent et tracestate sans les modifier.

Pièges

Aux frontières asynchrones (pools de threads, minuteurs, écrivains groupés), le contexte se perd si la bibliothèque ou le code ne le propage pas explicitement. Le drapeau sampled est une indication de l'appelant ; une décision d'échantillonnage prise service par service produit des traces avec des spans manquants. Un décalage d'horloge entre hôtes peut faire démarrer un span enfant avant son parent. Une périphérie publique devrait décider délibérément si elle poursuit une trace fournie par un client quelconque.