Utiliser l'outil Debug

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette section explique comment créer et gérer des sessions de débogage, et afficher les données de requête et de réponse à l'aide de l'UI et de l'API Apigee.

L'outil Offline Debug vous permet d'afficher et d'analyser les sessions de débogage précédemment téléchargées.

Créer une session de débogage

Lorsque vous créez une session de débogage, vous pouvez afficher les données de requête et de réponse dans l'UI (pour les requêtes créées dans l'API ou une autre source externe).

Créez une session de débogage à l'aide de l'UI ou de l'API Apigee, comme décrit dans les sections suivantes.

Nouvel éditeur de proxys

Pour créer une session de débogage dans le nouvel éditeur de proxy, procédez comme suit :

Si vous utilisez https://console.cloud.google.com/apigee : sélectionnez Développement de proxys > Proxys d'API.

Si vous utilisez la version classique de l'interface utilisateur d'Apigee : sélectionnez Développer > Proxys d'API, puis dans le volet Proxys, sélectionnez l'environnement correspondant au proxy que vous souhaitez déboguer.
Sélectionnez le proxy d'API que vous souhaitez déboguer. La vue Présentation de l'éditeur de proxy s'affiche.
Cliquez sur l'onglet Débogage en haut à gauche de la fenêtre.
Cliquez sur Démarrer la session de débogage en haut à droite du volet Débogage. La boîte de dialogue Démarrer la session de débogage s'affiche.

Dans la boîte de dialogue :
1. Sélectionnez l'environnement dans lequel vous souhaitez exécuter la session de débogage.
2. (Facultatif) Dans la liste déroulante Filter (Filtre), sélectionnez un filtre à appliquer à toutes les transactions de la session de débogage que vous créez. La valeur par défaut est None (All transactions) (Aucun), qui inclut toutes les transactions des données de débogage.
  Pour plus d'informations sur l'utilisation des filtres, consultez la section Utiliser des filtres dans une session de débogage. Pour plus d'informations sur les filtres intégrés, consultez la section Utiliser des filtres prédéfinis.
3. Cliquez sur Démarrer.

L'interface utilisateur d'Apigee affiche maintenant la vue Session de débogage en cours.

La session de débogage enregistre les requêtes pendant 10 minutes après la création de la session. Le champ Se termine dans affiche le temps restant de la session.

Vous ne verrez aucune information dans le volet de débogage tant que vous n'aurez pas envoyé de requête au proxy que vous déboguez dans l'environnement sélectionné. environnement de la session de débogage.

Une fois la requête envoyée, elle s'affiche au bas du volet de gauche.

Boîte de dialogue de démarrage de la session de débogage

Remarque : Au cours d'une session de débogage active, vous pouvez démarrer une autre session dans l'UI Apigee. Pour ce faire, cliquez à nouveau sur Démarrer la session de débogage.

Afficher le graphique de Gantt pour une transaction

Pour afficher les détails d'une transaction (requête et réponse) dans la vue de débogage, cliquez sur la ligne correspondant à la transaction, comme illustré dans l'image ci-dessus.

Un graphique de Gantt s'affiche alors dans le volet de droite, affichant les étapes de la requête et de la réponse.

Graphique de Gantt des étapes de transaction dans le volet de droite

L'axe horizontal du diagramme indique les heures auxquelles chaque étape s'est produite, mesurée en millisecondes. Chaque étape est représentée par un rectangle qui s'étend de l'heure de début à l'heure de fin de l'étape.

Vous pouvez avancer dans une session de débogage à l'aide des boutons Retour et Suivant situés en bas à droite du volet de débogage. Cliquez sur :

Retour pour déplacer la ligne sélectionnée à l'étape précédente du graphique ;
Suivant pour déplacer la ligne sélectionnée vers l'étape suivante du graphique.

Dans l'exemple ci-dessus, le graphique affiche deux règles exécutées dans la réponse :

ResponsePayload
Ajouter un CORS

Vous pouvez cliquer sur l'une de ces étapes pour en afficher les détails. Par exemple, si vous cliquez sur la règle Ajouter une règle CORS, des détails semblables à ceux présentés ci-dessous s'affichent à côté du graphique de Gantt.

Ajouter les détails de la règle CORS

Si vous avez ensuite décidé d'apporter des modifications à la configuration des stratégies, vous pouvez cliquer sur Développer pour passer à la vue Développer, où vous verrez les mêmes deux stratégies dans la réponse PostFlow.

Afficher l'onglet "Développer" en lien avec une session de débogage

Vous pouvez partager une session de débogage avec d'autres utilisateurs ayant accès à votre organisation et disposant des autorisations nécessaires. Pour ce faire, il vous suffit de leur envoyer l'URL affichée dans votre navigateur lorsque vous affichez la session de débogage. Le lien n'est valide que pendant 24 heures après la création de la session de débogage.

Télécharger une session de débogage

Une fois la session de débogage terminée, vous pouvez la télécharger afin de l'analyser ultérieurement dans l'outil de débogage hors connexion. Pour ce faire, cliquez sur Télécharger la session dans le volet de gauche.

Télécharger une session de débogage

Notez qu'une session de débogage est supprimée dans les 24 heures suivant son achèvement. Par conséquent, si vous souhaitez afficher la session de débogage au-delà de cette période, vous devez la télécharger avant.

Lorsque vous téléchargez une session de débogage, le nom du fichier de téléchargement se présente sous la forme "debug-{session ID}.json", {session ID} étant l'ID de la session de débogage. Toutefois, vous pouvez renommer le fichier si vous le souhaitez.

Éditeur de proxy classique

Pour créer une session de débogage dans l'éditeur de proxy classique, procédez comme suit :

Connectez-vous à l'UI Apigee.
Sélectionnez Proxys d'API dans la vue principale.
Sélectionnez le proxy d'API que vous souhaitez déboguer.

L'onglet Overview (Présentation) s'affiche.
Cliquez sur l'onglet Debug dans l'angle supérieur droit de la page :

La vue Debug s'affiche :

Dans le panneau Start a debug session (Démarrer une session Debug) :

Dans la liste déroulante Env, sélectionnez l'environnement et le numéro de révision du proxy d'API que vous souhaitez déboguer.

L'exemple suivant montre le panneau Start a debug session (Démarrer une session Debug) :

Panneau Démarrer une session Debug

(Facultatif) Dans la liste déroulante Filter (Filtre), sélectionnez un filtre à appliquer à toutes les transactions de la session de débogage que vous créez. La valeur par défaut est None (Aucun), qui inclut toutes les transactions des données de débogage.
Pour plus d'informations sur l'utilisation des filtres, consultez la section Utiliser des filtres dans une session de débogage. Pour plus d'informations sur les filtres intégrés, consultez la section Utiliser des filtres prédéfinis.

Cliquez sur Start Debug Session (Démarrer la session Debug).

L'UI Apigee affiche maintenant des détails sur la session Debug actuelle, y compris son ID, dans le panneau Debug details (Informations sur Debug).

Bien que l'UI ait créé la session de débogage, vous devez quand même envoyer la requête pour que des données soient collectées.

Dans le panneau Debug details (Informations sur Debug), vous pouvez effectuer les opérations suivantes :

Icône	Fonction	Description
	Télécharger	Téléchargez les données de débogage de la session active, que vous pouvez afficher hors connexion.
	Retour	Revenez au panneau précédent, dans lequel vous pouvez lancer une autre session de débogage. La session de débogage actuelle se poursuit jusqu'à ce qu'elle atteigne le délai avant expiration ou le nombre de transactions.
	Supprimer	Supprimez les données de la session de débogage actuellement sélectionnée. Cette action supprime les données de la session, mais elle n'arrête pas la session.

Le délai avant expiration par défaut est de 10 minutes pour une session Debug démarrée dans l'UI (il est différent pour une session démarrée avec l'API).

L'horloge démarre dès que vous cliquez sur Start trace session (Démarrer une session Debug). Vous pouvez donc choisir d'attendre jusqu'après l'étape suivante avant de cliquer sur Start trace session (Démarrer une session Debug) pour maximiser la quantité de données collectées.

Dans le panneau Envoyer des requêtes :
1. Dans le champ URL, saisissez le point de terminaison auquel vous souhaitez envoyer une requête. Vous pouvez également ajouter des paramètres de chaîne de requête à l'URL. Vous ne pouvez pas envoyer de requêtes autres que GET.
  Trouver l'URL du point de terminaison
  1. Accédez à Administrateur > Environnements > Accès.
  2. L'URL correspond au nom d'hôte de l'environnement respectif avec lequel vous souhaitez exécuter votre session de débogage.
2. Cliquez sur Send (Envoyer).
  Apigee envoie une requête à l'URL spécifiée. Chaque fois que vous cliquez sur Envoyer, l'UI Apigee consigne la requête dans le panneau Informations sur Debug.
  
  L'exemple suivant montre plusieurs requêtes réussies (générant un code d'état HTTP 200) :
  
  Cliquez sur Copier afin de copier l'ID de débogage pour référence ultérieure ou des requêtes.
  De plus, l'interface utilisateur affiche les données de débogage dans les sections "Carte de transactions" et "Détails de la phase" du panneau Envoyer des requêtes, puis remplit les sections "Point de terminaison du proxy", "En-têtes de requête", "Contenu de la requête" et "Propriétés", comme le montre l'exemple suivant :
  
  Pour en savoir plus sur les phases, la carte de transactions et les autres sections de la vue Envoyer des requêtes, consultez Comment lire un débogage.
La session de débogage est maintenant active et enregistre des données sur toutes les requêtes (sauf si elles sont filtrées). La session reste active jusqu'à ce que le délai avant expiration ou le nombre de requêtes enregistrées au cours de la session soit dépassé.
Vous pouvez créer un nombre illimité de sessions de débogage dans l'UI. Pour en savoir plus, consultez la section Démarrer une autre session de débogage.

Démarrer une autre session de débogage dans l'UI

Au cours d'une session de débogage active, vous pouvez démarrer une autre session dans l'UI Apigee. Pour ce faire, cliquez sur l'icône Flèche de retour () dans le panneau Informations sur Debug :

Flèche de retour au panneau "Démarrer une session Debug"

L'interface utilisateur retourne au panneau Démarrer une session Debug, dans lequel vous pouvez démarrer une nouvelle session de débogage.

Quand une session de débogage se termine-t-elle ?

Il ne suffit pas d'arrêter une session de débogage active. Toutefois, vous pouvez supprimer les données d'une session active, comme décrit dans la section Supprimer les données de session de débogage.

Lorsque vous créez une session de débogage, deux propriétés déterminent sa fin :

timeout : durée pendant laquelle vous collectez des données au cours d'une session. La durée par défaut dépend de la façon dont vous avez démarré la session (via l'UI ou l'API). La valeur maximale est de 600 secondes (ou 10 minutes).
Conseil : Vous ne pouvez pas configurer de délai avant expiration lorsque vous créez une session de débogage avec l'UI Apigee. Toutefois, vous pouvez le définir lorsque vous créez une session de débogage à l'aide de l'API.
count : nombre maximal de requêtes enregistrées dans une seule session par processeur de messages. Étant donné que le nombre de processeurs de messages est variable dans la plupart des clusters, les effets de cette valeur peuvent être imprévisibles. Apigee ne recommande pas de personnaliser ce paramètre.

Lorsque le délai avant expiration ou le nombre de requêtes est atteint, la session de débogage de ce processeur de messages prend fin.

Les termes suivants sont utilisés pour décrire l'état d'une session de débogage :

session active désigne une session de débogage qui n'a pas encore atteint son délai avant expiration ou qui a dépassé son nombre de requêtes. Une session active enregistre toujours les données des requêtes qui ne sont pas filtrées.
session terminée désigne une session de débogage ayant atteint son délai avant expiration ou dépassé son nombre de requêtes. Une session terminée n'enregistre plus les données sur les nouvelles requêtes, et les données sont supprimées dans les 24 heures qui suivent la fin de la session.

Lire un débogage

L'outil de débogage 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 débogage avec les principaux segments de traitement du proxy principaux étiquetés :

Carte des transactions de l'outil Debug

Schéma de débogage illustrant le flux Début de la requête de proxy > début de la requête cible > début de la réponse cible > début de la réponse du proxy > début du flux postérieur client.

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 Apigee. Par exemple, voici une expression qu'Apigee 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 Apigee. Par exemple, voici une expression qu'Apigee 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.
	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é. 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 débogage pour afficher les détails de l'étape sélectionnée, ou utilisez les boutons 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 qui ont été lues et auxquelles une valeur a été attribuée par une règle. Consultez également la page Utiliser 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 le TargetEndpoint qui a été sélectionné pour 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.

API Apigee

Pour créer une session de débogage à l'aide de l'API, envoyez une requête POST à la ressource suivante :

https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/debugsessions

Vous pouvez également :

définir la durée d'une session de débogage (en secondes) en transmettant la propriété timeout en tant que paramètre de requête ou dans le corps de la requête. Si elle est spécifiée dans les deux, la valeur timeout spécifiée dans le corps de la requête est prioritaire.
filtrer les données dans une session de débogage en transmettant la propriété filter dans le corps de la requête.

L'exemple suivant montre comment créer une session de débogage à l'aide de l'API.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"

Où $TOKEN est défini sur votre jeton d'accès OAuth 2.0, comme décrit dans la section Obtenir un jeton d'accès OAuth 2.0. Pour en savoir plus sur les options curl utilisées dans cet exemple, consultez la section Utiliser curl. Pour obtenir une description des variables d'environnement utilisées, consultez la section Définir des variables d'environnement pour les requêtes API Apigee.

Voici un exemple de réponse :

{
  "name":"56382416-c4ed-4242-6381-591bbf2788cf",
  "validity":300,
  "count":10,
  "tracesize":5120,
  "timeout":"600"
}

Les requêtes suivantes adressées à votre proxy d'API (jusqu'à ce que la durée de la session ou le nombre maximal de requêtes soient atteint) seront évaluées et potentiellement stockées dans les données de session de débogage.

Pour en savoir plus, consultez la page API Create Debug Session.

Définir la durée d'une session de débogage à l'aide de l'API

Pour définir la durée d'une session de débogage à l'aide de l'API, incluez les éléments suivants en tant que charge utile dans votre requête de création de session de débogage :

{
  "timeout":"debug_session_length_in_seconds"
}

L'exemple suivant crée une session de débogage de seulement 42 secondes :

curl https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions"
  -X "POST" \
  -H "Authorization: Bearer $TOKEN" \
  -d ' {
    "timeout":"42"
  } '

Vous pouvez définir le paramètre timeout d'une session dans les requêtes de création de session de débogage uniquement. Vous ne pouvez pas modifier la durée d'une session après sa création.

La valeur par défaut de timeout est 300 (cinq minutes). La valeur maximale est de 600 secondes (10 minutes).

Déboguer avec l'outil Debug

Le débogage 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 désormais utiliser l'outil Debug pour vous aider à identifier l'origine du goulot d'étranglement. Debug 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.
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é.

Filtrer les données dans une session de débogage

Lorsque vous créez une session de débogage, vous pouvez ajouter un filtre à cette session afin qu'Apigee ne renvoie que les données souhaitées. Un filtre est une instruction conditionnelle qu'Apigee évalue par rapport aux messages de requête et de réponse pour déterminer si ses données de débogage doivent être incluses dans la session de débogage. Par exemple, vous pouvez filtrer toutes les requêtes avec un code de réponse HTTP inférieur à 599 ou comparer les valeurs de la requête à des variables personnalisées.

Veuillez noter les points suivants :

Les requêtes qui ne sont pas incluses dans une session de débogage car elles sont filtrées ne sont pas comptabilisées dans le nombre maximal de transactions de la session de débogage.
Apigee ne prend pas en charge l'ajout de filtres dans la chaîne de requête.
Une fois une session de débogage démarrée, vous ne pouvez plus y ajouter de filtre. Pour ajouter un filtre, vous devez créer une session de débogage.

Utiliser des filtres

Utilisez un filtre lorsque vous créez une session de débogage à l'aide de l'UI ou de l'API Apigee, comme décrit dans les sections suivantes.

Interface utilisateur d'Apigee

Lorsque vous créez une session de débogage dans l'interface utilisateur, dans la liste déroulante Filtres, vous pouvez choisir un filtre prédéfini à appliquer dans le panneau Démarrer une session Debug, sélectionnez Filtre personnalisé, puis créez le vôtre à l'aide de la syntaxe des filtres.

API Apigee

Pour créer une session de débogage avec un filtre à l'aide de l'API, incluez les éléments suivants en tant que charge utile dans votre requête de création de session de débogage :

{
  "filter":"filter_body"
}

Pour en savoir plus sur la construction de filtres, consultez la section Syntaxe des filtres.

L'exemple suivant crée une session de débogage qui n'inclut que les transactions dans lesquelles l'en-tête A est égal à 42 et l'en-tête B à 43, ou le code d'erreur est ExpectedEOF :

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

Vous ne pouvez définir un filtre que dans les requêtes de création de session de débogage uniquement. Vous ne pouvez pas ajouter de filtre à une session de débogage existante, ni supprimer un filtre d'une session de débogage active.

Syntaxe des filtres

Les filtres acceptent la même syntaxe que celle utilisée par les conditions Apigee, comme décrit dans la documentation de référence sur les conditions. Par exemple :

Regroupement
Opérateurs logiques AND (&&) et OR (|")
Expressions de chemin d'accès
Opérateurs et opérandes
Littéraux (null, true et false)

De plus, les filtres peuvent accéder à l'ensemble des variables de flux qui sont décrites dans la documentation de référence sur les variables de flux, ainsi qu'aux variables personnalisées. Les exemples suivants ne montrent qu'une partie des variables de flux possibles que vous pouvez utiliser dans les filtres :

# Response codes:
  response.status.code <= 599
  response.status.code >=301 && response.status.code <=420

# Requests/responses:
  request.verb == "GET"
  request.header.A == 'B' || request.queryparam.X == 'Y'

# Query parameters:
  request.queryparam.myparam == 'fish'
  (request.queryparam.param1 == 'X' || request.queryparam.param2 == 'Y') && request.queryparam.param3 == 'Z'

# Faults:
  fault.code != 'messaging.runtime.RouteFailed'
  fault.name == 'IPDeniedAccess'

Pour plus d'informations sur l'utilisation des variables personnalisées, consultez la page sur l'utilisation des attributs personnalisés dans Apigee dans la communauté Apigee.

Filtres prédéfinis de l'UI

L'UI Apigee fournit un ensemble de filtres courants, ce qui vous évite d'avoir à écrire vos propres filtres personnalisés. Les filtres prédéfinis sont récapitulés dans le tableau ci-dessous.

Nom du filtre	Description
`Response Time Greater Than`	Recherche les problèmes de latence dans lesquels : `target.duration` est la latence cible, soit le temps (en millisecondes) nécessaire à l'envoi d'une requête à la cible et à sa réception depuis celle-ci (calculé en tant que différence entre `target.received.end.timestamp` et `target.sent.start.timestamp`) `client.duration` est la latence client, soit le temps (en millisecondes) nécessaire à l'envoi d'une requête au client et à sa réception depuis celui-ci (calculé en tant que différence entre `client.received.end.timestamp` et `client.sent.start.timestamp`) Exemple : target.duration > 420 && client.duration > 1000 Pour en savoir plus, consultez les sections `client` et `target` dans la documentation de référence sur les variables de flux.
`Response Code`	Vérifie si le code de réponse HTTP correspond à la valeur spécifiée. Exemple : response.status.code <= 599 Conseil : Si vous recevez des erreurs, essayez d'utiliser `message.status.code` au lieu de `response.status.code`.
`Header`	Vérifie si l'en-tête de requête spécifié est égal à la valeur spécifiée. Exemple : request.header.cache-control.1 == "16544"
`Path`	Vérifie si la requête correspond au chemin d'accès spécifié. Vous pouvez utiliser la correspondance des caractères génériques dans la valeur. Exemple : request.path == /myproxy/customer/4*
`Query Param`	Vérifie si le paramètre de requête spécifié est égal à la valeur spécifiée. Exemple : request.queryparam.lang == "language:en-us"
`Custom`	Vous permet d'insérer vos propres expressions. Vous pouvez utiliser n'importe quel objet figurant dans la documentation de référence sur les variables de flux et la syntaxe indiquée dans la documentation de référence sur les conditions. En outre, vous pouvez utiliser des variables personnalisées. Pour en savoir plus sur la création de filtres personnalisés, consultez la section Syntaxe des filtres.

Afficher les sessions de débogage

Apigee enregistre les données de session de débogage pendant 24 heures. Vous ne pouvez pas configurer cette valeur. Au bout de 24 heures, les données ne seront plus disponibles. Avant la fin de ce délai, vous pouvez afficher les sessions de débogage.

Affichez les sessions de débogage récentes à l'aide de l'UI ou de l'API Apigee, comme décrit dans les sections suivantes.

Nouvel éditeur de proxys

Pour afficher les sessions de débogage à l'aide du nouvel éditeur de proxy, procédez comme suit :

Si vous utilisez https://console.cloud.google.com/apigee : sélectionnez Développement de proxys > Proxys d'API.

Si vous utilisez la version classique de l'interface utilisateur d'Apigee : sélectionnez Développer > Proxys d'API, puis dans le volet Proxys, sélectionnez l'environnement correspondant au proxy que vous souhaitez déboguer.
Sélectionnez le proxy que vous souhaitez déboguer.
Cliquez sur l'onglet Débogage.
La section Sessions de débogage récentes affiche la liste des sessions de débogage disponibles.
Cliquez sur le lien de la session à afficher.

Éditeur de proxy classique

Pour afficher les sessions de débogage à l'aide de l'éditeur de proxy classique :

Connectez-vous à l'UI Apigee.
Sélectionnez Proxys d'API dans la vue principale.
Sélectionnez le proxy que vous souhaitez déboguer.
Cliquez sur l'onglet Debug en haut à droite de la vue Déploiements.
Dans le panneau Sessions Debug récentes :
1. Dans la liste déroulante Env, sélectionnez l'environnement du proxy d'API dont vous souhaitez afficher la session de débogage.
2. Dans la liste déroulante Rev (Rév.), sélectionnez le numéro de révision du proxy d'API dont vous souhaitez afficher la session de débogage.
L'UI d'Apigee affiche la liste des sessions de débogage disponibles.
Cliquez sur le lien de la session à afficher.

L'interface utilisateur d'Apigee charge la session de débogage et renseigne le panneau Envoyer des requêtes avec les données de débogage.

Sélectionner les options d'affichage dans l'UI

Dans l'UI Apigee, vous pouvez choisir les options d'affichage pour la session Debug.

Liste des options d'affichage

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 Conditions avec variables de flux.
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).

API Apigee

Grâce à l'API, vous pouvez effectuer les tâches suivantes :

Afficher toutes les sessions de débogage
Afficher toutes les transactions d'une session de débogage
Afficher les données de transaction pour une session de débogage

Afficher toutes les sessions de débogage à l'aide de l'API

Pour afficher toutes les sessions de débogage récentes définies pour une révision de proxy d'API dans un environnement, envoyez une requête GET à la ressource suivante :

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions

Vous pouvez également spécifier l'un des paramètres de requête suivants pour contrôler la quantité de données renvoyées :

pageSize : nombre maximal de sessions de débogage à répertorier. Par défaut, la taille de la page est de 25.
pageToken : jeton de page, renvoyé par un appel précédent, que vous pouvez utiliser pour récupérer la page suivante.

L'exemple suivant montre comment afficher les sessions de débogage pour la révision 1 du proxy d'API helloworld dans l'environnement test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

La réponse inclut un objet sessions contenant la liste des sessions de débogage actives, comme illustré dans l'exemple suivant :

{
  "sessions": [
    {
      "id": "a423ac73-0902-4cfa-4242-87a353a84d87",
      "timestamp_ms": 1566330186000
    },
    {
      "id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
      "timestamp_ms": 1566330286000
    }
  ]
}

Seules les sessions de débogage qui contiennent au moins une transaction sont incluses dans la réponse. Les sessions de débogage sans transaction ne figurent pas dans cette liste.

Pour en savoir plus, consultez la page API List Debug Sessions.

Afficher toutes les transactions d'une session de débogage à l'aide de l'API

Pour afficher la liste des transactions d'une session de débogage, envoyez une requête GET à la ressource suivante :

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Où debugsession est l'ID d'une session de débogage renvoyée lorsque vous affichez les sessions de débogage.

L'exemple suivant montre comment afficher les transactions d'une session de débogage pour la révision 1 de l'API helloworld dans l'environnement test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

La réponse inclut un tableau d'ID de transaction, comme illustré dans l'exemple suivant :

[
  "myorg-test-ver-5qxdb-64",
  "myorg-test-ver-5qxdb-65",
  "myorg-test-ver-5qxdb-66",
  "myorg-test-ver-5qxdb-67",
  "myorg-test-ver-5qxdb-68",
  "myorg-test-ver-5qxdb-69",
  "myorg-test-ver-5qxdb-70",
  "myorg-test-ver-5qxdb-71",
  "myorg-test-ver-5qxdb-72"
]

Pour en savoir plus, consultez la page API List Debug Session Data.

Afficher les données de transaction d'une session de débogage à l'aide de l'API

Pour afficher les données de transaction d'une session de débogage, envoyez une requête GET à la ressource suivante :

https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/apis/{api}/revisions/{rev}/debugsessions/{debugsession}/data/{transactionId}

Où debugsession est l'ID d'une session de débogage renvoyée lorsque vous affichez les sessions de débogage, et transactionId est l'ID de transaction renvoyé lorsque vous affichez la liste des transactions pour une session de débogage.

Les données de transaction enregistrées au cours d'une session de débogage sont au format JSON. Vous pouvez charger ces données dans l'outil Offline Debug.

L'exemple suivant montre comment télécharger les données de transaction d'une session de débogage pour la révision 1 de l'API helloworld dans l'environnement test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data/myorg-test-ver-5qxdb-64" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

La réponse se compose d'une charge utile JSON contenant les données de la transaction spécifiée, comme décrit dans la section Structure des données téléchargées.

Les données de débogage contiennent toutes les informations sur la requête et la réponse pour chaque partie du flux, dans un format JSON propriétaire. Vous pouvez enregistrer ces données et les utiliser ultérieurement dans l'outil Offline Debug.

Si aucune requête n'a été ajoutée à la session avant la fin de celle-ci, la réponse se présente comme suit :

[]

Pour en savoir plus, consultez la page API Get Debug Session Data.

Télécharger les données de session de débogage

Vous pouvez télécharger un fichier de résultats de débogage bruts pour le consulter hors connexion. Le fichier téléchargé affiche tous les détails de la session de débogage, y compris le contenu de tous les en-têtes, les variables et les règles.

Les données de session de débogage peuvent être téléchargées ou affichées dans l'UI pendant 24 heures uniquement. Ensuite, Apigee les supprime.

Nouvel éditeur de proxys

Pour télécharger la session de débogage actuelle dans le nouvel éditeur de proxys, cliquez sur Télécharger la session dans le volet de gauche de la vue de débogage.

Télécharger une session de débogage

Éditeur de proxy classique

Pour télécharger les données de la session de débogage actuelle à l'aide de l'éditeur de proxy classique, procédez comme suit :

Session active : cliquez sur l'icône de téléchargement () dans le panneau Informations sur Debug.
Session précédente : cliquez sur le nom de la session dans le panneau Sessions Debug récentes, comme décrit dans la section Afficher les sessions de débogage. Cliquez ensuite sur dans le panneau Informations sur Debug.

API Apigee

Pour afficher les ID de toutes les transactions de la session de débogage actuelle à l'aide de l'API Apigee, saisissez la commande suivante :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data

SESSION_ID correspond à l'ID de la session de débogage que vous souhaitez télécharger.

Consultez la section Répertorier les ID de transaction d'une session de débogage.

Pour obtenir les données de débogage d'une transaction à l'aide de l'API Apigee, entrez la commande suivante :

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data/TRANSACTION_ID

Structure des données téléchargées

La structure de téléchargement des données de session de débogage est différente pour l'UI Apigee et l'API Apigee.

UI Apigee

Lorsque vous téléchargez des données à l'aide de l'UI Apigee, la structure des données :

inclut toutes les transactions de l'ensemble de la session ;
stocke les transactions dans un tableau Messages ;
inclut des métadonnées sur la session (en tant qu'objet DebugSession).

API Apigee

Vous ne pouvez pas utiliser l'API Apigee pour afficher les données d'une session entière en même temps. Vous ne pouvez l'utiliser que pour afficher des données de transaction individuelles, comme décrit dans la section Afficher les sessions de débogage.

Exemple :

{
  "completed": true,
  "point": [
    ...
  ...
}

Exemples de données téléchargées

L'exemple suivant met en évidence un objet de métadonnées DebugSession dans les données téléchargées. Cet objet est suivi du tableau Messages qui contient les transactions de la session.

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

Si la session de débogage n'a inclus aucune requête, le tableau Message est vide, comme le montre l'exemple suivant :

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": []
}

Supprimer les données d'une session de débogage

Supprimez les données d'une session de débogage à l'aide de l'UI ou de l'API Apigee, comme décrit dans les sections suivantes.

Nouvel éditeur de proxys

Pour supprimer une session de débogage dans le nouvel éditeur de proxys, procédez comme suit :

Sélectionnez la ligne correspondant à la session que vous souhaitez supprimer.
Cliquez sur le menu à trois points à la fin de la ligne, puis sélectionnez Supprimer.

Éditeur de proxy classique

Cliquez sur dans le panneau Informations sur Debug de la session de débogage.

API Apigee

Pour supprimer toutes les données de session de débogage à l'aide de l'API, envoyez une requête DELETE à la ressource suivante :

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Où debugsession est l'ID d'une session de débogage renvoyée lorsque vous affichez les sessions de débogage.

L'exemple suivant montre comment supprimer des données de session de débogage pour la révision 1 de l'API helloworld dans l'environnement test.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

Si la requête aboutit, le corps de la réponse sera vide.

Les données de session de débogage ne sont conservées que pendant 24 heures. Si vous ne les supprimez pas explicitement avant la fin de ce délai, Apigee le fait pour vous.

Utiliser l'outil Debug

Créer une session de débogage

Nouvel éditeur de proxys

Afficher le graphique de Gantt pour une transaction

Partager une session de débogage

Télécharger une session de débogage

Éditeur de proxy classique

Trouver l'URL du point de terminaison

Démarrer une autre session de débogage dans l'UI

Quand une session de débogage se termine-t-elle ?

Lire un débogage

Légende de la carte des transactions

Comprendre les détails de la phase

API Apigee

Définir la durée d'une session de débogage à l'aide de l'API

Déboguer avec l'outil Debug

Filtrer les données dans une session de débogage

Utiliser des filtres

Interface utilisateur d'Apigee

API Apigee

Syntaxe des filtres

Filtres prédéfinis de l'UI

Afficher les sessions de débogage

Nouvel éditeur de proxys

Éditeur de proxy classique

Sélectionner les options d'affichage dans l'UI

API Apigee

Afficher toutes les sessions de débogage à l'aide de l'API

Afficher toutes les transactions d'une session de débogage à l'aide de l'API

Afficher les données de transaction d'une session de débogage à l'aide de l'API

Télécharger les données de session de débogage

Nouvel éditeur de proxys

Éditeur de proxy classique

API Apigee

Structure des données téléchargées

UI Apigee

API Apigee

Exemples de données téléchargées

Supprimer les données d'une session de débogage

Nouvel éditeur de proxys

Éditeur de proxy classique

API Apigee