Filtri di monitoraggio

Questa guida descrive come configurare i filtri quando utilizzi l'API Monitoring. Puoi utilizzare 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 monitori i processi in esecuzione sui tuoi sistemi. Per informazioni su questi filtri, consulta Filtri di integrità del 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 dimestichezza con le etichette, consulta la sezione Etichette per un'introduzione.

Utilizzo dei filtri

Puoi utilizzare i filtri nell'API Monitoring per:

Filtra selettori

Un filtro è costituito da almeno un selettore, ovvero una parola chiave del 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 menzionato nel parametro name.

    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 per un singolo progetto. Ad esempio, se l'ambito delle metriche per Project-A include Project-B, si verifica una corrispondenza quando name ha il valore Project-A e utilizzi il seguente filtro:

    project = "Project-B"

  • group: corrisponde alle risorse appartenenti a un solo Group.

    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 particolare tipo di metrica o serie temporale a una determinata etichetta 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 crea corrispondenze per le serie temporali con un'etichetta denominata instance_name, il cui valore inizia con gke-hipster o gke-nginx:

      metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")

La seguente tabella mostra i selettori consentiti nei filtri basati sulla chiamata all'API Monitoring:

Scopo del filtro Selettore project Selettore group Selettore resource Selettore metric
Definisci i gruppi sì sì*
Elenca membri di gruppi sì sì
Elenca serie temporali sì sì sì sì †
Elenco dei descrittori delle metriche sì sì
Elenco descrittori risorsa monitorata sì
* Il selettore di risorse offre opzioni aggiuntive se viene utilizzato per definire l'appartenenza ai gruppi.
† 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 Sintassi dei filtri per una discussione completa sugli oggetti e gli operatori di filtro disponibili.

Recupero dei dati delle serie temporali

Metodo: projects.timeSeries.list
Filtra oggetti: 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 provenienti da una specifica risorsa monitorata. Per maggiori dettagli, consulta Il modello delle metriche. Il tipo di metrica è specificato da un descrittore della metrica e la risorsa monitorata è specificata da un descrittore della risorsa monitorata.

Il filtro specificato per il metodo timeSeries.list deve includere un selettore metric e questo 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 dati di serie temporali allineati. Per saperne di più, consulta la sezione Selettore di gruppi:

    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"

  • Restituisci tutte le serie temporali dalle istanze di Compute Engine i cui nomi iniziano con frontend-, utilizza il filtro seguente: 

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = starts_with("frontend-")

  • Restituisci tutte le serie temporali dalle istanze di Compute Engine i cui nomi iniziano con gke-hipster o gke-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).*")

Definizione dell'appartenenza al gruppo

Metodo: projects.groups
Filtra oggetti: 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 ai gruppi è dinamica. Ogni volta che il filtro viene valutato, più o meno risorse potrebbero corrispondere al filtro. Il parametro name nell'oggetto Group specifica il gruppo e il progetto di ambito di un ambito delle metriche]metrics-scope-concept. Se nel filtro viene utilizzato il selettore project, deve specificare un progetto le cui metriche sono visibili al progetto di definizione dell'ambito.

  • Per restituire un elenco di tutte le istanze di macchine virtuali (VM) di Compute Engine in Europa, utilizza il seguente filtro: 
    resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")

Membri del gruppo di schede

Metodo: projects.groups.members.list
Filtra oggetti: project, resource.type, resource.labels.[KEY]

Utilizza un filtro per limitare i membri del gruppo recuperati. Il parametro name specifica un progetto di ambito di un ambito delle metriche e un gruppo definito in quel progetto. Se nel filtro viene utilizzato il selettore project, deve specificare un progetto le cui metriche sono visibili al progetto di definizione dell'ambito.

  • Per restituire un elenco di tutte le risorse dell'argomento Pub/Sub che appartengono al progetto my-project, utilizza il seguente filtro: 
    project = "my-project" AND resource.type = "pubsub_topic"

Elenco dei descrittori delle metriche

Metodo: projects.metricDescriptors.list
Filtra oggetti: project, metric.type

Utilizza un filtro per limitare i descrittori delle metriche 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 metriche disponibili. Per una panoramica sulla modalità di denominazione delle metriche, consulta Convenzioni di 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 che recuperi:

  • Per recuperare solo i descrittori risorsa monitorata di Pub/Sub, utilizza il seguente filtro: 
    resource.type = starts_with("pubsub")

Consulta l'elenco delle risorse monitorate per un elenco completo dei tipi di risorsa monitorata definiti da Monitoring.

Esempi

Negli esempi di filtro, utilizziamo il descrittore della metrica, il descrittore della risorsa monitorata e l'istanza della macchina virtuale, semplificati a titolo illustrativo:

    # 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 per la 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 ciascun dispositivo:

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

Per perfezionare la richiesta di query per la larghezza di banda di lettura solo per il dispositivo disco noto come "log_partition" su ogni istanza, definisci il filtro come segue. Questo filtro restituisce, per ogni istanza, al massimo una serie temporale, a seconda dell'esistenza o meno di un dispositivo con quel nome sull'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"

Applicazione di filtri con i gruppi

I seguenti esempi 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 dei gruppi 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 per la lettura del disco per tutte le istanze di Compute Engine in un determinato gruppo. Il gruppo deve essere definito nel progetto di 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 dei filtri

Per una panoramica dei filtri con esempi, consulta la sezione Utilizzare i filtri.

Un filtro di monitoraggio è una stringa composta da massimo 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 per i diversi selettori non devono essere mescolati.

A seconda dello scopo, alcuni selettori potrebbero essere obbligatori, facoltativi o vietati. Ad esempio, il filtro usato 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 verificare; 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 o instance_id.

    [KEYSTRING] può essere name, ma se contiene caratteri speciali, deve essere racchiuso tra virgolette (").

  • [OPERATOR]: 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 che quando viene utilizzato nel metodo timeSeries.list, il filtro has_substring prende un secondo argomento facoltativo, che specifica se la corrispondenza ignora o meno maiuscole e minuscole. 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)

    Quando viene utilizzato nel metodo timeSeries.list, è supportato solo il modulo has_substring(<string>).

    Il filtro monitoring.regex.full_match accetta una stringa di espressione regolare nella sintassi RE2.

Per raggruppare o modificare i confronti, puoi utilizzare i seguenti operatori. OR ha la 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") equivale a quanto segue:

(x = "a" OR x = "b" OR x = "c")
Solo nelle definizioni di gruppi, puoi utilizzare l'operatore di negazione unario, NOT, prima di un confronto, ma non con un operatore esistente (:) o prima di un'espressione tra parentesi:

NOT          # negates the following comparison

Filtra selettori

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>} significa che puoi scrivere tutto quanto segue:

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

Selettore progetto

Un selettore di progetti limita la selezione dei filtri agli elementi appartenenti a un singolo progetto o a uno qualsiasi di un insieme di progetti. Ogni progetto può essere specificato in base al proprio ID o numero:

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

Se il selettore di progetto ha più confronti, 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 gruppo

Un selettore di gruppo limita la selezione dei filtri 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 in un gruppo:

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

Il selettore di gruppi è 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 valori per i campi perSeriesAligner e alignmentPeriod. Questo perché l'appartenenza al gruppo è di per sé un tipo di serie temporale che deve essere unita ai dati delle metriche e fornire parametri di allineamento ti consente di controllare come avviene l'unione. Per ulteriori informazioni sui parametri di allineamento, consulta Aggregazione dei dati.

Selettore risorse

Un selettore di risorse limita la selezione dei filtri 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à. Ad esempio, il seguente filtro potrebbe essere usato per definire un gruppo che includa tutte le istanze VM di 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 dei gruppi

I selettori di risorse utilizzati per definire l'appartenenza al gruppo utilizzano le estensioni per la sintassi <resource_selector>:

  • Puoi includere filtri basati sul valore delle etichette del sistema di metadati, metadata.system_labels.[KEY] e delle etichette utente dei metadati, metadata.user_labels.[KEYSTRING]. Ti consigliamo di citare le chiavi per metadata.user_labels perché possono contenere caratteri speciali, come i trattini.

    Quando un selettore contiene un filtro per metadati e un filtro delle risorse, devi combinarli con AND. Non puoi utilizzare OR. Ad esempio, un grafico con il seguente selettore mostra l'utilizzo della CPU per tutte le istanze VM con un tipo di macchina e2-medium o e2-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 non uguale (!=) per confrontare tipi di risorse, etichette delle risorse e metadati. L'operatore può essere usato per confrontare stringhe, numeri, booleani o funzioni di sottostringhe. 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 utilizzare NOT prima che esista un operatore (:) o un'espressione tra parentesi.

  • Puoi usare l'operatore "exists" (:) per verificare l'esistenza delle chiavi. Ad esempio, il confronto resource.labels:zone è true se la chiave di etichetta zone è presente nella risorsa.

Ad esempio, una delle chiavi dei metadati delle risorse della piattaforma per le istanze VM è spot_instance. Il seguente selettore di filtri sceglie le istanze spot:

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

Selettore di metriche

Un selettore di metriche specifica determinate metriche o descrittori di metriche limitando il tipo di metrica e le relative etichette. Se utilizzato con il metodo projects.timeSeries.list, il selettore di 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 può essere utilizzato per recuperare una serie temporale per una specifica istanza di database:

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