Filtres Cloud Trace

Vous utilisez des filtres de traces pour sélectionner un ensemble de traces provenant de Cloud Trace. Utilisez un filtre de trace de l'une des manières suivantes :

En tant que paramètre de filtre dans une requête à l'aide de la méthode API list.
En tant que paramètre Filtre de requêtes lorsque vous créez un rapport d'analyse.
En tant que champ Filtrer sur la page Explorateur de traces. Pour en savoir plus sur la création et la modification de ces filtres, consultez Afficher les traces récentes.

Remarque :La barre de filtre de la page Explorateur de traces est accessible via un menu, et les options dépendent de votre configuration. Les options pilotées par menu incluent généralement le filtrage par état HTTP et par méthode HTTP. Lorsque vous utilisez App Engine, des options de service et de version sont également disponibles. Ces options ne sont pas disponibles lorsque vous utilisez les filtres Cloud Trace.

Les filtres vous permettent de spécifier une ou plusieurs conditions à remplir pour qu'une trace s'affiche. La syntaxe de filtrage vous permet de définir les correspondances exactes ou les tests de préfixe. Toutes les correspondances sont sensibles à la casse.

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 qui ont une latence d'une seconde ou plus et qui contiennent un délai nommé /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 0 pour "false" et 1 pour "true". Exemple :

Client:0

Caractères spéciaux

Pour rechercher une valeur contenant un espace ou le caractère deux-points (:), placez la valeur entre guillemets ("). Par exemple :

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

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

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

Syntaxe des filtres

Dans le tableau suivant et ailleurs sur cette page, NAME fait référence au nom d'un champ, tandis que VALUE fait référence à la valeur d'une paire clé/valeur. Les chaînes _PREFIX et _EXACT indiquent de manière visuelle 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 tableau suivant répertorie la syntaxe des filtres utilisés dans Cloud Trace :

API Trace Filtre de requêtes sur la page Rapports d'analyse	Filtrer sur la page Explorateur de traces
`root:[NAME_PREFIX]`	`RootSpan:[NAME_PREFIX]`
`+root:[NAME_EXACT]`	`RootSpan:+[NAME_EXACT]`
`span:[NAME_PREFIX]`	`SpanName:[NAME_PREFIX]`
`+span:[NAME_EXACT]`	`SpanName:+[NAME_EXACT]`
`[NAME_PREFIX]`	`RootSpan:[NAME_PREFIX]`
`label:[LABEL_KEY]`	`HasLabel:[LABEL_KEY]`
`[LABEL_KEY]: [VALUE_PREFIX]`	`[LABEL_KEY]:[VALUE_PREFIX]`^*
`+[LABEL_KEY]: [VALUE_EXACT]`	`[LABEL_KEY]:+[VALUE]`^*
`^[LABEL_KEY]: [VALUE_PREFIX]`	`[LABEL_KEY]:^[VALUE_PREFIX]`^*
`+^[LABEL_KEY]: [VALUE_EXACT]`	`[LABEL_KEY]:^+[VALUE_EXACT]`^{*, †}
`method:[VALUE_PREFIX]`	`Method:[VALUE_PREFIX]`
`latency:10ms`	`MinLatency:10ms`
`url:[VALUE_PREFIX]`	`URL:[VALUE_PREFIX]`

^* N'utilisez pas les mots clés Trace suivants comme clés de libellé : root, span, label, method, latency et url. Les traces associées à ces clés de libellé ne peuvent pas être interrogées.
^† Sur la page de l'explorateur de traces, l'annotation +^ est convertie en ^+ lorsque vous appuyez sur Entrée.

Le reste de cette page contient une description des filtres en cas d'utilisation de l'API Trace et du filtre de requêtes sur la page Rapports d'analyse. Si vous utilisez le champ Filtrer de la page Explorateur de traces, vous pouvez utiliser le mappage du tableau précédent pour créer une expression équivalente.

Exemples de filtres de requêtes

Voici la description des termes du filtre:

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 entier suivi d'un spécificateur d'unités : 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é de libellé 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é de libellé spécifiée, et la valeur du libellé doit commencer par [VALUE_PREFIX]. Par exemple, le terme suivant correspond aux traces dont la version d'App Engine commence par "2017".

g.co/gae/app/module_version:2017

+[LABEL_KEY]:[VALUE_EXACT]

La trace doit contenir exactement la clé de libellé 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 au délai racine uniquement, ajoutez (^) avant un terme de recherche et après l'élément facultatif (+). Pour le champ Filtrer de la page Explorateur de traces, si vous ajoutez l'annotation +^, elle est convertie en ^+ lorsque vous appuyez sur Entrée.

Voici quelques termes de recherche qui ne concernent que le délai racine et leurs équivalences:

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

En créant une requête avec des termes mixtes, la recherche peut être personnalisée davantage. Par exemple :

    +^url:/main /images method:200

correspond aux traces lorsque le libellé du délai racine /http/url est exactement "/main", que le nom du délai racine est précédé de /images et que tout délai porte le libellé /http/method avec la valeur 200.

Dépannage

Cette section contient des informations sur la résolution de problèmes.

Performances ralenties

Si votre filtre de trace est complexe, son exécution est plus longue et peut expirer. Pour améliorer les performances, simplifiez le filtre.

Aucun résultat

Si le 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 tous les mots du filtre sont dans la bonne casse et qu'ils sont bien orthographiés. Par exemple, si vous orthographiez mal 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 filtre un par un, utilisez le filtre Liste de traces ou l'API Explorer. Si l'un des termes ne renvoie aucun résultat, il pourrait être en cause.