Aggiungere filtri permanenti a una dashboard personalizzata

Questo documento descrive come aggiungere filtri permanenti a livello di dashboard alle tue dashboard personalizzate. I filtri permanenti, che consentono di modificare i dati visualizzati in una dashboard senza dover modificare ogni widget, hanno uno stato predefinito e possono essere applicati all'intera dashboard o solo a widget specifici. La barra degli strumenti della dashboard mostra tutti i filtri permanenti, insieme a un menu che consente di modificare temporaneamente il valore del filtro.

Se vuoi definire una presentazione predefinita dei dati in una dashboard insieme alle opzioni basate su menu per modificare la visualizzazione, aggiungi filtri permanenti. Ad esempio, se vuoi visualizzare le metriche per tutte le zone e anche quelle per una zona specifica, crea un filtro permanente basato sull'etichetta zone.

Puoi creare e applicare filtri permanenti utilizzando la console Google Cloud o l'API Cloud Monitoring. Questo documento descrive come utilizzare la console Google Cloud. Per informazioni sull'utilizzo dell'API Cloud Monitoring, consulta Creare e gestire le dashboard in base all'API: filtri della dashboard.

Per informazioni su come aggiungere e modificare raggruppamenti e filtri temporanei, consulta Aggiungere filtri temporanei a una dashboard personalizzata.

Come funzionano i filtri nella dashboard

Un filtro della dashboard specifica un'etichetta e un valore. Le serie temporali visualizzate nella dashboard determinano le etichette disponibili per l'applicazione dei filtri. Il modo in cui un widget supporta un filtro a livello di dashboard dipende dal tipo di dati visualizzati dal widget e dalla sua configurazione:

  • Per i widget che visualizzano dati delle serie temporali, come i grafici a linee, si applicano le seguenti regole:

    • Se le serie temporali visualizzate dal widget non supportano l'etichetta in un filtro, il filtro a livello di dashboard non modifica i dati visualizzati.

      Ad esempio, se aggiungi un filtro all'etichetta instance_id, ma un grafico nella dashboard non mostra i dati con l'etichetta instance_id, il filtro non modifica i dati visualizzati.

    • Se il widget specifica un valore per un'etichetta, il filtro a livello di dashboard non modifica i dati visualizzati.

      Ad esempio, se aggiungi un filtro all'etichetta instance_id, ma un grafico nella dashboard include un filtro basato sull'etichetta instance_id, il filtro a livello di dashboard non modifica i dati visualizzati.

    • In caso contrario, il grafico filtra i dati visualizzati solo per le serie temporali che soddisfano il filtro a livello di dashboard.

  • Per i widget del riquadro dei log, i filtri a livello di dashboard basati su un'etichetta della risorsa aggiornano la query. Ad esempio, se aggiungi il filtro a livello di dashboard cluster_name: mycluster, la query viene aggiornata in modo da includere resource.labels."cluster_name"="mycluster".

Puoi aggiungere più filtri a livello di dashboard. Questi filtri sono uniti dall'operatore logico AND.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per aggiungere o modificare i filtri permanenti utilizzando la console Google Cloud, chiedi all'amministratore di concederti il ruolo IAM Editor Monitoring (roles/monitoring.editor) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per ulteriori informazioni sui ruoli, consulta Controllare l'accesso con Identity and Access Management.

Crea un filtro permanente

Quando progetti una dashboard, potresti identificare diversi modi per visualizzare i dati visualizzati. Ad esempio, quando una dashboard mostra le metriche per le istanze VM, potresti voler visualizzare le metriche per tutte le VM e visualizzare le metriche per le VM in una zona specifica. Potresti creare un filtro permanente per l'etichetta zone con l'impostazione predefinita impostata su Tutte le zone, *. Quando visualizzi la dashboard, puoi usare il menu sul filtro zone per selezionare una zona specifica.

Puoi limitare un filtro permanente a widget specifici. Considera uno scenario in cui desideri una visualizzazione affiancata delle metriche per le VM in due zone diverse. Crei due raccolte di grafici e crei un filtro per ciascuna. La configurazione predefinita soddisfa l'obiettivo originale. Tuttavia, quando visualizzi la dashboard, la barra degli strumenti elenca le variabili e include menu per consentire di selezionare valori diversi. Puoi utilizzare questi menu per visualizzare i dati relativi a zone diverse.

I filtri permanenti che si applicano solo a widget specifici sono a volte chiamati variabili modello. Dopo aver creato un filtro di questo tipo, quando aggiungi un widget alla dashboard, puoi applicarlo anche a quel widget. Per maggiori informazioni, consulta Applicare un filtro permanente a un widget.

Per creare un filtro permanente:

  1. Nella console Google Cloud, vai alla pagina Dashboard :

    Vai a Dashboard

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Nella barra degli strumenti della dashboard, fai clic su Impostazioni, poi seleziona Gestisci filtri.
  3. Fai clic su Etichetta, quindi seleziona un'etichetta. Ad esempio, puoi selezionare zone.

  4. Fai clic su Valore predefinito, quindi seleziona il valore predefinito per l'etichetta. Per trovare una corrispondenza con tutti i valori, seleziona *.

    Una volta creato, il filtro viene aggiunto alla barra degli strumenti della dashboard. Per modificare temporaneamente il valore del filtro, seleziona il filtro, quindi fai una selezione dal menu.

  5. Esegui una di queste operazioni:

    • Per applicare il filtro a tutti i widget nella dashboard, seleziona Applica a tutti, quindi seleziona Applica.

    • Per applicare il filtro ad alcuni widget della dashboard:

      1. Deseleziona Applica a tutti.
      2. Nel campo Nome variabile, inserisci un nome visualizzato per la variabile.

      3. Espandi il menu Applica ai grafici, seleziona i widget a cui si applica il filtro, poi seleziona OK.

      4. Fai clic su Applica.

Applicare un filtro permanente a un widget

Per applicare un filtro permanente a un widget, devi associarlo alla variabile:

  • Per i grafici configurati mediante i menu, puoi eseguire questa associazione durante la creazione o la modifica del filtro.

  • Per il riquadro dei log, modifica il widget e configura la query predefinita. Segui le indicazioni nella sezione Sintassi per applicare un filtro permanente.

  • Per i grafici e le tabelle definiti in MQL o PromQL, modifica il grafico o la tabella, quindi modifica MQL o PromQL. Assicurati di seguire le indicazioni nella sezione Sintassi per applicare un filtro permanente.

Sintassi per applicare un filtro permanente

Ad esempio, di seguito viene mostrata la rappresentazione JSON parziale di una dashboard che definisce una variabile di modello e un filtro a livello di dashboard:

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

Nel file JSON visualizzato, la prima voce della struttura dashboardFilters è per una variabile di modello con il nome iid e un filtro a livello di dashboard con la chiave di etichetta zone. La variabile del modello è un alias dell'etichetta instance_id.

La struttura dei dati per una variabile di modello non elenca i widget a cui si applica. Puoi invece associare un widget a una variabile del modello modificando la query del widget in modo da includere un riferimento alla variabile. Quando il widget viene visualizzato nella dashboard, il valore della variabile del modello viene risolto.

Per informazioni su come annotare i riquadri e i grafici dei log, consulta le sezioni seguenti:

Riquadro dei log

Per configurare un riquadro dei log per filtrare la visualizzazione in base al valore di una variabile di modello, aggiungi la variabile al riquadro delle query. L'esempio seguente illustra una query che filtra in base al valore della variabile del modello iid:

${iid}

Prima che il riquadro dei log esegua una query per visualizzare i log, la variabile del modello viene risolta. In questo esempio, se il valore della variabile del modello è "12345", ${iid} viene sostituito con l'istruzione resource.labels."instance_id"="12345".

In una query puoi anche includere solo il valore di una variabile del modello. Ti consigliamo di utilizzare il valore solo come parte di un filtro definito con un'espressione regolare. Ad esempio, la seguente query utilizza un'espressione regolare per trovare corrispondenze con le voci di log che hanno un payload JSON contenente la stringa descritta:

jsonPayload.message=~"Connected to instance: ${iid.value}"

Se hai configurato una query per il riquadro dei log e poi selezioni il pulsante per aprire Esplora log, le variabili del modello vengono risolte prima dell'apertura di Esplora log.

La seguente tabella mostra come viene risolta la variabile del modello dal riquadro dei log:

Sintassi Valore
selezionato		 Espressione del riquadro dei log risolti
${iid} 12345 resource.labels."instance_id"="12345"
${iid} * ""
${iid.value} 12345 12345
${iid.value} * .*

Grafici e tabelle definiti da MQL

Quando utilizzi Monitoring Query Language (MQL) per configurare un grafico, aggiungi una barra verticale e la variabile alla stringa di query:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${iid}

Prima che il grafico esegua le query sulle serie temporali da visualizzare, la variabile del modello è risolta. In questo esempio, se il valore della variabile del modello è "12345", ${iid} viene sostituito con l'istruzione filter (resource.instance_id == '12345'). Questo filtro associa le serie temporali con un'etichetta denominata resource.instance_id e solo quando il valore di quell'etichetta è esattamente 12345.

Quando vuoi filtrare le serie temporali utilizzando un'espressione regolare, configura la query in modo da includere solo il valore della variabile del modello. Per illustrare la sintassi, di seguito viene mostrato come utilizzare un'espressione regolare per determinare se il valore dell'etichetta resource.instance_id contiene il valore della variabile del modello iid:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~"${iid.value}"
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

La tabella seguente mostra come viene risolta la variabile del modello per le query MQL:

Sintassi Valore
selezionato		 Espressione MQL risolta
${iid} 12345 filter (resource.instance_id == '12345')
${iid} * filter (true)
${iid.value} 12345 12345
${iid.value} * .*

Grafici e tabelle definiti da PromQL

Quando definisci un grafico utilizzando PromQL, aggiungi alla stringa di query la variabile racchiusa tra parentesi graffe:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Prima che il grafico esegua le query sulle serie temporali da visualizzare, la variabile del modello è risolta. In questo esempio, se il valore della variabile del modello è "12345", ${iid} viene sostituito con l'istruzione instance_id == '12345'.

In modo simile a MQL, quando definisci un widget con PromQL, la query può estrarre solo il valore della variabile del modello. Ti consigliamo di utilizzare il valore solo come parte di un filtro definito con un'espressione regolare. Per illustrare la sintassi, di seguito viene illustrato come utilizzare un'espressione regolare per determinare se il valore dell'etichetta instance_id contiene il valore della variabile del modello iid:

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${iid.value}"
}

La tabella seguente mostra come viene risolta la variabile del modello per le query PromQL:

Sintassi Valore
selezionato		 Espressione PromQL risolta
${iid} 12345 instance_id == '12345'
${iid} * noop_filter=~".*"
${iid.value} 12345 12345
${iid.value} * .+

Grafici e tabelle definiti con filtri delle serie temporali

Quando definisci un grafico utilizzando i filtri delle serie temporali, aggiungi la variabile alla stringa del filtro:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

A differenza dei grafici definiti in MQL e PromQL, non puoi utilizzare il valore di una variabile di modello in un filtro delle serie temporali.

La tabella seguente mostra come viene risolta la variabile del modello:

Sintassi Valore
selezionato		 Espressione di filtro risolta
${iid} 12345 resource.instance_id == "12345"
${iid} * Omessa
${iid.value} 12345 Funzionalità non supportata
${iid.value} * Funzionalità non supportata

Modificare un filtro permanente

Per modificare temporaneamente il valore di un filtro visualizzato sulla barra degli strumenti della dashboard, fai clic sul nome del filtro e inserisci un valore o effettua una selezione dal menu.

Per modificare la configurazione di un filtro permanente:

  1. Nella console Google Cloud, vai alla pagina Dashboard :

    Vai a Dashboard

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Nella barra degli strumenti della dashboard, fai clic su Impostazioni, poi seleziona Gestisci filtri.
  3. Trova il filtro da modificare, quindi utilizza i menu per apportare le modifiche.
  4. Fai clic su Applica.

Eliminare un filtro permanente

  1. Nella console Google Cloud, vai alla pagina Dashboard :

    Vai a Dashboard

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Nella barra degli strumenti della dashboard, fai clic su Impostazioni, poi seleziona Gestisci filtri.
  3. Trova il filtro da rimuovere e fai clic su Elimina.
  4. Fai clic su Applica.

Passaggi successivi