Questa guida descrive come configurare i filtri quando utilizzi l'API Monitoring. Utilizza i filtri per specificare le risorse monitorate, i tipi di metriche, le definizioni dei gruppi e le serie temporali. Puoi anche utilizzare un filtro per configurare un criterio di avviso che monitora i processi in esecuzione sui tuoi sistemi. Per informazioni su questi filtri, consulta Filtri di integrità di processo.
Prima di iniziare
Se non hai familiarità con le metriche, le serie temporali e le risorse monitorate, consulta Metriche, serie temporali e risorse.
Se non hai familiarità con le etichette, consulta la sezione Etichette per un'introduzione.
Utilizzo dei filtri
Puoi utilizzare i filtri nell'API Monitoring per:
- Seleziona i dati delle serie temporali specifici che vengono
restituito da una richiesta dell'API
list
. Il filtro può selezionare le serie temporali in base alle proprietà del progetto, del gruppo, della risorsa monitorata e della metrica dei dati. Per ulteriori informazioni ed esempi, consulta Recupero dei dati delle serie temporali.
Assegna le risorse a un
Group
in base alle proprietà delle risorse e al progetto a cui appartengono. Per ulteriori informazioni ed esempi, consulta la sezione Definire l'appartenenza al gruppo.Seleziona le risorse all'interno di un gruppo in base alle loro proprietà. Per ulteriori informazioni ed esempi, consulta Aggiungere membri al gruppo di schede.
Elenca tipi di metriche specifici. Per ulteriori informazioni ed esempi, consulta la sezione Descrittori delle metriche delle schede.
Elenca determinati tipi di risorse monitorate. Per ulteriori informazioni ed esempi, consulta Elenco dei descrittori delle risorse monitorate.
Selettori di filtro
Un filtro è costituito da almeno un selettore, ovvero una parola chiave di filtro. I seguenti esempi illustrano i diversi selettori:
-
project
: corrisponde quando le metriche del progetto specificato sono visibili al progetto di definizione dell'ambito di un ambito delle metriche indicato nel parametroname
.Utilizza il selettore
project
quando un progetto Google Cloud può visualizzare le metriche di più progetti Google Cloud o account AWS e vuoi visualizzare solo le metriche di un singolo progetto. Ad esempio, se l'ambito delle metriche perProject-A
includeProject-B
, si verifica una corrispondenza quandoname
ha un valore diProject-A
e utilizzi il seguente filtro:project = "Project-B"
-
group
: corrisponde alle risorse appartenenti a unGroup
.Il seguente filtro corrisponde al gruppo con l'identificatore
group-id
:group.id = "group-id"
-
resource
: corrisponde alle risorse monitorate di un determinato tipo o con valori di etichetta specifici.-
Il seguente filtro corrisponde a tutte le risorse monitorate che sono istanze di macchine virtuali (VM) Compute Engine:
resource.type = "gce_instance"
-
Il seguente filtro corrisponde a tutte le risorse la cui zona inizia con
europe-
:resource.labels.zone = starts_with("europe-")
-
-
metric
: corrisponde a un determinato tipo di metrica o a una serie temporale con un'etichetta specifica che corrisponde a un valore specifico.-
Il seguente filtro corrisponde a un tipo di metrica specifico:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
-
Il seguente filtro abbina le serie temporali a un'etichetta denominata
instance_name
, il cui valore inizia congke-hipster
ogke-nginx
:metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")
-
La tabella seguente mostra i selettori consentiti nei filtri in base alla chiamata dell'API di monitoraggio:
Scopo del filtro | Selettore project |
Selettore group |
Selettore resource |
Selettore metric |
---|---|---|---|---|
Definisci i gruppi | sì | yes* | ||
Elenca membri di gruppi | sì | sì | ||
Elenca le serie temporali | sì | sì | sì | sì † |
Elenca descrittori della metrica | sì | sì | ||
Elenca i descrittori delle risorse monitorate | sì |
† Quando elenchi le serie temporali, devi specificare esattamente un tipo di metrica.
Le seguenti sezioni mostrano esempi di utilizzi tipici dei filtri di monitoraggio. Consulta la sezione Sintassi dei filtri per una discussione completa degli oggetti e degli operatori di filtro disponibili.
Recupero dei dati delle serie temporali
Metodo:
projects.timeSeries.list
Oggetti filtro:
project
, group.id
, resource.type
, resource.labels.[KEY]
, metric.type
,
metric.labels.[KEY]
Una serie temporale è un elenco di punti dati con timestamp di un tipo di metrica di una risorsa monitorata specifica. Per maggiori dettagli, consulta Il modello metrico. Il tipo di metrica è specificato da un descrittore di metrica e la risorsa monitorata è specificata da un descrittore di risorsa monitorata.
Il filtro specificato per il metodo timeSeries.list
deve includere un
metric
selettore e questo selettore deve specificare esattamente un tipo di metrica:
- Per restituire tutte le serie temporali per un determinato tipo di metrica:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Per restituire tutte le serie temporali per un gruppo specifico. Il selettore
group
funziona solo con i dati delle serie temporali allineati. Per ulteriori informazioni, consulta il selettore di gruppo:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND group.id = "2468013579"
Per restituire tutte le serie temporali da un'istanza Compute Engine specifica, utilizza il seguente filtro:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = "my-instance-name"
Per restituire tutte le serie temporali delle istanze Compute Engine i cui nomi iniziano con
frontend-
, utilizza il seguente filtro:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = starts_with("frontend-")
Per restituire tutte le serie temporali delle istanze Compute Engine i cui nomi iniziano con
gke-hipster
ogke-nginx
, utilizza il seguente filtro:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
Definire l'appartenenza al gruppo
Metodo:
projects.groups
Oggetti filtro: project
, resource.type
, resource.labels.key
,
metadata.system_labels.[KEY]
, metadata.user_labels.[KEY]
Un gruppo può contenere un numero qualsiasi di risorse, come specificato da un filtro. L'appartenenza al gruppo è dinamica; più o meno risorse potrebbero corrispondere al filtro ogni volta che viene valutato. Il parametro name
nell'oggetto
Group
specifica il gruppo e il
project di ambito di un ambito delle metrichemetrics-scope-concept.
Se nel filtro viene utilizzato il selettore project
, deve essere specificato un progetto le cui metriche sono visibili al progetto di ambito.
resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
Membri del gruppo di schede
Metodo:
projects.groups.members.list
Oggetti filtro: project
, resource.type
, resource.labels.[KEY]
Utilizza un filtro per limitare i membri del gruppo da recuperare. Il parametro name
specifica un progetto di definizione dell'ambito di un ambito delle metriche e un
gruppo definito in quel progetto. Se nel
project
viene utilizzato il selettore nel
project
, deve essere specificato un progetto le cui metriche sono visibili al
project
progetto di ambito.
- Per restituire un elenco di tutte le risorse degli argomenti Pub/Sub appartenenti al progetto
my-project
, utilizza il seguente filtro:project = "my-project" AND resource.type = "pubsub_topic"
Descrittori delle metriche delle schede
Metodo:
projects.metricDescriptors.list
Oggetti filtro: project
, metric.type
Utilizza un filtro per limitare i descrittori delle metriche che vengono recuperati:
- Per restituire solo i descrittori delle metriche di Compute Engine,
utilizza il seguente filtro:
metric.type = starts_with("compute.googleapis.com")
Consulta l'elenco delle metriche per un elenco completo dei tipi di metrica disponibili. Per una panoramica della denominazione delle metriche, consulta le Convenzioni di denominazione delle metriche.
Elenco dei descrittori risorsa monitorata
Metodo:
projects.monitoredResourceDescriptors.list
Oggetti filtro: resource.type
Utilizza un filtro per limitare i descrittori risorsa monitorata che vengono recuperati:
- Per recuperare solo i descrittori delle risorse monitorate Pub/Sub,
utilizza il seguente filtro:
resource.type = starts_with("pubsub")
Consulta Elenco delle risorse monitorate per un elenco completo dei tipi di risorsa monitorata definiti da Monitoring.
Esempi
Negli esempi di filtri, utilizziamo il seguente descrittore della metrica, il descrittore della risorsa monitorata e l'istanza della macchina virtuale, semplificati per l'illustrazione:
# 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" }
Esempi di recupero delle metriche
Per richiedere l'utilizzo della larghezza di banda di lettura del disco per tutte le istanze e tutti i dispositivi, definisci un filtro come segue. Questo filtro restituisce, per ogni istanza, una serie temporale distinta che indica la larghezza di banda di lettura per ciascun dispositivo:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Per perfezionare la richiesta di query per la larghezza di banda in lettura solo per il dispositivo di disco noto come "log_partition" in ogni istanza, definisci il filtro come segue. Questo filtro restituisce, per ogni istanza, al massimo una serie temporale, a seconda che in quell'istanza esista un dispositivo con quel nome:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND metric.labels.device_name = "log_partition"
Per limitare la richiesta a una singola istanza, specifica l'istanza:
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"
Filtrare con i gruppi
Gli esempi riportati di seguito illustrano l'utilizzo del selettore di gruppi nei filtri per limitare le risorse monitorate a quelle di un gruppo specifico. Consulta Selettore di risorse per le definizioni di gruppo per informazioni sui selettori utilizzati per definire l'appartenenza al gruppo.
{ "name": "projects/my-test-project/groups/024681012", "display_name": "My Redis Cluster", "filter": "metadata.user_labels.role=redis" }
In una chiamata al metodo projects.timeSeries.list
,
il seguente filtro richiede l'utilizzo della larghezza di banda di lettura del disco per tutte
le istanze Compute Engine in un determinato gruppo. Il gruppo deve essere definito nel progetto di definizione dell'ambito di un ambito delle metriche specificato nel parametro name
del metodo:
resource.type = "gce_instance" AND group.id = "024681012" AND metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Riferimento: sintassi del filtro
Per una panoramica dei filtri con esempi, consulta Utilizzare i filtri.
Un filtro di monitoraggio è una stringa composta da un massimo di quattro tipi di selettori:
<monitoring_filter> ::= <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>
Il filtro corrisponde a un elemento se tutti i selettori inclusi corrispondono all'elemento.
Come descritto nelle sezioni seguenti, alcuni selettori possono avere più confronti uniti da AND
o OR
. L'ordine dei selettori nel filtro non è importante, ma i confronti tra selettori diversi non devono essere mescolati.
A seconda dello scopo del filtro, alcuni selettori potrebbero essere obbligatori, facoltativi o vietati. Ad esempio, il filtro utilizzato per elencare le serie temporali deve contenere un selettore di metriche. Tuttavia, il filtro che definisce le risorse in un gruppo non può contenere un selettore di metriche, perché i gruppi non contengono tipi di metriche o serie temporali.
Confronti
I filtri e i relativi selettori vengono creati a partire dai confronti. Ogni confronto ha la seguente forma:
-
[OBJECT]: seleziona un valore da testare; uno dei seguenti:
project group.id metric.type metric.labels.[KEY] resource.type resource.labels.[KEY] metadata.system_labels.[KEY] metadata.user_labels.[KEYSTRING]
[KEY] è un nome, ad esempio
zone
oinstance_id
.[KEYSTRING] può essere un nome, ma se contiene caratteri speciali, deve essere racchiuso tra virgolette (
"
). -
[OPERATORE]: un operatore di confronto; uno dei seguenti:
= # equality (case-sensitive) > < >= <= # numeric ordering != # not equal : # "has" substring match and test for key (case-sensitive)
-
[VALORE]: un valore letterale o una chiamata di funzione integrata; uno dei seguenti:
<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>)
Tranne quando viene utilizzato nel metodo
timeSeries.list
, il filtrohas_substring
accetta un secondo argomento facoltativo, che specifica se la corrispondenza ignora la maiuscola o meno. Il valore predefinito èfalse
, quindi la corrispondenza predefinita è sensibile alle maiuscole:- Sensibilità alle maiuscole:
display_name=has_substring("Demo")
- Sensibilità alle maiuscole:
display_name=has_substring("Demo", false)
- Senza distinzione tra maiuscole e minuscole:
display_name=has_substring("Demo", true)
Se utilizzato nel metodo
timeSeries.list
, è supportato solo il formatohas_substring(<string>)
.Il filtro
monitoring.regex.full_match
accetta una stringa di espressione regolare nella sintassi RE2. - Sensibilità alle maiuscole:
Puoi utilizzare i seguenti operatori per raggruppare o modificare i confronti. OR
ha una precedenza superiore a AND
. Gli operatori devono essere scritti in maiuscolo:
(...) # grouping comparisons AND # conjunction (optional but recommended) OR # disjunction
L'operatore AND
può essere omesso tra gli operatori, ma è più chiaro e meno soggetto a errori se lo includi.
Il confronto x = one_of("a", "b", "c")
è equivalente al seguente:
(x = "a" OR x = "b" OR x = "c")
NOT
prima di un confronto, ma non con un operatore EXISTS (:
) o prima di un'espressione tra parentesi:
NOT # negates the following comparison
Selettori di filtro
Utilizza i selettori per limitare le selezioni dei filtri a determinati elementi.
Nelle sezioni seguenti, le parentesi graffe vengono utilizzate per indicare la ripetizione. Ad esempio,
la notazione <x> {OR <y>}
indica che puoi scrivere uno dei seguenti
valori:
<x> <x> OR <y> <x> OR <y> OR <y> <x> OR <y> OR <y> OR <y> ...
Selettore di progetti
Un selettore di progetti limita la selezione del filtro agli elementi appartenenti a un singolo progetto o a uno di un insieme di progetti. Ogni progetto può essere specificato tramite il suo ID o il suo numero:
<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}
Se il selettore di progetti contiene più di un confronto, racchiudi l'intero selettore tra parentesi per una migliore leggibilità. Ad esempio:
(project=12345 OR project="my-project-id") AND resource.type="gce_instance"
Selettore di gruppi
Un selettore di gruppo limita la selezione del filtro agli elementi appartenenti a un singolo gruppo:
<group_selector> ::= group.id '=' <string>
Ad esempio, il seguente filtro può essere utilizzato per recuperare una serie temporale da ciascuna delle istanze VM di un gruppo:
group.id = 12345 AND resource.type = "gce_instance" AND metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Il selettore di gruppo è consentito solo nei filtri passati al metodo
projects.timeSeries.list
. Inoltre, la selezione del gruppo richiede dati allineati, ovvero la chiamata projects.timeSeries.list
deve includere i valori per i campi perSeriesAligner
e alignmentPeriod
. Questo perché l'appartenenza al gruppo è essa stessa un tipo di serie temporale che deve essere unita ai dati delle metriche e la fornitura di parametri di allineamento ti consente di controllare la modalità di unione.
Per saperne di più sui parametri di allineamento, consulta
Aggregare i dati.
Selettore risorse
Un selettore di risorse limita la selezione del filtro alle risorse o agli elementi associati alle risorse che hanno valori di tipo di risorsa o etichetta specifici:
<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>}
Se utilizzi più di un <r_label_comparison>
nel selettore, li devi inserire tutti tra parentesi per una migliore leggibilità.
Ad esempio, il seguente filtro potrebbe essere utilizzato per definire un gruppo che includa tutte le istanze VM Compute Engine negli Stati Uniti e in Europa.
resource.type = "gce_instance" AND (resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))
Selettore di risorse per le definizioni di gruppo
I selettori di risorse utilizzati per definire l'appartenenza al gruppo utilizzano estensioni alla sintassi<resource_selector>
:
Includi i filtri in base al valore delle etichette dei metadati di sistema
metadata.system_labels.[KEY]
e delle etichette dei metadati utentemetadata.user_labels.[KEYSTRING]
. Ti consigliamo di inserire le chiavi permetadata.user_labels
tra virgolette perché possono contenere caratteri speciali come i trattini.Quando un selettore contiene un filtro dei metadati e un filtro delle risorse, devi combinarli con
AND
; non puoi utilizzareOR
. Ad esempio, un grafico con il seguente selettore mostra l'utilizzo della CPU per tutte le istanze VM con un tipo di macchinae2-medium
oe2-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")
Puoi utilizzare l'operatore di non equivalenza (
!=
) per confrontare tipi di risorse, etichette delle risorse e metadati. L'operatore può essere utilizzato per confrontare stringhe, numeri, valori booleani o le funzioni di sottostringa. Ad esempio,resource.type!=starts_with("gce")
è true se il tipo di risorsa non inizia con"gce"
.Puoi utilizzare un singolo operatore
NOT
prima di un confronto delle risorse. Ad esempio,NOT resource.labels.zone="europe"
è true se la zona della risorsa non include"europe"
. Non puoi utilizzareNOT
prima di un operatore Exists (Esiste) (:
) o di un'espressione tra parentesi.Puoi utilizzare l'operatore "esiste" (
:
) per verificare l'esistenza delle chiavi. Ad esempio, il confrontoresource.labels:zone
è true se la chiave dell'etichettazone
è presente nella risorsa.
Ad esempio, una delle chiavi dei metadati della risorsa della piattaforma per le istanze VM è spot_instance
. Il seguente selettore di filtri sceglie le istanze di tipo spot:
resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true
Selettore delle metriche
Un selettore di metriche specifica determinate metriche o descrittori delle metriche limitando il tipo di metrica e le etichette delle metriche. Se utilizzato con il metodo
projects.timeSeries.list
,
il selettore delle metriche deve specificare un singolo tipo di metrica:
<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>}
Ad esempio, il seguente filtro potrebbe essere utilizzato per recuperare una serie temporale per un'istanza di database specifica:
metric.type = "cloudsql.googleapis.com/database/state" AND (metric.labels.resource_type = "instance" AND metric.labels.resource_id = "abc-123456")