Filtres de surveillance

Ce guide décrit l'utilisation de filtres de surveillance pour spécifier des ressources surveillées, des types de métriques, des définitions de groupes et des séries temporelles.

Pour obtenir une présentation des métriques, des séries temporelles et des ressources surveillées, consultez la page Métriques, séries temporelles et ressources.

Les filtres utilisent largement les libellés. Pour en savoir plus, consultez la section Libellés.

Utiliser des filtres

Vous pouvez utiliser des filtres dans l'API Monitoring v3 pour effectuer les opérations suivantes :

  • Récupérer les séries temporelles. Utilisez un filtre pour sélectionner les données de séries temporelles en fonction du projet, du groupe, des propriétés des ressources surveillées et des propriétés des métriques. Pour en savoir plus et obtenir des exemples, consultez la section Récupérer des données de séries temporelles.

  • Définir les ressources d'un groupe. Utilisez un filtre pour attribuer des ressources à une ressource Group en fonction des propriétés des ressources et du projet auquel elles appartiennent. Pour obtenir plus d'informations et d'exemples, consultez la section Définir l'appartenance à un groupe.

  • Répertorier les membres d'un groupe. Utilisez un filtre pour sélectionner des ressources dans un groupe en fonction de leurs propriétés et du projet auquel elles appartiennent. Pour obtenir plus d'informations et d'exemples, consultez la section Répertorier les membres d'un groupe.

  • Répertorier les descripteurs de métriques. Utilisez un filtre pour inspecter des types de métriques spécifiques parmi les centaines de types définis dans Monitoring. Pour obtenir plus d'informations et d'exemples, consultez la section Répertorier les descripteurs de métriques.

  • Répertorier les descripteurs de ressources surveillées. Utilisez un filtre pour inspecter des types de ressources surveillées à partir de plusieurs dizaines de types de ressources définis dans Monitoring. Pour obtenir plus d'informations et d'exemples, consultez la section Répertorier les descripteurs de ressources surveillées.

En fonction des opérations que vous limitez parmi celles mentionnées ci-dessus, votre filtre peut être constitué de l'opérateur logique AND et de sélecteurs de la liste suivante. Ce sont de simples exemples : il existe plusieurs types d'opérateurs de comparaison, par exemple.

  • Sélecteur de projet : limite la correspondance de filtre aux objets appartenant à un ou plusieurs projets dans l'espace de travail mentionné dans le paramètre name de la méthode.

    project = "project-id-or-number" OR project = "another-id-or-number"
    
  • Sélecteur de groupe : met en correspondance les ressources appartenant à un objet Group (unique). Exemple :

    group.id = "group-id"
    
  • Sélecteur de ressource : met en correspondance les ressources surveillées d'un type particulier ou ayant des valeurs de libellé particulières. Par exemple, voici différentes manières de spécifier des informations sur les ressources :

    resource.type = "the_resource_type"
    resource.labels.a_label_for_the_resource_type = "label_value"
    
  • Sélecteur de métrique : limite le filtre aux métriques ou aux séries temporelles d'un type de métrique particulier ou ayant des valeurs de libellé particulières. Par exemple, voici différentes manières de spécifier des types de métriques :

    metric.type = "the_metric_type"
    metric.labels.a_label_for_the_metric_type = "label_value"
    

Le tableau suivant indique les sélecteurs autorisés dans les filtres en fonction de leur utilisation :

Objectif du filtre Sélecteur de projet Sélecteur de groupe Sélecteur de ressource Sélecteur de métrique
Définir des groupes Oui Oui1
Répertorier les membres d'un groupe Oui Oui
Répertorier les séries temporelles Oui Oui Oui Oui2
Répertorier les descripteurs de métriques Oui Oui
Répertorier les descripteurs de ressources surveillées Oui
1 Le sélecteur de ressource comporte des options supplémentaires lorsqu'il est utilisé pour définir l'appartenance à un groupe.
2 Lorsque vous répertoriez des séries temporelles, vous devez spécifier exactement un type de métrique.

Les sections suivantes présentent des exemples d'utilisations courantes de filtres de surveillance. Pour en savoir plus sur les opérateurs et les objets de filtrage disponibles, consultez la section Syntaxe des filtres.

Récupérer des données de séries temporelles

Méthode : projects.timeSeries.list
Objets de filtrage : project, group.id, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

Une série temporelle est une liste de points de données horodatés d'un type de métrique issus d'une ressource surveillée spécifique. Pour en savoir plus, consultez la section Modèle de métrique. Le type de métrique est spécifié par un descripteur de métrique, et la ressource surveillée est spécifiée par un descripteur de ressource surveillée. Les filtres doivent inclure un sélecteur de métrique, lequel doit spécifier exactement un type de métrique.

  • Toutes les séries temporelles pour un type de métrique particulier :

    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Séries temporelles liées aux ressources d'un groupe spécifique. Le sélecteur group ne fonctionne qu'avec les données de séries temporelles alignées. Pour en savoir plus, consultez la section Sélecteur de groupe :

    group.id = "2468013579" AND
        metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • Séries temporelles d'une instance Compute Engine spécifique :

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = "my-instance-name"
    
  • Séries temporelles d'instances Compute Engine portant des noms similaires :

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = starts_with("frontend-")
    
  • Séries temporelles d'instances Compute Engine commençant par gke-hipster ou gke-nginx :

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
    

Définir l'appartenance à un groupe

Méthode : projects.groups
Objets de filtrage : project, resource.type, resource.labels.key, metadata.system_labels.[KEY], metadata.user_labels.[KEY]

Un groupe peut contenir un nombre illimité de ressources, tel que spécifié par un filtre. L'appartenance à un groupe est dynamique. Une ou plusieurs ressources peuvent correspondre au filtre chaque fois qu'il est appliqué. Le paramètre name de l'objet Group spécifie le groupe et l'espace de travail propriétaire. Si l'objet project est utilisé dans le filtre, il doit spécifier un projet membre de l'espace de travail.

  • Toutes les instances de VM Compute Engine en Europe :

    resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
    

Répertorier les membres d'un groupe

Méthode : projects.groups.members.list
Objets de filtrage : project, resource.type, resource.labels.[KEY]

Utilisez un filtre pour limiter les membres du groupe que vous récupérez. Le paramètre name de la méthode spécifie un espace de travail et un groupe défini dans celui-ci. Si l'objet project est utilisé dans le filtre, il doit spécifier un projet membre de l'espace de travail.

  • Toutes les ressources de sujet Cloud Pub/Sub appartenant au projet my-project :

    project = "{my-project}" AND resource.type = "pubsub_topic"
    

Répertorier les descripteurs de métriques

Méthode : projects.metricDescriptors.list
Objets de filtrage : project, metric.type

Utilisez un filtre pour limiter les descripteurs de métriques que vous récupérez :

  • Toutes les métriques Compute Engine :

    metric.type = starts_with("compute.googleapis.com")
    

Consultez la page Liste des métriques pour obtenir la liste complète des types de métriques définis par Monitoring. Pour en savoir plus sur le nommage des métriques, consultez la page conventions de nommage et exigences.

Répertorier les descripteurs de ressources surveillées

Méthode : projects.monitoredResourceDescriptors.list
Objets de filtrage : resource.type

Utilisez un filtre pour limiter les descripteurs de ressources surveillées que vous récupérez :

  • Tous les descripteurs de ressources surveillées par Cloud Pub/Sub :

    resource.type = starts_with("pubsub")
    

Consultez la page Liste des ressources surveillées pour obtenir la liste complète des types de ressources surveillées définis par Monitoring.

Référence : syntaxe des filtres

Pour obtenir une présentation des filtres et des exemples, consultez la section Utiliser des filtres.

Un filtre de surveillance est une chaîne composée de quatre types de sélecteurs au maximum :

<monitoring_filter> ::=  <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>

Le filtre correspond à un élément si tous les sélecteurs inclus correspondent à cet élément. Comme décrit dans les sections suivantes, certains sélecteurs peuvent comporter plusieurs comparaisons jointes par AND ou OR.

Selon l'objectif du filtre, certains sélecteurs peuvent être obligatoires, facultatifs ou interdits. Par exemple, le filtre qui définit les ressources d'un groupe ne peut pas contenir de sélecteur de métrique, car les groupes ne contiennent pas de type de métrique ni de série temporelle. En revanche, le filtre utilisé pour répertorier les séries temporelles doit contenir un sélecteur de métrique. L'ordre des sélecteurs dans le filtre n'a pas d'importance, mais les comparaisons des différents sélecteurs ne doivent pas être mélangées.

Comparaisons

Les filtres et leurs sélecteurs sont basés sur des comparaisons. Chaque comparaison se présente sous la forme suivante :

[OBJECT] [OPERATOR] [VALUE]

Ces éléments sont décrits ci-dessous :

  • [OBJECT] : sélectionne une valeur à tester, parmi les suivantes :

    project
    group.id
    metric.type
    metric.labels.[KEY]
    resource.type
    resource.labels.[KEY]
    metadata.system_labels.[KEY]
    metadata.user_labels.[KEYSTRING]
    

    [KEY] est un nom, tel que zone ou instance_id. [KEYSTRING] peut être un nom, mais s'il contient des caractères spéciaux, il doit être placé entre guillemets (").

  • [OPERATOR] : un opérateur de comparaison, parmi les suivants :

    =            # equality (case-sensitive)
    > < >= <=    # numeric ordering
    !=           # not equal
    :            # "has" substring match and test for key (case-sensitive)
    
  • [VALUE] : une valeur littérale ou un appel de fonction intégré, parmi les suivants :

    <string>     # "a Unicode string". Don't use apostrophes (`'`) to quote strings.
    <bool>       # true or false
    <number>     # 0, -2, 123456, 3.14156
    <function>   # operators on the right side of '=' or '!=':
                 #   starts_with(<string>)
                 #   ends_with(<string>)
                 #   has_substring(<string> [, ignore_case=false])
                 #   one_of(<string>,...,<string>) for up to 100 strings
                 #   monitoring.regex.full_match(<RE2-string>)
    

    Sauf dans le cas de timeSeries.list, le filtre has_substring utilise un deuxième argument facultatif, qui spécifie si la correspondance ignore ou non la casse. La valeur par défaut est false. La correspondance par défaut est donc sensible à la casse :

    • Sensible à la casse : display_name=has_substring("Demo")
    • Sensible à la casse : display_name=has_substring("Demo", false)
    • Non sensible à la casse : display_name=has_substring("Demo", true)

    Seul le format has_substring(<string>) est compatible avec timeSeries.list.

    Le filtre monitoring.regex.full_match utilise une chaîne d'expression régulière dans la syntaxe RE2.

Vous pouvez utiliser les opérateurs suivants pour regrouper ou modifier des comparaisons. OR a une priorité plus élevée que AND. Les opérateurs doivent être écrits en majuscules :

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

L'opérateur AND peut être omis entre les opérateurs, mais il est plus clair de l'inclure et cela réduit les erreurs.

La comparaison x = one_of("a", "b", "c") équivaut à :

(x = "a" OR x = "b" OR x = "c")

Dans les définitions de groupes uniquement, vous pouvez utiliser l'opérateur de négation unaire avant une comparaison, mais pas avant une expression entre parenthèses :

NOT          # negates the following comparison

Sélecteurs de filtres

Les sélecteurs vous permettent de limiter les sélections de filtres à certains éléments. Dans les sections suivantes, les accolades sont utilisées pour afficher la répétition. Par exemple, la notation <x> {OR <y>} signifie que vous pouvez écrire l'un des éléments suivants :

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

Sélecteur de projet

Un sélecteur de projet limite la sélection du filtre aux éléments appartenant à un seul projet ou à n'importe quel projet d'un ensemble de projets. Chaque projet peut être spécifié par son ID ou son numéro :

<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}

Si le sélecteur de projet comporte plusieurs comparaisons, placez le sélecteur entier entre parenthèses pour une meilleure lisibilité. Exemple :

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

Sélecteur de groupe

Un sélecteur de groupe limite la sélection du filtre aux éléments appartenant à un seul groupe :

<group_selector> ::= group.id '=' <string>

Par exemple, le filtre suivant peut être utilisé pour récupérer une série temporelle de chacune des instances de VM d'un groupe :

group.id = 12345 AND
    resource.type = "gce_instance" AND
    metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Le sélecteur de groupe n'est autorisé que dans les filtres transmis à projects.timeSeries.list. De plus, la sélection de groupes nécessite des données alignées. Autrement dit, l'appel de projects.timeSeries.list doit inclure les valeurs de perSeriesAligner et de alignmentPeriod. En effet, l'appartenance à un groupe est elle-même une sorte de série temporelle qui doit être associée aux données de métrique. Si vous spécifiez des paramètres d'alignement, vous pouvez contrôler la manière dont cette agrégation se produit. Pour en savoir plus sur les paramètres d'alignement, consultez la section Agréger des données.

Sélecteur de ressource

Un sélecteur de ressources limite la sélection du filtre aux ressources (ou aux éléments associés aux ressources) qui ont un type de ressource ou des valeurs de libellé spécifiques :

<resource_selector> ::= <resource_type_expression>
                      | <resource_label_expression>
                      | <resource_type_expression> AND <resource_label_expression>

<resource_type_expression> ::= resource.type '=' <string>
                             | resource.type ':' <string>
                             | resource.type '=' starts_with '(' <string>')'
                             | resource.type '=' ends_with '(' <string> ')'

<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
                              | <r_label_comparison> {OR <r_label_comparison>}

<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
                       | resource.labels.[KEY] ':' <string>
                       | resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
                       | resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

Si vous utilisez plusieurs <r_label_comparison> dans votre sélecteur, placez-les entre parenthèses pour une meilleure lisibilité. Par exemple, le filtre suivant peut être utilisé pour définir un groupe incluant toutes les instances de VM aux États-Unis et en Europe :

resource.type = "gce_instance" AND
  (resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))

Sélecteur de ressource pour les définitions de groupes

Les sélecteurs de ressource utilisés pour définir l'appartenance à un groupe utilisent des extensions de la syntaxe <resource_selector> :

  1. Vous pouvez utiliser les noms metadata.system_labels.[KEY] et metadata.user_labels.[KEYSTRING] dans des comparaisons de la même manière que resource.labels.[KEY]. Les clés de metadata.user_labels doivent être placées entre guillemets, car elles peuvent contenir des caractères spéciaux tels que des tirets.

  2. Vous pouvez utiliser l'opérateur "différent de" (!=) pour comparer les types de ressources, les libellés de ressource et les métadonnées. L'opérateur peut être utilisé lors de la comparaison de chaînes, de nombres, de valeurs booléennes ou de fonctions de sous-chaîne. Par exemple, resource.type!=starts_with("gce") est défini sur "true" si le type de ressource ne commence pas par "gce".

  3. Vous pouvez utiliser un seul opérateur NOT avant toute comparaison de ressources. Par exemple, NOT resource.labels.zone:"europe" est défini sur "true" si la zone de la ressource n'inclut pas "europe". Vous ne pouvez pas utiliser NOT avant une expression entre parenthèses.

  4. Vous pouvez utiliser l'opérateur existant (:) pour tester l'existence de clés. Par exemple, la comparaison resource.labels.zone est défini sur "true" si la clé de libellé zone est présente dans la ressource.

Par exemple, l'une des clés de métadonnées de ressource de plate-forme pour les instances de VM est spot_instance. Le sélecteur de filtre suivant sélectionne les instances qui sont des instances spot :

    resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

Sélecteur de métrique

Un sélecteur de métrique spécifie certaines métriques ou certains descripteurs de métriques en limitant le type de métrique et les libellés de métriques. Lorsque vous répertoriez des données de séries temporelles, le sélecteur de métrique doit spécifier un seul type de métrique :

<metric_selector> ::= <metric_name_expression> [AND <metric_label_expression>]

<metric_name_expression> ::= metric.type '=' <string>
                           | metric.type ':' <string>
                           | metric.type '=' starts_with '(' <string> ')'
                           | metric.type '=' ends_with '(' <string> ')'

<metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
                            | <metric_label_comparison> {OR <metric_label_comparison>}

<metric_label_comparison> ::= metric.labels.[KEY] '=' <string> | <bool>
                            | metric.labels.[KEY] ':' <string>
                            | metric.labels.[KEY] '=' starts_with '(' <string> ')'
                            | metric.labels.[KEY] '=' ends_with '(' <string> ')'
                            | metric.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

Par exemple, le filtre suivant peut être utilisé afin de récupérer une série temporelle pour une instance de base de données spécifique :

metric.type = "cloudsql.googleapis.com/database/state" AND
  (metric.labels.resource_type = "instance" AND
   metric.labels.resource_id = "abc-123456")

Exemples

Dans les exemples de filtrage, nous utilisons le descripteur de métrique, le descripteur de ressource surveillée et l'instance de machine virtuelle suivants, qui ont été simplifiés pour l'illustration :

# Metric descriptor:
{ "name": "projects/my-project-id/metricDescriptors/compute.googleapis.com%2Finstance%2Fdisk%2Fread_bytes_count"
  "type": "compute.googleapis.com/instance/disk/read_bytes_count",
  "labels": [ { "key": "device_name",
                "description": "The name of the disk device." } ] }

# Monitored resource descriptor:
{  "name": "monitoredResourceDescriptors/gce_instance"
   "type": "gce_instance",
   "labels": [
     { "key": "instance_id",
       "description": "The instance ID provide by Google Compute Engine." },
     { "key": "zone",
       "description": "The Google Cloud Platform zone hosting the instance."
     } ] }

# Resource descriptor for a virtual machine instance.
{ "type": "gce_instance",
  "instance_id": "1472038649266883453",
  "zone": "us-east-1b",
  "disks": [ "log_partition" ],
  "machine_type": "n1-standard-2",
  "tags": { "environment": "bleeding-edge",
            "role": "frobulator" },
  "project_id": "my-project-id" }

Exemples de récupération de métriques

Pour demander l'utilisation de la bande passante en lecture de disque pour toutes les instances et tous les appareils, définissez un filtre comme indiqué ci-dessous. Cela renvoie, pour chaque instance, une série temporelle distincte indiquant la bande passante en lecture pour chaque appareil :

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Pour affiner la requête d'interrogation de la bande passante en lecture pour uniquement le disque appelé "log_partition" sur chaque instance, définissez le filtre comme indiqué ci-dessous. Ce filtre renvoie, pour chaque instance, une série temporelle au maximum, selon qu'un appareil de ce nom existe sur cette instance :

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

Pour limiter la requête à une seule instance, spécifiez cette instance :

resource.type = "gce_instance" AND
resource.labels.instance_id = "1472038649266883453" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

Filtrer avec des groupes

Les exemples suivants illustrent l'utilisation du sélecteur de groupe dans les filtres pour restreindre les ressources surveillées à celles d'un groupe spécifique. Pour plus d'informations sur les sélecteurs utilisés pour définir l'appartenance à un groupe, consultez la section Définitions de groupe.

{ "name": "projects/my-test-project/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "metadata.user_labels.role=redis" }

Dans un appel à la méthode projects.timeSeries.list, le filtre suivant demande l'utilisation de la bande passante en lecture de disque pour toutes les instances Compute Engine d'un groupe particulier. Le groupe doit être défini dans l'espace de travail spécifié dans le paramètre name de la méthode :

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"