Crea e gestisci dashboard per API

Questo documento descrive come creare e gestire dashboard personalizzate e i relativi widget utilizzando la risorsa Dashboard nell'API Cloud Monitoring. Gli esempi qui mostrano come gestire le tue dashboard utilizzando curl per richiamare l'API e mostrano come utilizzare Google Cloud CLI. Sebbene tu possa anche gestire le tue dashboard personalizzate tramite la console Google Cloud, l'API fornisce un metodo programmatico per gestire molte dashboard contemporaneamente.

L'endpoint supporta i seguenti metodi per la gestione e la configurazione delle dashboard:

• dashboards.create: crea una dashboard
• dashboards.delete: elimina una dashboard specificata
• dashboards.list: recupera un elenco di tutte le dashboard di un determinato progetto
• dashboards.get: recupera una dashboard specificata
• dashboards.patch: aggiorna la struttura di una dashboard specificata

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

Non puoi recuperare, modificare o eliminare le dashboard predefinite.

Informazioni sulle dashboard

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

Layout della dashboard

I layout definiscono l'ordine in cui vengono ordinati i componenti di una dashboard. L'API fornisce i seguenti layout:

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

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

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

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

Ad esempio, di seguito viene mostrata 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 più tipi di oggetti Widget:

• Widget di grafici e tabelle:

  • XyChart: visualizza i dati utilizzando gli assi X e Y. I seguenti grafici sono istanze del widget XyChart:

  • Grafici a linee

  • Grafici a barre

  • Grafici ad area in pila

  • Mappe termiche

  • Grafici di Analisi dei log

  • Widget SLO, ma la creazione di grafici SLO mediante l'API non è supportata.

  Se crei un grafico a linee, un grafico a barre in pila o un grafico ad area in pila, puoi specificare che una metrica faccia riferimento all'asse Y sinistro o destro. Quando vengono rappresentati più metriche nei grafici, puoi utilizzare entrambi gli assi Y.

  • PieChart: mostra il valore più recente di una metrica, in cui ogni serie temporale contribuisce con una sezione della torta.

  • Scorecard: mostra il valore più recente di una metrica e come questo valore è correlato a una o più soglie.

  • TimeSeriesTable: mostra il valore più recente di una metrica. Puoi ordinare la tabella in base alle colonne, filtrarla e aggiungere o rimuovere colonne dalla visualizzazione.

• Grafici per i criteri di avviso e i widget degli incidenti:

  • AlertChart: mostra un riepilogo di un criterio di avviso per singola condizione. Questo widget visualizza i dati sotto forma di grafico a linee, mostra la soglia ed elenca 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 tipi di risorse specifici.

• Widget di log ed errori:

  • ErrorReportingPanel: visualizza i gruppi di errori archiviati nel progetto Google Cloud selezionato.

  • LogsPanel: visualizza le voci di log con ambito a livello di progetto archiviate nel progetto Google Cloud attuale. Puoi configurare il widget in modo da mostrare le voci di log archiviate nei progetti Google Cloud accessibili tramite l'ambito delle metriche attuale.

• Widget di testo e organizzazione:

  Per includere questi widget in una dashboard, quest'ultima deve avere un elemento MosaicLayout.

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

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

  • SectionHeader: crea un divisore orizzontale nella dashboard e una voce nella tabella dei contenuti della dashboard.

  • Text: mostra contenuti testuali, come testo non elaborato o una stringa di Markdown.

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

Ad esempio, quanto segue mostra 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 mostra i dati delle serie temporali e i dati di log relativi alle risorse di produzione. In alternativa, puoi aggiungere l'etichetta playbook per indicare che la dashboard contiene informazioni utili per risolvere gli errori.

L'aggiunta di etichette a una dashboard è facoltativa.

Ad esempio, quanto segue mostra 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 viene 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 imposta il campo value su una stringa vuota.

Filtri per la dashboard

Quando progetti una dashboard, potresti identificare diversi modi per visualizzare i dati visualizzati. Ad esempio, quando una dashboard mostra le metriche per le istanze di macchine virtuali (VM), potresti voler visualizzare le metriche per tutte le VM e per una zona specifica. In questo tipo di situazione, ti consigliamo di creare un filtro permanente e di impostare il valore predefinito del filtro sulla vista più utilizzata. I filtri permanenti possono essere applicati ad alcuni o a tutti i widget della dashboard. Quando visualizzi la dashboard con la 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 in una dashboard che supportano l'etichetta del filtro e che non specificano un valore per quell'etichetta.

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

• Le variabili del modello sono variabili con nome che si applicano a widget specifici. Ogni variabile è associata a un'etichetta e a un valore specifici. Sei tu a decidere a quali widget si applica una variabile del modello.

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

Ad esempio, di seguito viene mostrata la rappresentazione JSON parziale di una dashboard che definisce una variabile di 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 file JSON visualizzato, la prima voce della struttura dashboardFilters è per una variabile di modello con il nome 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 dei dati per una variabile di modello non elenca i widget a cui si applica. Puoi invece associare un widget a una variabile del modello modificando la query del widget in modo da includere un riferimento alla variabile. Quando il widget viene visualizzato nella dashboard, il valore della variabile del modello viene risolto.

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

• Riquadro Log
• Grafici e tabelle definiti da MQL
• Grafici e tabelle definiti da PromQL
• Grafici e tabelle definiti con filtri delle serie temporali

Riquadro dei log

Per configurare un riquadro dei log per filtrare la visualizzazione in base al valore di una variabile di modello, aggiungi la variabile al riquadro delle query. L'esempio seguente 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 visualizzare i log, la variabile del modello viene risolta. In questo esempio, se il valore della variabile del modello è "12345", ${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'espressione regolare. Ad esempio, la seguente query utilizza un'espressione regolare per trovare corrispondenze con le voci di log che hanno 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 selezioni il pulsante per aprire Esplora log, le variabili del modello vengono risolte prima dell'apertura di Esplora log.

La seguente tabella mostra come viene risolta la variabile del modello dal riquadro dei log:

Grafici e tabelle definiti da MQL

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

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

Prima che il grafico esegua le query sulle serie temporali da visualizzare, la variabile del modello è risolta. In questo esempio, se il valore della variabile del modello è "12345", ${iid} viene sostituito con l'istruzione filter (resource.instance_id == '12345'). Questo filtro associa le 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 tabella seguente mostra come viene risolta la variabile del modello per le query MQL:

Grafici e tabelle definiti da PromQL

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

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

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

In modo simile a 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. Per illustrare la sintassi, di seguito viene illustrato come utilizzare un'espressione regolare per determinare se il valore dell'etichetta instance_id contiene il valore della variabile del modello iid:

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

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

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:

Crea una dashboard

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

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

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

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 monitoring dashboards create --config-from-file=my-dashboard.json

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

Per ulteriori configurazioni di 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.

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

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

Elenco dashboard

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

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

gcloud monitoring dashboards list

Gli esempi restituiscono le dashboard personalizzate associate al tuo progetto.

Impagina la risposta dell'elenco

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

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

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

gcloud monitoring dashboards list --page-size=1

Ottieni dashboard

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

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

{
  "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 monitoring dashboards describe ${DASHBOARD_ID} --format=json

{
  "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 attuale, puoi richiamare il metodo dashboards.get e trovarlo nella risposta.

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 monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

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

Passaggi successivi

• Esempi di dashboard e layout
• Crea e gestisci dashboard personalizzate con la console Google Cloud