Il est possible qu'une partie ou l'ensemble des informations de cette page ne s'appliquent pas au Cloud de confiance S3NS. Pour en savoir plus, consultez Différences par rapport à Google Cloud.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Filtres de surveillance

Les filtres de l'API Cloud Monitoring vous permettent de sélectionner des séries temporelles, des types de métriques et des ressources surveillées spécifiques dans les requêtes API.

Avant de commencer

Si vous ne connaissez pas les métriques, les séries temporelles et les ressources surveillées, consultez Métriques, séries temporelles et ressources.

Si vous ne connaissez pas le fonctionnement des libellés, consultez la section Libellés pour obtenir une présentation.

Utiliser des filtres

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

Sélectionner les données de séries temporelles spécifiques qui sont renvoyées par une requête API list. Le filtre peut sélectionner des séries temporelles en fonction des propriétés de la ressource surveillée et des propriétés de la métrique des données. Pour en savoir plus et obtenir des exemples, consultez la section Récupérer des données de séries temporelles.

Répertorier des types de métriques spécifiques. Pour obtenir plus d'informations et des exemples, consultez Répertorier les descripteurs de métriques.
Répertorier des types de ressources surveillées spécifiques. Pour obtenir plus d'informations et d'exemples, consultez la section Répertorier les descripteurs de ressources surveillées.

Sélecteurs de filtres

Un filtre comprend au moins un sélecteur, c'est-à-dire un mot clé de filtre. Les exemples suivants illustrent les différents sélecteurs :

resource : correspond aux ressources surveillées d'un type particulier ou ayant des valeurs d'étiquette particulières.
- Le filtre suivant correspond à toutes les ressources surveillées qui sont des instances de machine virtuelle (VM) Compute Engine :
```
resource.type = "gce_instance"
```
metric : correspond à un type de métrique ou à une série temporelle spécifique avec un libellé particulier qui correspond à une valeur spécifique.
- Le filtre suivant correspond à un type de métrique spécifique :
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
- Le filtre suivant correspond aux séries temporelles comportant un libellé nommé instance_name, dont la valeur commence par gke-hipster ou gke-nginx :
```
metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")
```

Le tableau suivant indique les sélecteurs autorisés dans les filtres en fonction de l'appel de l'API Monitoring :

Objectif du filtre	Sélecteur de `resource`	Sélecteur de `metric`
Répertorier les séries temporelles	oui	oui ^*
Répertorier les descripteurs de métriques		Oui
Répertorier les descripteurs de ressources surveillées	oui

^* Lorsque vous listez 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 filtre : project, 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.

Le filtre spécifié pour la méthode timeSeries.list doit inclure un sélecteur metric, et ce sélecteur doit spécifier un seul type de métrique :

Pour renvoyer toutes les séries temporelles d'un type de métrique particulier, utilisez le filtre suivant :
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
Pour renvoyer toutes les séries temporelles d'une instance Compute Engine spécifique, utilisez le filtre suivant :
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = "my-instance-name"
```
Pour renvoyer toutes les séries temporelles des instances Compute Engine dont le nom commence par frontend-, utilisez le filtre suivant :
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = starts_with("frontend-")
```

Pour renvoyer toutes les séries temporelles des instances Compute Engine dont le nom commence par gke-hipster ou gke-nginx, utilisez le filtre suivant :

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

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.

Par exemple, pour ne renvoyer que les descripteurs de métriques Compute Engine, utilisez le filtre suivant :

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

Pour obtenir la liste complète des types de métriques disponibles, consultez Liste des métriques. Pour en savoir plus sur la façon dont les métriques sont nommées, consultez Conventions d'attribution de noms aux métriques.

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.

Par exemple, pour ne récupérer que les descripteurs de ressources surveillées Pub/Sub, utilisez le filtre suivant :

resource.type = starts_with("pubsub")

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

Exemples

Dans les exemples de filtrage, nous utilisons le descripteur de la métrique, le descripteur de ressource surveillée et l'instance de machine virtuelle suivants, simplifiés à des fins d'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 provided 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 de lecture sur disque pour toutes les instances et tous les appareils, définissez un filtre comme suit. Ce filtre renvoie, pour chaque instance, une série temporelle distincte indiquant la bande passante de lecture pour chaque appareil :

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

Pour affiner la requête afin d'interroger la bande passante de lecture uniquement pour le disque nommé "log_partition" sur chaque instance, définissez le filtre comme suit. 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"

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 deux types de sélecteurs au maximum :

    <monitoring_filter> ::= <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 associées par AND ou OR. L'ordre des sélecteurs dans le filtre n'a pas d'importance, mais les comparaisons pour différents sélecteurs ne doivent pas être mélangées.

Selon l'objectif du filtre, certains sélecteurs peuvent être obligatoires, facultatifs ou interdits. Par exemple, le filtre utilisé pour lister les séries temporelles doit contenir un sélecteur de métrique.

Comparaisons

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

[OBJECT] : sélectionne une valeur à tester, parmi les suivantes :
```
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
    
```
[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] : opérateur de comparaison, l'un des suivants :

=            # equality (case-sensitive)
> < >= <=    # numeric ordering
!=           # not equal
:            # "has" substring match and test for key (case-sensitive)

[VALUE] : valeur littérale ou appel de fonction intégré, l'un des éléments 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 lorsqu'il est utilisé dans la méthode timeSeries.list, le filtre has_substring accepte un deuxième argument facultatif, qui spécifie si la correspondance ignore la casse ou non. La valeur par défaut est false, de sorte que la correspondance par défaut est 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)
Lorsqu'il est utilisé dans la méthode timeSeries.list, seul le format has_substring(<string>) est accepté.

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 à ce qui suit :

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

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 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> ')'

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

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

Si vous utilisez plusieurs <r_label_comparison> dans votre sélecteur, placez-les tous entre parenthèses pour une meilleure lisibilité.

Sélecteur de métrique

Un sélecteur de métriques spécifie certaines métriques ou certains descripteurs de métriques en limitant le type de métrique et les étiquettes de métrique. Lorsqu'il est utilisé avec la méthode projects.timeSeries.list, le sélecteur de métriques 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_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>

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

Par exemple, le filtre suivant peut être utilisé pour 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")