Utilizzare l'editor di codice per MQL

Questa sezione descrive le funzionalità dell'editor di codice per Monitoring Query Language (MQL). L'editor è disponibile nella console Google Cloud e fornisce suggerimenti, rilevamento degli errori e altro tipo di assistenza per la creazione di query MQL valide.

Questa pagina non riguarda il linguaggio MQL; per un insieme di esempi e per ulteriori informazioni sul linguaggio, consulta Esempi e Informazioni sul linguaggio MQL. Riferimento MQL fornisce un riferimento completo per la lingua.

Accesso all'editor di codice

Per accedere all'editor di codice quando utilizzi Esplora metriche, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina  Esplora metriche:

   Vai a Esplora metriche

   Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

2. Nella barra degli strumenti del riquadro di creazione di query, seleziona il pulsante con il nome  MQL o  PromQL.
3. Verifica che sia selezionato MQL nell'opzione di attivazione/disattivazione Lingua. L'opzione di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che ti consente di formattare la query.

Segui passaggi simili per accedere all'editor di codice quando crei un grafico in una dashboard.

Utilizzo dell'editor di codice

Per utilizzare l'editor di codice, digita la query nell'editor e fai clic su Esegui query:

Completamento automatico

Mentre digiti la query, l'editor visualizza un elenco di completamenti sintatticamente validi. Puoi visualizzare manualmente il menu del completamento automatico premendo Control+Space e chiuderlo premendo Escape.

Per spostarti nell'elenco delle opzioni, utilizza i tasti freccia. Premi Enter per inserire la scelta selezionata.

Per inserire il prefisso comune a tutte le opzioni disponibili, premi Tab.

Messaggi di errore

I messaggi di errore vengono visualizzati nella parte inferiore del riquadro dell'editor.

Se nella query sono presenti errori che interferiscono con i suggerimenti di completamento automatico, durante la digitazione vengono visualizzati messaggi di errore. Altrimenti, vengono visualizzati messaggi di errore quando esegui la query.

Piegatura del codice

L'editor offre la possibilità di comprimere i segmenti delle query in modo da nasconderli temporaneamente dalla visualizzazione.

L'editor indica i segmenti pieghevoli della query con l'accento circonflesso accanto ai numeri di riga, come mostrato nello screenshot seguente:

Trova e sostituisci

L'editor supporta una funzionalità Trova e sostituisci. Per trovare e, facoltativamente, sostituire i termini nella query, premi Control+F (o Command+F su Mac). Il seguente screenshot mostra la funzionalità:

Controlli dell'editor

L'editor dispone di due controlli che determinano la sua modalità di interazione con la query.

Per impostazione predefinita, la query viene eseguita solo quando fai clic su Esegui query. Puoi configurare l'editor di codice in modo che esegua automaticamente la query durante la digitazione, ma questa opzione è disattivata per impostazione predefinita.

Per attivare l'opzione di esecuzione automatica, utilizza il pulsante di attivazione/disattivazione Esecuzione automatica. Quando questa opzione è abilitata, l'editor funziona nel seguente modo:

• Il pulsante Esegui query non viene visualizzato.
• I messaggi di errore vengono visualizzati continuamente durante la digitazione.

• Se il cursore si trova alla fine di una query incompleta ma priva di errori, l'editor mostra un triangolo giallo nella barra di controllo. Se c'è spazio, viene visualizzato anche il testo Query incompleta.

  L'editor di codice non tenta di valutare le query incomplete.

È presente anche una barra di controllo tra l'editor di codice e l'area del grafico. Utilizza questa barra per modificare le dimensioni relative delle due regioni.

Salva grafici

Da Esplora metriche

Nell'editor di codice in Metrics Explorer puoi salvare il grafico in una dashboard. Per salvare il grafico:

1. Se l'opzione di esecuzione automatica non è abilitata, esegui la query facendo clic su Esegui query prima di salvare il grafico. Se non esegui prima la query, l'editor di codice salva l'ultima query eseguita.

2. Fai clic su Salva grafico. Una finestra di dialogo ti informa che il salvataggio del grafico sostituisce la query con una forma rigida. Per ulteriori informazioni, consulta la sezione Query in formato rigido.

3. Per continuare a salvare il grafico:

   1. Assegna al grafico un titolo descrittivo.
   2. Seleziona la dashboard per il nuovo grafico.
   3. Fai clic su Salva nella finestra di dialogo.

Da una dashboard

Per salvare un grafico che stai aggiungendo a una dashboard, segui questi passaggi:

1. Assegna al grafico un titolo descrittivo.

2. Se l'opzione di esecuzione automatica non è abilitata, esegui la query facendo clic su Esegui query prima di salvare il grafico. Se non esegui prima la query, l'editor di codice salva l'ultima query eseguita.

3. Fai clic su Salva. Una finestra di dialogo ti informa che il salvataggio del grafico sostituisce la query con una forma rigida. Per ulteriori informazioni, consulta la sezione Query in formato rigido.

4. Fai clic su Salva nella finestra di dialogo per salvare il grafico e tornare alla dashboard.

Esci dall'editor di codice

Per uscire dall'editor di codice senza salvare un grafico o una condizione, fai clic su Torna al widget del selettore di query. Qualsiasi testo della query nell'editor viene ignorato, ma hai la possibilità di salvarlo negli appunti.

Visualizza le query in formato rigido

Per visualizzare una query in formato rigido quando utilizzi l'editor di codice, fai clic su Altre opzioni e seleziona Visualizza in formato rigido.

Per ulteriori informazioni, consulta la sezione Query in formato rigido.

Intervalli di tempo, grafici e l'editor di codice

Ad eccezione delle query MQL utilizzate nelle condizioni per i criteri di avviso, le query MQL nell'editor di codice devono includere un intervallo di tempo. L'intervallo di tempo specifica il sottoinsieme di dati da restituire come parte della query. L'intervallo di tempo può essere espresso in modo implicito utilizzando il selettore dell'intervallo di tempo del grafico o in modo esplicito nel testo della query MQL.

Per impostazione predefinita, il selettore dell'intervallo di tempo è impostato su un'ora.

Per modificare l'intervallo di tempo di un grafico, utilizza il selettore dell'intervallo di tempo. Ad esempio, se vuoi visualizzare i dati relativi alla settimana precedente, seleziona Ultima settimana dal selettore dell'intervallo di tempo. Puoi anche specificare un'ora di inizio e di fine o indicare un orario in cui visualizzare la cronologia.

Per informazioni sulla creazione di criteri di avviso con l'editor di codice, consulta Creazione di criteri di avviso MQL.

Utilizzare le impostazioni del grafico per la selezione temporale

Puoi impostare il periodo di tempo per una query utilizzando il selettore di data e ora del grafico. Questo selettore è il modo predefinito per impostare il periodo di tempo. Per modificare il periodo di tempo, seleziona un'altra opzione di tempo sul grafico. Se selezioni, ad esempio, una settimana, la query restituisce i dati relativi al periodo trascorso da adesso a una settimana prima.

Quando utilizzi questo meccanismo predefinito, non devi specificare un intervallo di tempo esplicito nel testo della query. Il valore sul grafico è utilizzato in modo implicito.

Utilizzo di within per la selezione dell'intervallo di tempo

Puoi specificare l'intervallo di tempo della query in modo esplicito nella query utilizzando l'operazione within. Questa operazione determina l'intervallo dei dati restituiti. Se la query include un'operazione within, le opzioni di selezione dell'ora nel grafico vengono disabilitate e viene utilizzato l'intervallo di tempo specificato nella query.

Se rimuovi un'operazione within esplicita dalla query, le opzioni del grafico vengono riattivate automaticamente, in modo che la query includa sempre un periodo di tempo.

Devi utilizzare una selezione temporale esplicita se vuoi utilizzare il metodo API timeSeries.query per inviare la query. Per maggiori informazioni, consulta Utilizzo di MQL dall'API Monitoring.

Impostazioni di tempo e grafici salvati

Se utilizzi MQL per creare un grafico e poi lo salvi in una dashboard, si verificano due cose alla query:

1. La query che hai fornito nell'editor viene convertita in forma canonica. La conversione non cambia il significato della query, ma realizza elementi espliciti che vengono presupposti nella query, come nomi completi delle colonne o operazioni di allineamento. Per maggiori informazioni, consulta la sezione Query in formato rigido.

2. La selezione dell'intervallo di tempo nella query viene rimossa. I grafici sulle dashboard condividono un selettore di orario e le modifiche al selettore si applicano a tutti i grafici nella dashboard. Pertanto, il selettore dell'intervallo di tempo della query originale non è più necessario.

Per informazioni sulla gestione delle dashboard e sulla modifica dei grafici, consulta Gestire le dashboard personalizzate.

Query, allineamento e periodi di visualizzazione

MQL include una serie di operazioni potenzialmente poco chiare che specificano i periodi di tempo. Le seguenti operazioni sono correlate all'intervallo di una query:

• within: specifica la finestra di output della query. Questa operazione determina la quantità di dati restituiti. Se, ad esempio, specifichi within 1h, la query genera solo punti i cui timestamp rientrano nell'ultima ora, motivo per cui questa operazione sostituisce le opzioni del selettore dell'ora del grafico.

• Le seguenti operazioni si riferiscono al periodo di allineamento delle tabelle di output. Entrambe richiedono una tabella allineata come input oppure forniscono un valore predefinito:

  • every: specifica il periodo per l'output della tabella allineato.

  • window: specifica la finestra per le operazioni di allineamento.

  In entrambi i casi, se un'operazione align viene fornita con una finestra di allineamento esplicita, deve corrispondere al periodo specificato per l'operazione window, se fornito. Per la funzione di allineamento delta, la finestra di allineamento e il punto devono essere uguali; se viene specificata una finestra di allineamento esplicita, l'operazione every, se specificata, deve corrispondere. In tutti i casi, la finestra di allineamento deve essere grande almeno quanto il periodo di allineamento o i dati di input verranno ignorati.

MQL ha anche un'operazione graph_period, che specifica il periodo dei punti di output per i grafici. Questa operazione è utile nelle query inviate all'API il cui output viene rappresentato in un grafico da software di terze parti. Il software per i grafici di Monitoring ignora l'operazione graph_period nelle query, impostando il periodo di punti in base alla larghezza nel tempo del grafico di output.

Nei grafici di Monitoring, il periodo del grafico viene impostato in base al valore del selettore dell'intervallo di tempo del grafico e al numero massimo di punti che un grafico può visualizzare. Ad esempio, se selezioni una settimana, il periodo del grafico potrebbe essere di un'ora. Per i grafici sulle dashboard, per visualizzare il periodo del grafico, fai clic su Statistiche query.

La relazione tra il periodo di allineamento della query e il periodo del grafico può modificare l'aspetto di un grafico. Questa relazione è descritta nella sezione seguente.

Bande min/max

Quando il periodo di allineamento della query si avvicina al periodo del grafico, quest'ultimo rappresenta ogni serie temporale tracciata con una singola linea. Se il periodo di allineamento della query è inferiore alla metà del periodo del grafico, quest'ultimo include un'area ombreggiata attorno a ogni linea. Questa regione, chiamata banda min/max, mostra l'intervallo di valori che ha prodotto il valore medio.

Ad esempio, supponi la seguente query MQL:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

Questa query restituisce l'utilizzo medio della CPU delle VM per zona, con un periodo di allineamento di un'ora.

Se il selettore di tempo del grafico è impostato su una settimana, il periodo del grafico è un'ora, indicato in un chip. Per la query di esempio, il periodo del grafico e il periodo di allineamento sono uguali. La query genera un grafico simile al seguente:

Ad esempio, se modifichi il periodo di allineamento passato all'operazione every da 1h a 1m nella query precedente, la query genera un grafico che include le bande min/max:

Le linee del grafico sono rappresentate su un grafico con un periodo di un'ora, in base alla settimana selezionata per il grafico, pertanto le linee sono le stesse dell'esempio precedente. Tuttavia, la query produce un punto ogni minuto, quindi le bande min/max mostrano l'intervallo di valori di un minuto della query che rientrano in ciascun punto del grafico di un'ora.

Se l'operazione every viene omessa, il periodo di allineamento della query predefinito corrisponde al valore della finestra di allineamento oppure, se la finestra di allineamento non è specificata, a un minuto.

Criteri di avviso basati su MQL

Puoi anche utilizzare MQL e l'editor di codice per creare query da utilizzare nei criteri di avviso.

Per creare un criterio di avviso basato su MQL dalla console Google Cloud, segui i consueti passaggi per creare il criterio, descritti in Gestione dei criteri di avviso, ma quando crei la condizione per il criterio di avviso, utilizzi l'editor di codice anziché il selettore di metriche basato su modulo.

Per saperne di più, consulta la sezione Creazione di criteri di avviso MQL.

Conversione query

Puoi utilizzare il selettore di metriche per i grafici o in Metrics Explorer per creare una query e convertirla in MQL. La query MQL corrispondente viene mostrata nell'editor.

Per convertire una query basata su menu in MQL, quando utilizzi Metrics Explorer, segui questi passaggi:

1. Nella barra degli strumenti del riquadro di creazione di query, seleziona il pulsante con il nome  MQL o  PromQL.
2. Verifica che sia selezionato MQL nell'opzione di attivazione/disattivazione Lingua. L'opzione di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che ti consente di formattare la query.

Per convertire una query basata su modulo in MQL, fai clic su MQL quando visualizzi un grafico in una dashboard.

Consideriamo una richiesta molto semplice, come "Ottieni l'utilizzo della CPU dalle mie istanze VM di Compute Engine". Questa query riguarda il tipo di risorsa monitorata gce_instance e il tipo di metrica compute.googleapis.com/instance/cpu/usage_time.

Il seguente screenshot mostra questa query nel selettore di metriche basate su moduli:

I tipi di metrica e di risorse monitorate sono stati inseriti manualmente. Tutti gli altri campi hanno valori predefiniti.

Il seguente screenshot mostra il risultato della conversione della selezione basata su modulo in una query MQL:

La query MQL recupera le serie temporali per i tipi di metrica e di risorse specificati ed esegue l'allineamento della frequenza a intervalli di 1 minuto. La query convertita è in formato restrittivo.

Nota: non puoi riconvertire la rappresentazione MQL in impostazioni del selettore delle metriche basate sul modulo. MQL supporta query che non puoi creare con il selettore delle metriche. Quando esci dall'editor di codice, il testo della query viene scartato se non lo salvi.