Questa pagina descrive come fornire query MQL (Monitoring Query Language) all'API Cloud Monitoring.
Questa pagina non tratta la creazione delle query MQL. Per una serie di query di esempio, consulta la sezione Esempi. MQL Refererence fornisce un riferimento completo per il linguaggio.
Per informazioni generali sui criteri di avviso basati su MQL, consulta Criteri di avviso con MQL.
Utilizzo di MQL dall'API
Puoi fornire query MQL nelle seguenti posizioni nell'API Monitoring:
Per selezionare e manipolare i dati delle serie temporali utilizzando MQL, chiama il metodo
timeSeries.query. Per alcuni esempi, consulta la sezione Utilizzo ditimeSeries.query.Per selezionare e manipolare i dati delle serie temporali per i grafici, devi fornire la query a una specifica
TimeSeriesQueryquando chiami il metododashboards.create. Per un esempio, consulta Creazione di grafici.Per creare condizioni basate su MQL nei criteri di avviso, descrivi la condizione per il criterio di avviso con il tipo di condizione
MonitoringQueryLanguageConditionquando chiamialertPolicies.create. Per alcuni esempi, consulta la sezione Creazione di condizioni per i criteri di avviso.
Recupero dei dati con timeSeries.query in corso...
Per recuperare i dati delle serie temporali dall'API con una query MQL, utilizza il metodo timeSeries.query.
Il metodo timeSeries.query ha una struttura minima, simile alla seguente
in JSON:
{
"query": string
}
Per il valore del campo query, specifica una stringa in MQL, come mostrato nelle seguenti semplici query:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
}
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h"
}
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m"
}
Se la query crea una tabella di output non allineata, devi fornire una durata utilizzando l'operazione della tabella within quando chiami direttamente l'API. Strumenti di creazione di grafici come Metrics Explorer forniscono una durata predefinita delle query. La query nello snippet JSON seguente funziona nell'editor di codice MQL di Metrics Explorer, ma non va a buon fine se viene fornita direttamente all'API:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}
Con l'aggiunta di un'operazione tabella within alla query precedente, l'esempio precedente può essere fornito direttamente all'API:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}
Per fare esperimenti con l'API, puoi utilizzare lo strumento Explorer API nella pagina di riferimento di timeSeries.query.
Per un'introduzione allo strumento Explorer API, consulta Explorer API.
Un altro modo per provare l'API è inserire la query in un file di testo e quindi eseguirla utilizzando curl. L'esempio seguente passa la query
nel file query.json al metodo timeSeries.query:
curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query
Per ulteriori informazioni sull'utilizzo di curl, vedi Richiamare curl.
In caso di esito positivo, la query restituisce una tabella contenente la serie temporale richiesta. La tabella è divisa in due componenti:
timeSeriesDescriptordescrive le chiavi di etichetta, i valori delle etichette e i punti dati nella tabella. Non contiene dati, ma solo li descrive.timeSeriesDatacontiene i dati descritti nel descrittore della serie temporale. Questi dati vengono presentati sotto forma di array di coppie.- Il primo elemento della coppia,
labelValues, registra un insieme di valori per le etichette elencate nel descrittore della serie temporale. - Il secondo,
pointData, è un array incorporato di coppie valore/timestamp, che rappresenta i dati raccolti con l'insieme specificato di valori di etichetta.
- Il primo elemento della coppia,
La risposta, leggermente riformattata, ha il seguente aspetto:
[{
"timeSeriesTable": {
"timeSeriesDescriptor": {
"labelDescriptors": [
{ "key": "resource.project_id" },
{ "key": "resource.zone" },
{ "key": "resource.instance_id" },
{ "key": "metric.instance_name" }
],
"valueDescriptors": [
{
"key": "value.utilization",
"valueType": "DOUBLE",
"metricKind": "GAUGE"
}
],
"pointDescriptors": [
{
"key": "value.utilization",
"valueType": "DOUBLE",
"metricKind": "GAUGE"
}
]
},
"timeSeriesData": [
{
"labelValues": [
{ "stringValue": "632526624816" },
{ "stringValue": "us-central1-a" },
{ "stringValue": "5106847938297466291" },
{ "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
],
"pointData": [
{
"values": [
{
"doubleValue": 0.063896992710942874
}
],
"timeInterval": {
"startTime": "1969-12-31T23:59:59.999999Z",
"endTime": "2020-03-02T20:17:00Z"
}
},
{ ... additional value/timestamp pairs ...}
]
},
{ ... additional labelValue/pointData pairs ...},
]
}
Creazione di grafici
Puoi utilizzare il metodo dashboards.create per creare in modo programmatico le dashboard e i grafici che contengono.
L'unica differenza tra la creazione di grafici basati su MQL e altri grafici è il tipo di query TimeSeriesQuery che utilizzi per completare il set di dati del grafico.
Creazione di un grafico basato su MQL
Per le query MQL, utilizzala come valore del campo stringa timeSeriesQueryLanguage nell'array DataSet del grafico.
Di seguito è riportata una semplice definizione di dashboard che include MQL:
{
"displayName": "Dashboard for MQL chart (API)",
"gridLayout": {
"widgets": [
{
"title": "Min/Max Compute Engine CPU utilization",
"xyChart": {
"dataSets": [
{
"timeSeriesQuery": {
"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
},
"plotType": "LINE",
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
},
"chartOptions": {
"mode": "COLOR"
}
}
}
]
}
}
Nel progetto viene creata una dashboard denominata "Dashboard per grafico MQL (API)". La dashboard contiene un grafico chiamato "Utilizzo CPU Min/Max di Compute Engine", che mostra due righe, una per i valori più elevati e una per quelli più bassi.
Per maggiori informazioni su questa query di esempio, consulta Combinare le selezioni con
union.
Creazione di un grafico
Puoi inserire il JSON della dashboard in un file e poi passare il file a gcloud beta monitoring dashboards create oppure utilizzare curl per pubblicarlo su https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards.
Per ulteriori esempi, consulta la sezione Creare una dashboard.
Per ulteriori informazioni sull'utilizzo di curl, vedi Richiamare curl.
Per informazioni generali sulla creazione di grafici e dashboard, consulta Gestire le dashboard per API. Per il materiale di riferimento, consulta
Dashboards.
Creazione di condizioni per i criteri di avviso
Puoi utilizzare il metodo alertPolicies.create per
creare criteri di avviso a livello di programmazione.
L'unica differenza tra la creazione di criteri di avviso basati su MQL e altri criteri di avviso è il tipo di Condition che utilizzi. In caso contrario, puoi creare questi criteri come qualsiasi altro criterio di avviso.
Di seguito è riportata una query MQL semplice per una condizione del criterio di avviso che verifica l'utilizzo della CPU di Compute Engine superiore al 15%:
fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'
Per saperne di più sull'operazione di avviso MQL condition, consulta
Criteri di avviso con MQL.
Creazione del criterio di avviso
Per creare un criterio di avviso basato su una query MQL, utilizza il tipo di condizione AlertPolicy MonitoringQueryLanguageCondition.
MonitoringQueryLanguageCondition ha la seguente struttura:
{
"query": string,
"duration": string,
"trigger": {
object (Trigger)
}
}
Il valore del campo query è una stringa di query di avviso MQL in formato conciso o rigoroso. Gli esempi in questo documento sono
in forma concisa. Per ulteriori informazioni sul formato restrittivo, consulta Query in formato restrittivo.
Il campo duration specifica il periodo di tempo durante il quale ogni valutazione della query deve generare un valore true prima dell'attivazione del criterio di avviso. Per maggiori informazioni, consulta
Comportamento dei criteri di avviso basati su metriche.
Il valore deve essere un numero di minuti, espresso in secondi; ad esempio, 600s per una durata di 10 minuti.
Il campo trigger specifica quante serie temporali devono soddisfare la condizione durante il periodo duration, espresso sotto forma di conteggio o percentuale. Il
valore predefinito è un conteggio pari a 1. Per saperne di più,
consulta la pagina Trigger.
Per l'esempio di query di avviso, con una durata di 10 minuti e un numero di trigger pari a 1, la struttura ha il seguente aspetto:
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
"duration": "600s",
"trigger" : {
"count": 1
}
}
Utilizza questa struttura come valore di un campo conditionMonitoringQueryLanguage in una condizione, che a sua volta è incorporata in una struttura di criteri di avviso.
Per saperne di più su queste strutture, consulta AlertPolicy.
Di seguito è riportato un criterio minimo completo con una condizione MonitoringQueryLanguageCondition in JSON:
{
"displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
"combiner":"OR",
"conditions":[
{
"displayName":"MQL-based utilization condition, API",
"conditionMonitoringQueryLanguage":
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
"duration": "600s",
"trigger" : {
"count": 1
},
},
}
],
}
Creazione di un criterio di avviso
Per creare il criterio, puoi inserire il JSON del criterio di avviso in un file e poi passarlo a gcloud alpha monitoring policies create o utilizzare curl per pubblicarlo su https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.
Per ulteriori informazioni sull'API Monitoring per i criteri di avviso, consulta Gestione dei criteri di avviso tramite API.
Per ulteriori informazioni sull'utilizzo di curl, vedi Richiamare curl.
Richiamo di curl in corso...
Ogni chiamata curl include un insieme di argomenti, seguiti dall'URL di una risorsa API. Gli argomenti comuni includono
un ID progetto Google Cloud e un token di autenticazione. Questi valori sono rappresentati qui dalle variabili di ambiente PROJECT_ID e TOKEN.
Potresti anche dover specificare altri argomenti, ad esempio per specificare il tipo di richiesta HTTP (ad esempio -X DELETE). La richiesta predefinita è GET, pertanto gli esempi non la specificano.
Ogni chiamata curl ha questa struttura generale:
curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
Per utilizzare curl, devi specificare l'ID progetto e un token di accesso. Per ridurre la digitazione e gli errori, puoi inserirli nelle variabili di ambiente
e trasmetterli a curl in questo modo.
Per impostare queste variabili:
Crea una variabile di ambiente che contenga l'ID del progetto di ambito delle metriche. Questi passaggi chiamano la variabile
PROJECT_ID:PROJECT_ID=a-sample-projectEsegui l'autenticazione in Google Cloud CLI:
gcloud auth loginFacoltativo. Per evitare di dover specificare l'ID progetto con ogni comando
gcloud, imposta l'ID progetto come predefinito utilizzando gcloud CLI:gcloud config set project ${PROJECT_ID}Crea un token di autorizzazione e acquisiscilo in una variabile di ambiente. Questi passaggi chiamano la variabile
TOKEN:TOKEN=`gcloud auth print-access-token`Devi aggiornare periodicamente il token di accesso. Se i comandi che hanno funzionato improvvisamente indicano che non sei autenticato, invia di nuovo il comando.
Per verificare di aver ricevuto un token di accesso, ripeti la variabile
TOKEN:echo ${TOKEN} ya29.GluiBj8o....