Skip to main content
Le traçage distribué suit une requête ou une opération à travers les services instrumentés. Une trace regroupe les spans de ce travail. Chaque span est une opération chronométrée, comme une requête HTTP, un appel à la base de données, une opération de file de messages ou une tâche en arrière-plan. Quand un span manque, une partie du chemin reste inconnue. Utilisez une trace quand un log signale un échec sans montrer le chemin de l’opération. Une trace peut montrer :
  • Quelle opération a démarré la requête.
  • Où la requête a passé du temps.
  • Quelle opération enfant a renvoyé une erreur.
  • Quels logs, problèmes, actions et métriques ont le même ID de trace.
  • Quel service, quel environnement et quelle version ont envoyé chaque span.

​
Champs des traces et des spans

Un span racine démarre une trace et n’a pas de parent. Les spans enfants ont le même ID de trace, leur propre ID de span et un ID de parent. Seuls ces ID relient les opérations. Les horodatages seuls ne suffisent pas. LogBrew compte un span comme span d’erreur uniquement quand son status vaut error.

​
Une requête à travers plusieurs services

  1. Le service web démarre un span serveur pour la route de paiement.
  2. Un client de paiement crée un span enfant pour sa requête HTTP sortante.
  3. Le service de paiement poursuit la trace avec son propre span serveur.
  4. Un helper de base de données enregistre un span enfant pour l’écriture.
  5. L’application envoie un log d’erreur sans risque dans le span de paiement actif.
Ces 5 enregistrements ont le même ID de trace. Si un service ne reçoit pas le contexte de trace, son travail ne rejoint pas la trace, même si leurs horaires se chevauchent.

​
Propager le contexte

Les SDK LogBrew utilisent le contexte de trace W3C. Par exemple, le SDK Node.js poursuit un en-tête traceparent entrant valide avec un nouveau span de requête. Si l’en-tête manque ou n’est pas valide, il démarre une nouvelle racine. Les logs, problèmes, actions et métriques capturés dans le périmètre de cette requête portent la trace de la requête. L’instrumentation sortante écrit un en-tête traceparent uniquement vers les cibles que vous configurez, par exemple avec tracePropagationTargets. Envoyez le contexte de trace uniquement à des services de confiance et instrumentés. Un ID de trace met des opérations en corrélation. Ce n’est pas une authentification. Un message de file de messages peut aussi porter le contexte de trace. En Node.js, appelez createLogBrewQueueTraceHeaders() dans l’opération du producteur pour ajouter un en-tête traceparent au message. Dans le consommateur, passez cet en-tête à queueOperationWithLogBrewSpan() comme traceparent. Consultez Traçage des files de messages en JavaScript. Les intégrations Node.js et Python pour les requêtes entrantes et sortantes n’enregistrent dans les spans ni le corps des requêtes ou des réponses, ni les chaînes de requête, ni des en-têtes arbitraires, ni la valeur brute de traceparent. Nommez les spans d’après des modèles de route, pas d’après des URL concrètes. Pour les intégrations de votre runtime, lisez le guide Intégration du SDK.

​
Spans de capture

LogBrew stocke chaque nouveau log, problème, action et métrique avec un ID de trace. Si un signal ne fait référence à aucun span dans le même envoi, LogBrew ajoute pour lui un span de capture : Le span_id du signal identifie alors son span de capture. Si le signal n’avait pas de contexte de trace, LogBrew crée un nouvel ID de trace pour lui. Cette trace montre que LogBrew a stocké le signal. Elle ne montre pas le chemin d’une requête. Ne lisez pas les spans de capture d’une trace comme une seule requête. Les spans de capture comptent dans span_count et error_span_count. Un log d’erreur peut donc amener --status error à sélectionner une trace dans laquelle aucune opération de l’application n’a échoué. Lisez l’operation de chaque span d’erreur avant de tirer une conclusion.

​
Lire une trace

Utilisez un ID de trace exact, issu d’un log, d’un problème ou d’une liste de traces :
--status error sélectionne les traces qui ont au moins un span d’erreur. --status ok sélectionne les traces sans span d’erreur. --min-duration-ms 500 sélectionne les traces qui ont duré 500 millisecondes ou plus. Lisez d’abord la durée du span racine. Examinez ensuite les spans enfants les plus longs et les statuts d’erreur. Gardez en vue le projet, le service, l’environnement et la version, pour qu’une trace de staging ne devienne pas une preuve sur la production. Une trace montre une seule exécution, pas une référence de performance. Avant de proposer une modification de performance, comparez plusieurs traces avec la tendance de la métrique associée.

​
Résumé d’une trace

GET /api/telemetry/traces/{trace_id}/summary renvoie un résumé sans les attributs des spans : Si root_span.parent_span_id a une valeur, le vrai span racine n’est pas dans la trace. Ne lisez pas root_span comme le début de la requête.

​
Expliquer une trace

logbrew explain trace renvoie une investigation de trace :
analysis.causality vaut evidence_only. L’analyse ne prouve pas la cause racine. La CLI demande la version 3 de la réponse, dans laquelle chaque problème, action et métrique associé a aussi son span_id exact. Pour examiner un span avec son parent, ses enfants et les limites entre services, exécutez :
topology.parent_chain_status indique si la chaîne de parents est complète :

​
Contexte de trace manquant

Certains signaux n’ont pas de trace de leur requête. Lisez l’état de la trace : not_linked n’est pas une erreur. Une trace available peut aussi montrer que le signal n’avait pas de contexte de requête. Si le span de capture du signal n’a pas de parent_span_id, aucun span n’était actif quand l’application a capturé le signal. Le travail en arrière-plan hors du périmètre d’une requête donne souvent ce résultat. Pour trouver un lien manquant :
  1. Lisez le projet, le service, l’environnement, la version et l’heure du signal.
  2. Vérifiez que le travail s’est exécuté dans une requête ou une opération instrumentée.
  3. Vérifiez que les intégrations client et serveur propagent le contexte à travers cette limite.
  4. Après avoir corrigé l’instrumentation, capturez un nouveau signal et lisez-le.
Une nouvelle version du SDK n’ajoute pas de contexte de trace aux signaux envoyés plus tôt. Ne reliez pas un signal à une trace par l’horodatage, la route, le message ou la version.

​
Planifier le traçage d’un projet

Commencez par une requête ou une tâche importante, comme le paiement. Instrumentez une limite à la fois :
  1. Créez un span pour la requête entrante ou l’opération en arrière-plan.
  2. Ajoutez des spans enfants pour les appels sortants importants.
  3. Poursuivez le contexte de trace W3C à travers les limites entre services de confiance.
  4. Envoyez un log sans risque dans le span actif.
  5. Lisez ce log, ouvrez son ID de trace et vérifiez la racine, les enfants, le service, l’environnement, la version, le statut et la durée.
Ajoutez la limite suivante seulement quand cette vérification réussit. Une trace partagée montre une corrélation. Elle ne prouve pas qu’un span a causé un problème. Pour vérifier les noms des spans, exécutez logbrew traces --project "<project_id>" --pagination cursor --json. L’objet naming_quality compte les traces de cette page qui ont un nom racine générique (generic_name_traces) ou une route non reconnue (unmatched_route_traces). Si le nommage doit être amélioré, naming_quality.next_action.code vaut improve_trace_naming.