Creare e gestire le dashboard tramite API

Questo documento descrive come creare e gestire dashboard personalizzate e i widget al loro interno utilizzando la risorsa Dashboard nell'API Cloud Monitoring. Gli esempi riportati di seguito illustrano come gestire le dashboard utilizzandocurl per richiamare l'API e come utilizzare Google Cloud CLI. Sebbene tu possa anche gestire le tue dashboard personalizzate tramite la console Google Cloud, l'API ti offre un modo programmatico per gestire molte dashboard contemporaneamente.

L'endpoint supporta i seguenti metodi per gestire e configurare le dashboard:

Puoi richiamare l'API direttamente utilizzando l'utilità curl o Google Cloud CLI.

Non puoi recuperare, modificare o eliminare dashboard predefinite.

Informazioni sulle dashboard

Quando crei una dashboard, devi specificare i componenti o i widget che vuoi visualizzare e il layout per 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 delle dashboard

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

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

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

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

  • ColumnLayout: suddivide lo spazio disponibile in colonne verticali e organizza un insieme di widget in verticale 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 presentarlo nella dashboard. Una dashboard può avere più di un Widget. Esistono diversi tipi di oggetti Widget:

  • Il widget XyChart mostra i dati sugli assi X e Y.

    Questo widget mostra un set di dati che può essere costituito da dati delle 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 visualizzati 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

  • Widget visualizzati da una dimensione, ad esempio il valore più recente:

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

    • Scorecard: mostra il valore più recente di una serie temporale e la sua relazione con una o più soglie.

    • TimeSeriesTable: mostra il valore più recente o un valore aggregato per ogni serie temporale. Le tabelle supportano la personalizzazione. Ad esempio, puoi assegnare un codice a colori alle celle e configurare i nomi delle colonne e l'allineamento dei dati.

  • Widget che mostrano i criterio di avviso o le informazioni sugli incidenti:

    • AlertChart: mostra un riepilogo di una criterio di avviso con una sola condizione. Questo widget mostra i dati sotto forma di grafico a linee, la soglia e il numero di incidenti aperti.

    • IncidentList: mostra un elenco di incidenti. Puoi configurare il widget in modo da mostrare gli incidenti per criteri di avviso specifici o per tipi di risorse specifici.

  • Widget che mostrano voci di log ed errori:

  • 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 nell'indice della dashboard.

    • Text: mostra i contenuti di testo come testo non elaborato o come stringa Markdown.

    Per includere i widget di testo e di 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 XyChart widget 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 mostra i dati delle serie temporali e i dati dei 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.

L'aggiunta di etichette a una dashboard è facoltativa.

Ad esempio, di seguito è mostrato 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 più modi per visualizzare i dati visualizzati. Ad esempio, supponiamo che una dashboard mostri dati delle serie temporali per le tue istanze di macchine virtuali (VM). Potresti voler visualizzare i dati delle serie temporali per tutte le VM e solo i dati di una zona specifica. In questo caso, ti consigliamo di creare un filtro bloccato o una variabile e poi 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 dell'etichetta. Ad esempio, quando un grafico include il filtro zone = us-central1-a, ignora un filtro bloccato la cui chiave dell'etichetta è zone. Analogamente, questo filtro viene ignorato dai grafici che non hanno un'etichetta con una chiave zone.

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

Sia per i filtri che per le variabili bloccate, la barra degli strumenti della dashboard mostra ogni variabile insieme a un menu che consente di modificare temporaneamente il valore della variabile. La stessa struttura di dati viene utilizzata per rappresentare i filtri bloccati e le variabili. Per ulteriori informazioni, vedi DashboardFilter.

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

Creare filtri e variabili

Console

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

API

Per definire filtri e variabili bloccati, utilizza la struttura di 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 quando vuoi creare un filtro bloccato.
  • Per creare un filtro bloccato o una variabile basata su etichetta, devi specificare il campo labelKey. Ometti questo campo se vuoi una variabile solo con 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 di valori o se può selezionare più valori.

    • Per impostare un singolo valore predefinito e limitare gli utenti alla selezione di esattamente un'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 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 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 dell'etichetta zone, che viene visualizzata nella barra degli strumenti. I campi valueType e stringValue specificano il singolo valore predefinito. Per ulteriori informazioni, consulta la pagina dei riferimenti API per la struttura di dati dashboardFilters.

  • La variabile basata su etichette ha il nome my_label_based_variable e la sua chiave di etichetta è instance_id. Il valore predefinito per 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, pertanto l'operatore 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. Per applicare una variabile a un widget, modifica la query per il widget.

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.

Console

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

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

Come altro esempio, prendi in considerazione una variabile solo valore, value_only_severity_variable, e supponiamo che nel menu dei valori siano selezionati tre valori: ERROR, INFO e NOTICE. Aggiungi quanto segue al riquadro delle query del widget del riquadro dei log:

severity =~ "${value_only_severity_variable}"

Di seguito è illustrata la forma visualizzata:

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

API

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

"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 di stringa che include il valore di una variabile basata su etichette:

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

Come altro esempio, prendi in considerazione una variabile solo valore, value_only_severity_variable, e supponiamo che nel menu siano selezionati tre valori: ERROR, INFO e NOTICE. Aggiungi quanto segue al riquadro delle query del widget del riquadro dei log:

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

Di seguito è illustrata 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 risolti
${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 applicare una variabile basata su etichetta a un grafico con una query PromQL, 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 con valore, ometti la clausola .value. Ad esempio, per filtrare in base alla zona utilizzando una variabile di solo valore, la query includerà qualcosa di simile al seguente:

zone=~"${my_value_only_variable}"

API

Ad esempio, il seguente JSON illustra una query che si basa sulla variabile basata su etichetta my_label_based_variable, 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 con valore, ometti la clausola .value. Ad esempio, per filtrare in base alla zona utilizzando una variabile di solo valore, la query includerà qualcosa di 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

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 dalle iniezioni SQL. Per ulteriori informazioni, consulta la sezione Eseguire query con parametri.

Console

Poiché SQL non interpreta l'operatore jolly come "qualsiasi valore", ti consigliamo di utilizzare sempre un'istruzione IF quando applichi le variabili a una query SQL. L'esempio seguente illustra l'utilizzo di una variabile 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 casting 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 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 e poi la variabile da applicare alla clausola WHERE.
  3. Nella finestra di dialogo visualizzata, controlla il codice generato e 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 generi un elenco di nomi di log e invii il risultato in una tabella con una singola colonna denominata LogName.log_name A questo punto, crea un grafico, seleziona Inserisci filtro variabile e poi seleziona 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.

API

Poiché SQL non interpreta l'operatore jolly come "qualsiasi valore", ti consigliamo di utilizzare sempre un'istruzione IF quando applichi le variabili a una query SQL. L'esempio seguente illustra l'utilizzo di una variabile 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 chiamata 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 esegue 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 casting 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 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 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.

Console

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${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:

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

Se hai una variabile solo con valore, ometti la clausola .value. Ad esempio, per filtrare in base alla zona utilizzando una variabile di solo valore, la query includerà qualcosa di simile al seguente:

resource.zone=~'${my_value_only_variable}'

API

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

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

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

Se hai una variabile solo con valore, ometti la clausola .value. Ad esempio, per filtrare in base alla zona utilizzando una variabile di solo valore, la query includerà qualcosa di simile al seguente:

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:

Sintassi Valore
selezionato		 Espressione MQL risolta
${my_label_based_variable} 12345 filter (resource.instance_id == '12345')

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

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.

Console

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

Per applicare una variabile basata sul valore a questi tipi di grafici:

  1. Modifica il grafico.
  2. Nel riquadro della 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, 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 monitoraggio non possono filtrare le serie temporali in base al valore in una variabile basata su etichette. Tuttavia, puoi filtrare in base a variabili di solo valore. Ad esempio, la seguente query mostra il valore del campo Filtri di una query che applica un filtro in base a zone, in base al valore di una variabile di 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})

API

Ad esempio, il seguente JSON illustra una query che si basa su una variabile basata su etichette, my_label_based_variable, 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 monitoraggio non possono filtrare le serie temporali in base al valore in una variabile basata su etichette. Tuttavia, puoi filtrare in base a variabili di 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 Monitoraggio. 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} * ".*"

Crea una dashboard

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

Quando crei una dashboard, l'API genera automaticamente il dashboard_id. Se vuoi specificare un dashboard_id personalizzato, puoi impostare il campo name di un oggetto Dashboard. Il formato del campo del nome è il seguente:

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

API

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

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

Ad esempio, se vuoi duplicare una dashboard:

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

Per ulteriori informazioni, consulta la documentazione di riferimento di gcloud monitoring dashboards create.

Terraform

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

Per creare una dashboard utilizzando Terraform, utilizza la risorsa Terraform google_monitoring_dashboard.

Nel comando, imposta i seguenti campi:

  • dashboard_json: la rappresentazione JSON della dashboard, che utilizza il formato Dashboards.

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

  • parent: il nome completo del progetto. Ad esempio, puoi impostare questo campo su "projects/PROJECT_ID", dove PROJECT_ID è l'ID del progetto Google Cloud.

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

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

Eliminare le dashboard

Per eliminare una dashboard personalizzata, invoca il metodo dashboards.delete e specifica la dashboard da eliminare.

API

Per eliminare una dashboard personalizzata, invia una richiesta DELETE all'endpoint Dashboard, specificando 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}

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

gcloud

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

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Per ulteriori informazioni, consulta la documentazione di riferimento di gcloud monitoring dashboards delete.

Terraform

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

Elenco dashboard

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

API

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

gcloud

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

gcloud monitoring dashboards list

Per ulteriori informazioni, consulta la documentazione di riferimento di gcloud monitoring dashboards list.

Terraform

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

Gli esempi restituiscono le dashboard personalizzate associate al tuo progetto.

Eseguire la paginazione della risposta dell'elenco

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

API

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

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

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

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

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

Terraform

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

Ottieni dashboard

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

API

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

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

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

gcloud

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

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

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 ulteriori informazioni, consulta il riferimento gcloud monitoring dashboards describe.

Terraform

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

Aggiornamento dashboard

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

API

Per aggiornare una dashboard personalizzata, invia una richiesta PATCH all'endpoint Dashboard e fornisci l'oggetto Dashboard rivisto 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}

L'esempio precedente aggiorna una dashboard personalizzata esistente utilizzando il filemy-updated-dashboard.json. La risposta, che include un nuovo valore etag, è una copia della scheda della dashboard aggiornata.

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

Per ulteriori informazioni, consulta il riferimento gcloud monitoring dashboards update.

L'esempio precedente aggiorna una dashboard personalizzata esistente utilizzando il filemy-updated-dashboard.json. La risposta, che include un nuovo valore etag, è una copia della scheda della dashboard aggiornata.

Terraform

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

Per aggiornare una dashboard utilizzando Terraform, utilizza la risorsa Terraform google_monitoring_dashboard.

Nel comando, imposta i seguenti campi:

  • dashboard_json: la rappresentazione JSON della dashboard, che utilizza il formato Dashboards.

  • parent: il nome completo del progetto. Ad esempio, puoi impostare questo campo su "projects/PROJECT_ID", dove PROJECT_ID è l'ID del progetto Google Cloud.

Passaggi successivi