Creare e gestire variabili e filtri bloccati

Questo documento descrive come bloccare i filtri a livello di dashboard in modo che questi filtri siano permanenti. I filtri bloccati, che consentono di modificare i dati visualizzati da una dashboard senza dover modificare ogni widget, hanno uno stato predefinito e vengono applicati all'intera dashboard. La barra degli strumenti della dashboard mostra ogni filtro bloccato, insieme a un menu che consente di modificare temporaneamente il valore del filtro.

Le variabili sono simili ai filtri bloccati, ma si applicano solo a widget specifici. Questo documento descrive come creare variabili e come applicarle con un widget. Una variabile può modificare la query del widget o può controllarne la visibilità. La barra degli strumenti della dashboard mostra ogni variabile per nome, insieme a un menu che consente di modificare temporaneamente il valore della variabile. Per aiutarti a distinguere i filtri dalle variabili, nella barra degli strumenti, il nome di una variabile è preceduto dal simbolo del dollaro $.

Questo documento descrive come utilizzare la console Google Cloud per creare variabili e filtri bloccati. Per informazioni sull'utilizzo dell'API Cloud Monitoring, consulta Crea e gestisci le dashboard tramite API: filtri della dashboard.

Per informazioni su come aggiungere e modificare raggruppamenti e filtri temporanei, che si applicano solo alla sessione corrente, vedi Aggiungere filtri temporanei a una dashboard personalizzata.

Questa funzionalità è supportata solo per i progetti Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.

Informazioni sui filtri bloccati

Un filtro bloccato contiene un'etichetta, uno o più valori predefiniti e un elenco di tutti i valori possibili. L'elenco di tutti i valori possibili viene derivato dinamicamente dai dati delle serie temporali visualizzati nella dashboard. Per informazioni sulla struttura di un filtro, vedi DashboardFilter.

Non applichi un filtro bloccato ai singoli widget. Vengono invece utilizzate le seguenti regole per determinare se il filtro bloccato può modificare i dati visualizzati dal widget:

• Se il widget mostra dati che includono la chiave di etichetta specificata da un filtro bloccato e se il widget non specifica un valore per quella chiave di etichetta, il filtro bloccato può modificare i dati visualizzati.

  Ad esempio, supponiamo che tu aggiunga il filtro bloccato cluster_name: mycluster. I grafici mostrano automaticamente solo le serie temporali che hanno un'etichetta cluster_name con il valore mycluster. Allo stesso modo, le query sui widget del pannello dei log vengono modificate in resource.labels."cluster_name"="mycluster" e i grafici mostrano automaticamente solo le serie temporali che includono l'etichetta nel filtro bloccato.

• Un filtro bloccato viene ignorato da un widget quando il widget include un filtro per la stessa chiave dell'etichetta o quando i dati visualizzati dal widget non contengono la chiave dell'etichetta specificata nel filtro bloccato.

Informazioni sulle variabili

Una variabile ha un nome e un tipo. Una variabile viene applicata a un determinato widget modificando la query contenuta nel widget. Per informazioni sulla struttura di un filtro, vedi DashboardFilter.

Nella barra degli strumenti della dashboard, i nomi delle variabili sono preceduti dal simbolo del dollaro $. Se vedi anche l'icona visibility Visibile, la variabile controlla la visibilità di almeno un widget.

Le variabili possono essere basate su etichette o avere solo un valore:

• Le variabili basate su etichette sono come filtri bloccati. Queste variabili contengono una chiave di etichetta, uno o più valori di etichetta predefiniti e un elenco di tutti i valori di etichetta possibili. L'elenco di tutti i valori possibili viene derivato dinamicamente dai dati delle serie temporali visualizzati nella dashboard.

• Le variabili solo valore contengono uno o più valori predefiniti e potrebbero elencare tutti i valori possibili. Se non specifichi un valore predefinito, viene selezionato l'operatore jolly (*) per il valore predefinito. Per definire l'insieme di tutti i valori possibili, fornisci una matrice di valori o scrivi una query SQL.

  Esistono tre tipi di variabili di solo valore: personalizzata, input di testo e query SQL.

  • Personalizzato: da utilizzare quando vuoi enumerare sia l'elenco di tutti i valori possibili sia impostare uno o più valori predefiniti. Ad esempio, puoi impostare l'elenco di tutti i valori possibili su prod, staging, dev e impostare il valore predefinito su prod.

  • Input di testo: da utilizzare quando non si conoscono tutti i valori possibili. Ad esempio, potresti voler filtrare per URL, ma quando crei la variabile, non conosci l'elenco esatto degli URL. Poi, quando utilizzi il menu dei filtri per il widget, puoi inserire nuovi URL e salvare le modifiche per la sessione corrente o nella definizione della variabile.

  • Query SQL: utilizza questa opzione quando vuoi generare l'elenco dei valori possibili utilizzando una query SQL. Queste variabili sono destinate a essere applicate ai grafici creati utilizzando l'analisi dei log.

    Per queste variabili, assicurati che il risultato della query sia una tabella con una colonna, che il tipo di dati di questa colonna sia stringa e che ogni riga della tabella contenga un valore stringa univoco:

    SELECT log_name
    FROM `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    La query SQL non può dipendere da una variabile.

Per applicare una variabile a un widget, aggiorna la query emessa dal widget o la visibilità del widget. Puoi sempre modificare il widget per aggiornare la query. Tuttavia, per le variabili basate su etichette e alcuni tipi di widget, puoi aggiornare la query effettuando selezioni di menu. Per controllare la visibilità, devi modificare il widget. Per saperne di più, consulta le seguenti sezioni di questo documento:

• Aggiornare la query di un widget
• Impostare la visibilità di un widget

Prima di iniziare

Completa i seguenti passaggi per il Google Cloud progetto in cui vuoi configurare filtri e variabili:

• Per ottenere le autorizzazioni necessarie per aggiungere o modificare variabili o filtri bloccati utilizzando la console Google Cloud , chiedi all'amministratore di concederti il ruolo IAM Editor Monitoring (roles/monitoring.editor) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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

  Per saperne di più sui ruoli, consulta Controllare l'accesso con Identity and Access Management.

Creare e bloccare un filtro

Per creare e bloccare un filtro che si applica a tutti i widget della dashboard che supportano i filtri:

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 console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
3. Seleziona una dashboard, vai alla barra degli strumenti della dashboard e poi fai clic su settings Impostazioni.
4. Nella sezione Filtri, fai clic su Aggiungi un filtro.
5. Fai clic su arrow_drop_down Etichetta e poi seleziona un'etichetta. Ad esempio, potresti selezionare zone.
6. Per consentire a un utente di selezionare più valori dal menu dei valori della variabile, seleziona Selezione multipla. Quando l'opzione Selezione multipla non è attivata, gli utenti possono selezionare una sola opzione dal menu dei valori.

7. Fai clic su arrow_drop_down Valore predefinito e poi seleziona il valore o i valori predefiniti per l'etichetta. Per trovare la corrispondenza di 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 e poi effettua una selezione dal menu.

8. Fai clic su Fine, quindi su Applica.

9. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

Creare una variabile

Per creare una variabile che si applichi a widget specifici della dashboard:

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 console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
3. Seleziona una dashboard, vai alla barra degli strumenti della dashboard e poi fai clic su settings Impostazioni.
4. Nella sezione Variabili, fai clic su Aggiungi una variabile.

5. Seleziona il tipo di variabile e poi completa la finestra di dialogo.

   Per creare una variabile basata su un'etichetta, seleziona Etichetta. Utilizza questa opzione quando vuoi una variabile con una chiave e un valore di etichetta e che possa essere utilizzata come filtro. L'elenco di tutti i valori possibili viene derivato dinamicamente dai dati delle serie temporali visualizzati nella dashboard. Il menu Applica ai grafici consente di selezionare i widget la cui query deve essere modificata dalla variabile. Puoi anche aggiornare la query modificando il widget.

   Per le variabili solo valore, hai le seguenti opzioni:

   • SQL: utilizza questa opzione quando vuoi che i risultati di una query SQL generino l'elenco di tutti i valori possibili.

     Inserisci uno o più valori predefiniti e una query SQL che generi l'elenco di tutti i valori possibili. Assicurati che il risultato della query sia una tabella con una colonna, che il tipo di dati di questa colonna sia stringa e che ogni riga della tabella contenga un valore stringa univoco.

   • Personalizzato: utilizza questa opzione quando vuoi specificare sia l'elenco dei valori possibili sia un valore predefinito. Ad esempio, puoi impostare il campo Valori su prod, staging, dev e il Valore predefinito su prod.

   • Input di testo: utilizza questa opzione quando vuoi specificare un elenco di valori che vengono applicati come predefiniti.

6. Fai clic su Fine, quindi su Applica.

7. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

8. Applica la variabile ai widget. Se aggiorni la query di un widget, quando modifichi il valore della variabile, la query viene modificata e i dati visualizzati dal widget vengono modificati. Puoi anche utilizzare una variabile per controllare se un widget è visibile. Per ulteriori informazioni, consulta le seguenti sezioni di questo documento:

   • Impostare la visibilità di un widget
   • Aggiornare la query di un widget

Impostare la visibilità di un widget

Quando un widget esegue una query sui dati, puoi utilizzare una variabile per controllare se il widget è visibile in una dashboard. Ad esempio, supponiamo che un dashboard contenga widget che mostrano i dati per i tuoi sistemi di produzione e un altro insieme di widget che mostrano i dati per i tuoi sistemi di staging. Durante il debug durante lo sviluppo, potresti voler visualizzare solo i dati di staging. Configurando la visibilità dei widget della dashboard con una variabile, puoi passare dai soli dati di produzione ai soli dati di staging e a tutti i dati.

Qualsiasi tipo di variabile può controllare se un widget è visibile o nascosto.

Per configurare la visibilità di un widget:

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. Seleziona una dashboard.
3. Vai alla barra degli strumenti del widget di cui vuoi configurare la visibilità e fai clic su edit Modifica.
4. Nel riquadro Display, espandi Visibilità widget.

5. Seleziona una variabile e completa la finestra di dialogo.

6. Fai clic su Fine, quindi su Applica.

7. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

   La dashboard viene aggiornata. Quando almeno un widget della dashboard è nascosto a causa dei controlli di visibilità, la dashboard mostra un banner. Per visualizzare tutti i widget, fai clic su Mostra tutti i widget.

Quando utilizzi una variabile per controllare la visibilità di almeno un widget nella dashboard, nella barra degli strumenti il nome della variabile è annotato con un'icona visibility Visibile.

Limitazioni

Quando configuri la visibilità di un widget, si applicano le seguenti limitazioni:

• I widget organizzativi come gruppo comprimibile, intestazione di sezione e visualizzazione singola sono sempre visibili.

• Puoi eliminare una variabile a cui fanno riferimento i controlli di visibilità di un widget. L'azione di eliminazione della variabile rimuove anche qualsiasi riferimento alla variabile.

• Non tutte le dashboard supportano la creazione di variabili. Tuttavia, se una dashboard contiene variabili, puoi utilizzarle per gestire la visibilità dei widget nella dashboard.

Aggiornare la query di un widget

Questa sezione descrive come includere variabili nella query emessa dal widget. Di conseguenza, quando modifichi il valore della variabile, la query viene modificata e anche i dati visualizzati dal widget vengono modificati:

• Per i grafici che utilizzano query SQL o PromQL e per i widget del pannello dei log, devi modificare il widget e la query. Questa sezione descrive come apportare queste modifiche.

• Per i grafici che hai configurato utilizzando i menu o la modalità di filtro diretto, Monitoring modifica la query quando selezioni il widget utilizzando il menu Applica ai grafici. In alternativa, puoi modificare il widget, andare al campo Filtro e selezionare la variabile.

Per scoprire come aggiornare la query di un widget con una variabile basata su etichetta o una variabile solo con valori, consulta le seguenti sezioni:

• Sintassi generale per dereferenziare una variabile
• Widget del pannello dei log
• Grafici con query PromQL
• Grafici con query SQL

• Grafici con query di filtro di Monitoring

  Quando utilizzi l'interfaccia basata su menu per creare un grafico che mostri dati delle serie temporali, le tue selezioni vengono convertite in un filtro di Monitoring.

Creare filtri e variabili

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

Sintassi generale per dereferenziare una variabile

Per tutti i widget, ad eccezione di quelli definiti da SQL, utilizza la seguente sintassi per applicare una variabile a una query:

• Per applicare una variabile basata su etichette e risolvere la chiave e il valore dell'etichetta in un'espressione di filtro valida per il linguaggio di query, utilizza ${my_label_based_variable}.

• Per applicare solo il valore di una variabile basata su etichette, utilizza ${my_label_based_variable.value}. Il confronto deve utilizzare un'espressione regolare.

• Per applicare solo il valore di una variabile solo valore, utilizza ${my_value_only_variable}. Per le variabili di solo valore, non includere una clausola .value. Il confronto deve utilizzare un'espressione regolare.

Widget del riquadro dei log

Per applicare una variabile a un widget del pannello dei log, aggiorna il riquadro delle query. La sintassi di questi widget segue quella specificata in Sintassi generale.

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

severity =~ "${value_only_severity_variable}"

severity =~ "^(ERROR|INFO|NOTICE)$"

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

severity =~ "^(ERROR|INFO|NOTICE)$"

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

La tabella seguente mostra come vengono risolte le variabili di esempio nel riquadro dei log. Come accennato in precedenza, quando viene utilizzato solo il valore di una variabile, devi utilizzare un'espressione regolare come operatore di confronto:

Grafici con query PromQL

Per aggiornare un grafico con una query PromQL in modo che dipenda da una variabile basata su etichette, segui le indicazioni riportate in Sintassi generale.

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

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

zone=~"${my_value_only_variable}"

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

zone=~\"${my_value_only_variable}\"

La seguente tabella mostra come vengono risolte le variabili di esempio da PromQL. Come accennato in precedenza, quando viene utilizzato solo il valore di una variabile, devi utilizzare un'espressione regolare come operatore di confronto:

Grafici con query SQL

Quando vuoi aggiornare un widget definito da SQL in modo che dipenda da una variabile, aggiorna la clausola WHERE in modo che faccia riferimento al valore della variabile. Per tutte le variabili, aggiungi il prefisso "@" al nome della variabile, ad esempio: @variable_name. Per le variabili basate sulle etichette, aggiungi .value al nome della variabile, @my_label_based_variabe.value.

Per le query SQL, la sostituzione delle variabili si basa su BigQuery ed è sicura contro l'SQL injection. Per ulteriori informazioni, consulta la sezione Esecuzione di query parametrizzate.

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Grafici con query di filtri di monitoraggio

Per aggiornare un grafico con una query sotto forma di filtro di monitoraggio in modo che dipenda da una variabile basata su etichette, segui le indicazioni riportate in Sintassi generale.

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

La seguente tabella mostra come le variabili di esempio vengono risolte dal filtro Monitoring. Come accennato in precedenza, quando viene utilizzato solo il valore di una variabile, devi utilizzare un'espressione regolare come operatore di confronto:

Modificare un filtro o una variabile bloccati

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

Se la dashboard contiene una tabella che mostra dati delle serie temporali, puoi aggiungere filtri temporanei o modificare filtri e variabili permanenti utilizzando il pulsante Filtra dashboard in base a questo valore filter_list di una cella. Se selezionato, questo pulsante applica un nuovo filtro temporaneo o aggiorna il valore di un filtro o di una variabile esistente. I filtri e le variabili esistenti vengono aggiornati quando la chiave dell'etichetta per la colonna della tabella corrisponde alla chiave dell'etichetta per un filtro o una variabile.

Per modificare la configurazione di un filtro bloccato o di una variabile:

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 console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
3. Nella barra degli strumenti della dashboard, fai clic su settings Impostazioni.
4. Trova il filtro o la variabile che vuoi modificare ed espandi la relativa definizione.
5. Dopo aver completato le modifiche, fai clic su Applica.
6. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

Eliminare un filtro o una variabile bloccati

Per eliminare un filtro o una variabile bloccati:

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 console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
3. Nella barra degli strumenti della dashboard, fai clic su settings Impostazioni.
4. Individua il filtro o la variabile che vuoi rimuovere, quindi fai clic su delete Elimina.
5. Fai clic su Applica.
6. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

Passaggi successivi

• Esplorare i dati dei grafici
• Accedere alle dashboard specifiche per le risorse