Questo documento descrive come creare e gestire le dashboard personalizzate e i widget al loro interno utilizzando la risorsa Dashboard
nell'API Cloud Monitoring.
Gli esempi riportati qui mostrano come gestire le dashboard utilizzando curl
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 offre un modo programmatico per gestire molte dashboard contemporaneamente.
L'endpoint supporta i seguenti metodi per gestire e configurare le dashboard:
dashboards.create
: crea una dashboarddashboards.delete
: elimina una dashboard specificatadashboards.list
: recupera un elenco di tutte le dashboard in un determinato progettodashboards.get
: recupera una dashboard specificatadashboards.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.
Prima di iniziare
Quando crei una dashboard, devi specificare i componenti o i widget che vuoi visualizzare, nonché il layout di questi widget. Puoi anche aggiungere filtri permanenti alla dashboard.
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 uguale larghezza 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 orizzontalmente in ogni riga.ColumnLayout
: divide lo spazio disponibile in colonne verticali e dispone un insieme di widget in verticale 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 presentare il componente nella dashboard. Una dashboard può avere più
widget. Esistono diversi 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 widgetXyChart
:Grafici a linee
Grafici a barre
Grafici ad area in pila
Mappe termiche
Grafici dell'analisi dei log
I 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 in grafico più metriche, puoi utilizzare entrambi gli assi Y.
PieChart
: visualizza l'ultimo valore di una metrica, in cui ogni serie temporale contribuisce a una sezione del grafico a torta.Scorecard
: mostra il valore più recente di una metrica e in che modo 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.
Grafico degli avvisi e widget degli incidenti:
AlertChart
: mostra il riepilogo di un criterio di avviso per condizione singola. Questo widget mostra i dati sotto forma di grafico a linee, indica la soglia ed elenca il numero di incidenti aperti.IncidentList
: visualizza un elenco di incidenti. Puoi configurare il widget in modo che mostri gli incidenti per criteri di avviso specifici o per tipi di risorse specifici.
Widget di log ed errori:
ErrorReportingPanel
: mostra i gruppi di errori archiviati nel progetto Google Cloud selezionato.LogsPanel
: mostra le voci di log con ambito a livello di progetto archiviate nel progetto Google Cloud attuale. Puoi configurare il widget in modo che mostri 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, questa deve avere un elemento
MosaicLayout
.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 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"
}
}
}
]
}
}
Filtri per la dashboard
Quando progetti una dashboard, potresti identificare diversi modi per visualizzare i dati visualizzati. Ad esempio, quando una dashboard mostra metriche per le istanze di macchine virtuali (VM), potresti voler visualizzare le metriche per tutte le VM e le metriche per una zona specifica. In questo tipo di situazione, consigliamo di creare un filtro permanente e impostare il valore predefinito di quel filtro sulla vista di uso più comune. 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 nella dashboard:
I filtri a livello di dashboard si applicano a tutti i widget su una dashboard che supportano l'etichetta del filtro e che non specificano un valore per l'etichetta.
Ad esempio, se un grafico include il filtro
zone = us-central1-a
, ignora un filtro della dashboard basato sull'etichettazone
. Analogamente, i grafici senza etichettazone
ignorano i filtri della dashboard con questa etichetta.Le variabili del 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 a quali widget viene applicata una variabile di modello.
Tutti i tipi di filtro sono rappresentati con la stessa struttura di dati.
Per ulteriori informazioni, vedi DashboardFilter
.
Ad esempio, quanto segue mostra 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 JSON visualizzato, la prima voce nella struttura dashboardFilters
riguarda 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 viene applicata. Per associare un widget a una variabile di modello, modifica 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.
Consulta le seguenti sezioni su come annotare i riquadri e i grafici dei log:
- 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 in modo da filtrare la visualizzazione in base al valore di una variabile del 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 la query sui log da visualizzare, la variabile del modello viene risolta. In questo esempio, se il valore della variabile di modello è "12345"
, ${iid}
viene sostituito con l'istruzione resource.labels."instance_id"="12345"
.
Inoltre, puoi includere in una query solo il valore di una variabile di 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 associare 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 selezioni il pulsante per aprire Esplora log, le variabili del modello vengono risolte prima dell'apertura di Esplora log.
La seguente tabella mostra in che modo la variabile del modello viene risolta dal riquadro dei log:
Sintassi | Valore selezionato |
Espressione del riquadro dei log risolti |
---|---|---|
${iid} |
12345 |
resource.labels."instance_id"="12345" |
${iid} |
* |
"" |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
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 la query per la serie temporale, la variabile del modello viene risolta. In questo esempio, se il valore della variabile di modello è "12345"
, ${iid}
viene sostituito con l'istruzione filter (resource.instance_id == '12345')
. Questo filtro corrisponde alle serie temporali che hanno un'etichetta denominata resource.instance_id
e solo quando il valore di questa etichetta è esattamente 12345
.
Se 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, quanto segue
mostra 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 di modello per le query MQL:
Sintassi | Valore selezionato |
Espressione MQL risolta |
---|---|---|
${iid} |
12345 |
filter (resource.instance_id == '12345') |
${iid} |
* |
filter (true) |
${iid.value} |
12345 |
12345 |
${iid.value} |
* |
.* |
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 la query per la serie temporale, la variabile del modello viene risolta. In questo esempio, se il valore della variabile di modello è "12345"
, ${iid}
viene sostituito con l'istruzione instance_id == '12345'
.
Analogamente 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 nell'ambito di un filtro definito con un'espressione regolare. Per illustrare la sintassi, quanto segue mostra come utilizzare un'espressione regolare per determinare se il valore dell'etichetta instance_id
contiene il valore della variabile modello iid
:
compute_googleapis_com:instance_cpu_utilization{ instance_id=~"${iid.value}" }
La seguente tabella mostra come viene risolta la variabile di modello per le query PromQL:
Sintassi | Valore selezionato |
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 di filtro:
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" ${iid}"
A differenza dei grafici definiti da 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 | Valore selezionato |
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, richiama il metodo dashboards.create
e fornisci 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}"
Protocollo
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:
- Completa i passaggi descritti in Ottieni la dashboard per scaricare la definizione della dashboard originale.
- Modifica il JSON restituito per rimuovere i campi
etag
ename
, quindi cambia il valore del campodisplayName
. - Esegui il comando per creare la dashboard.
Per saperne di più, consulta la documentazione di gcloud monitoring dashboards
create
.
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 Dashboard e layout di esempio.
Elimina dashboard
Per eliminare una dashboard personalizzata, richiama il metodo dashboards.delete
e specifica la dashboard da eliminare.
Protocollo
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}
Se l'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 saperne di più, consulta la documentazione di gcloud monitoring dashboards
delete
.
Elenco dashboard
Per elencare tutte le dashboard personalizzate che appartengono a un progetto, richiama 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 il comando gcloud monitoring
dashboards list
:
gcloud monitoring dashboards list
Per saperne di più, consulta la documentazione di gcloud monitoring dashboards
list
.
Gli esempi restituiscono le dashboard personalizzate associate al progetto.
Impagina la risposta all'elenco
Il metodo dashboards.list
supporta l'impaginazione, che
consente di acquisire 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
. Ad
esempio:
{ "dashboards" : [ { "displayName" : "Grid Layout Example", "gridLayout" : { "widgets" : [ { ... }, { ... }, { ... }, ] } } ] }, "nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"
Per ogni pagina rimanente, devi includere il valore 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, richiama 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 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 saperne di più, consulta la documentazione di gcloud monitoring dashboards
describe
.
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.
Protocollo
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}
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 saperne di più, consulta la documentazione di gcloud monitoring dashboards
update
.
Gli esempi aggiornano una dashboard personalizzata esistente utilizzando il file my-updated-dashboard.json
e restituiscono una copia dell'elenco della dashboard aggiornata. I dati restituiti includono un nuovo valore etag
.