Creare e gestire le dashboard tramite API

La risorsa Dashboard nell'API Cloud Monitoring ti consente di creare e gestire in modo programmatico dashboard personalizzate e i relativi widget su larga scala. Puoi gestire le dashboard personalizzate utilizzando Google Cloud CLI, Terraform o chiamate REST ai metodi create, list, get, patch e delete.

Non puoi recuperare, modificare o eliminare le dashboard predefinite utilizzando l'API. Per informazioni su come creare e gestire dashboard personalizzate utilizzando la console Google Cloud , consulta Crea e gestisci dashboard personalizzate.

Informazioni sulle dashboard

Quando crei una dashboard, devi specificare quali componenti, o widget, vuoi visualizzare e il layout di questi widget. Puoi anche aggiungere etichette e filtri alla dashboard. Le etichette possono aiutarti a trovare una dashboard o indicare il tipo di contenuti al suo interno.

Layout della dashboard

I layout definiscono l'ordine dei componenti di una dashboard. L'API fornisce i seguenti layout:

  • GridLayout: divide lo spazio disponibile in colonne verticali di larghezza uguale e dispone un insieme di widget utilizzando una strategia basata sulle righe.

  • MosaicLayout: divide lo spazio disponibile in una griglia. Ogni widget può occupare uno o più blocchi della griglia.

  • RowLayout: divide lo spazio disponibile in righe e dispone un insieme di widget in orizzontale in ogni riga.

  • ColumnLayout: divide lo spazio disponibile in colonne verticali e dispone un insieme di widget verticalmente in ogni colonna.

Ad esempio, di seguito è riportata la rappresentazione JSON di una dashboard in RowLayout con tre widget Text:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Widget delle dashboard

Un widget contiene un singolo componente della dashboard e la configurazione di come presentare il componente nella dashboard. Una dashboard può avere più di un widget. Esistono diversi tipi di oggetti Widget:

  • Widget XyChart: visualizza i dati sugli assi X e Y.

    Questo widget mostra un set di dati che può essere costituito da dati di serie temporali o generato da una query SQL. Questo widget ti consente di associare i dati del grafico all'asse Y sinistro o destro. Quando vengono tracciati più tipi di metriche, puoi utilizzare entrambi gli assi Y. Il widget XyChart supporta i seguenti stili di visualizzazione:

    • Grafici a linee
    • Grafici a barre
    • Grafici ad area in pila
    • Mappe termiche

    Puoi specificare l'intervallo di tempo per i widget XyChart. Questa impostazione esegue l'override dell'impostazione a livello di dashboard. Configura l'override dell'intervallo di tempo di un grafico quando vuoi che mostri i dati in un intervallo di tempo più lungo o più breve di quello appropriato per altri widget della dashboard. Per un esempio, consulta Dashboard con un widget XyChart che imposta un override dell'intervallo di tempo.

  • Widget che mostrano una dimensione, ad esempio l'ultimo valore:

    • PieChart: mostra i valori più recenti di una raccolta di serie temporali, in cui ogni serie temporale contribuisce con una sezione al grafico a torta.

    • Scorecard: visualizza l'ultimo valore di una serie temporale e la relazione di questo valore con una o più soglie.

    • TimeSeriesTable: visualizza l'ultimo valore o un valore aggregato per ogni serie temporale. Le tabelle supportano la personalizzazione. Ad esempio, puoi codificare le celle con colori e configurare i nomi delle colonne e l'allineamento dei dati.

  • Widget che mostrano informazioni criterio di avviso o sull'avviso:

    • AlertChart: visualizza un riepilogo di una criterio di avviso con una singola condizione. Questo widget visualizza i dati sotto forma di grafico a linee, mostra la soglia ed elenca il numero di avvisi aperti.

    • IncidentList: visualizza un elenco di avvisi. Puoi configurare il widget in modo che mostri gli avvisi per policy di avviso specifiche o per tipi di risorse specifici.

  • Widget che mostrano voci di log ed errori:

  • Widget che mostrano i dati di traccia:

    • Widget XyChart: visualizza i dati sugli assi X e Y.

    • TimeSeriesTable: mostra il valore più recente o un valore aggregato. Le tabelle supportano la personalizzazione.

  • Widget di testo e organizzazione:

    • CollapsibleGroup: mostra una raccolta di widget. Puoi comprimere la visualizzazione di un gruppo.

    • SingleViewGroup: mostra un widget in una raccolta di widget. Puoi selezionare il widget da visualizzare.

    • SectionHeader: crea un divisore orizzontale nella dashboard e una voce nel sommario della dashboard.

    • Text: visualizza i contenuti testuali, come testo non elaborato o stringa Markdown.

    Per includere i widget di testo e organizzazione in una dashboard, questa deve avere un MosaicLayout.

Oltre a questi oggetti, puoi anche aggiungere un segnaposto vuoto a una dashboard.

Ad esempio, di seguito è riportata la rappresentazione JSON di un widget XyChart il cui asse Y destro è configurato:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Etichette della dashboard

Le etichette possono aiutarti a gestire e organizzare le dashboard. Ad esempio, potresti aggiungere un'etichetta denominata prod per indicare che la dashboard visualizza i dati delle serie temporali e i dati di log per le risorse di produzione. In alternativa, puoi aggiungere l'etichetta playbook per indicare che la dashboard contiene informazioni utili per la risoluzione dei problemi relativi agli errori.

L'aggiunta di etichette a una dashboard è facoltativa.

Ad esempio, di seguito è riportato un oggetto Dashboard che specifica l'etichetta denominata playbook.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Come illustrato nell'esempio precedente, il campo labels è implementato come map, dove i campi key e value sono entrambi stringhe. Quando aggiungi un'etichetta a una dashboard, imposta key sul nome dell'etichetta e il campo value su una stringa vuota.

Filtri e variabili della dashboard

Quando progetti una dashboard, potresti identificare diversi modi per visualizzare i dati mostrati dalla dashboard. Ad esempio, supponiamo che una dashboard mostri i dati delle serie temporali per le tue istanze di macchine virtuali (VM). Potresti voler visualizzare i dati delle serie temporali per tutte le VM o solo i dati che si trovano in una zona specifica. In questa situazione, ti consigliamo di creare un filtro bloccato o una variabile e di impostare il valore predefinito del filtro sulla zona visualizzata più di frequente.

I filtri bloccati si applicano a tutti i widget della dashboard che supportano l'etichetta specificata nel filtro, a meno che il widget non contenga un filtro con la stessa chiave etichetta. Ad esempio, se un grafico include il filtro zone = us-central1-a, ignora un filtro bloccato la cui chiave etichetta è zone. Analogamente, questo filtro viene ignorato dai grafici che non hanno un'etichetta con una chiave zone.

Le variabili sono come i filtri bloccati, ma si applicano solo a widget specifici. Le variabili possono essere basate su etichette o avere solo un valore. Le variabili di solo valore contengono uno o più valori predefiniti e un elenco di tutti i valori possibili. Se non specifichi un valore predefinito, questo viene impostato sull'operatore con caratteri jolly (*). Per definire l'insieme di tutti i valori possibili, puoi fornire un array di valori o scrivere una query SQL.

Se crei un filtro o una variabile bloccati, Monitoring aggiorna la barra degli strumenti della dashboard personalizzata per visualizzare un filtro. Per i filtri bloccati, il nome del filtro della barra degli strumenti è il nome del filtro bloccato. Per le variabili, il nome del filtro della barra degli strumenti è un segno di dollaro $ seguito dal nome della variabile. Ogni filtro della barra degli strumenti contiene un menu che ti consente di modificare il valore della variabile o del filtro bloccato associato. Per le variabili, puoi sostituire il filtro della barra degli strumenti con un widget della dashboard. Per saperne di più, consulta Dashboard con un widget FilterControl.

Per i widget che eseguono query sui dati, puoi includere una variabile nella query del widget e puoi utilizzarla per controllare la visibilità del widget. Quando la query dipende da una variabile, i dati richiesti dal widget cambiano quando modifichi il valore della variabile. Di conseguenza, cambiano anche i dati visualizzati. Quando utilizzi una variabile per controllare la visibilità di un widget, nella barra degli strumenti viene visualizzata un'icona Visibile. Per le limitazioni relative alla visibilità, consulta Imposta la visibilità di un widget.

La stessa struttura di dati viene utilizzata per rappresentare filtri e variabili bloccati. Per saperne di più, consulta DashboardFilter.

Per un esempio che mostra come controllare la visibilità di un widget utilizzando una variabile, consulta Dashboard con visibilità dei widget configurata.

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

Prima di iniziare

Completa i seguenti passaggi nel progetto Google Cloud in cui vuoi creare o gestire le dashboard:

gcloud

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Terraform

Per utilizzare gli esempi di Terraform in questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura Credenziali predefinite dell'applicazione con le tue credenziali utente.

  1. Installa Google Cloud CLI.

  2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  3. Se utilizzi una shell locale, crea le credenziali di autenticazione locale per il tuo account utente: 

    gcloud auth application-default login

    Non è necessario farlo se utilizzi Cloud Shell.

    Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud .

REST

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

    Installa Google Cloud CLI.

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Crea una dashboard

Per creare una nuova dashboard personalizzata, richiama il metodo dashboards.create e fornisci il layout e i widget da visualizzare nella dashboard.

Il campo name è facoltativo. Il valore del campo name ha la seguente struttura:

"name": "projects/PROJECT_ID_OR_NUMBER/dashboards/DASHBOARD_ID"

Quando crei una dashboard, l'API genera automaticamente il componente DASHBOARD_ID. Se vuoi specificare un DASHBOARD_ID personalizzato, puoi specificare il campo name dell'oggetto Dashboard.

gcloud

Per creare una dashboard in un progetto, utilizza il comando gcloud monitoring dashboards create.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json --project=PROJECT_ID

Prima di eseguire il comando precedente, sostituisci quanto segue:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

Ad esempio, per duplicare una dashboard:

  1. Completa i passaggi descritti in Recupera dashboard per scaricare la definizione della dashboard originale.
  2. Modifica il JSON restituito per rimuovere i campi etag e name e modifica il valore del campo displayName.
  3. Esegui il comando per creare la dashboard.

Per saperne di più, consulta il riferimento gcloud monitoring dashboards create.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per saperne di più, consulta la documentazione di riferimento del provider Terraform.

Per creare una dashboard utilizzando Terraform, segui questi passaggi:

  1. Installa e configura Terraform per il tuo progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

  2. Utilizza la risorsa Terraform google_monitoring_dashboard.

    Nel comando, imposta i seguenti campi:

    • dashboard_json: la rappresentazione JSON della dashboard, utilizzando il formato Dashboard.

      Per esempi di questo formato, puoi elencare le dashboard utilizzando Explorer API oppure puoi aprire una dashboard nella console Google Cloud e visualizzare la rappresentazione JSON.

    • parent: il nome completo del progetto. Ad esempio, puoi impostare questo campo su "projects/PROJECT_ID", dove PROJECT_ID è l'ID del tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

REST

Per creare una nuova dashboard, invia una richiesta POST all'endpoint Dashboard.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Prima di eseguire il comando precedente, configura quanto segue:

  • ${PROJECT_ID}: una variabile di ambiente che memorizza l'ID progetto in cui creare la dashboard. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

Gli esempi creano una dashboard di esempio utilizzando il file my-dashboard.json. Puoi gestire la dashboard tramite la consoleGoogle Cloud .

Per altre configurazioni delle dashboard, consulta Esempi di dashboard e layout.

Elimina dashboard

Per eliminare una dashboard personalizzata, richiama il metodo dashboards.delete e specifica la dashboard che vuoi eliminare.

gcloud

Per eliminare una dashboard personalizzata, utilizza gcloud monitoring dashboards delete e specifica l'ID completo della dashboard da eliminare:

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

Prima di eseguire il comando precedente, sostituisci quanto segue:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • DASHBOARD_ID: l'ID della dashboard.

Per saperne di più, consulta il riferimento gcloud monitoring dashboards delete.

Terraform

Puoi eliminare le risorse utilizzando Terraform. Per informazioni sull'eliminazione delle risorse, consulta il comando Terraform destroy.

REST

Per eliminare una dashboard personalizzata, invia una richiesta DELETE all'endpoint Dashboard, qualificato con l'ID della dashboard da eliminare.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Prima di eseguire il comando precedente, configura quanto segue:

  • ${PROJECT_ID}: una variabile di ambiente che memorizza l'ID progetto in cui creare la dashboard. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • ${DASHBOARD_ID}: una variabile di ambiente che memorizza l'ID della dashboard.

In caso di esito positivo, il metodo restituisce una risposta vuota. In caso contrario, restituisce un errore.

Elenco dashboard

Per elencare tutte le dashboard personalizzate che appartengono a un progetto, richiama il metodo dashboards.list e specifica l'ID progetto.

gcloud

Per elencare tutte le dashboard personalizzate di un progetto, utilizza il comando gcloud monitoring dashboards list:

gcloud monitoring dashboards list --project=PROJECT_ID

Prima di eseguire il comando precedente, sostituisci quanto segue:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

Per saperne di più, consulta il riferimento gcloud monitoring dashboards list.

Terraform

Non puoi utilizzare Terraform per inviare una query al tuo progetto con la risposta che è un elenco di dashboard. Tuttavia, puoi visualizzare queste dashboard utilizzando la console Google Cloud .

REST

Per elencare tutte le dashboard personalizzate di un progetto, invia l'ID progetto all'endpoint Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Prima di eseguire il comando precedente, configura quanto segue:

  • ${PROJECT_ID}: una variabile di ambiente che memorizza l'ID progetto in cui creare la dashboard. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

Gli esempi restituiscono le dashboard personalizzate associate al tuo progetto.

Impagina la risposta dell'elenco

Il metodo dashboards.list supporta l'impaginazione, che ti consente di visualizzare i risultati una pagina alla volta anziché tutti insieme.

gcloud

Per specificare il numero di risorse per pagina, passa il flag --page-size con il comando. Ad esempio:

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

Prima di eseguire il comando precedente, sostituisci quanto segue:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

Terraform

Non puoi utilizzare Terraform per inviare una query al tuo progetto con la risposta che è un elenco impaginato di dashboard. Tuttavia, puoi visualizzare queste dashboard utilizzando la console Google Cloud .

REST

Per la pagina iniziale dell'elenco dei risultati, specifica il parametro di query pageSize con la richiesta:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

Prima di eseguire il comando precedente, configura quanto segue:

  • ${PROJECT_ID}: una variabile di ambiente che memorizza l'ID progetto in cui creare la dashboard. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

Il metodo restituisce la prima pagina dell'elenco e il token nextPageToken. Ad esempio:

{
  "dashboards" : [
    {
      "displayName" : "Grid Layout Example",
      "gridLayout" : {
        "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
      }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Per ogni pagina rimanente, devi includere il nextPageToken corrispondente nella richiesta.

Ottieni dashboard

Per ottenere una dashboard personalizzata specifica per un progetto, richiama il metodo dashboards.get, qualificato con l'ID dashboard.

gcloud

Per ottenere una dashboard personalizzata specifica, utilizza il comando gcloud monitoring dashboards describe e specifica l'ID della dashboard:

gcloud monitoring dashboards describe DASHBOARD_ID --format=json --project=PROJECT_ID

Prima di eseguire il comando precedente, sostituisci quanto segue:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • DASHBOARD_ID: l'ID della dashboard.

Il comando restituisce la dashboard richiesta:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Per saperne di più, consulta il riferimento gcloud monitoring dashboards describe.

Terraform

Non puoi utilizzare Terraform per inviare una query al tuo progetto con la risposta che è una singola dashboard. Tuttavia, puoi visualizzare queste dashboard utilizzando la console Google Cloud .

REST

Per ottenere una dashboard personalizzata specifica, invia l'ID della dashboard all'endpoint Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Prima di eseguire il comando precedente, configura quanto segue:

  • ${PROJECT_ID}: una variabile di ambiente che memorizza l'ID progetto in cui creare la dashboard. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • ${DASHBOARD_ID}: una variabile di ambiente che memorizza l'ID della dashboard.

Nell'espressione precedente, ${DASHBOARD_ID} è una variabile di ambiente che memorizza il nome completo della dashboard.

Il metodo restituisce una risposta simile al seguente esempio:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Aggiornamento dashboard

Per aggiornare una dashboard personalizzata esistente, richiama il metodo dashboards.patch. Per ottenere il valore etag corrente, puoi richiamare il metodo dashboards.get e trovarlo nella risposta.

gcloud

Per aggiornare una dashboard personalizzata, utilizza gcloud monitoring dashboards update, specifica l'ID della dashboard da aggiornare e fornisci le modifiche alla dashboard.

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

Prima di eseguire il comando precedente, sostituisci quanto segue:

  • PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • DASHBOARD_ID: l'ID della dashboard.

Per saperne di più, consulta il riferimento gcloud monitoring dashboards update.

L'esempio precedente aggiorna una dashboard personalizzata esistente utilizzando il file my-updated-dashboard.json. La risposta, che include un nuovo valore etag, è una copia dell'elenco delle dashboard aggiornato.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per saperne di più, consulta la documentazione di riferimento del provider Terraform.

Per aggiornare una dashboard utilizzando Terraform:

  1. Installa e configura Terraform per il tuo progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

  2. Utilizza la risorsa Terraform google_monitoring_dashboard.

    Nel comando, imposta i seguenti campi:

    • dashboard_json: la rappresentazione JSON della dashboard, utilizzando il formato Dashboard.

    • parent: il nome completo del progetto. Ad esempio, puoi impostare questo campo su "projects/PROJECT_ID", dove PROJECT_ID è l'ID del tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.

REST

Per aggiornare una dashboard personalizzata, invia una richiesta PATCH all'endpoint Dashboard e fornisci l'oggetto Dashboard modificato e il valore etag della risposta dashboards.get più recente.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Prima di eseguire il comando precedente, configura quanto segue:

  • ${PROJECT_ID}: una variabile di ambiente che memorizza l'ID progetto in cui creare la dashboard. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
  • ${DASHBOARD_ID}: una variabile di ambiente che memorizza l'ID della dashboard.

L'esempio precedente aggiorna una dashboard personalizzata esistente utilizzando il file my-updated-dashboard.json. La risposta, che include un nuovo valore etag, è una copia dell'elenco delle dashboard aggiornato.

Passaggi successivi