Questo documento descrive come creare e gestire
le 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 mostrare come utilizzare Google Cloud CLI.
Sebbene tu possa anche gestire le dashboard personalizzate tramite
Google Cloud, l'API fornisce una
il modo programmatico per gestire molte dashboard contemporaneamente.
L'endpoint supporta i seguenti metodi per la gestione e la configurazione delle dashboard:
dashboards.create
: crea una dashboarddashboards.delete
: elimina una dashboard specificatadashboards.list
: recupera un elenco di tutte di 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 il metodo
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 nella dashboard.
Layout della dashboard
I layout definiscono l'ordine in cui vengono ordinati i componenti di una dashboard. L'API fornisce con i seguenti layout:
GridLayout
: consente di dividere lo spazio disponibile in verticale di stessa larghezza e dispone un insieme di widget utilizzando strategia.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
presente il componente nella dashboard. Una dashboard può avere più di una
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 widgetXyChart
: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: specifica che una metrica si riferisce all'asse Y sinistro o destro. Quando più in un grafico, puoi utilizzare entrambi gli assi Y.
PieChart
: visualizza il valore più recente di una metrica. in cui ogni serie temporale contribuisce con una sezione alla torta.Scorecard
: visualizza il valore più recente di una metrica e la relazione tra questo valore e una o più soglie.TimeSeriesTable
: mostra il valore più recente di una metrica. Puoi ordinare la tabella in base alle colonne, filtrarla e aggiungere rimuovere le colonne dalla visualizzazione.
Grafici per i criteri di avviso e i widget degli incidenti:
AlertChart
: mostra un riepilogo di una singola condizione criterio di avviso. Questo widget visualizza i dati sotto forma di grafico a linee, mostra della 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 per di risorse specifiche.
Widget di log ed errori:
ErrorReportingPanel
: display gruppi di errori archiviati nei progetto Google Cloud.LogsPanel
: display voci di log con ambito a livello di progetto archiviate nell' progetto Google Cloud attuale. Puoi configurare il widget in modo che mostri le voci di log archiviati in progetti Google Cloud accessibili tramite ambito delle metriche.
Widget di testo e organizzazione:
Per includere questi widget in una deve avere un elemento
MosaicLayout
.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 in della dashboard, viene creata una voce nella tabella contenuti.Text
: mostra i contenuti testuali, come testo non elaborato o come Stringa Markdown.
Oltre a questi oggetti, puoi anche aggiungere uno spazio vuoto segnaposto in una dashboard.
Ad esempio, quanto segue mostra la rappresentazione JSON di un
Widget XyChart
di cui è configurato l'asse Y destro:
{
"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,
potresti aggiungere l'etichetta playbook
per indicare che la dashboard
contiene informazioni per aiutarti a risolvere gli errori.
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
su una dashboard, imposta key
sul nome dell'etichetta e
value
su una stringa vuota.
Filtri per la dashboard
Quando progetti una dashboard, potresti identificare diversi modi per visualizzare il i dati mostrati nella dashboard. Ad esempio, quando una dashboard mostra metriche per le istanze di macchine virtuali (VM), può essere utile visualizzare e potresti voler visualizzare le metriche per una zona specifica. In questo tipo di situazione, consigliamo di creare un filtro permanente e impostare il valore predefinito valore di quel filtro alla vista più usata. I filtri permanenti possono si applicano ad 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
, 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 con nome 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 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
è 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. 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 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 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 far corrispondere le voci di log che hanno un payload JSON che contiene stringa:
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 da 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
sia stato risolto. In questo esempio, se il valore della variabile del modello
è "12345"
, il valore ${iid}
viene sostituito con l'istruzione
filter (resource.instance_id == '12345')
. Questo filtro corrisponde al tempo
serie con l'etichetta resource.instance_id
e solo quando il valore
di quell'etichetta è esattamente 12345
.
Per filtrare le serie temporali utilizzando un'espressione regolare:
configurare la query in modo da includere solo il valore della variabile del modello.
Per spiegare la sintassi, procedi come riportato di seguito
mostra come utilizzare un'espressione regolare per determinare se il valore dell'attributo
L'etichetta resource.instance_id
contiene il valore della variabile di 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 MQL query:
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 da 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
sia stato risolto. In questo esempio, se il valore della variabile del modello
è "12345"
, il valore ${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. 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 di 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, richiama il metodo
dashboards.create
e fornisci il metodo
layout e i widget da visualizzare nella dashboard.
Quando crei una dashboard, l'API genera automaticamente
dashboard_id
. Se vuoi specificare un valore dashboard_id
personalizzato, puoi impostare il valore
Campo name
di un oggetto Dashboard
. Il formato del campo del nome è simile a quello
le seguenti:
"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:
- Completa i passaggi descritti in Scarica la dashboard per scaricare la definizione di la dashboard originale.
- Modifica il JSON restituito per rimuovere
etag
ename
e modifica il valore del campodisplayName
. - 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 ulteriori 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
a
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}
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 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 al
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, usa il comando gcloud monitoring
dashboards list
:
gcloud monitoring dashboards list
Per ulteriori informazioni, consulta la documentazione di riferimento di 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
ti consente di visualizzare i risultati una pagina alla volta anziché tutti in una volta.
Protocollo
Per la pagina iniziale dell'elenco dei risultati, specifica il parametro di ricerca pageSize
con 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 il nextPageToken
. Per
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
Metodo dashboards.get
, qualificato con l'ID dashboard.
Protocollo
Per ottenere una dashboard personalizzata specifica, invia l'ID dashboard al
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 ulteriori informazioni, consulta la documentazione di riferimento di 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 la documentazione di riferimento di gcloud monitoring dashboards
update
.
Gli esempi aggiornano una dashboard personalizzata esistente utilizzando
my-updated-dashboard.json
file e restituisci una copia del file aggiornato
nella dashboard. I dati restituiti includono un nuovo valore etag
.