Passer au contenu principal

​
1. Objet

Ce document définit le comportement normatif et les exigences d’usage du traçage des données Yourouter. L’objectif est de permettre l’audit, le rapprochement et le diagnostic en interrogeant Tencent Cloud Application Performance Management (APM) pour une trace distribuée de bout en bout d’une requête unique, à partir d’un identifiant de trace renvoyé par Yourouter.

​
2. Terminologie

Les termes MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY et OPTIONAL dans ce document s’interprètent comme dans la RFC 2119 (niveaux d’exigence).
  • Trace ID : identifiant unique permettant de récupérer une trace distribuée dans Tencent Cloud APM.
  • APM : Tencent Cloud Application Performance Management.
  • Client : tout appelant de l’API Yourouter (service, SDK, script, etc.).
  • Fenêtre de rétention des traces : période pendant laquelle une trace est consultable dans APM. Dans cette spécification : 72 heures (3 jours).

​
3. Protocole

Cette spécification n’impose pas les détails de transport au-delà de l’exigence que le Trace ID soit transmis via un en-tête de réponse HTTP.

​
4. Exigences sur le Trace ID dans la réponse

​
4.1 Définition de l’en-tête

Yourouter MUST renvoyer l’en-tête de réponse suivant sur chaque réponse API réussie :
  • Nom d’en-tête : X-Yourouter-Trace-Id
  • Valeur : <trace_id> (chaîne non vide identifiant la trace de cette requête)
Note : cette spécification ne définit pas le format, la longueur, l’encodage ni les propriétés d’ordonnancement du Trace ID.

​
4.2 Absence d’en-tête

  • Si Yourouter ne peut générer ou signaler une trace pour des raisons hors de son contrôle, il MAY omettre l’en-tête.
  • Si l’en-tête X-Yourouter-Trace-Id est absent, le Client MUST considérer la requête comme non traçable et MUST NOT s’appuyer sur Tencent Cloud APM pour une validation fondée sur la trace de cette requête.

​
5. Rétention

​
5.1 Fenêtre de rétention

Les données de trace dans Tencent Cloud APM sont conservées et consultables pendant 72 heures (3 jours). Après la fin de la fenêtre, la trace SHALL être considérée comme non consultable ou indisponible.

​
5.2 Exigences liées au temps

Tout audit, rapprochement, collecte de preuves ou diagnostic dépendant des données de trace APM MUST être achevé dans les 72 heures suivant l’heure de la requête. Après 72 heures, les utilisateurs MUST NOT interpréter l’impossibilité de localiser la trace comme une preuve de dysfonctionnement ou d’incohérence du système.

​
6. Persistance côté client

​
6.1 Persistance immédiate (obligatoire)

Dès réception d’une réponse, le Client MUST extraire et persister immédiatement la valeur de X-Yourouter-Trace-Id. Les cibles de persistance MAY inclure (sans s’y limiter) : journaux applicatifs, pipelines de logs structurés, bases de données, systèmes de tickets, charges d’alerte ou champs personnalisés des plateformes d’observabilité.

​
6.2 Ensemble minimal de corrélation

Le Client SHOULD persister avec le Trace ID les champs suivants pour une corrélation fiable :
  • identifiant de requête côté client (par ex. ID interne)
  • horodatage de la requête (précision au moins à la seconde)
  • chemin ou opération de l’API Yourouter
  • code HTTP (ou indicateur équivalent de succès / échec)

​
7. Procédure de requête APM

​
7.1 Procédure obligatoire

Dans la fenêtre de rétention, les utilisateurs MUST suivre cette procédure pour récupérer la trace :
  1. Obtenir la valeur X-Yourouter-Trace-Id depuis les en-têtes de réponse.
  2. Ouvrir la console Tencent Cloud APM.
  3. Aller à Trace Search / Distributed Tracing (les noms de menu peuvent varier selon la version APM).
  4. Rechercher avec le Trace ID et ouvrir le détail de la trace.
  5. Examiner la latence de bout en bout, le graphe des dépendances, les erreurs / nouvelles tentatives et les appels sortants de Yourouter vers les services amont.

​
7.2 Échec de recherche

Si la trace est introuvable dans les 72 heures, les utilisateurs SHOULD d’abord vérifier :
  • copie correcte du Trace ID (pas de troncature ni d’espaces)
  • paramètres d’échantillonnage APM (certaines requêtes peuvent ne pas produire de trace)
  • la plage horaire inclut l’instant de la requête
Si tout est confirmé et que la trace reste introuvable, les utilisateurs MAY transmettre le Trace ID et les métadonnées de requête au support Yourouter pour enquête.

​
8. Attribution et validation

​
8.1 Principe d’attribution

Dans la vue détail de la trace, les utilisateurs SHALL utiliser les appels sortants de Yourouter vers les services amont comme preuve principale de validation, notamment :
  • hôte / point de terminaison / URL de destination (pour valider la destination du routage)
  • latence, codes d’état et détails d’erreur (pour valider le résultat et le comportement)

​
8.2 Non-objectifs

Cette spécification MUST NOT exiger ni supposer de noms stables de spans, clés d’attributs ou conventions d’étiquetage internes. Les implémentations et la documentation SHOULD NOT dépendre de noms d’étiquettes fixes comme interface publique.

​
9. Sécurité et confidentialité

Les Clients SHOULD éviter de journaliser des charges de requête sensibles (prompts, données personnelles, etc.). Les Clients SHOULD ne stocker que le Trace ID et les métadonnées de corrélation minimales nécessaires aux besoins d’audit et de diagnostic.

​
10. Conformité

Une implémentation est conforme à cette spécification si :
  • Yourouter renvoie X-Yourouter-Trace-Id sur les réponses réussies (section 4.1).
  • La fenêtre de rétention est documentée et appliquée comme 72 heures (section 5).
  • La documentation impose aux Clients d’extraire et persister immédiatement le Trace ID et décrit la procédure de requête obligatoire (sections 6 et 7).