Ce guide explique comment configurer des filtres lorsque vous utilisez l'API Monitoring. Les filtres permettent de spécifier les ressources surveillées, les types de métriques, les définitions de groupe, et les séries temporelles. Vous pouvez également utiliser un filtre pour configurer une règle d'alerte surveille processus exécutés sur vos systèmes. Pour en savoir plus sur ces filtres, consultez la section Filtres d'état de processus.
Avant de commencer
Si vous ne connaissez pas bien les métriques, les séries temporelles et les ressources surveillées, Consultez la section 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 permet de sélectionner des séries temporelles en fonction du projet, du groupe, des propriétés de la ressource surveillée et les 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.
Attribuer des ressources à un groupe (
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.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 des types de métriques spécifiques. Pour obtenir plus d'informations et des exemples, consultez la section 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:
-
project: établit une correspondance lorsque les métriques des projet sont visibles par le projet effectuant une surveillance pour un champ d'application des métriques mentionnée dans le paramètrename.Utilisez le sélecteur
projectlorsqu'un projet Google Cloud Peut afficher les métriques de plusieurs projets Google Cloud ou comptes AWS et que vous ne voulez que les métriques d'un seul projet. Par exemple, si le champ d'application des métriques ; pourProject-AinclutProject-B, puis la correspondance se produit lorsquenamea une valeur deProject-Aet vous utilisez le filtre suivant:project = "Project-B"
-
group: établit une correspondance avec les ressources appartenant à unGroupLe filtre suivant permet d'établir une correspondance avec le groupe associé au identifiant
group-id:group.id = "group-id" -
resource: correspond à ressources surveillées d'un type particulier ou possédant une étiquette particulière valeurs.-
Le filtre suivant correspond à toutes les ressources surveillées sont des instances de machines virtuelles (VM) Compute Engine:
resource.type = "gce_instance"
-
Le filtre suivant renvoie toutes les ressources dont la zone commence avec
europe-:resource.labels.zone = starts_with("europe-")
-
-
metric: correspond à un spécifique type de métrique ou série temporelle avec avec une étiquette spécifique correspondant à 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 portant un libellé nommé
instance_name, dont la valeur commence pargke-hipsterougke-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 project |
Sélecteur group |
Sélecteur resource |
Sélecteur metric |
|---|---|---|---|---|
| Définir des groupes | oui | oui* | ||
| Répertorier les membres d'un groupe | Oui | Oui | ||
| Répertorier les séries temporelles | Oui | Oui | oui | oui † |
| Répertorier les descripteurs de statistiques | Oui | Oui | ||
| Répertorier les descripteurs de ressources surveillées | oui |
† 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
Filtrer les objets:
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. la ressource surveillée est spécifiée descripteur de ressources surveillées.
Le filtre spécifié pour la méthode timeSeries.list doit inclure un élément
metric. Ce sélecteur doit spécifier exactement un type de métrique:
- Pour renvoyer toutes les séries temporelles d'un type de métrique particulier:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Permet de renvoyer toutes les séries temporelles d'un groupe spécifique. Le sélecteur
groupne fonctionne qu'avec les données de séries temporelles alignées. Pour en savoir plus, consultez la section Sélecteur de groupe :metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND group.id = "2468013579"
Pour renvoyer toutes les séries temporelles d'une instance Compute Engine spécifique, procédez comme suit : utilisez le filtre suivant:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = "my-instance-name"
Renvoyer toutes les séries temporelles des instances Compute Engine dont les noms commencez par
frontend-, utilisez le filtre suivant:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = starts_with("frontend-")Renvoyer toutes les séries temporelles des instances Compute Engine dont les noms commencez par
gke-hipsterougke-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).*")
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. Groupe
l'adhésion est dynamique. plus ou moins de ressources peuvent correspondre au filtre
l'heure à laquelle le filtre est évalué. Le paramètre name dans
L'objet Group spécifie le groupe et le
projet effectuant une surveillance du champ d'application des métriquesmetrics-scope-concept.
Si le sélecteur project est utilisé dans le filtre, il doit spécifier une
projet dont les métriques sont visibles par le projet effectuant une surveillance.
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
spécifie un projet effectuant une surveillance d'un champ d'application des métriques et un
défini dans ce projet. Si le sélecteur project est utilisé dans le
filtre, il doit spécifier un projet dont les métriques sont visibles
de surveillance.
- Pour renvoyer la liste de toutes les ressources de sujet Pub/Sub appartenant à
projet
my-project, utilisez le filtre suivant: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 :
- Pour ne renvoyer que les descripteurs de métriques Compute Engine,
utilisez le filtre suivant:
metric.type = starts_with("compute.googleapis.com")
Consultez la Liste des métriques pour obtenir la liste complète des métriques disponibles. de données. Pour savoir comment attribuer un nom aux métriques, consultez la section Nommage des métriques conventions.
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 :
- 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 les types de ressources surveillées définis par Monitoring.
Examples
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 du disque pour toutes les instances et tous les appareils, définissez un filtre comme suit. Ce filtre renvoie, pour chaque instance, Séries temporelles distinctes 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 appelé "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 l'instance en question:
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 composant sélecteur de groupe dans les filtres pour restreindre les ressources surveillées à ceux d'un groupe spécifique. Voir Sélecteur de ressources pour les définitions de groupe pour en savoir plus sur les sélecteurs utilisés pour définir l'appartenance à un 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 du disque
d'instances Compute Engine dans un groupe particulier. Le groupe doit être défini dans le projet de champ d'application d'un champ d'application de métriques 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"
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 avoir plusieurs
comparaisons jointes 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
entremêlés.
Selon l'objectif du filtre, certains sélecteurs peuvent être obligatoires, facultatifs ou interdits. Par exemple, le filtre permettant de lister les séries temporelles doit contenir un sélecteur de métrique. Toutefois, le filtre qui définit les ressources d'un groupe ne peut pas contenir un sélecteur de métriques, car les groupes ne contiennent aucun type de métrique ni de séries temporelles.
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 ; l'une des options 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
zoneouinstance_id[KEYSTRING] peut être un nom, mais s'il contient des caractères spéciaux, elle doit être placée entre guillemets (
"). -
[OPERATOR]: opérateur de comparaison. l'une des options suivantes:
= # 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ée. au choix les é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 s'il est utilisé dans la méthode
timeSeries.list, Le filtrehas_substringaccepte un deuxième argument facultatif, qui spécifie si la correspondance ignore la casse ou non. La valeur par défaut la valeur estfalse. 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)
Lorsqu'elle est utilisée dans la méthode
timeSeries.list, seul le formulairehas_substring(<string>)est pris en charge.Le filtre
monitoring.regex.full_matchprend une d'expression régulière dans Syntaxe RE2. - Sensible à la casse:
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")Seulement dans les définitions de groupe, vous pouvez utiliser l'opérateur de négation unaire,
NOT,
avant une comparaison, mais pas avec un opérateur existe (:) ni avant un
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 n'importe quelle
suivantes:
<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é son identifiant 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 permet de 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 à la
projects.timeSeries.list. De plus,
La sélection d'un groupe nécessite des données alignées. c'est-à-dire
L'appel projects.timeSeries.list doit inclure des valeurs pour les champs
perSeriesAligner et 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
Agrégation 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> ')'
<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, alors
placez-les tous entre parenthèses
pour une meilleure lisibilité.
Par exemple, le filtre suivant pourrait être utilisé pour définir un groupe qui inclut
sur toutes les instances de VM Compute Engine
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> :
Vous incluez des filtres basés sur la valeur des étiquettes du système de métadonnées,
metadata.system_labels.[KEY]et les étiquettes utilisateur des métadonnées,metadata.user_labels.[KEYSTRING]Nous vous recommandons de citer clés pourmetadata.user_labels, car elles peuvent contenir des clés tels que des traits d'union.Lorsqu'un sélecteur contient un filtre de métadonnées et un filtre de ressource, vous doit les combiner avec
AND; vous ne pouvez pas utiliserOR. Par exemple, un graphique Le sélecteur suivant affiche l'utilisation du processeur pour toutes les VM instances dont le type de machine este2-mediumoue2-micro:metric.type="compute.googleapis.com/instance/cpu/utilization" resource.type="gce_instance" AND (metadata.system_labels."machine_type"="e2-medium" OR metadata.system_labels."machine_type"="e2-micro")
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".Vous pouvez utiliser un seul opérateur
NOTavant une 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 utiliserNOTavant un opérateur existe (:) ou une expression entre parenthèses.Vous pouvez utiliser la valeur (
:) pour tester l'existence de clés. Par exemple, la comparaisonresource.labels:zoneest "true" si l'étiquette la clézoneest 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. Lorsqu'elle est utilisée avec
la méthode projects.timeSeries.list,
le sélecteur de métriques ne doit spécifier qu'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 heure 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")