Creare e gestire variabili e filtri bloccati

Questo documento descrive come bloccare i filtri a livello di dashboard in modo che siano permanenti. I filtri bloccati, che ti 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 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. La barra degli strumenti della dashboard mostra ogni variabile, insieme a un menu che consente di modificare temporaneamente il valore della variabile.

Questo documento descrive come utilizzare la console Google Cloud per creare variabili e filtri bloccati. Per informazioni sull'utilizzo dell'API Cloud Monitoring, consulta Creare e gestire 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.

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. Per informazioni sulla struttura di un filtro, consulta DashboardFilter.

Non applichi un filtro bloccato con singoli widget. Per determinare se il filtro bloccato può modificare i dati visualizzati dal widget, vengono utilizzate le seguenti regole:

• Se il widget visualizza 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 di aggiungere il filtro bloccato cluster_name: mycluster. I grafici mostrano automaticamente solo le serie temporali con 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 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 in esso contenuta. Per informazioni sulla struttura di un filtro, consulta DashboardFilter.

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

• Le variabili basate su etichette sono simili ai 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 ricavato dinamicamente dai dati delle serie temporali visualizzati nella dashboard.

• Le variabili solo valore contengono uno o più valori predefiniti e possono elencare tutti i valori possibili. Se non specifichi un valore predefinito, l'operatore jolly (*) viene selezionato per il valore predefinito. Per definire l'insieme di tutti i valori possibili, fornisci un array 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 elencare sia l'elenco di tutti i valori possibili sia 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.

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

  • Query SQL: da utilizzare quando vuoi generare l'elenco dei valori possibili utilizzando una query SQL. Queste variabili devono essere applicate ai grafici creati utilizzando Log Analytics.

    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 variabile deve eseguire una query sulla stessa tabella del grafico.

Per applicare una variabile a un widget, aggiorna la query contenuta nel widget. Se utilizzi la console Google Cloud, per le variabili basate su etichette e per alcuni tipi di widget, puoi eseguire questa associazione utilizzando una selezione di menu. Tuttavia, puoi sempre modificare la query del widget per applicare una variabile. Per ulteriori informazioni, consulta Applicare una variabile a un widget.

Prima di iniziare

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 di monitoraggio (roles/monitoring.editor) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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.

Creare e bloccare un filtro

Per creare e bloccare un filtro che si applichi 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 dashboard, fai clic su settings Impostazioni.
3. Nella sezione Filtri, fai clic su Aggiungi un filtro.
4. Fai clic su arrow_drop_down Etichetta e seleziona un'etichetta. Ad esempio, puoi selezionare zone.
5. Per consentire a un utente di selezionare più valori dal menu dei valori della variabile, seleziona Multipla selezione. Quando l'opzione Selezione multipla non è attivata, gli utenti possono selezionare soltanto un'opzione dal menu dei valori.

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

7. Fai clic su Fine e poi su Applica.

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

Creare una variabile

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

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 settings Impostazioni.
3. Nella sezione Variabili, fai clic su Aggiungi una variabile.

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

   Per creare una variabile basata su etichetta, seleziona Etichetta. Utilizza questa opzione se vuoi una variabile con una chiave e un valore di etichetta che possa essere utilizzata come un filtro. L'elenco di tutti i valori possibili viene ricavato dinamicamente dai dati delle serie temporali visualizzati nella dashboard.

   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 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 questa colonna sia stringa e che ogni riga della tabella contenga un valore di stringa univoco.

   • Personalizzato: utilizza questa opzione se vuoi specificare sia l'elenco di 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 se vuoi specificare un elenco di valori da applicare come predefiniti.

5. Inserisci un nome per la variabile. Il nome viene visualizzato nella barra degli strumenti della dashboard.

6. Fai clic su Fine e poi su Applica.

7. Applica la variabile ai widget del riquadro dei log e ai widget configurati con SQL, MQL o PromQL. Per ulteriori informazioni, consulta Applicare una variabile a un widget.

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

Applicare una variabile a un widget

Per applicare una variabile a un widget, è necessario modificare la query utilizzata dal widget:

• Per i grafici che utilizzano query SQL, PromQL o MQL 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, Monitoraggio modifica la query quando selezioni il widget utilizzando il menu Applica ai grafici.

Per scoprire come applicare una variabile basata su etichetta o una variabile solo valore a un widget, consulta le seguenti sezioni:

• Sintassi generale per il dereferenziamento di una variabile
• Widget del riquadro dei log
• Grafici con query PromQL
• Grafici con query SQL
• Grafici con query MQL

• Grafici con query di filtro di monitoraggio

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

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 il dereferenziamento di 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 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 è conforme a 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 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:

Grafici con query PromQL

Per applicare una variabile basata su etichetta a un grafico con una query PromQL, 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 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:

Grafici con query SQL

Quando vuoi applicare una variabile a un widget definito in SQL, aggiorna la clausola WHERE in modo che faccia riferimento al valore della variabile. Per tutte le variabili, anteponi al nome della variabile il segno "at", 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 è protetta da SQL injection. Per ulteriori informazioni, consulta la sezione Eseguire query con parametri.

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 MQL

Per applicare una variabile basata su etichetta a un grafico con una query MQL, aggiungi un tubo, (|), e segui le indicazioni riportate in Sintassi generale.

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

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

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

resource.zone=~'${my_value_only_variable}'

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

resource.zone=~'${my_value_only_variable}'

La tabella seguente illustra come le variabili di esempio vengono risolte dall'MQL. 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 sui filtri di monitoraggio

Per applicare una variabile basata su etichette a un grafico contenente una query sotto forma di filtro di monitoraggio, 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 tabella seguente illustra come le variabili di esempio vengono risolte dal filtro Monitoraggio. 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 qualsiasi filtro visualizzato nella barra degli strumenti della dashboard, fai clic sul nome del filtro, 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 filter_list Filtra dashboard in base a questo valore 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 dashboard, fai clic su settings Impostazioni.
3. Trova il filtro o la variabile che vuoi modificare ed espandi la relativa definizione.
4. Dopo aver completato le modifiche, fai clic su Applica.
5. Per salvare la dashboard modificata, fai clic su Salva nella barra degli strumenti.

Eliminare un filtro o una variabile bloccati

Per eliminare un filtro bloccato o 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 dashboard, fai clic su settings Impostazioni.
3. Individua il filtro o la variabile da rimuovere, quindi fai clic su delete Elimina.
4. Fai clic su Applica.
5. 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