Utiliser l'outil Trace

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Qu'est-ce que l'outil Trace ?

Trace est un outil permettant de dépanner et de surveiller les 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 vous effectuez un appel d'API à la plate-forme Edge et vous lisez les résultats.

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

   Edge

   Pour accéder à la page "Proxys 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 (Private Cloud)

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

   1. Connectez-vous à http://ms-ip:9000, où ms-ip est l'adresse IP ou le nom DNS du nœud de 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 "Proxys 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 Déploiement à tracer pour sélectionner l'environnement de déploiement et la révision du proxy que vous souhaitez tracer.
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 direct.
   

   

7. Si aucun trafic en direct ne transite par votre proxy, envoyez simplement une requête à l'API. Vous pouvez utiliser l'outil de votre choix pour envoyer la requête, comme curl, Postman ou tout autre outil que vous connaissez. Vous pouvez également envoyer la demande directement depuis l'outil Trace. Il vous suffit de saisir l'URL et de cliquer sur Envoyer. Remarque : Vous ne pouvez envoyer qu'une requête GET à partir de l'outil Trace, mais pas de requête POST.
   
   Remarque : Une session Trace peut prendre en charge 10 transactions de requête/réponse par processeur de messages via le proxy d'API sélectionné. Dans le cloud Edge, avec deux processeurs de messages gérant le trafic, 20 transactions de requête/réponse sont acceptées. Une session de trace s'arrête automatiquement au bout de 10 minutes si vous ne l'arrêtez pas manuellement.
   
8. Lorsque vous avez capturé un nombre suffisant de requêtes, cliquez sur Stop Trace Session (Arrêter la session Trace).
9. Une liste des transactions de requête/réponse capturées s'affiche dans le menu de gauche. Cliquez sur l'une des transactions pour afficher les 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 du backend est une application Node.js. Consultez 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 de messages à l'aide de filtres

Vous pouvez filtrer les requêtes qui s'affichent dans l'outil Trace en spécifiant des valeurs d'en-tête et/ou de paramètre de requête. Les filtres vous permettent de cibler des appels spécifiques qui peuvent poser problème. Par exemple, vous devrez peut-être vous concentrer sur les demandes qui ont un contenu spécifique ou qui proviennent de partenaires ou d'applications spécifiques. Vous pouvez appliquer les filtres suivants :

• En-têtes HTTP : limitez la trace aux appels qui contiennent un en-tête spécifique. C'est un bon moyen de résoudre les problèmes. Vous pouvez envoyer un en-tête au développeur de votre application et lui demander de l'inclure dans l'appel qui pose problème. Apigee Edge n'enregistrera alors que les appels comportant cet en-tête spécifique, ce qui vous permettra d'examiner les résultats.
• Paramètres de requête : seuls les appels avec une valeur de paramètre spécifique seront enregistrés.

Informations à connaître sur la fonctionnalité Filtrer

• Vous devez redémarrer votre session Trace après avoir spécifié les paramètres de filtre dans les champs de filtre.
• Les paramètres de filtre sont combinés avec un opérateur AND. Toutes les paires nom/valeur de requête et/ou d'en-tête spécifiées doivent être présentes dans la requête pour que la correspondance soit établie.
• La correspondance de modèles n'est pas acceptée dans l'outil Filtres.
• Les paramètres et les valeurs des filtres sont sensibles à la casse.

Créer un filtre de trace

1. Si une session Trace est en cours d'exécution, arrêtez-la en cliquant sur Stop Trace Session (Arrêter la session Trace).
2. Cliquez sur Filtres en haut à gauche de l'outil Trace pour développer le champ "Filtres".
   
   
   
3. Dans le champ "Filtres", spécifiez les valeurs de paramètre de requête et/ou d'en-tête sur lesquelles vous souhaitez filtrer. Dans cet exemple, nous spécifions deux paramètres de requête pour filtrer les résultats. Les deux paramètres doivent être présents dans la demande pour que la correspondance soit établie.
   
   
   
4. Démarrez la session de trace.
5. Appelez vos API. Seules les requêtes qui incluent tous les en-têtes et/ou paramètres de requête spécifiés sont considérées comme correspondantes.

Dans l'exemple ci-dessus, cet appel d'API s'affichera dans Trace :

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

Mais cela ne fonctionnera pas :

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 affichant 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 règles, etc.
• En vérifiant le chemin de base, vous pouvez vous assurer qu'une règle achemine le message vers le serveur approprié.

Sélectionner les options d'affichage

Choisissez les options d'affichage pour la session Trace.

Télécharger les résultats de trace

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

Pour le télécharger, cliquez sur Download Trace Session (Télécharger la session Trace).

Afficher les requêtes au format curl

Après avoir tracé un appel d'API effectué sur un serveur cible, vous pouvez afficher la requête sous forme de commande curl. Cette fonctionnalité 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 en quoi la requête du proxy au serveur cible diffère de la requête d'origine. La commande curl représente la requête modifiée.
• Pour les charges utiles de messages plus volumineuses, curl vous permet d'afficher les en-têtes HTTP et le contenu des messages au même endroit. (Le nombre de caractères est actuellement limité à environ 1 000. Pour obtenir un conseil sur la façon de contourner cette limite, consultez ce post de la communauté.)

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

Pour afficher les requêtes au format curl après un appel d'API dans Trace, sélectionnez l'étape "Requête envoyée au serveur cible" dans le diagramme de la carte des transactions, puis cliquez sur le bouton Afficher curl dans la colonne "Requête envoyée au serveur cible" du 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.