Questa guida descrive come configurare i filtri quando utilizzi l'API Monitoring. Utilizzi i filtri per specificare le risorse monitorate, i tipi di metriche e le serie temporali.
Prima di iniziare
Se non hai familiarità con metriche, serie temporali e 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 restituiti da una richiesta API
list
. Il filtro può selezionare serie temporali in base alle proprietàrisorsa monitoratae e alle proprietà delle metriche. Per ulteriori informazioni ed esempi, vedi Recupero dei dati delle serie temporali.
Elenca tipi di metriche particolari. Per ulteriori informazioni ed esempi, consulta Elenco dei descrittori delle metriche.
Elenca tipi di risorsa monitorata specifici. Per ulteriori informazioni ed esempi, consulta Elenco risorsa monitorata monitorate.
Selettori dei filtri
Un filtro è costituito da almeno un selettore, ovvero una parola chiave del filtro. I seguenti esempi illustrano i diversi selettori:
-
resource
: corrisponde alle risorse monitorate di un tipo specifico 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"
-
-
metric
: corrisponde a un particolare tipo di metrica o serie temporale con con un'etichetta particolare 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 corrisponde alle serie temporali con 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 Monitoring:
Scopo del filtro | Selettore resource |
Selettore metric |
---|---|---|
Elenca serie temporali | sì | Sì * |
Elenca descrittori della metrica | sì | |
Elenca i descrittori risorsa monitorata | sì |
Le seguenti sezioni mostrano esempi di utilizzi tipici dei filtri di monitoraggio. Consulta la sezione Sintassi dei filtri per una discussione completa degli operatori e degli oggetti filtro disponibili.
Recupero dei dati delle serie temporali
Metodo:
projects.timeSeries.list
Oggetti filtro:
project
, 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 i dettagli, vedi Il modello di metrica. 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
selettore metric
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 di una specifica istanza Compute Engine, 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 dalle 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-")
Restituisci tutte le serie temporali dalle 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).*")
Elenco dei descrittori delle metriche
Metodo:
projects.metricDescriptors.list
Filtra oggetti: project
, metric.type
Utilizza un filtro per limitare i descrittori delle metriche recuperati.
Ad esempio, 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 metriche disponibili. Per una panoramica della denominazione delle metriche, consulta Convenzioni per la denominazione delle metriche.
Elenco dei descrittori risorsa monitorata
Metodo:
projects.monitoredResourceDescriptors.list
Filtra oggetti: resource.type
Utilizza un filtro per limitare i descrittori risorsa monitorata recuperati.
Ad esempio, per recuperare solo i descrittori risorsa monitorata di Pub/Sub, utilizza il seguente filtro:
resource.type = starts_with("pubsub")
Per un elenco completo dei tipi di risorsa monitorata definiti da Monitoring, consulta Elenco delle risorse monitorate.
Esempi
Negli esempi di filtro, utilizziamo il seguente descrittore della metrica, il descrittore di risorsa monitorata e l'istanza di 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 separata che riporta la larghezza di banda di lettura per ogni dispositivo:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Per perfezionare la richiesta in modo da eseguire query sulla larghezza di banda di lettura solo per il dispositivo di archiviazione noto come "log_partition" in ogni istanza, definisci il filtro nel seguente modo. Questo filtro restituisce, per ogni istanza, al massimo una serie temporale, a seconda che esista o meno un dispositivo con quel nome nell'istanza:
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"
Riferimento: sintassi del filtro
Per una panoramica dei filtri con esempi, consulta Utilizzo dei filtri.
Un filtro di monitoraggio è una stringa composta da un massimo di due tipi di selettori:
<monitoring_filter> ::= <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 per selettori diversi non devono essere
intercalati.
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.
Confronti
I filtri e i relativi selettori vengono creati a partire dai confronti. Ogni confronto ha il seguente formato:
-
[OBJECT]: seleziona un valore da testare; uno dei seguenti:
metric.type metric.labels.[KEY] resource.type resource.labels.[KEY]
[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)
-
[VALUE]: 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 o meno la distinzione tra maiuscole e minuscole. Il valore predefinito èfalse
, quindi la corrispondenza predefinita distingue tra maiuscole e minuscole:- Sensibile alle maiuscole:
display_name=has_substring("Demo")
- Sensibile 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 modulohas_substring(<string>)
.Il filtro
monitoring.regex.full_match
accetta una stringa di espressione regolare nella sintassi RE2. - Sensibile alle maiuscole:
Puoi utilizzare i seguenti operatori per raggruppare o modificare i confronti. OR
ha
precedenza maggiore rispetto 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 includerlo.
Il confronto x = one_of("a", "b", "c")
è equivalente a quanto segue:
(x = "a" OR x = "b" OR x = "c")
Selettori dei filtri
Utilizza i selettori per limitare le selezioni dei filtri a determinati elementi.
Nelle sezioni seguenti, le parentesi graffe vengono utilizzate per mostrare la ripetizione. Ad esempio,
la notazione <x> {OR <y>}
indica che puoi scrivere uno dei
seguenti elementi:
<x> <x> OR <y> <x> OR <y> OR <y> <x> OR <y> OR <y> OR <y> ...
Selettore risorse
Un selettore risorse limita la selezione del filtro alle risorse o agli elementi associati alle risorse che hanno un tipo di risorsa o valori di 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, racchiudili tutti tra parentesi per una migliore leggibilità.
Selettore delle metriche
Un selettore di metriche specifica determinate metriche o descrittori di 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 solo 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")