Cette page a été traduite par l'API Cloud Translation.

Utiliser l'outil Trace

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Qu'est-ce que l'outil de traçage ?

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.

Regardez cette vidéo pour découvrir l'outil Trace.

Utiliser Trace

Trace est simple à utiliser. Vous démarrez une session de traçage, effectuez un appel d'API sur la plate-forme Edge et lisez les résultats.

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

Pour accéder à la page des 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 (cloud privé)

Remarque: L'interface utilisateur Classic Edge est disponible avec Edge for Private Cloud uniquement.

Pour accéder à la page des proxys d'API à l'aide de l'interface utilisateur Classic Edge:
1. Connectez-vous à http://ms-ip:9000, où ms-ip correspond à l'adresse IP ou au nom DNS du nœud du serveur de gestion.
2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
Sélectionnez un proxy d'API sur la page Proxies des API.
Assurez-vous que l'API dont vous souhaitez effectuer le traçage est déployée.
Cliquez sur Trace pour accéder à la vue de l'outil Trace.
Utilisez le menu déroulant Deployment to Trace (Déploiement vers trace) pour sélectionner l'environnement de déploiement et la révision de proxy que vous souhaitez suivre.
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.
Si aucun trafic en temps réel ne transite par votre proxy, envoyez simplement une requête à l'API. Vous pouvez utiliser l'outil de votre choix, tel que curl, Postman ou tout autre outil que vous connaissez. Vous pouvez également envoyer la requête directement depuis l'outil Trace lui-même. Il vous suffit de saisir l'URL, puis de cliquer sur Envoyer. Remarque:Vous ne pouvez envoyer une requête GET qu'à partir de l'outil Trace, mais pas de requête POST.

Remarque:Une session Trace peut accepter 10 transactions requête/réponse par processeur de messages via le proxy d'API sélectionné. Dans le cloud périphérique, où deux processeurs de messages gèrent le trafic, 20 transactions requête/réponse sont prises en charge. Une session de traçage s'arrête automatiquement au bout de 10 minutes si vous ne l'arrêtez pas manuellement.
Lorsque vous avez capturé un nombre suffisant de requêtes, cliquez sur Stop Trace Session (Arrêter la session de trace).
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 section 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 la page 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.

Détail de la phase	Description
Point de terminaison du proxy	Indique le flux ProxyEndpoint sélectionné pour exécution. Un proxy d'API peut avoir plusieurs points de terminaison de proxy nommés.
Variables	Répertorie les variables de flux lues et auxquelles une valeur a été attribuée par une stratégie. Consultez également la section Gérer l'état du proxy avec des variables de flux. Remarques : Le signe égal (=) indique la valeur attribuée à la variable. Un signe égal barré (≠) indique qu'aucune valeur n'a pu être attribuée à la variable, car elle est en lecture seule ou qu'une erreur s'est produite lors de l'exécution de la règle. Un champ vide indique que la valeur de la variable a été lue.
En-têtes de requête	Répertorie les en-têtes de requête HTTP.
Contenu de la requête	Affiche le corps de la requête HTTP.
Propriétés	Les propriétés représentent l'état interne du proxy d'API. Elles ne sont pas affichées par défaut.
Point de terminaison cible	Indique quel TargetEndpoint a été sélectionné pour l'exécution.
En-têtes de réponse	Répertorie les en-têtes de réponse HTTP.
Contenu de la réponse	Affiche le corps de la réponse HTTP.
PostClientFlow	Affiche des informations sur le PostClientFlow, qui s'exécute une fois la requête renvoyée à l'application cliente à l'origine de la requête. Seules des règles MessageLogging peuvent être associées au PostClientFlow. Actuellement, le PostClientFlow sert principalement à mesurer l'intervalle de temps entre les horodatages de début et de fin du message de réponse.

Affiner la capture d'un message à l'aide de filtres

Vous pouvez filtrer les requêtes qui s'affichent dans l'outil Trace en spécifiant les valeurs d'en-tête et/ou de paramètre de requête. 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 demandes associées à des contenus spécifiques, ou sur celles provenant de partenaires ou d'applications spécifiques. Vous pouvez appliquer les filtres suivants :

En-têtes HTTP : limitez la trace aux appels contenant 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 avec cet en-tête spécifique afin que vous puissiez examiner les résultats.
Paramètres de requête : seuls les appels avec la valeur d'un paramètre spécifique seront enregistrés.

Ce que vous devez savoir 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 reliés par l'opérateur ET. Toutes les paires requête et/ou nom d'en-tête/valeur spécifiées doivent être présentes dans la requête pour que la mise en correspondance aboutisse.
La correspondance de modèle n'est pas prise en charge dans l'outil Filtres.
Les paramètres et les valeurs de filtre sont sensibles à la casse.

Créer un filtre de trace

Si une session de traçage est en cours d'exécution, arrêtez-la en cliquant sur Stop Trace Session (Arrêter la session Trace).
Cliquez sur Filtres en haut à gauche de l'outil Trace pour développer le champ "Filtres".
Dans le champ "Filtres", spécifiez le paramètre de requête et/ou les valeurs d'en-tête que vous souhaitez utiliser comme filtre. Dans cet exemple, nous spécifions deux paramètres de requête à utiliser pour le filtrage. Les deux paramètres doivent être présents dans la requête pour que la mise en correspondance aboutisse.
Démarrez la session de traçage.
Appelez vos API. Seules les requêtes incluant tous les en-têtes et/ou paramètres de requête spécifiés génèrent une correspondance réussie.

Sous "Transactions", quatre résultats correspondant à deux paramètres de requête prédéfinis s'affichent.

Dans l'exemple ci-dessus, cet appel d'API apparaîtra dans Trace:

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

En revanche, elles ne vont 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 voir d'un coup d'œil 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 consultant 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élection des options d'affichage

Choisissez les options d'affichage pour la session de traçage.

Option	Description
Show Disabled Policies (Afficher les règles désactivées)	Affiche les règles désactivées. 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.
Show Skipped Phases (Afficher les phases ignorées)	Affiche les phases ignorées. Une phase ignorée se produit lorsque la règle 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.
Show all FlowInfos (Afficher toutes les FlowInfos)	Représente les transitions au sein d'un segment de flux.
Automatically Compare Selected Phase (Comparer automatiquement la phase sélectionnée)	Compare la phase sélectionnée à la précédente. Désactivez cette option pour n'afficher que la phase sélectionnée.
Show Variables (Afficher les variables)	Affiche ou masque les variables qui ont été lues et/ou auxquelles une valeur a été attribuée.
Show Properties (Afficher les propriétés)	Les propriétés représentent l'état interne du proxy d'API. (Masqué par défaut).

Télécharger les résultats de trace

Vous pouvez télécharger un fichier XML de résultats de trace bruts pour les afficher 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 l'ensemble des en-têtes, variables et stratégies.

Pour la télécharger, cliquez sur Télécharger la session de trace.

Afficher les requêtes en tant que curl

Après avoir tracé un appel d'API effectué sur un serveur cible, vous pouvez afficher la requête sous la forme d'une commande curl. Cette fonctionnalité est particulièrement utile pour le débogage, et ce 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 message plus volumineuses, curl vous permet de voir les en-têtes HTTP et le contenu des messages au même endroit. (La limite est actuellement fixée à 1 000 caractères. Pour découvrir comment dépasser 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 requêtes curl après la réception d'un appel d'API dans Trace, sélectionnez l'étape "Request sent to target server" (Requête envoyée au serveur cible) dans le schéma de carte des transactions, puis cliquez sur le bouton Show curl (Afficher curl) dans la colonne "Request sent to target server" (Requête envoyée au serveur cible) dans le volet "Phase Details" (Détails de la phase).

Les annotations d'image indiquent le bouton "Show curl" (Afficher le curl) et l'un des cercles du diagramme de carte des transactions.

Compatibilité d'Apigee avec l'utilisation de Trace

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:

Connectez-vous à https://apigee.com/edge.
Sélectionnez Admin > Confidentialité et sécurité dans la barre de navigation de gauche.
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.