Creare e gestire variabili e filtri bloccati

I filtri e le variabili bloccati in una dashboard personalizzata in Cloud Monitoring ti consentono di modificare dinamicamente i dati visualizzati nella dashboard dalla barra degli strumenti senza modificare i singoli widget. I filtri bloccati si applicano a tutti i widget che supportano l'etichetta del filtro, mentre le variabili si applicano a widget specifici per modificarne le query o controllarne la visibilità.

Questo documento descrive come configurare filtri e variabili bloccati nella consoleGoogle Cloud . Per configurarle utilizzando l'API Cloud Monitoring, consulta Crea e gestisci le dashboard tramite API: filtri della dashboard. Per applicare filtri o raggruppamenti solo alla sessione corrente, consulta Aggiungi filtri temporanei a una dashboard personalizzata.

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 ricavato dinamicamente dai dati delle serie temporali visualizzati nella dashboard.

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 visualizza dati che includono la chiave etichetta specificata da un filtro bloccato e se il widget non specifica un valore per quella chiave 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 un valore mycluster. Analogamente, le query sui widget del riquadro dei log vengono modificate in resource.labels."cluster_name"="mycluster" e i grafici visualizzano automaticamente solo le serie temporali che includono l'etichetta nel filtro bloccato.

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

Nell'API, i filtri bloccati sono definiti dalla struttura DashboardFilter. Ad esempio, la seguente struttura definisce un filtro bloccato. Le serie temporali con un'etichetta zone il cui valore è us-central1-c corrispondono al filtro bloccato.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL"
},

Informazioni sulle variabili

Analogamente ai filtri bloccati, una variabile ha un nome, un tipo e uno o più valori predefiniti. Tuttavia, a differenza dei filtri bloccati, che sono sempre basati su etichette, le variabili non devono dipendere dalle etichette.

Una variabile viene applicata a un determinato widget modificando la query contenuta nel widget.

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

Le variabili definite dall'utente 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 possibili valori di etichetta. L'elenco di tutti i valori possibili viene ricavato dinamicamente dai dati delle serie temporali visualizzati nella dashboard.

  • Le variabili di solo valore contengono uno o più valori predefiniti e potrebbero elencare tutti i valori possibili. Se non specifichi un valore predefinito, come valore predefinito viene selezionato l'operatore con caratteri jolly (*). Per definire l'insieme di tutti i valori possibili, puoi fornire un array di valori o scrivere una query SQL.

    Esistono tre tipi di variabili di solo valore: Personalizzata, Input di testo e Query SQL.

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

    • Inserimento di testo: utilizza questa opzione se non conosci tutti i valori possibili. Quando crei questa variabile, puoi specificare uno o più valori. Tuttavia, l'opzione di menu ti consente di aggiungere nuovi valori che si applicano alla sessione corrente.

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

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

      SELECT log_name
FROM `VIEW`
GROUP BY log_name

      La query SQL non può dipendere da una variabile.

Esiste una variabile definita dal sistema, @__project_id. Puoi utilizzare questa variabile solo nella clausola FROM per le query SQL. Per scoprire come applicare questa variabile a una query, consulta Grafici con query SQL.

Per applicare una variabile a un widget, aggiorna la query inviata 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 nei menu. Per controllare la visibilità, devi modificare il widget. Per saperne di più, consulta le seguenti sezioni di questo documento:

Nell'API, le variabili sono definite dalla struttura DashboardFilter. Ad esempio, la seguente struttura definisce la variabile my_zone_variable che opera sull'etichetta della risorsa zone. Le serie temporali che hanno un'etichetta zone con valore us-central1-c corrispondono alla variabile.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "templateVariable": "my_zone_variable",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL",
},

Prima di iniziare

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

Crea e fissa un filtro

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

  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 o il progetto di gestione di App Hub.
  3. Seleziona una dashboard, vai alla barra degli strumenti della dashboard e poi fai clic su Impostazioni.
  4. Nella sezione Filtri, fai clic su Aggiungi un filtro.
  5. Fai clic su Etichetta e poi seleziona un'etichetta. Ad esempio, potresti selezionare zone.
  6. Per consentire agli utenti di selezionare più valori dal menu dei valori del filtro, seleziona Selezione multipla. Quando l'opzione Selezione multipla non è attiva, gli utenti possono selezionare una sola opzione dal menu dei valori.

  7. Fai clic su Valore predefinito e poi seleziona il valore o i valori predefiniti per l'etichetta. Per trovare una corrispondenza con tutti i valori, seleziona *.

    Dopo aver creato il filtro, questo viene aggiunto alla barra degli strumenti della dashboard. Per modificare temporaneamente il valore del filtro, seleziona il filtro, quindi effettua una selezione dal menu.

  8. Fai clic su Fine e poi su Applica.

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

Crea una variabile

Per creare una variabile che si applica a widget della dashboard specifici, segui questi passaggi:

  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 o il progetto di gestione di App Hub.
  3. Seleziona una dashboard, vai alla barra degli strumenti della dashboard e poi fai clic su 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 etichetta, seleziona Etichetta. Utilizza questa opzione quando vuoi una variabile con una chiave e un valore di etichetta che possa essere utilizzata come un filtro bloccato. L'elenco di tutti i valori possibili viene ricavato 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 di solo valore, hai a disposizione le seguenti opzioni:

    • SQL: utilizza questa opzione se 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 genera 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 quella colonna sia una stringa e che ogni riga della tabella contenga un valore di stringa univoco.

    • Personalizzato: utilizza questa opzione se 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.

    • Inserimento di testo: utilizza questa opzione se vuoi specificare un elenco di valori applicati come predefiniti.

  6. Fai clic su Fine e poi su Applica.

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

    Monitoring aggiunge la variabile alla barra degli strumenti della dashboard. Il nome sulla barra degli strumenti è un simbolo del dollaro $ seguito dal nome della variabile. La barra degli strumenti contiene un menu che ti consente di modificare il valore della variabile.

  8. (Facoltativo) Sposta la variabile dalla barra degli strumenti della dashboard a un widget della dashboard.

    Puoi aggiungere alla dashboard un widget che ti consente di modificare il valore della variabile. Se apporti questa modifica, la variabile della barra degli strumenti viene rimossa. Tuttavia, puoi posizionare il widget che controlla la variabile accanto ai widget interessati. Per scoprire come apportare questa modifica, consulta Aggiungi un widget per gestire il valore di una variabile.

  9. 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 saperne di più, consulta le seguenti sezioni di questo documento:

Aggiungi un widget per gestire il valore di una variabile

Poiché le variabili si applicano a un sottoinsieme di widget della dashboard, potresti voler raggruppare il controllo della variabile e i widget a cui si applica. Ad esempio, puoi creare un gruppo comprimibile o una sezione nella dashboard per il menu delle variabili e i widget associati. Questa strategia semplifica anche la barra degli strumenti, rimuovendo le variabili che non si applicano a tutti i widget.

Per gestire il valore di una variabile utilizzando un widget della dashboard, segui questi passaggi:

  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 o il progetto di gestione di App Hub.
  3. Nella finestra di dialogo Aggiungi widget, vai alla sezione Layout e seleziona Variabile.

  4. Completa la finestra di dialogo e seleziona Salva.

    La dashboard mostra un widget che ti consente di selezionare il valore per la variabile. Puoi spostare questo widget in un gruppo comprimibile o riposizionarlo in altro modo.

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

Imposta la visibilità di un widget

Quando un widget esegue query sui dati, puoi utilizzare una variabile per controllare se il widget è visibile in una dashboard. Ad esempio, supponiamo che una dashboard contenga widget che mostrano i dati per i tuoi sistemi di produzione e un altro set di widget che mostrano i dati per i tuoi sistemi di gestione temporanea. Durante il debug in fase di sviluppo, potresti voler visualizzare solo i dati di gestione temporanea. Configurando la visibilità dei widget della dashboard con una variabile, puoi passare dalla visualizzazione dei soli dati di produzione, ai soli dati di gestione temporanea 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à, quindi fai clic su Modifica.
  4. Nel riquadro Visualizzazione, espandi Visibilità widget.

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

  6. Fai clic su Fine e poi 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 viene annotato con un'icona Visibile.

Limitazioni

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

  • I widget organizzativi, come i widget di 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 variable-delete 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.

Aggiorna la query di un widget

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

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

  • Per i grafici configurati 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 di solo valore, consulta le sezioni seguenti:

Crea filtri e variabili

Console

Per informazioni su come utilizzare la console Google Cloud per creare filtri e variabili bloccati, consulta i seguenti documenti:

REST

Per definire filtri e variabili bloccati, utilizza la struttura dei dati dashboardFilters.

  • Per creare una variabile, imposta il valore del campo templateVariable sul nome della variabile. Ometti questo campo o imposta il valore su una stringa vuota se vuoi creare un filtro bloccato.
  • Per creare un filtro bloccato o una variabile basata su etichette, devi specificare il campo labelKey. Ometti questo campo se vuoi una variabile di solo valore.

  • Imposta il valore predefinito per il filtro o la variabile. La configurazione di questo campo determina se un utente può selezionare esattamente un'opzione dal menu dei valori o se può selezionare più valori.

  • Per impostare un singolo valore predefinito e limitare gli utenti alla selezione di una sola opzione nel menu dei valori, imposta il campo valueType su STRING e imposta anche il campo stringValue:

    "valueType": "STRING",
"stringValue": "my-default-value",

  • Per impostare almeno un valore predefinito e consentire agli utenti di selezionare più opzioni nel menu dei valori, imposta il campo valueType su STRING_ARRAY e imposta anche il campo stringArrayValue. Nell'esempio seguente, sono presenti tre valori predefiniti.

    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • (Facoltativo) Per specificare l'elenco di tutti i valori possibili per una variabile di solo valore, imposta il campo stringArray o il campo timeSeriesQuery. Se specifichi una query, deve essere una query di analisi.

Ad esempio, considera il seguente oggetto dashboardFilters:

{
  "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",
  ...
}

Il JSON precedente definisce un filtro bloccato e due variabili:

  • Il filtro bloccato ha la chiave di etichetta zone, che viene visualizzata nella barra degli strumenti. I campi valueType e stringValue specificano il singolo valore predefinito. Per saperne di più, consulta la pagina dei riferimenti API per la struttura dei dati dashboardFilters.

  • La variabile basata su etichette ha il nome my_label_based_variable e la chiave di etichetta è instance_id. Il valore predefinito di questa variabile è impostato su un ID istanza specifico. Puoi anche configurare il valore predefinito utilizzando un array. Nella barra degli strumenti, il filtro viene visualizzato con il nome my_label_based_variable.

  • La variabile solo valore è denominata my_value_only_variable. Questa voce non specifica un valore predefinito, quindi l'operatore con caratteri jolly, (*), viene applicato automaticamente. Inoltre, questa variabile utilizza una query SQL per generare l'elenco dei possibili valori per la variabile.

Tieni presente che l'oggetto dashboardFilters non elenca i widget a cui si applica la variabile. Invece, aggiorni la query di un widget in modo che dipenda da una variabile.

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 fare in modo che la chiave e il valore dell'etichetta vengano risolti 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 di 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 riquadro dei log, aggiorna il riquadro delle query. La sintassi di questi widget segue quella specificata in Sintassi generale.

Console

Ad esempio, la seguente query utilizza un'espressione regolare per confrontare il valore del campo jsonPayload.message con un valore stringa che include il valore di una variabile basata su etichetta:

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

Come altro esempio, considera una variabile solo valore, value_only_severity_variable, e supponi che nel menu dei valori siano selezionati tre valori: ERROR, INFO e NOTICE. A questo punto, aggiungi quanto segue al riquadro delle query del widget del riquadro dei log:

severity =~ "${value_only_severity_variable}"

Di seguito è illustrato il modulo visualizzato:

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

REST

Ad esempio, il seguente JSON illustra come aggiornare la query di un widget del riquadro dei log con una variabile basata su etichette:

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

Ad esempio, la seguente query utilizza un'espressione regolare per confrontare il valore del campo jsonPayload.message con un valore stringa che include il valore di una variabile basata su etichetta:

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

Come altro esempio, considera una variabile solo valore, value_only_severity_variable, e supponi che nel menu siano selezionati tre valori: ERROR, INFO e NOTICE. A questo punto, aggiungi quanto segue al riquadro delle query del widget del riquadro dei log:

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

Di seguito è riportata la query eseguita dal widget del riquadro dei log:

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

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

La tabella seguente illustra come le variabili di esempio vengono risolte dal 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:

Sintassi Valore
selezionato		 Espressione del riquadro dei log risolta
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

La variabile di esempio si basa sull'etichetta della risorsa instance_id.
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

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.

Console

Ad esempio, la seguente query si basa sulla variabile basata su etichette, my_label_based_variable, che viene risolta in un'espressione di filtro:

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

Puoi anche modificare la query per risolvere solo il valore di una variabile. L'esempio seguente utilizza un'espressione regolare per confrontare il valore di una query basata su etichette con instance_id:

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

Se hai una variabile solo valore, ometti la clausola .value. Ad esempio, per filtrare in base alla zona utilizzando una variabile solo valore, la query includerebbe un elemento simile al seguente:

zone=~"${my_value_only_variable}"

REST

Ad esempio, il seguente JSON illustra una query che si basa sulla variabile basata su etichette, my_label_based_variable, che viene risolta in un'espressione di filtro:

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

Puoi anche modificare la query per risolvere solo il valore di una variabile. L'esempio seguente utilizza un'espressione regolare per confrontare il valore di una query basata su etichette con instance_id:

"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
},

Se hai una variabile solo valore, ometti la clausola .value. Ad esempio, per filtrare in base alla zona utilizzando una variabile solo valore, la query includerebbe un elemento simile al seguente:

zone=~\"${my_value_only_variable}\"

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

Sintassi Valore
selezionato		 Espressione PromQL risolta
${my_label_based_variable} 12345 instance_id == '12345'

La variabile di esempio si basa sull'etichetta della risorsa instance_id.
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

Grafici con query SQL

Puoi utilizzare le variabili in due punti delle query SQL:

  • La clausola FROM può dipendere dalla variabile definita dal sistema denominata @__project_id, che si risolve nel valore del progetto selezionato.

  • La clausola WHERE può dipendere da variabili definite dall'utente.

Aggiorna la clausola FROM in modo che dipenda da una variabile definita dal sistema

Se crei modelli di dashboard e questi modelli tracciano i risultati delle query SQL, sostituisci l'ID progetto nella query con la variabile @__project_id. Quando installi il template in un progetto, la variabile viene risolta automaticamente nell'ID progetto. Non è necessario modificare manualmente il widget e aggiornare la clausola FROM.

Di seguito è riportata una clausola FROM che dipende dalla variabile definita dal sistema:

FROM `@__project_id.global._Default._Default`

La clausola FROM non può dipendere da variabili definite dall'utente.

Aggiorna la clausola WHERE in modo che dipenda da una variabile definita dall'utente

Questa sezione descrive come aggiornare la clausola WHERE di un widget definito da SQL in modo che dipenda da una variabile definita dall'utente. Per tutte le variabili, aggiungi il prefisso "@" al nome della variabile, ad esempio: @variable_name. Per le variabili basate su 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 è protetta da SQL injection. Per saperne di più, consulta Esecuzione di query parametrizzate.

Console

Poiché SQL non interpreta l'operatore con caratteri jolly come "qualsiasi valore", ti consigliamo di utilizzare sempre un'istruzione IF quando utilizzi variabili in una query SQL. L'esempio seguente illustra l'utilizzo di una variabile di solo valore il cui tipo di dati è una stringa:

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

Quando l'opzione di menu per la variabile consente agli utenti di selezionare più valori, devi eseguire il cast del valore della variabile in un tipo di dati GoogleSQL utilizzando la funzione CAST. La seguente query illustra questa sintassi:

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

L'istruzione IF mostrata negli esempi precedenti è consigliata perché SQL non interpreta l'operatore con caratteri jolly come "qualsiasi valore". Pertanto, se ometti l'istruzione IF e selezioni l'operatore con caratteri jolly, il risultato della query è una tabella vuota. Nel secondo esempio, la funzione UNNEST converte l'array in una tabella.

Per aggiungere una clausola WHERE formattata correttamente:

  1. Modifica il widget.
  2. Nella barra degli strumenti, seleziona Inserisci filtro variabile, quindi seleziona la variabile di cui vuoi aggiornare la clausola WHERE.
  3. Nella finestra di dialogo che si apre, esamina il codice generato e poi fai clic su Copia e chiudi.

  4. Incolla il codice copiato nel riquadro Query e apporta le modifiche necessarie.

    Ad esempio, supponiamo di creare una variabile denominata LogName che genera un elenco di nomi di log e restituisce il risultato in una tabella con una singola colonna denominata log_name. Successivamente, crei un grafico, selezioni Inserisci filtro variabile e poi selezioni la variabile LogName. Viene generato il seguente codice:

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    In questo esempio, devi modificare il codice generato e sostituire LogName = con log_name =, in modo che l'unione delle tabelle possa avvenire:

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. Fai clic su Esegui e poi su Applica.

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

REST

Poiché SQL non interpreta l'operatore con caratteri jolly come "qualsiasi valore", ti consigliamo di utilizzare sempre un'istruzione IF quando utilizzi variabili in una query SQL. L'esempio seguente illustra l'utilizzo di una variabile di solo valore il cui tipo di dati è una stringa:

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

Ad esempio, di seguito è riportata una rappresentazione JSON parziale di un grafico che mostra i risultati di una query SQL. Per supportare il filtro dei risultati in base al nome di un log, è stata aggiunta una clausola WHERE che fa riferimento alla variabile denominata LogName:

"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"
  }
}

La variabile LogName invia anche una query per determinare l'elenco dei possibili nomi dei log:

"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
    }
  }
],

Quando l'opzione di menu per la variabile consente agli utenti di selezionare più valori, devi eseguire il cast del valore della variabile in un tipo di dati GoogleSQL utilizzando la funzione CAST. La seguente query illustra questa sintassi:

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

L'istruzione IF mostrata negli esempi precedenti è consigliata perché SQL non interpreta l'operatore con caratteri jolly come "qualsiasi valore". Pertanto, se ometti l'istruzione IF e selezioni l'operatore con caratteri jolly, il risultato della query è una tabella vuota. Nel secondo esempio, la funzione UNNEST converte l'array in una tabella.

Grafici con query di filtro di Monitoring

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

Console

Se utilizzi la console Google Cloud per creare i grafici e l'interfaccia basata su menu, puoi aggiornare la query del grafico utilizzando il campo Applica ai grafici della variabile o modificando il widget e selezionando la variabile basata su etichette dal menu Filtro. Il menu Filtro elenca tutte le variabili basate su etichette e tutte le chiavi di etichetta.

Per aggiornare la query di un grafico in modo che dipenda da una variabile basata su valori, procedi nel seguente modo:

  1. Modifica il grafico.
  2. Nel riquadro delle query, fai clic su Aggiungi filtro e seleziona una chiave di etichetta. Ad esempio, puoi selezionare zona.
  3. Nel menu Valore, seleziona la variabile solo valore.
  4. Fai clic su Applica.
  5. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

Ad esempio, il seguente JSON illustra una query che si basa su una variabile basata su etichette, my_label_based_variable, che viene risolta in un'espressione di filtro:

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

I widget che utilizzano una query sotto forma di filtro di Monitoring non possono filtrare le serie temporali in base al valore di una variabile basata su etichette; tuttavia, puoi filtrare in base alle variabili solo valore. Ad esempio, la seguente query mostra il valore del campo Filtri di una query che filtra per zone, in base al valore di una variabile di tipo Solo valore:

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

REST

Ad esempio, il seguente JSON illustra una query che si basa su una variabile basata su etichette, my_label_based_variable, che viene risolta in un'espressione di filtro:

"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
},

I widget che utilizzano una query sotto forma di filtro di Monitoring non possono filtrare le serie temporali in base al valore di una variabile basata su etichette; tuttavia, puoi filtrare in base alle variabili solo valore. Ad esempio, la seguente query mostra il campo "filter" di una query che filtra per zone, in base al valore di una variabile solo valore:

"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 tabella seguente illustra come le variabili di esempio vengono risolte dal filtro di Monitoring. Come accennato in precedenza, quando viene utilizzato solo il valore di una variabile, devi utilizzare un'espressione regolare come operatore di confronto:

Sintassi Valore
selezionato		 Espressione di filtro risolta
${my_label_based_variable} 12345 resource.instance_id == "12345"

La variabile di esempio si basa sull'etichetta della risorsa instance_id.
${my_label_based_variable} * Omessa
${my_label_based_variable.value} 12345 Non supportata
${my_label_based_variable.value} * Non supportata
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

Modifica un filtro o una variabile bloccati

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

Se la dashboard contiene una tabella che mostra i dati delle serie temporali, puoi aggiungere filtri temporanei o modificare filtri e variabili permanenti utilizzando il pulsante Filtra dashboard in base a questo valore di una cella. Quando viene 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 di etichetta della colonna della tabella corrisponde alla chiave di etichetta di un filtro o di 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 o il progetto di gestione di App Hub.
  3. Nella barra degli strumenti della dashboard, fai clic su 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.

Elimina 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 o il progetto di gestione di App Hub.
  3. Nella barra degli strumenti della dashboard, fai clic su Impostazioni.
  4. Individua il filtro o la variabile da rimuovere e fai clic su Elimina.
  5. Fai clic su Applica.
  6. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

Limitazioni

  • I filtri a livello di dashboard si basano sul filtro dei dati in base alle coppie chiave-valore. Questi filtri non vengono applicati quando i dati non supportano le coppie chiave-valore o quando non supportano la chiave specifica. Ad esempio, non puoi utilizzare un filtro a livello di dashboard per modificare i dati visualizzati da un widget di traccia.

  • Per applicare una variabile a un widget, devi modificare la query del widget. Non tutti i widget supportano la modifica.

Passaggi successivi