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 da 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 ogni filtro permanente, insieme a un menu che consente di modificare temporaneamente il valore del filtro.

Se vuoi definire una presentazione predefinita dei dati su una dashboard insieme a opzioni basate su menu per modificare questa visualizzazione, aggiungi filtri permanenti. Ad esempio, se vuoi visualizzare le metriche per tutte le zone e anche le metriche 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 dashboard per 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 della 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, ad esempio grafici a linee, si applicano le seguenti regole:

    • Se la serie temporale visualizzata dal widget non supporta l'etichetta in un filtro, il filtro a livello di dashboard non modifica i dati visualizzati.

      Ad esempio, se aggiungi un filtro sull'etichetta instance_id, ma un grafico nella dashboard non mostra 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 sull'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 di 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 con un AND logico.

Prima di iniziare

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

Potresti anche essere in grado di 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 le metriche per le VM in una zona specifica. Potresti creare un filtro permanente per l'etichetta zone con l'impostazione predefinita su tutte le zone, *. Nella dashboard, puoi usare il menu del filtro zone per selezionare una zona specifica.

Puoi limitare un filtro permanente a widget specifici. Considera uno scenario in cui vuoi una visualizzazione affiancata delle metriche delle VM in due zone diverse. Crea due raccolte di grafici e crea un filtro per ogni raccolta. La configurazione predefinita soddisfa il tuo obiettivo originale. Tuttavia, quando visualizzi la dashboard, la barra degli strumenti elenca le variabili e include menu che ti consentono di selezionare valori diversi. È possibile utilizzare questi menu per visualizzare i dati relativi a zone diverse.

I filtri permanenti che si applicano solo a widget specifici sono talvolta denominati variabili modello. Dopo aver creato un filtro di questo tipo, quando aggiungi un widget alla dashboard, puoi applicarlo anche al widget. Per scoprire di più, consulta la pagina 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 il cui sottotitolo è Monitoring.

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

  4. Fai clic su Valore predefinito, quindi seleziona il valore predefinito per l'etichetta. Per trovare la 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, fai clic sul filtro ed effettua una selezione dal menu.

  5. Esegui una di queste operazioni:

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

    • Per applicare il filtro ad alcuni widget nella dashboard:

      1. Deseleziona Applica a tutti.
      2. Nella casella di testo 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 e seleziona OK.

      4. Fai clic su Applica.

Applica un filtro permanente a un widget

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

  • Per i grafici configurati utilizzando 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. Assicurati di seguire le indicazioni nella sezione Sintassi per applicare un filtro permanente.

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

Sintassi per applicare un filtro permanente

Ad esempio, quanto segue mostra 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 JSON visualizzato, la prima voce nella struttura dashboardFilters riguarda 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 viene applicata. Per associare un widget a una variabile di modello, modifica 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.

Consulta le seguenti sezioni su come annotare i riquadri e i grafici dei log:

Riquadro dei log

Per configurare un riquadro dei log in modo da filtrare la visualizzazione in base al valore di una variabile del 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 la query sui log da visualizzare, la variabile del modello viene risolta. In questo esempio, se il valore della variabile di modello è "12345", ${iid} viene sostituito con l'istruzione resource.labels."instance_id"="12345".

Inoltre, puoi includere in una query solo il valore di una variabile di 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 associare le voci di log con 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 in che modo la variabile del modello viene risolta 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 la query per la serie temporale, la variabile del modello viene risolta. In questo esempio, se il valore della variabile di modello è "12345", ${iid} viene sostituito con l'istruzione filter (resource.instance_id == '12345'). Questo filtro corrisponde alle serie temporali che hanno un'etichetta denominata resource.instance_id e solo quando il valore di questa etichetta è esattamente 12345.

Se 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, quanto segue mostra 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 seguente tabella mostra come viene risolta la variabile di 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 la query per la serie temporale, la variabile del modello viene risolta. In questo esempio, se il valore della variabile di modello è "12345", ${iid} viene sostituito con l'istruzione instance_id == '12345'.

Analogamente 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 nell'ambito di un filtro definito con un'espressione regolare. Per illustrare la sintassi, quanto segue mostra come utilizzare un'espressione regolare per determinare se il valore dell'etichetta instance_id contiene il valore della variabile modello iid:

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

La seguente tabella mostra come viene risolta la variabile di 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 di filtro:

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

A differenza dei grafici definiti da 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 qualsiasi filtro visualizzato nella 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 il cui sottotitolo è Monitoring.

  2. Nella barra degli strumenti della dashboard, fai clic su Impostazioni e seleziona Gestisci filtri.
  3. Individua il filtro da modificare e 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 il cui sottotitolo è Monitoring.

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

Passaggi successivi