Diagnose API errors with front-to-back tracing - Application Real-Time Monitoring Service

La surveillance du navigateur affiche le temps de réponse d'une requête API, mais n'offre aucune visibilité sur les performances réseau ni sur la trace d'appel backend, ce qui complique le dépannage des problèmes d'API. Le traçage de bout en bout résout ce problème en reliant les appels API frontend à l'intégralité de leurs traces backend, vous offrant ainsi une vue complète du cycle de vie de la requête.

Prérequis

Vous avez activé la surveillance du navigateur et la surveillance des applications pour Application Real-Time Monitoring Service (ARMS). Pour plus d'informations, consultez Activer ARMS. La surveillance des applications ARMS nécessite la version 2.4.5 ou ultérieure. Pour les détails de configuration, voir Présentation de la surveillance des applications.

Contexte

La surveillance des applications révèle les performances des API backend et la trace d'appel, mais pas l'expérience utilisateur réelle. La surveillance du navigateur affiche uniquement le temps total et le statut d'une requête API, sans fournir les détails backend. Le traçage de bout en bout comble cette lacune en reliant les actions utilisateur frontend aux services backend, créant ainsi une expérience de dépannage unifiée et complète.

Configurer la surveillance du navigateur ARMS

Requêtes API de même origine

Vérifiez qu'un mappage existe entre votre site frontend et l'application backend.
Assurez-vous que la déclaration automatique des API est activée.

Définissez le paramètre enableLinkTrace sur true pour activer le traçage de bout en bout. Le code suivant présente un exemple de configuration :

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxx",imgUrl:"https://arms-retcode.aliyuncs.com/r.png?", enableLinkTrace: true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
</script>

Requêtes API inter-origines (Cross-origin)

Vérifiez qu'un mappage existe entre votre site frontend et l'application backend.

Définissez les paramètres enableLinkTrace et enableApiCors sur true.

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxx",imgUrl:"https://arms-retcode.aliyuncs.com/r.png?", 
enableLinkTrace: true, enableApiCors: true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
</script>

Important

Si vous définissez le paramètre enableApiCors sur true, votre service backend doit également prendre en charge les requêtes inter-origines et les valeurs d'en-tête personnalisées. Assurez-vous que toutes les requêtes fonctionnent correctement lors des tests d'intégration. Dans le cas contraire, les requêtes peuvent échouer. Le code suivant présente un exemple de configuration Nginx :

upstream test {
        server 192.168.220.123:9099;
        server 192.168.220.123:58080;
    }
    server {
        listen    5800;
        server_name  192.168.220.123;
        root         /usr/share/nginx/html;
        include /etc/nginx/default.d/*.conf;
        location / {
            proxy_pass http://test;
            proxy_set_header Host $host:$server_port;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Real-PORT $remote_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   EagleEye-TraceID $eagleeye_traceid;
            proxy_set_header   EagleEye-SessionID $eagleEye_sessionid;
            proxy_set_header   EagleEye-pAppName $eagleeye_pappname;
        }

Pour configurer l'ignorance, consultez ignore. Voici la configuration :

let whitelist = ['api.xxx','source3']; // Whitelist.
let blacklist = ['source2','source6']; // Blacklist.
// Choose between a whitelist or blacklist based on your needs by returning true or false in the function.
ignore: {
            ignoreApis: [
                function(str) {   // Function.
                    if (whitelist.includes(str)) {
                        return false;
                    }
                    return true; // Return true to ignore.
                }]
         }

Remarque

Le paramètre ignore agit comme une liste d'autorisation ou une liste de blocage. Il empêche la modification des en-têtes pour les requêtes adressées à des ressources tierces spécifiques, ce qui permet d'éviter les erreurs de requête.

Fonctionnement

Lorsque la déclaration automatique des API est activée, le SDK ajoute deux en-têtes personnalisés, EagleEye-TraceID et EagleEye-SessionID, aux requêtes API envoyées vers la même origine.
Si la requête API est envoyée vers une origine différente, le SDK n'ajoute pas ces en-têtes personnalisés. Cela garantit que la requête inter-origines peut être envoyée sans erreur.
Pour vérifier que la configuration du traçage de bout en bout est active, ouvrez la console de développement de votre navigateur et inspectez les en-têtes de requête d'un appel API. Si les en-têtes EagleEye-TraceID et EagleEye-SessionID sont présents, la fonctionnalité est active.

Avertissement
Les valeurs EagleEye-TraceID et EagleEye-SessionID ont une signification spécifique et sont générées automatiquement. Ne les générez pas manuellement.

Cas d'utilisation et exemples

La chronologie aide à déterminer si la latence élevée provient du transport réseau ou du processus backend. Cliquez sur la pile d'appels de l'application backend pour afficher la trace d'appel backend complète de la requête.

Si une API renvoie un code d'erreur ou si une erreur de logique métier se produit, suivez ces étapes pour identifier la cause :
1. Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, choisissez Browser Monitoring > Browser Monitoring.
2. Sur la page Browser Monitoring, sélectionnez une région dans la barre de navigation supérieure et cliquez sur le nom de l'application que vous souhaitez gérer.
3. Dans le volet de navigation de gauche, cliquez sur API request.
4. Dans la section API link trace (TOP 20) à droite, trouvez l'API ou l'ID de trace pertinent dans la API failure list et cliquez sur Managed Service for OpenTelemetry dans la colonne Actions. Une vue s'ouvre, affichant le temps frontend global et une chronologie des appels backend.
  
  Les résultats de la trace sont affichés dans un tableau sous l'onglet Invocation trace. Les colonnes incluent le nom de l'application, l'heure du journal, le statut, l'adresse IP, le type d'appel, le nom du service, la pile d'appels, le profilage des threads et la chronologie. Dans ce tableau, vous pouvez consulter le type d'appel (tel que Browser ou HTTP Entry), le statut (un point rouge indique une erreur, un point vert indique un succès) et une comparaison du temps pris par chaque span.
5. Utilisez la chronologie pour déterminer si la latence élevée est causée par le transport réseau ou le traitement backend.
6. Pour l'application backend, cliquez sur l'icône de loupe dans la colonne Method Stack pour afficher la trace d'appel backend complète de cette requête. Vous pouvez ensuite identifier la cause de l'erreur API en fonction de votre logique métier.
  
  Le panneau de détails de la trace d'appel affiche un tableau montrant la hiérarchie des appels, le numéro de ligne, les informations étendues et la chronologie (en millisecondes) pour chaque méthode. Les noms de méthode avec une latence inhabituellement élevée sont mis en évidence en rouge, et les barres bleues à droite visualisent la proportion de temps de chaque méthode, vous aidant à localiser rapidement les goulots d'étranglement de performance.
Si une requête API présente une latence élevée, suivez ces étapes pour identifier la cause :
1. Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, choisissez Browser Monitoring > Browser Monitoring.
2. Sur la page Browser Monitoring, sélectionnez une région dans la barre de navigation supérieure et cliquez sur le nom de l'application que vous souhaitez gérer.
3. Dans le volet de navigation de gauche, cliquez sur API request.
4. Dans la section API link trace (TOP 20) à droite, triez les API par durée de requête décroissante pour trouver l'API ou l'ID de trace présentant une latence élevée.
5. Cliquez sur le lien Managed Service for OpenTelemetry dans la colonne Actions pour afficher le temps frontend global et une chronologie des appels backend.
  - Si un temps de traitement backend court accompagne un temps de réponse global long, cela indique une latence réseau élevée. Dans ce cas, cliquez sur View details pour inspecter les détails de la session, y compris le réseau, la région, le navigateur, l'appareil et le système d'exploitation.
  - Si le temps de traitement backend est long, cela indique de mauvaises performances. Cliquez sur l'icône de loupe dans la colonne Method Stack. Dans la boîte de dialogue de la pile d'appels locale, examinez la trace backend pour trouver la partie la plus gourmande en temps et identifier le problème.