Utiliser l'outil Trace

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Qu'est-ce que l'outil Trace ?

Trace est un outil de dépannage et de surveillance des proxys d'API exécutés sur Apigee Edge. Trace vous permet de vérifier les détails de chaque étape via un flux de proxy d'API.

Utiliser Trace

Trace est simple à utiliser. Vous démarrez une session de trace, puis effectuez un appel d'API vers la plate-forme Edge, et lire les résultats.

1. Accédez à la page "Proxies" de l'API, comme décrit ci-dessous.
   

   Edge

   Pour accéder à la page Proxies d'API à l'aide de l'interface utilisateur Edge:

   1. Connectez-vous à apigee.com/edge.
   2. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.

   Classic Edge (cloud privé)

   Pour accéder à la page Proxies d'API à l'aide de l'interface utilisateur Classic Edge:

   1. Connectez-vous à http://ms-ip:9000, où ms-ip est le Adresse IP ou nom DNS du nœud du serveur de gestion.
   2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
2. Sélectionnez un proxy d'API sur la page Proxies d'API.
3. Assurez-vous que l'API que vous souhaitez tracer est déployée.
4. Cliquez sur Trace pour accéder à la vue de l'outil Trace.
5. Utilisez le menu déroulant Deployment to Trace (Déploiement vers trace) pour sélectionner les éléments l'environnement de déploiement et la révision du proxy que vous souhaitez suivre.
6. Cliquez sur Start Trace Session (Démarrer une session Trace). Lorsque la session Trace est active, le proxy d'API enregistre les détails de chaque étape du pipeline de traitement. Pendant l'exécution de la session Trace, les messages et les données contextuelles sont capturés à partir du trafic en temps réel.
   

   

7. Si aucun trafic en temps réel ne transite par votre proxy, envoyez simplement une requête à l'API. Vous pouvez utiliser n'importe quel outil pour envoyer la requête, tel que curl, Postman ou n'importe quel outil familier. Vous pouvez également envoyer la requête directement depuis l'outil Trace. Saisissez simplement l'URL, puis cliquez sur Envoyer. Remarque:Vous ne pouvez envoyer une demande GET qu'à partir de l'outil Trace, mais pas une requête POST.
   
   Remarque:Une session Trace peut accepter 10 transactions requête/réponse par via le proxy d'API sélectionné. Dans le cloud Edge, avec deux processeurs de messages du trafic, 20 transactions de requête/réponse sont prises en charge. Une session de trace automatiquement s'arrête au bout de 10 minutes si vous ne l'arrêtez pas manuellement.
   
8. Une fois que vous avez capturé un nombre suffisant de requêtes, cliquez sur Stop Trace (Arrêter la trace) Session :
9. Une liste des transactions de requête/réponse capturées s'affiche dans le menu de gauche. Cliquez sur l'une des les transactions pour afficher des résultats détaillés.

Lire une trace

L'outil de trace comporte deux parties principales, la carte des transactions et les détails de la phase :

• La carte des transactions utilise des icônes pour marquer chaque étape importante qui se produit pendant une transaction de proxy d'API, y compris l'exécution de règles, les étapes conditionnelles et les transitions. Passez la souris sur n'importe quelle icône pour afficher des informations récapitulatives. Les étapes du flux de requêtes s'affichent en haut de la carte des transactions, tandis que les étapes du flux de réponses s'affichent en bas.
• La section Phase Details (Détails de la phase) de l'outil répertorie les informations sur le traitement interne du proxy, y compris les variables définies ou lues, les en-têtes de requête et de réponse, et bien plus encore. Cliquez sur une icône pour afficher les détails de la phase de cette étape.

Voici un exemple de carte de l'outil de trace avec les principaux segments de traitement du proxy principaux étiquetés :

Carte des transactions de l'outil Trace

Légende de la carte des transactions

Le tableau suivant décrit la signification des icônes que vous verrez dans la carte des transactions. Ces icônes marquent chacune des étapes importantes de traitement du flux du proxy.

Icônes de la carte des transactions

	Application cliente qui envoie une requête au ProxyEndpoint du proxy d'API.
	Les cercles marquent les points de terminaison de transition dans le flux du proxy. Ils sont présents lorsqu'une requête provient du client, lorsque la requête atteint la cible, lorsque la réponse est renvoyée par la cible et lorsque la réponse revient au client.
	Les barres verticales indiquent le début d'un segment dans le flux du proxy d'API. Les segments de flux sont : requête ProxyEndpoint, requête TargetEndpoint, réponse TargetEndpoint et réponse ProxyEndpoint. Un segment inclut les étapes PreFlow, Flux conditionnels et PostFlow. Pour en savoir plus, consultez la page Configurer des flux.
	Indique que des actions Analytics se sont produites en arrière-plan.
	Flux conditionnel qui renvoie la valeur "true". Pour en savoir plus sur les flux conditionnels, consultez la page Configurer des flux. Notez que certaines conditions sont générées par Edge. Par exemple, voici une expression que Edge utilise pour vérifier si une erreur s'est produite dans le ProxyEndpoint : ((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))
	Flux conditionnel qui renvoie la valeur "false". Pour en savoir plus sur les flux conditionnels, consultez la page Configurer des flux. Notez que certaines conditions sont générées par Edge. Par exemple, voici une expression que Edge utilise pour vérifier si une erreur s'est produite dans le TargetEndpoint : (((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))
	Règles Chaque type de règle possède une icône unique. Celle-ci concerne la règle AssignMessage. Ces icônes vous permettent de voir si les règles sont exécutées dans le bon ordre, et de savoir si elles ont abouti ou non. Vous pouvez cliquer sur l'icône d'une règle pour afficher les résultats de son exécution et pour savoir s'ils correspondent à ceux attendus ou non. Par exemple, vous pouvez voir si le message a été transformé correctement ou s'il est mis en cache. Les règles d'exécution correctement appliquées sont clairement indiquées par des coches. En cas d'erreur, un point d'exclamation rouge apparaît sur l'icône. Conseil : Prêtez attention à l'info-bulle ou à la chronologie pour savoir si l'une des règles prend plus de temps que prévu.
	S'affiche lorsque la cible backend est une application Node.js. Voir Présentation de Node.js sur Apigee Edge
	Cible de backend appelée par le proxy d'API.
	La chronologie indique le temps (en millisecondes) nécessaire au traitement. La comparaison des segments de temps écoulé vous permet d'isoler les règles dont l'exécution prend le plus de temps et qui ralentissent vos appels d'API.
	Le symbole epsilon indique une période inférieure à une milliseconde.
	Désactivée. Apparaît sur l'icône d'une règle lorsqu'elle est désactivée. Une règle peut être désactivée avec l'API publique. Consultez la documentation de référence sur la configuration des proxys d'API.
	Erreur. Apparaît sur l'icône d'une règle lorsque la condition de l'étape de règle renvoie la valeur "false" (voir Variables de flux et conditions), ou sur l'icône d'une règle RaiseFault à chaque exécution de celle-ci.
	Ignorée. Apparaît sur l'icône d'une règle lorsque celle-ci n'a pas été exécutée, car la condition de l'étape a renvoyé la valeur "false". Pour en savoir plus, consultez la page Variables de flux et conditions.

Comprendre les détails de la phase

La partie Phase Details (Détails de la phase) de l'outil vous fournit de nombreuses informations sur l'état de votre proxy à chaque étape de traitement. Voici quelques informations fournies dans les détails de la phase. Cliquez sur une icône de l'outil de trace pour afficher les détails de l'étape sélectionnée, ou utilisez les boutons Next/Back (Suivant/Retour) pour passer d'une étape à l'autre.

Affiner la capture des messages à l'aide de filtres

Vous pouvez filtrer les requêtes qui s'affichent dans l'outil Trace en spécifiant l'en-tête et/ou la requête des valeurs de paramètres. Les filtres vous permettent de cibler des appels spécifiques susceptibles de causer des problèmes. Par exemple, vous pouvez avoir besoin de vous concentrer sur les requêtes associées à un contenu spécifique ou à des requêtes de partenaires ou d'applications spécifiques. Vous pouvez appliquer les filtres suivants :

• En-têtes HTTP : limitez la trace aux appels contenant un nom d'utilisateur en-tête. C'est un bon moyen de vous aider à résoudre les problèmes. Vous pouvez envoyer un en-tête développeur de l'application et lui demander de l'inclure dans l'appel qui pose problème. Apigee Edge enregistre uniquement les appels avec cet en-tête spécifique afin que vous puissiez examiner les résultats.
• Paramètres de requête : uniquement les appels avec une valeur spécifique d'un paramètre. sont enregistrées.

Ce que vous devez savoir sur la fonctionnalité Filtrer

• Vous devez redémarrer votre session Trace après avoir spécifié les paramètres du filtre dans le filtre .
• Les paramètres de filtre sont reliés par un opérateur AND. Toutes les paires nom/valeur de requête et/ou d'en-tête spécifiées doit être présent dans la requête pour que la correspondance aboutisse.
• La correspondance de format n'est pas prise en charge dans l'outil Filtres.
• Les valeurs et les paramètres de filtre sont sensibles à la casse.

Créer une trace filtre

1. Si une session Trace est en cours d'exécution, arrêtez-la en cliquant sur Stop Trace (Arrêter la trace) Session :
2. Cliquez sur Filtres en haut à gauche de l'outil Trace pour développer la Filtres.
   
   
   
3. Dans le champ Filtres, spécifiez le paramètre de requête et/ou les valeurs d'en-tête que vous souhaitez filtrer. activé. Dans cet exemple, nous spécifions deux paramètres de requête à utiliser pour le filtrage. Les deux paramètres doivent être présentes dans la requête de mise en correspondance réussie.
   
   
   
4. Démarrez la session de trace.
5. appeler vos API ; Uniquement les requêtes incluant tous les en-têtes et/ou requêtes spécifiés permettent une mise en correspondance réussie.

Dans l'exemple ci-dessus, l'appel d'API suivant s'affiche dans Trace:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

En revanche, cela n'aura pas pour effet de:

http://docs-test.apigee.net/cats?name=Penny

Déboguer avec Trace

Trace vous permet d'afficher de nombreux détails internes sur un proxy d'API. Exemple :

• Vous pouvez rapidement voir quelles règles s'exécutent correctement ou échouent.
• Supposons que vous ayez remarqué dans l'un des tableaux de bord Analytics que l'une de vos API enregistre une baisse inhabituelle de performances. Vous pouvez maintenant utiliser Trace pour vous aider à identifier l'emplacement du goulot d'étranglement. Trace indique la durée (en millisecondes), nécessaire à l'exécution de chaque étape de traitement. Si l'une des étapes prend trop de temps, vous pouvez prendre des mesures correctives.
• En observant les détails de la phase, vous pouvez vérifier les en-têtes envoyés au backend, afficher les variables définies par les stratégies, etc.
• En vérifiant le chemin de base, vous pouvez vous assurer qu'une règle achemine le message vers le serveur approprié.

Sélection des options d'affichage

Choisissez les options d'affichage pour la session de trace.

Télécharger les résultats de trace

Vous pouvez télécharger un fichier XML contenant les résultats de trace bruts pour les afficher et les rechercher hors connexion dans un texte. éditeur. Le fichier présente tous les détails de la session d'écoute, y compris le contenu de tous les en-têtes, variables et stratégies.

Pour procéder au téléchargement, cliquez sur Download Trace Session (Télécharger la session Trace).

Afficher les requêtes en tant que curl

Après avoir suivi un appel d'API effectué vers un serveur cible, vous pouvez afficher la requête sous forme de fichier curl . Ceci est particulièrement utile pour le débogage pour plusieurs raisons:

• Le proxy d'API peut modifier la requête. Il est donc utile de voir comment la requête du proxy le serveur cible diffère de la requête d'origine. La commande curl représente l'instance requête.
• Pour les charges utiles de message plus volumineuses, la commande curl vous permet de voir les en-têtes HTTP et le message contenu en un seul endroit. (Le texte est actuellement limité à environ 1 000 caractères. Pour un conseil sur au-delà de cette limite, consultez ce post destiné à la communauté).

Pour des raisons de sécurité, la fonctionnalité curl masque l'en-tête d'autorisation HTTP.

Pour afficher les requêtes sous forme de curl après un appel d'API dans Trace, sélectionnez l'option "Request sent to serveur cible" dans le schéma du mappage des transactions, puis cliquez sur l'icône Afficher curl sur le bouton "Request sent to target server" (Demande envoyée au serveur cible) dans le volet Détails de la phase.

Utilisation de Trace par l'assistance Apigee

Par défaut, Apigee Edge permet à l'assistance Apigee d'utiliser l'outil Trace sur vos proxys d'API pour fournir une assistance. Vous pouvez désactiver cette option à tout moment. Toutefois, la désactivation de cette option peut limiter la capacité de l'assistance Apigee à vous fournir l'assistance.

Pour désactiver l'assistance Apigee pour l'utilisation de l'outil Trace:

1. Connectez-vous à https://apigee.com/edge.
2. Sélectionnez Admin > Confidentialité et sécurité dans la barre de navigation de gauche.
3. Cliquez sur le bouton Activer l'assistance Apigee pour Trace pour désactiver l'utilisation de l'outil de traçage par l'assistance Apigee.