Filtres Cloud Trace

Les filtres Cloud Trace vous permettent d'interroger la méthode list de l'API Trace pour récupérer uniquement les traces qui correspondent à des critères spécifiques, tels que les noms de spans, la latence minimale, les attributs HTTP ou les libellés.

Ces expressions de filtre ne s'appliquent pas à la page Explorateur Trace de la console Google Cloud . Dans l'explorateur de traces, vous pouvez filtrer les traces à l'aide des filtres prédéfinis du volet Filtres d'étendue ou de la barre Filtrer. Pour en savoir plus, consultez Rechercher et explorer des traces.

Présentation du filtre

Les filtres de traces consistent en une série de comparaisons appelées termes. Les traces doivent correspondre à tous les termes du filtre pour être sélectionnées. Par exemple, le filtre suivant correspond aux traces dont la latence est d'une seconde ou plus et qui contiennent une portée nommée /modules.GetNumInstances :

+span:/modules.GetNumInstances latency:1s

Toutes les comparaisons de chaînes sont sensibles à la casse.

Attributs booléens

Pour spécifier des valeurs pour les attributs booléens, utilisez false pour "false" et true pour "true" :

Client:true

Caractères spéciaux

Les valeurs simples, c'est-à-dire celles qui correspondent à l'expression régulière [a-zA-Z0-9./_][a-zA-Z0-9./_-]*, peuvent être fournies sans guillemets :

environment:production
path:/index.html
error_code:200

Les valeurs qui incluent d'autres caractères, y compris des espaces, doivent être entourées de guillemets doubles (") :

my-label:"Notice: This value contains spaces and a colon"

Pour rechercher le caractère guillemet double ou barre oblique inverse (\) dans une chaîne entre guillemets, échappez le caractère avec une barre oblique inverse :

my-label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"

Syntaxe de filtre

Sur cette page, NAME fait référence au nom d'un champ et VALUE à la valeur d'une paire clé-valeur. Les chaînes _PREFIX et _EXACT indiquent visuellement si un test est un test de préfixe ou une correspondance exacte. Par exemple, root:[NAME_PREFIX] signifie que le nom du délai racine doit commencer par [NAME_PREFIX].

Le reste de cette page décrit la syntaxe des filtres pour l'API Trace.

Exemples de filtres de requêtes

La liste suivante décrit les termes de filtrage :

root:[NAME_PREFIX]

Le nom du délai racine de la trace doit commencer par [NAME_PREFIX]. Par exemple, le filtre suivant correspond à une trace nommée "/_ah/background", mais pas à une trace nommée "/_ahx/background" :

root:/_ah/
+root:[NAME]

Le nom du délai racine de la trace doit être exactement [NAME]. Exemple :

+root:/_ah/background
[NAME_PREFIX]

Cette syntaxe est un raccourci pour root:[NAME_PREFIX].

+[NAME]

Cette syntaxe est un raccourci pour +root:[NAME].

span:[NAME_PREFIX]

La trace doit avoir au moins un délai dont le nom commence par [NAME_PREFIX]. Exemple :

span:/modules.
+span:[NAME]

La trace doit avoir au moins un délai dont le nom est exactement [NAME]. Exemple :

+span:/modules.GetNumInstances
latency:[DURATION]

La trace doit avoir une latence globale supérieure ou égale à [DURATION]. La durée est exprimée sous la forme d'un nombre entier suivi d'un spécificateur d'unité : s pour les secondes, ms pour les millisecondes ou ns pour les nanosecondes. Si aucun spécificateur d'unité n'est défini, les unités sont exprimées en millisecondes. Par exemple, les quatre durées suivantes sont identiques :

12s 12000ms 12000000ns 12000
label:[LABEL_KEY]

La trace doit contenir exactement la clé d'étiquette spécifiée. La valeur du libellé (le cas échéant) n'a pas d'importance. Exemple :

label:/http/url
[LABEL_KEY]:[VALUE_PREFIX]

La trace doit contenir exactement la clé d'étiquette spécifiée, et la valeur de l'étiquette doit commencer par [VALUE_PREFIX]. Par exemple, le terme suivant correspond aux traces dont la version App Engine commence par "2017" :

g.co/gae/app/module_version:2017
+[LABEL_KEY]:[VALUE_EXACT]

La trace doit contenir exactement la clé d'étiquette et la valeur spécifiées. Exemple :

+g.co/gae/app/module_version:201750925t173233.387410594824284458
method:[VALUE_PREFIX]

Cette syntaxe est un raccourci pour le test de libellé /http/method:[VALUE_PREFIX].

+method:[VALUE_EXACT]

Cette syntaxe est un raccourci pour le test de libellé +/http/method:[VALUE_EXACT].

url:[VALUE_PREFIX]

Cette syntaxe est un raccourci pour le test de libellé /http/url:[VALUE_PREFIX].

+url:[VALUE_EXACT]

Cette syntaxe est un raccourci pour le test de libellé +/http/url:[VALUE_EXACT].

Exemples de recherches sur le délai racine

Pour limiter le terme de recherche à la portée racine uniquement, ajoutez un accent circonflexe (^) avant un terme de recherche et après le signe plus facultatif (+). Dans le champ Filtre de la page Explorateur de traces, si vous ajoutez l'annotation +^, elle est convertie en ^+ lorsque vous appuyez sur Entrée.

La liste suivante présente quelques termes de recherche avec portée racine uniquement et leurs équivalences :

^label:[LABEL_KEY]
Il s'agit d'une recherche portant sur la racine label:[LABEL_KEY].
^[LABEL_KEY]:[VALUE_PREFIX]
Il s'agit d'une recherche portant sur la racine [LABEL_KEY]:[VALUE_PREFIX].
+^[LABEL_KEY]:[VALUE]
Il s'agit d'une recherche portant sur la racine +[LABEL_KEY]:[VALUE].
^method:[VALUE_PREFIX]
Il s'agit d'une recherche portant sur la racine method:[VALUE_PREFIX].
+^method:[VALUE]
Il s'agit d'une recherche portant sur la racine +method:[VALUE].
^url:[VALUE_PREFIX]
Il s'agit d'une recherche portant sur la racine url:[VALUE_PREFIX].
+^url:[VALUE]
Il s'agit d'une recherche portant sur la racine +url:[VALUE].
^span:[NAME_PREFIX]
Cela équivaut à root:[NAME_PREFIX].
+^span:[NAME]
Cela équivaut à +root:[NAME].

Vous pouvez personnaliser davantage votre recherche en créant une requête avec des termes mixtes. Par exemple,

+^url:/main /images method:200

correspond aux traces lorsque le libellé de la portée racine /http/url est exactement "/main", que le nom de la portée racine est précédé de /images et que n'importe quelle portée comporte le libellé /http/method avec une valeur de 200.

Dépannage

Les sections suivantes décrivent comment résoudre les problèmes courants liés aux filtres de trace.

Performances ralenties

Si votre filtre de trace est compliqué, son exécution prendra plus de temps et il pourra expirer. Pour améliorer les performances, simplifiez le filtre.

Aucun résultat

Si votre filtre ne renvoie aucune trace, vérifiez les points suivants :

  • Assurez-vous qu'il n'y a pas d'espaces dans le filtre, sauf ceux qui séparent les comparaisons.

  • Assurez-vous que la casse et l'orthographe de tous les mots du filtre sont correctes. Par exemple, si vous faites une faute d'orthographe dans un mot clé tel que method:GET, le filtre est interprété comme label:method:GET, ce qui ne correspond à aucune trace.

  • Pour tester les termes de filtrage un par un, accédez à la méthode d'API list, puis utilisez l'APIs Explorer. Si l'un des termes ne renvoie aucun résultat, il peut être la raison pour laquelle aucune donnée n'est renvoyée.

    APIs Explorer est ouvert lorsque la page affiche un volet intitulé Essayer cette méthode. Si nécessaire, cliquez sur Essayer pour ouvrir l'APIs Explorer.