Crea e salva le query utilizzando il linguaggio di query di Logging

Questo documento descrive come recuperare e analizzare i log quando si utilizza Esplora log scrivendo query nel campo dell'editor di query ed effettuando selezioni dai menu di filtro utilizzando le opzioni incluse nelle voci di log. Le query che crei vengono scritte nel linguaggio di query di Logging.

Puoi anche salvare le query nella pagina Esplora log o utilizzando il metodo dell'API Logging savedQueries.create.

Prima di iniziare

• Per creare query, devi disporre delle autorizzazioni per leggere i dati di log. Queste autorizzazioni sono incluse nel ruolo Visualizzatore Logging (roles/logging.viewer). Per maggiori dettagli sulle autorizzazioni IAM necessarie, vedi Autorizzazioni per la console Google Cloud.

• Per creare e utilizzare query private, il tuo ruolo Identity and Access Management deve includere le autorizzazioni logging.queries.{list, create, get, update, delete}.

• Per creare e utilizzare query condivise, il tuo ruolo Identity and Access Management deve includere le autorizzazioni logging.queries.{listShared, share, getShared, updateShared, deleteShared}.

Creazione di query

Per creare query utilizzando la console Google Cloud, segui questi passaggi:

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

   Vai a Esplora log

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

2. Seleziona il progetto Google Cloud o un'altra risorsa Google Cloud per cui vuoi visualizzare i log.

   Per visualizzare i log che stai inviando da un account Amazon Web Services (AWS) a Logging, seleziona il progetto connettore AWS nel selettore di risorse della console Google Cloud, quindi utilizza Esplora log. Il progetto del connettore AWS archivia il nome della risorsa Amazon (ARN) per l'account AWS e lo collega ai servizi Google Cloud. Per ulteriori informazioni, consulta Raccogliere metriche dagli account AWS.

3. Utilizza il riquadro Query per creare la tua query.

   

   Il riquadro Query fornisce diversi modi per creare ed eseguire espressioni di query:

   • Cerca il testo in tutti i campi del log.
   • Seleziona le opzioni dai menu dei filtri.
   • Scrivere o modificare le query utilizzando l'editor di query.
   • Puoi visualizzare, modificare o eseguire le query nelle schede Recenti, Salvati, Suggeriti e Raccolta.

Cerca testo nei campi dei log

Per cercare il testo in tutti i campi dei log e trovare tutte le voci di log corrispondenti, inserisci i termini di ricerca nel campo di ricerca:

Puoi cercare parole e frasi, e i termini di ricerca possono includere operatori booleani ed espressioni regolari:

• Per eseguire una ricerca sensibile alle maiuscole, devi utilizzare un'espressione regolare.

• Per eseguire una ricerca senza distinzione tra maiuscole e minuscole lungo i confini dei token, inserisci i termini di ricerca senza accento grave o virgolette.

  Ad esempio, per cercare voci di log che contengono la parola hello e la parola world, inserisci hello world. Questo comando, che viene convertito in SEARCH("hello world"), corrisponde alle voci di log che contengono i token hello e world, in qualsiasi ordine. Poiché la ricerca non è sensibile alle maiuscole, la ricerca corrisponde anche a una voce di log che contiene i token Hello e World. La ricerca non corrisponde al token worlds.

• Per eseguire una ricerca senza distinzione tra maiuscole e minuscole di una frase lungo i confini del token, aggrega la frase tra apici inversi.

  Ad esempio, per cercare la frase hello world, inserisci `hello world`. Questo comando, convertito in SEARCH("`hello world`"), corrisponde alle voci di log contenenti il token hello world. La ricerca non corrisponde al token hello worlds.

• Per eseguire una ricerca senza distinzione tra maiuscole e minuscole di una sottostringa, racchiudi il testo tra virgolette doppie. Ad esempio, "hello world" corrisponde a Hello World e Hello world. La stessa query corrisponde anche a hello worlds, perché la ricerca non viene eseguita lungo i limiti dei token.

  Nota: le ricerche di sottostringhe sono più lente di quelle basate su token. Pertanto, ti consigliamo di utilizzare ricerche basate su token, se possibile.

Per visualizzare i termini di ricerca all'interno dell'espressione di query, attiva Mostra query.

Dopo aver inserito i termini di ricerca, fai clic su Esegui query o premi il tasto Invio. I risultati della query vengono visualizzati nel riquadro Risultati delle query.

Operatori booleani

Le voci del campo di ricerca vengono convertite in espressioni booleane che specificano un sottoinsieme di tutte le voci di log nella risorsa Google Cloud selezionata.

Il campo di ricerca supporta l'utilizzo degli operatori booleani AND, OR e NOT. Quando utilizzi gli operatori booleani nelle espressioni di ricerca, tieni presente quanto segue:

• Non puoi utilizzare le parentesi per nidificare le regole. Tutte le parentesi dell'espressione di ricerca vengono analizzate come termini di ricerca.
• Devi usare le maiuscole per gli operatori booleani. and, or e not in minuscolo vengono analizzati come termini di ricerca, non come operatori.

Se non includi operatori, tutti i termini e le frasi di ricerca vengono uniti da AND. Puoi omettere l'operatore AND tra i termini di ricerca.

Gli operatori AND e OR sono operatori di cortocircuito. Puoi combinare le regole AND e OR nella stessa espressione. Ad esempio, se i due operatori vengono misti, l'espressione a AND b OR c AND d diventa la seguente espressione del linguaggio di query di Logging:

"a"
"b" OR "c"
"d"

L'operatore NOT ha la precedenza più alta, seguito da OR e AND in questo ordine.

L'operatore NOT esegue una negazione del termine successivo. Ad esempio, NOT error restituisce voci di log che non contengono error. Puoi anche sostituire l'operatore NOT con l'operatore - (meno). Ad esempio, le seguenti due query sono identiche:

"response" AND "successful" AND NOT "error"

"response successful" -"error"

Questa logica funziona anche con una frase, se l'operatore - (meno) non è compreso tra le virgolette. Ad esempio, le seguenti due query sono identiche:

-"response successful"

NOT "response successful"

Costruire query con i menu filtro

Puoi utilizzare i menu del filtro nel riquadro Query per aggiungere parametri di risorsa, nome log e gravità di log al campo dell'editor di query. Queste opzioni corrispondono ai campi LogEntry di tutti i log di Logging.

Le opzioni nei menu Risorsa e Nome log derivano dalle voci di log archiviate da Cloud Logging.

• Risorsa: consente di specificare il valore resource.type e il valore resource.labels associato. Puoi selezionare un singolo tipo di risorsa utilizzando questo menu del filtro e nessuna o più etichette delle risorse da applicare alla query. I parametri della risorsa sono uniti dall'operatore logico AND.
• Nome log: consente di specificare il logName. Puoi selezionare più nomi di log da applicare alla query. Quando selezioni più nomi di log, viene utilizzato l'operatore logico OR.
• Gravità: ti consente di specificare la gravità. Puoi selezionare più livelli di gravità contemporaneamente da aggiungere alla query. Se selezioni più livelli di gravità, viene utilizzato l'operatore logico OR.

Per utilizzare uno dei menu del filtro:

1. Espandi il Menu in uno dei menu del filtro nel riquadro Query.

2. Perfeziona i parametri del filtro.

3. Fai clic su Applica. Vedrai i parametri nel campo dell'editor di query.

   Per visualizzare i termini di ricerca all'interno dell'espressione di query, attiva Mostra query.

4. Dopo aver esaminato la query, fai clic su Esegui query. I risultati della query vengono visualizzati nel riquadro Risultati delle query.

Per alcuni tipi di risorse Compute Engine, come gce_instance e gce_network, viene visualizzato il nome della risorsa con l'ID risorsa come sottotesto. Ad esempio, per il tipo di risorsa gce_instance, vedrai il nome della VM insieme all'ID della VM. I nomi delle risorse consentono di identificare l'ID risorsa corretto su cui creare query.

Visualizza i log per intervallo di tempo

Esistono due modi per visualizzare i log scritti in un intervallo di tempo specifico:

1. Utilizza il selettore dell'intervallo di tempo.
2. Includi un'espressione timestamp nel campo dell'editor di query.

Utilizzare il selettore dell'intervallo di tempo

L'intervallo di tempo predefinito è di un'ora, ma puoi scegliere tra le opzioni di tempo preimpostate, specificare un'ora di inizio e di fine personalizzata o centrare l'intervallo di tempo attorno a un timestamp specifico utilizzando il selettore dell'intervallo di tempo. Ad esempio, per visualizzare i dati relativi all'ultima settimana, seleziona Ultima settimana dal selettore dell'intervallo di tempo.

Puoi anche impostare le preferenze di fuso orario utilizzando il selettore dell'intervallo di tempo.

Includi un'espressione timestamp nel campo dell'editor di query

Per aggiungere un'espressione timestamp direttamente al campo dell'editor di query, utilizza il linguaggio di query di Logging.

Se il campo dell'editor di query contiene un'espressione con un timestamp, il selettore dell'intervallo di tempo viene disabilitato e la query utilizza l'espressione timestamp come limitazione dell'intervallo di tempo. Se una query non utilizza un'espressione timestamp, la query utilizza il selettore dell'intervallo di tempo come limitazione dell'intervallo di tempo.

Scrivere query avanzate utilizzando il linguaggio di query di Logging

Puoi utilizzare il linguaggio di query di Logging per creare query più avanzate nel campo dell'editor di query di Esplora log:

1. Se non vedi il campo dell'editor di query nel riquadro Query, attiva Mostra query.

2. Inserisci le espressioni di query direttamente nel campo dell'editor di query.

   Se hai aggiunto termini di ricerca nel campo di ricerca o selezionato parametri nei menu dei filtri, questi vengono visualizzati anche nel campo dell'editor di query e vengono valutati come parte dell'espressione di query.

3. Dopo aver esaminato la query, fai clic su Esegui query.

   I log corrispondenti alla query sono elencati nel riquadro Risultati delle query. Anche i riquadri Istogramma e Campi log vengono modificati in base all'espressione della query.

Per esempi di query comuni che potresti utilizzare, vedi Esempi di query con Esplora log.

Nota: la lunghezza di una query non può superare i 20.000 caratteri.

Utilizza query recenti

Quando esegui una query, questa viene aggiunta all'elenco di query Recenti, che contiene le ultime 10.000 query uniche in un periodo di 30 giorni.

Per visualizzare le query recenti, seleziona la scheda Recenti nel riquadro Query. Nella scheda Recenti sono disponibili le seguenti opzioni:

• Flusso di dati: per eseguire la query e inviare il flusso dei risultati, scegli questa opzione.
• Esegui: per eseguire la query, scegli questa opzione.

• Altre opzioni: consente di visualizzare l'espressione di query con le opzioni per eseguire la query o salvarla nell'elenco di query salvate. Puoi anche selezionare direttamente la query per ottenere queste opzioni.

  Per salvare la query:

  1. Fai clic su Salva con nome. Viene visualizzata la finestra di dialogo Salva query.

  2. Completa i seguenti campi:

     • Nome (obbligatorio): specifica un nome per la query. I nomi possono avere un massimo di 64 caratteri.
     • (Facoltativo) Descrizione: fornisci una descrizione che consenta di identificare lo scopo della query.
     • (Facoltativo) Includi campi di riepilogo: abilita Includi campi di riepilogo e inserisci i campi di riepilogo che vuoi visualizzare.
     • (Facoltativo) Tronca campi di riepilogo: abilita i Campi di riepilogo per troncare e seleziona il numero di caratteri da troncare e se il troncamento si verifica all'inizio o alla fine dei campi.

  3. Fai clic su Salva query. La query è ora disponibile nell'elenco Query salvate.

Puoi anche ordinare e filtrare le query recenti; il filtro corrisponde al testo nell'espressione di query.

Salvare le query

Nota: se i dati sono gestiti tramite un ambiente Assured Workloads, questa funzionalità potrebbe essere interessata o limitata. Per informazioni, consulta Restrizioni e limitazioni in Assured Workloads.

Le query salvate consentono di archiviare le espressioni di query per esplorare i log in modo più coerente ed efficiente. Il riquadro Query di Esplora log presenta una scheda Salvati, in cui puoi accedere alle query salvate. Puoi anche salvare le query utilizzando il metodo dell'API Logging savedQueries.create.

Console

Per salvare un'espressione di query che hai creato nel campo dell'editor di query, procedi nel seguente modo:

1. Fai clic su Salva nel riquadro Query. Si apre la finestra di dialogo Salva query, con l'espressione di query nel campo dell'editor di query.

2. Completa i seguenti campi:

   • Nome (obbligatorio): specifica un nome per la query. I nomi possono avere un massimo di 64 caratteri.
   • (Facoltativo) Descrizione: fornisci una descrizione che consenta di identificare lo scopo della query.
   • (Facoltativo) Includi campi di riepilogo personalizzati: abilita Includi campi di riepilogo e inserisci i campi di riepilogo che vuoi visualizzare.
   • (Facoltativo) Tronca campi di riepilogo: abilita i Campi di riepilogo per troncare e seleziona il numero di caratteri da troncare e se il troncamento si verifica all'inizio o alla fine dei campi.

3. Fai clic su Salva query. Le query salvate vengono visualizzate in un elenco nella scheda Salvati.

Per eseguire una query salvata, fai clic su Esegui. Per eseguire la query e eseguire il flusso dei risultati, fai clic su Trasmetti in streaming.

Puoi anche ordinare e filtrare le query salvate; il filtro corrisponde al testo nell'espressione di query.

API

Per salvare una query con l'API Logging, usa il metodo savedQueries.create. Per ulteriori informazioni su questo metodo, sui relativi parametri e sui dati di risposta, consulta la pagina di riferimento per savedQueries.create.

Puoi eseguire il metodo savedQueries.create utilizzando il widget Explorer API nella pagina di riferimento del metodo. Per le query di Esplora log, devi specificare il campo loggingQuery. L'esempio seguente illustra il corpo di una richiesta di esempio, che contiene un'istanza di SavedQuery:

{
"parent": "projects/my-project/locations/global"
"savedQueryId": "compute-query"
{
  "displayName": "compute-admin-activity-query",
  "description": "Queries for Compute Engine Admin Activity logs.",

  "loggingQuery":
    {
      "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
    },
  "visibility": "PRIVATE"
}
}

Condividere query

Le query condivise consentono agli utenti di un progetto Google Cloud di condividere tra loro le query salvate. Puoi visualizzare le query condivise nella scheda Salvati.

Per i ruoli e le autorizzazioni necessari per visualizzare e modificare le query condivise, vedi Autorizzazioni della console Google Cloud. Tieni presente che gli utenti con il ruolo IAM roles/logging.admin o roles/editor possono modificare le query condivise di altri utenti.

Crea una query condivisa

Console

Puoi condividere query che hai già salvato o puoi condividere una nuova query.

Per creare e condividere una query, segui questi passaggi:

1. Inserisci una query nel campo dell'editor query.

2. Fai clic su Salva.

3. Completa i campi nella finestra di dialogo Salva query.

4. Attivare l'opzione Condividi con il progetto.

5. Fai clic su Salva query.

La tua query è ora condivisa con altri utenti del progetto Google Cloud.

Per condividere una query già salvata:

1. Seleziona la scheda Salvati.

2. Seleziona Altre opzioni e poi Modifica oppure seleziona direttamente la query.

3. Nella finestra di dialogo Modifica query, attiva Condividi con il progetto e quindi fai clic su Aggiorna query.

La tua query è ora condivisa con altri utenti del progetto Google Cloud.

API

Puoi utilizzare l'API Logging per creare una query condivisa utilizzando il metodo savedQueries.Create e specificando un valore SHARED nel campo visibility.

Visualizza query condivise

Console

Per visualizzare rapidamente tutte le query condivise, ordina la colonna Visibilità in modo da visualizzare prima le query condivise:

1. Seleziona la scheda Salvati.

2. Fai clic su Tutte.

3. Ordina la colonna Visibilità.

La colonna Visibilità indica se e come le query vengono condivise:

• Condivise da me: query che hai salvato e condiviso con altri utenti del progetto Google Cloud.
• Condivise: query condivise da altri utenti del progetto Google Cloud.
• Private: query che hai salvato e non hai condiviso con altri utenti del progetto Google Cloud.

Visualizzare solo le tue query

Per visualizzare le query salvate che hai creato o condiviso, fai clic su Miei. Viene visualizzato un elenco delle query che hai creato e salvato. Nella colonna Visibilità puoi vedere le query private non condivise. Le query che hai condiviso sono contrassegnate da Condivisi da me.

Utilizzare le query suggerite

Logging genera query suggerite in base al contesto del tuo progetto Google Cloud, ad esempio i prodotti Google Cloud che stai utilizzando. Le query suggerite possono aiutarti a identificare i problemi e fornirti insight sull'integrità complessiva dei tuoi sistemi. Ad esempio, rilevando che utilizzi Google Kubernetes Engine, Logging potrebbe suggerire una query che trova tutti i log degli errori per i tuoi container.

Per visualizzare ed eseguire le query suggerite, seleziona la scheda Suggerite nel riquadro Query. La scheda Suggerite mostra un elenco di query, ciascuna con una descrizione e le seguenti opzioni:

• Flusso di dati: per eseguire la query e inviare il flusso dei risultati, scegli questa opzione.
• Esegui: per eseguire la query, scegli questa opzione.

• Altre opzioni: consente di visualizzare i dettagli dell'espressione di query con le opzioni per eseguire la query o salvarla. Puoi anche selezionare direttamente la query per ottenere queste opzioni.

  Per esaminare i dettagli di una query suggerita, procedi in uno dei seguenti modi:

  • Seleziona la riga della query.

  • Fai clic su Altro e seleziona Visualizza. Si apre la finestra di dialogo Dettagli query.

  Nella finestra di dialogo Dettagli query, vedi la query e le opzioni Esegui, Stream o Salva con nome:

  • Per salvare la query:

    1. Fai clic su Salva con nome.
    2. Completa i campi nella finestra di dialogo Salva query.

    La query modificata viene visualizzata nell'elenco Salvati, dove puoi scegliere di eseguire la query in un secondo momento.

  • Per eseguire subito la query, fai clic su Esegui. La query viene eseguita e appare nel campo dell'editor query.

  • Per eseguire subito la query e inviare in streaming i risultati, fai clic su Trasmetti in streaming.

  • Per chiudere la finestra di dialogo e tornare all'elenco delle query suggerite, fai clic su Chiudi.

Osserva i seguenti comportamenti previsti:

• I caricamenti pagine successivi potrebbero non mostrare le stesse query nello stesso ordine.
• Potresti visualizzare zero query suggerite.
• A volte l'esecuzione di una query suggerita restituisce zero log.

Seleziona query dalla libreria

Logging offre una libreria di query basata su casi d'uso comuni e prodotti Google Cloud. Queste query possono aiutarti a trovare i log in modo efficiente durante le sessioni di risoluzione dei problemi critici ed esplorare i log per comprendere meglio quali dati di logging sono disponibili.

Per visualizzare ed eseguire le query della libreria, segui questi passaggi:

1. Seleziona la scheda Raccolta nel riquadro Query.

2. Nella colonna Tutte le query sono visualizzate ampie categorie di query e sottoinsiemi di query disponibili basati sui prodotti Google Cloud. Per restringere la selezione delle query che vedi, fai clic su uno dei prodotti.

   Puoi anche utilizzare il campo di ricerca per cercare le query disponibili in base a categoria, descrizione o contenuto dell'espressione di query.

3. Per esaminare un'espressione di query, esegui una delle seguenti operazioni:

   a. Fai clic sulla riga della query.

   b. Fai clic su Altro e seleziona Visualizza.

4. Nella finestra di dialogo Dettagli query, vedi la query e le opzioni Esegui, Trasmetti in streaming o Salva con nome:

   • Per salvare la query:

     1. Fai clic su Salva con nome.
     2. Completa i campi nella finestra di dialogo Salva query.

     La query modificata viene visualizzata nell'elenco Salvati, dove puoi scegliere di eseguire la query in un secondo momento.

   • Per eseguire subito la query, fai clic su Esegui. La query viene eseguita e appare nel campo dell'editor query.

   • Per eseguire subito la query e inviare in streaming i risultati, fai clic su Trasmetti in streaming.

   • Per chiudere la finestra di dialogo e tornare all'elenco delle query suggerite, fai clic su Chiudi.

Passaggi successivi

• Query di esempio