Utilisation d'expressions de filtre

Utilisez des expressions de filtre pour afficher une carte de trace ou les traces d'une demande, d'un service, d'une connexion entre deux services (une périphérie) ou de demandes répondant à une condition spécifique. X-Ray fournit un langage d'expression de filtre pour filtrer les demandes, les services et les limites en fonction des données contenues dans les en-têtes des demandes, de l'état des réponses et des champs indexés des segments d'origine.

Lorsque vous choisissez une période de traces à afficher dans la console X-Ray, vous pouvez obtenir plus de résultats que ce que la console peut afficher. Dans le coin supérieur droit, la console affiche le nombre de suivis qu'elle a analysés et s'il y a d'autres suivis disponibles. Vous pouvez utiliser une expression de filtre pour limiter les résultats aux traces que vous souhaitez rechercher.

Filtrer les détails de l'expression

Lorsque vous choisissez un nœud dans la carte de trace, la console crée une expression de filtre en fonction du nom de service du nœud et des types d'erreurs présents en fonction de votre sélection. Pour trouver les suivis montrant les problèmes de performances ou concernant des demandes spécifiques, vous pouvez ajuster l'expression fournie par la console ou créer vos propres expressions. Si vous ajoutez des annotations avec le X-RaySDK, vous pouvez également filtrer en fonction de la présence d'une clé d'annotation ou de la valeur d'une clé.

Note

Si vous choisissez une plage de temps relative dans la carte de trace et que vous choisissez un nœud, la console convertit la plage de temps en heure de début et de fin absolues. Pour assurer que les suivis du nœud apparaissent dans les résultats de recherche et éviter d'analyser les heures auxquelles le nœud n'était pas actif, la plage de temps inclut uniquement les heures pendant lesquelles le nœud a envoyé des suivis. Pour effectuer une recherche par rapport à l'heure actuelle, vous pouvez revenir à une plage de temps relative dans la page des suivis et relancer l'analyse.

S'il y a toujours plus de résultats disponibles que la console ne peut en afficher, la console affiche le nombre de suivis correspondants et le nombre de suivis analysés. Le pourcentage affiché est le pourcentage de la période sélectionnée qui a été analysée. Pour vous assurer d’afficher tous les suivis correspondants représentés dans les résultats, réduisez encore votre expression de filtrage ou choisissez une période plus courte.

Pour obtenir les résultats les plus récents en premier, la console démarre l'analyse à la fin de la plage de temps et fonctionne en marche arrière. S'il y a un grand nombre de suivis, mais peu de résultats, la console fractionne la plage de temps en blocs qu'elle analyse en parallèle. La barre de progression indique les parties de la plage de temps qui ont été analysées.

Utilisation d'expressions de filtrage avec les groupes

Les groupes constituent un ensemble de suivis qui sont définis par une expression de filtre. Vous pouvez utiliser des groupes pour générer des graphiques de service supplémentaires et fournir CloudWatch des statistiques Amazon.

Les groupes sont identifiés par leur nom ou par un nom de ressource Amazon (ARN) et contiennent une expression de filtre. Le service compare les suivis entrants à l'expression, et les stocke en conséquence.

Vous pouvez créer et modifier des groupes en utilisant le menu déroulant à gauche de la barre de recherche d'expression de filtre.

Note

Si le service rencontre une erreur en qualifiant un groupe, ce groupe n'est plus inclus dans le traitement des suivis entrants et une métrique d'erreur est enregistrée.

Pour plus d'informations sur les groupes, consultezConfiguration des groupes.

Syntaxe d'une expression de filtrage

Les expressions de filtrage peuvent contenir un mot-clé, un opérateur unaire ou binaire et une valeur de comparaison.

keyword operator value

Différents opérateurs sont disponibles pour les différents types de mot-clé. Par exemple, responsetime est un mot-clé valeur et peut être comparé aux opérateurs liés à des chiffres.

Exemple — demandes dont le temps de réponse était supérieur à 5 secondes

responsetime > 5

Vous pouvez combiner plusieurs expressions dans une expression composée avec les opérateurs AND ou OR.

Exemple — demandes dont la durée totale était de 5 à 8 secondes

duration >= 5 AND duration <= 8

Les mots-clés et opérateurs simples permettent uniquement de rechercher des problèmes au niveau des données de suivi. Si une erreur survient en aval, mais est gérée par votre application et n'est pas renvoyée à l'utilisateur, la recherche lancée sur error ne la trouvera pas.

Pour trouver les données de suivi concernant des problèmes en aval, vous pouvez utiliser les mots-clés complexes service() et edge(). Ces mots-clés vous permettent d'appliquer une expression de filtre à tous les nœuds en aval, à un seul nœud en aval ou à un arc entre deux nœuds. Pour encore plus de granularité, vous pouvez filtrer les services et les arcs par type avec la fonction id().

Mots-clés booléens

Les valeurs des mots-clés booléens sont true ou false. Utilisez ces mots-clés pour trouver des données de suivi ayant généré des erreurs.

Mots-clés booléens

• ok— Le code d'état de la réponse était 2XX Success.

• error— Le code d'état de la réponse était 4XX Client Error.

• throttle— Le code d'état de la réponse était 429 trop de demandes.

• fault— Le code d'état de la réponse était une erreur de serveur 5XX.

• partial— La demande contient des segments incomplets.

• inferred— La demande contient des segments déduits.

• first— L'élément est le premier d'une liste énumérée.

• last— L'élément est le dernier d'une liste énumérée.

• remote— L'entité responsable est distante.

• root— Le service est le point d'entrée ou le segment racine d'une trace.

Les opérateurs booléens trouvent les segments dans lesquels la clé spécifiée est true ou false.

Opérateurs booléens

• none — L'expression est vraie si le mot clé est vrai.

• !— L'expression est vraie si le mot clé est faux.

• =, != — Comparez la valeur du mot-clé à la chaîne true oufalse. Ces opérateurs agissent de la même manière que les autres opérateurs mais sont plus explicites.

Exemple — le statut de la réponse est 2XX OK

ok

Exemple — le statut de la réponse n'est pas 2XX OK

!ok

Exemple — le statut de la réponse n'est pas 2XX OK

ok = false

Exemple — la dernière trace de panne énumérée porte le nom d'erreur « désérialiser »

rootcause.fault.entity { last and name = "deserialize" }

Exemple — demandes avec des segments distants dont la couverture est supérieure à 0,7 et dont le nom du service est « traces »

rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }

Exemple — requêtes avec des segments déduits dont le type de service est « :DynamoDB » AWS

rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }

Exemple — requêtes dont un segment porte le nom « plan de données » comme racine

service("data-plane") {root = true and fault = true}

Mots-clés valeur

Utilisez les mots-clés valeur pour rechercher des demandes avec un temps de réponse, une durée ou un statut de réponse spécifique.

Mots-clés valeur

• responsetime— Temps nécessaire au serveur pour envoyer une réponse.

• duration— Durée totale de la demande, y compris tous les appels en aval.

• http.status— Code d'état de la réponse

• index— Position d'un élément dans une liste énumérée.

• coverage— Pourcentage décimal du temps de réponse de l'entité par rapport au temps de réponse du segment racine. Applicable uniquement aux entités de cause racine des temps de réponse.

Opérateurs numériques

Les mots-clés valeur utilisent l'égalité standard et les opérateurs de comparaison.

• =, != — Le mot clé est égal ou non à une valeur numérique.

• <,<=,>, >= — Le mot clé est inférieur ou supérieur à une valeur numérique.

Exemple — le statut de la réponse n'est pas 200 OK

http.status != 200

Exemple — demande dont la durée totale était de 5 à 8 secondes

duration >= 5 AND duration <= 8

Exemple — demandes traitées avec succès en moins de 3 secondes, y compris tous les appels en aval

ok !partial duration <3

Exemple — entité de liste énumérée dont l'indice est supérieur à 5

rootcause.fault.service { index > 5 }

Exemple — demandes pour lesquelles la dernière entité dont la couverture est supérieure à 0,8

rootcause.responsetime.entity { last and coverage > 0.8 }

Mots-clés chaîne

Utilisez des mots-clés de chaîne pour rechercher des traces contenant du texte spécifique dans les en-têtes de demande ou un utilisateur IDs spécifique.

Mots-clés chaîne

• http.url— DemandeURL.

• http.method— Méthode de demande.

• http.useragent— Demande une chaîne d'agent utilisateur.

• http.clientip— Adresse IP du demandeur.

• user— Valeur du champ utilisateur sur n'importe quel segment de la trace.

• name— Le nom d'un service ou d'une exception.

• type— Type de service

• message— Message d'exception.

• availabilityzone— Valeur du champ de zone de disponibilité sur n'importe quel segment de la trace.

• instance.id— Valeur du champ ID d'instance sur n'importe quel segment de la trace.

• resource.arn— Valeur du ARN champ de ressource sur n'importe quel segment de la trace.

Les opérateurs chaîne trouvent des valeurs qui sont égales à un texte spécifique ou contiennent un texte spécifique. Ces valeurs doivent toujours être spécifiées entre guillemets.

Opérateurs de chaîne

• =, != — Le mot clé est égal ou non à une valeur numérique.

• CONTAINS— Le mot clé contient une chaîne spécifique.

• BEGINSWITH, ENDSWITH — Le mot clé commence ou se termine par une chaîne spécifique.

Exemple — filtre http.url

http.url CONTAINS "/api/game/"

Pour vérifier si un champ existe sur une donnée de suivi, quelle que soit sa valeur, vérifiez si elle contient la chaîne vide.

Exemple — filtre utilisateur

Trouvez toutes les traces avec l'utilisateurIDs.

user CONTAINS ""

Exemple — sélectionnez les traces dont la cause première est une erreur et qui incluent un service appelé « Auth »

rootcause.fault.service { name = "Auth" }

Exemple — sélectionne les traces dont la cause première est le temps de réponse et dont le dernier service est de type DynamoDB

rootcause.responsetime.service { last and type = "AWS::DynamoDB" }

Exemple — sélectionne les traces dont la cause première est une erreur dont la dernière exception contient le message « accès refusé pour account_id : 1234567890 »

rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890" 

Mots-clés complexes

Utilisez les mots-clés complexes pour trouver des demandes en fonction du nom du service, du nom de l'arc ou d'une valeur d'annotation. Pour les services et les arcs, vous pouvez spécifier une expression de filtrage supplémentaire qui s'applique au service ou à l'arc. Pour les annotations, vous pouvez appliquer un filtre sur la valeur d'une annotation avec une clé spécifique en utilisant des opérateurs booléens, numériques ou de chaîne.

Mots-clés complexes

• annotation[key]— Valeur d'une annotation avec champ key. La valeur d'une annotation peut être un booléen, un nombre ou une chaîne. Vous pouvez donc utiliser n'importe quel opérateur de comparaison de ce type. Vous pouvez utiliser ce mot clé en combinaison avec le edge mot clé service or. Une clé d'annotation contenant des points (points) doit être placée entre crochets ([]).

• edge(source, destination) {filter}— Connexion entre les services source and destination. Les accolades facultatives peuvent contenir une expression de filtre qui s'applique aux segments de cette connexion.

• group.name / group.arn— La valeur de l'expression de filtre d'un groupe, référencée par le nom ou le groupe du groupeARN.

• json— objet de la JSON cause première. Voir Obtenir des données de AWS X-Ray pour connaître les étapes de création d'JSONentités par programmation.

• service(name) {filter}— Service avec nom name. Les accolades facultatives peuvent contenir une expression de filtre qui s'applique aux segments créés par le service.

Utilisez le mot clé service pour trouver des traces pour les requêtes qui atteignent un certain nœud de votre carte de suivi.

Les opérateurs de mots clés complexes trouvent les segments dans lesquels la clé spécifiée a été définie ou non définie.

Opérateurs de mots clés complexes

• none — L'expression est vraie si le mot clé est défini. Si le mot clé est de type booléen, il sera évalué à la valeur booléenne.

• !— L'expression est vraie si le mot clé n'est pas défini. Si le mot clé est de type booléen, il sera évalué à la valeur booléenne.

• =, != — Comparez la valeur du mot-clé.

• edge(source, destination) {filter}— Connexion entre les services source and destination. Les accolades facultatives peuvent contenir une expression de filtre qui s'applique aux segments de cette connexion.

• annotation[key]— Valeur d'une annotation avec champ key. La valeur d'une annotation peut être un booléen, un nombre ou une chaîne. Vous pouvez donc utiliser n'importe quel opérateur de comparaison de ce type. Vous pouvez utiliser ce mot clé en combinaison avec le edge mot clé service or.

• json— objet de la JSON cause première. Voir Obtenir des données de AWS X-Ray pour connaître les étapes de création d'JSONentités par programmation.

Utilisez le mot clé service pour trouver des traces pour les requêtes qui atteignent un certain nœud de votre carte de suivi.

Exemple — Filtre de service

Demandes comprenant un appel vers api.example.com avec une anomalie (erreur de la série 500).

service("api.example.com") { fault }

Vous pouvez exclure le nom du service pour appliquer une expression de filtre à tous les nœuds sur votre cartographie des services.

Exemple — filtre de service

Demandes à l'origine d'une erreur n'importe où sur votre carte de trace.

service() { fault }

Le mot-clé arc applique une expression de filtre à une connexion entre deux nœuds.

Exemple — filtre de bord

Demande pour laquelle l'appel du service api.example.com à backend.example.com a échoué suite à une erreur.

edge("api.example.com", "backend.example.com") { error }

Vous pouvez également utiliser l'opérateur ! avec les mots-clés service et arc pour exclure un service ou un arc des résultats d'une autre expression de filtre.

Exemple — filtre de service et de demande

Demande dont le nom URL commence par http://api.example.com/ et contient /v2/ mais n'atteint pas un service nomméapi.example.com.

http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")

Exemple — filtre de service et de temps de réponse

Trouvez des traces là où http url est défini et où le temps de réponse est supérieur à 2 secondes.

http.url AND responseTime > 2

Pour les annotations, vous pouvez appeler toutes les traces où annotation[key] est défini ou utiliser les opérateurs de comparaison correspondant au type de valeur.

Exemple — annotation avec valeur de chaîne

Demandes avec une annotation nommée gameid avec une valeur de chaîne "817DL6VO".

annotation[gameid] = "817DL6VO"

Exemple — l'annotation est définie

Demandes avec une annotation nommée age set.

annotation[age]

Exemple — l'annotation n'est pas définie

Demandes sans annotation nommées age set.

!annotation[age]

Exemple — annotation avec valeur numérique

Demandes avec un âge d'annotation avec une valeur numérique supérieure à 29.

annotation[age] > 29

Exemple — annotation en combinaison avec le service ou l'arête

service { annotation[request.id] = "917DL6VO" }

edge { source.annotation[request.id] = "916DL6VO" }

edge { destination.annotation[request.id] = "918DL6VO" }

Exemple — groupe avec utilisateur

Demandes où les traces rencontrent le filtre de high_response_time groupe (par exempleresponseTime > 3) et où l'utilisateur s'appelle Alice.

group.name = "high_response_time" AND user = "alice"

Exemple — JSON avec une entité de cause première

Requêtes avec entités de cause racine correspondantes.

rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

fonction id

Lorsque vous fournissez un nom de service pour les mots-clés service ou edge, vous obtenez des résultats pour tous les nœuds correspondant à ce nom. Pour un filtrage plus précis, vous pouvez utiliser la fonction id pour spécifier un type de service en plus d'un nom et faire la distinction entre les nœuds portant le même nom.

Utilisez cette account.id fonction pour spécifier un compte particulier pour le service, lorsque vous consultez les traces de plusieurs comptes dans un compte de surveillance.

id(name: "service-name", type:"service::type", account.id:"account-ID")

Vous pouvez utiliser la fonction id à la place d'un nom de service dans les filtres de service et d'arc.

service(id(name: "service-name", type:"service::type")) { filter }

edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }

Par exemple, AWS Lambda les fonctions génèrent deux nœuds dans la carte de trace : un pour l'invocation de la fonction et un pour le service Lambda. Les deux nœuds ont le même nom, mais des types différents. Un filtre de service standard trouvera des données de suivi pour les deux.

Exemple — filtre de service

Demandes qui incluent une erreur sur n'importe quel service nommé random-name.

service("function-name") { error }

Utilisez la fonction id pour limiter la recherche aux erreurs portant sur la fonction elle-même et exclure les erreurs du service.

Exemple — filtre de service avec fonction id

Demandes qui incluent une erreur sur un service nommé random-name de type AWS::Lambda::Function.

service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }

Pour rechercher des nœuds par type, vous pouvez également exclure complètement le nom.

Exemple — filtre de service avec fonction d'identification et type de service

Demandes qui incluent une erreur sur un service de type AWS::Lambda::Function.

service(id(type: "AWS::Lambda::Function")) { error }

Pour rechercher des nœuds pour un utilisateur en particulier Compte AWS, spécifiez un ID de compte.

Exemple — filtre de service avec fonction d'identification et identifiant de compte

Demandes qui incluent un service associé à un identifiant de compte spécifiqueAWS::Lambda::Function.

service(id(account.id: "account-id"))