Crea e gestisci dashboard per API

Questo documento descrive come creare e gestire le dashboard personalizzate e i relativi widget 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 quali componenti, o widget, da visualizzare e il layout dei 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 in cui vengono ordinati i 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: divide lo spazio disponibile in una a griglia. Ogni widget può occupare uno o più blocchi della griglia.

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

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

Ad esempio, quanto segue mostra 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 una 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 di dati di serie temporali o generati 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
    • Heatmaps

  • Widget che vengono 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 oppure un aggregato per ogni serie temporale. Le tabelle supportano la personalizzazione. Ad esempio, puoi assegnare colori alle celle e configurare i nomi e i dati delle colonne allineamento.

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

    • AlertChart: mostra un riepilogo di una singola condizione criterio di avviso. 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 che mostri gli incidenti per criteri di avviso specifici o per di risorse specifiche.

  • 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: visualizza un widget in un 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 uno spazio vuoto segnaposto in 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, potrebbe aggiungere un'etichetta denominata prod per indicare che la dashboard mostra dei dati delle serie temporali e dei dati di log per le tue 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, quanto segue mostra un oggetto Dashboard che specifica l'etichetta 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 per la dashboard

Quando progetti una dashboard, potresti identificare più modi per visualizzare i dati visualizzati. 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 e solo i dati di una zona specifica. In questo situazione, consigliamo di creare un filtro permanente e impostare il valore predefinito valore di quel filtro alla vista più usata. I filtri permanenti possono essere applicati a alcuni o a tutti i widget della dashboard. Quando visualizzi la dashboard con Console Google Cloud, la barra degli strumenti della dashboard mostra i filtri permanenti e un menu che puoi utilizzare per modificare temporaneamente il valore del filtro.

Esistono diversi tipi di filtri permanenti per le dashboard:

  • I filtri a livello di dashboard si applicano a tutti i widget su una dashboard che supportano etichetta di filtro e che non specificano un valore per quell'etichetta.

    Ad esempio, quando un grafico include il filtro zone = us-central1-a, questo ignora un filtro della dashboard basato sull'etichetta zone. Analogamente, i grafici senza un'etichetta zone ignorano i filtri della dashboard con questa etichetta.

  • Le variabili di modello sono variabili denominate che si applicano a widget specifici. Ogni variabile è associata a un'etichetta e a un valore specifici. Sei tu a stabilire quali widget a cui si applica una variabile di modello.

Tutti i tipi di filtri sono rappresentati con la stessa struttura di dati. Per ulteriori informazioni, vedi DashboardFilter.

Ad esempio, di seguito è riportata la rappresentazione JSON parziale di una dashboard che definisce una variabile del modello e un filtro a livello di dashboard:

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

Nel JSON visualizzato, la prima voce nella struttura dashboardFilters è per una variabile di modello denominata iid e un filtro a livello di dashboard con la chiave di etichetta zone. La variabile del modello è Un alias dell'etichetta instance_id.

La struttura di dati di una variabile del modello non elenca i widget a cui si applica. Devi invece associare un widget a una variabile di modello. Modificando la query del widget per includere un riferimento alla variabile. Quando il widget viene visualizzato nella dashboard, il valore della variabile del modello sia risolto.

Per informazioni su come annotare i riquadri e i grafici dei log, consulta le sezioni seguenti:

Riquadro dei log

Per configurare un riquadro dei log per filtrare la visualizzazione in base al valore di un , aggiungila al riquadro delle query. Nell'esempio che segue illustra una query che filtra in base al valore della variabile del modello iid:

${iid}

Prima che il riquadro dei log esegua una query per trovare i log da visualizzare, la variabile del modello sia stato risolto. In questo esempio, se il valore della variabile del modello è "12345", il valore ${iid} viene sostituito con l'istruzione resource.labels."instance_id"="12345".

In una query puoi anche includere solo il valore di una variabile del modello. Ti consigliamo di utilizzare il valore solo come parte di un filtro definito con un un'espressione regolare. Ad esempio, la seguente query utilizza un'espressione regolare per trovare le voci di log con un payload JSON contenente la stringa descritta:

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

Se hai configurato una query per il riquadro dei log e poi seleziona il pulsante per aprire Esplora log, le variabili del modello vengono risolte prima sia aperto Esplora log.

La tabella seguente mostra in che modo la variabile del modello viene risolta tramite riquadro dei log:

Sintassi Selected
Value		 Espressione del riquadro dei log risolti
${iid} 12345 resource.labels."instance_id"="12345"
${iid} * ""
${iid.value} 12345 12345
${iid.value} * .*

Grafici e tabelle definiti in MQL

Quando utilizzi Monitoring Query Language (MQL) per configurare un grafico, aggiungi una barra verticale alla stringa di query:

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

Prima che il grafico esegua query sulle serie temporali da visualizzare, la variabile del modello viene risolta. In questo esempio, se il valore della variabile del modello è "12345", ${iid} viene sostituito dall'istruzione filter (resource.instance_id == '12345'). Questo filtro corrisponde alle serie temporali con un'etichetta denominata resource.instance_id e solo quando il valore di quell'etichetta è esattamente 12345.

Quando vuoi filtrare le serie temporali utilizzando un'espressione regolare, configura la query in modo da includere solo il valore della variabile del modello. Per illustrare la sintassi, di seguito viene mostrato come utilizzare un'espressione regolare per determinare se il valore dell'etichetta resource.instance_id contiene il valore della variabile del modello iid:

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

La seguente tabella mostra come viene risolta la variabile del modello per le query MQL:

Sintassi Selected
Value		 Espressione MQL risolta
${iid} 12345 filter (resource.instance_id == '12345')
${iid} * filter (true)
${iid.value} 12345 12345
${iid.value} * .*

Grafici e tabelle definiti tramite PromQL

Quando definisci un grafico utilizzando PromQL, aggiungi alla stringa di query il valore variabile racchiusa tra parentesi graffe:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Prima che il grafico esegua query sulle serie temporali da visualizzare, la variabile del modello viene risolta. In questo esempio, se il valore della variabile del modello è "12345", il valore ${iid} viene sostituito con l'istruzione instance_id == '12345'.

Come per MQL, quando definisci un widget con PromQL, la query può estrarre solo il valore della variabile del modello. Ti consigliamo di Utilizzare il valore solo come parte di un filtro definito con un'espressione regolare. A illustrano la sintassi, quanto segue mostra come utilizzare un'espressione regolare per determina se il valore dell'etichetta instance_id contiene il valore dell'attributo variabile di modello iid:

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

La tabella seguente mostra come viene risolta la variabile del modello per PromQL query:

Sintassi Selected
Value		 Espressione PromQL risolta
${iid} 12345 instance_id == '12345'
${iid} * noop_filter=~".*"
${iid.value} 12345 12345
${iid.value} * .+

Grafici e tabelle definiti con filtri delle serie temporali

Quando definisci un grafico utilizzando i filtri delle serie temporali, aggiungi la variabile alla stringa del filtro:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

A differenza dei grafici definiti in MQL e PromQL, non puoi utilizzare il valore di una variabile di modello in un filtro delle serie temporali.

La tabella seguente mostra come viene risolta la variabile del modello:

Sintassi Selected
Value		 Espressione di filtro risolta
${iid} 12345 resource.instance_id == "12345"
${iid} * Omessa
${iid.value} 12345 Non supportata
${iid.value} * Non supportata

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

Protocollo

Per creare una nuova dashboard, invia una richiesta POST all'indirizzo 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, procedi nel seguente modo:

  1. Completa i passaggi descritti in Scarica la dashboard per scaricare la definizione di la 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.

Gli esempi creano una dashboard di esempio utilizzando il file my-dashboard.json. Puoi gestire la tua dashboard tramite console Google 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 specificare la dashboard da eliminare.

Protocollo

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 .

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.

Elenco dashboard

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

Protocollo

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 Comando gcloud monitoring dashboards list:

gcloud monitoring dashboards list

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

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.

Protocollo

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. Per 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

Ottieni dashboard

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

Protocollo

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 all'esempio seguente:

{
  "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 la gcloud monitoring dashboards describe e specifica l'ID della 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 gcloud monitoring dashboards describe.

Aggiornamento dashboard

Per aggiornare una dashboard personalizzata esistente, richiama il metodo dashboards.patch. Per ottenere lo stato attuale di etag , puoi richiamare il metodo dashboards.get e trovare nella risposta.

Protocollo

Per aggiornare una dashboard personalizzata, invia una richiesta PATCH a Dashboard e fornisce l'oggetto Dashboard rivisto e il valore etag dal 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}

gcloud

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

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

Per ulteriori informazioni, consulta gcloud monitoring dashboards update.

Gli esempi aggiornano una dashboard personalizzata esistente utilizzando il filemy-updated-dashboard.json e restituiscono una copia della scheda della dashboard aggiornata. I dati restituiti includono un nuovo valore etag.

Passaggi successivi