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 offre suggerimenti, rilevamento degli errori e altro supporto per la creazione di query MQL valide.

Questa pagina non copre il linguaggio MQL. Per una serie di esempi e per ulteriori informazioni sul linguaggio, consulta gli Esempi e Informazioni sul linguaggio MQL. Riferimento MQL fornisce un riferimento completo per il linguaggio.

Accesso all'editor di codice

Per accedere all'editor di codice quando utilizzi Metrics Explorer, procedi nel seguente modo:

1. Nel pannello di navigazione della console Google Cloud, seleziona Monitoring e poi  Metrics Explorer:

   Vai a Metrics Explorer

2. Nella barra degli strumenti del riquadro del generatore di query, seleziona il pulsante il cui nome è  MQL o  PromQL.
3. Verifica che MQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che consente di formattare la query.

Puoi utilizzare 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 nella casella di testo e fai clic su Esegui query:

Completamento automatico

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

Per spostarti nell'elenco di opzioni, utilizza i tasti freccia. Premendo Enter viene inserita l'opzione 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 sono presenti errori nella query che interferiscono con i suggerimenti di completamento automatico, durante la digitazione vengono visualizzati messaggi di errore. In caso contrario, i messaggi di errore vengono visualizzati quando esegui la query.

Piegatura del codice

L'editor fornisce la funzionalità di code folding, ovvero la possibilità di comprimere segmenti delle query, per consentirti di nasconderli temporaneamente.

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

Trova e sostituisci

L'editor supporta la 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 in che modo interagisce 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 abilitare l'opzione di esecuzione automatica, utilizza il pulsante di attivazione/disattivazione Esecuzione automatica. Quando questa opzione è abilitata, l'editor funziona come segue:

• Il pulsante Esegui query non è 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.

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

Salvare i grafici

Da Metrics Explorer

Dall'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 è attivata, 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 che hai eseguito.

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

3. Per continuare a salvare il grafico:

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

Da una dashboard

Per salvare un grafico che aggiungi a una dashboard:

1. Assegna al grafico un titolo descrittivo.

2. Se l'opzione di esecuzione automatica non è attivata, 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 che hai eseguito.

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

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 query. Qualsiasi testo di query nell'editor viene ignorato, ma hai la possibilità di salvarlo negli appunti.

Visualizza le query in formato restrittivo

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

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

Intervalli di tempo, grafici e 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, per visualizzare i dati della settimana precedente, seleziona Ultima settimana dal selettore dell'intervallo di tempo. Puoi anche indicare un'ora di inizio e di fine oppure un'ora in cui visualizzare le informazioni.

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 tempo del grafico. Questo selettore è il modo predefinito per impostare il periodo di tempo. Per modificare il periodo di tempo, seleziona un'opzione diversa nel grafico. Se selezioni, ad esempio, una settimana, la query restituisce i dati da adesso a una settimana fa.

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

Utilizzo di within per la selezione dell'intervallo di tempo

Puoi specificare l'intervallo di tempo per la query in modo esplicito nella query utilizzando l'operazione within. Questa operazione determina l'intervallo di dati restituiti. Se la query include un'operazione within, le opzioni di selezione temporale sul 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 la selezione temporale esplicita se vuoi usare il metodo API timeSeries.query per inviare la query. Per ulteriori informazioni, consulta Utilizzare MQL dall'API Monitoring.

Impostazioni del tempo e grafici salvati

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

1. La query fornita nell'editor viene convertita in una forma canonica, o rigida. La conversione non cambia il significato della query, ma rende espliciti gli elementi presupposti nella query, come i nomi completi delle colonne o le operazioni di allineamento. Per ulteriori informazioni, consulta Query in formato restrittivo.

2. La selezione dell'intervallo di tempo nella query viene rimossa. I grafici sulle dashboard condividono un selettore temporale e le modifiche al selettore vengono applicate 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 prevede 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 produce solo punti i cui timestamp sono compresi nell'ultima ora, motivo per cui questa operazione sostituisce le opzioni del selettore di ora del grafico.

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

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

  • 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 disponibile. Per la funzione di allineamento delta, la finestra di allineamento e il periodo devono essere gli stessi; se viene concessa una finestra di allineamento esplicita, l'operazione every, se fornita, deve essere d'accordo. 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 da software di terze parti. Il software di creazione di grafici di Monitoring ignora l'operazione graph_period nelle query, impostando il periodo dei punti in base alla larghezza temporale 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, fai clic su Statistiche query per visualizzare il periodo del grafico.

La relazione tra il periodo di allineamento delle 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 delle query è vicino al periodo del grafico, il grafico rappresenta ogni serie temporale grafica con una singola linea. Se il periodo di allineamento della query è inferiore alla metà del periodo del grafico del grafico, quest'ultimo include un'area ombreggiata intorno a ogni linea. Questa regione, chiamata banda min/max, mostra l'intervallo di valori che ha prodotto il valore medio.

Supponiamo, ad esempio, che la seguente query MQL sia semplice:

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

Questa query restituisce l'uilizzazione media 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 è di un'ora, indicato in un chip. Per la query di esempio, il periodo del grafico e il periodo allineamento sono uguali. Eseguendo la query, si produce 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 produce un grafico che include le bande minime e massime:

Le linee del grafico rappresentano graficamente un periodo di un'ora, basato sulla 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 ogni punto del grafico di un'ora.

Se l'operazione every viene omessa, il periodo di allineamento delle query predefinito è il valore della finestra di allineamento o, se la finestra di allineamento non è specificata, 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 Gestire i criteri di avviso, ma quando crei la condizione per il criterio di avviso, utilizzi l'editor di codice anziché il selettore di metriche basate su modulo.

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

Conversione di query

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

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

1. Nella barra degli strumenti del riquadro del generatore di query, seleziona il pulsante il cui nome è  MQL o  PromQL.
2. Verifica che MQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che consente di formattare la query.

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

Prendi in considerazione una richiesta molto semplice, ad esempio "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 modulo:

La metrica e i tipi 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 risorse specificati ed esegue l'allineamento delle tariffe a intervalli di 1 minuto. La query convertita è in formato strict.

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