Salvare e condividere query SQL

Observability Analytics ti consente di salvare e condividere query SQL in modo da poter eseguire nuovamente indagini frequenti di Cloud Logging e collaborare con i membri del team nel tuo progetto. Puoi mantenere private le query salvate per uso personale o condividerle con altri membri del progetto.

Se non hai scritto query in Observability Analytics, consulta prima Esegui query e analizza i log. Per scoprire come creare grafici dei risultati delle query e salvarli in una dashboard personalizzata, consulta Crea grafici dei risultati delle query SQL.

Differenze tra query salvate e viste di analisi

Una query salvata è una query che esegui utilizzando la pagina Observability Analytics e che poi salvi come query. L'azione di salvataggio ti consente di eseguire nuovamente questa query quando preferisci. Quando salvi la query, puoi scegliere di renderla privata o visibile ad altri utenti che dispongono delle autorizzazioni necessarie per utilizzare Observability Analytics. Non puoi scrivere una query SQL in cui la clausola FROM specifica una query salvata.

Una vista di analisi contiene una query che puoi eseguire nuovamente quando preferisci. Per creare una vista di analisi, scrivi una query SQL su una vista log e poi salvi il risultato come vista. A differenza delle query salvate, non puoi rendere privata una vista di analisi. Puoi eseguire query su una vista di analisi. Questa funzionalità ti consente di trasformare i dati di log dal formato LogEntry in un altro formato più adatto alle tue esigenze. Poi, anziché scrivere le query su una vista log, esegui la query sulla vista di analisi.

Puoi salvare le query che eseguono query su una vista log o una vista di analisi.

Prima di iniziare

Questa sezione descrive i passaggi da completare prima di poter utilizzare Observability Analytics.

Configura i bucket di log

Assicurati che sia stato eseguito l'upgrade dei bucket di log per utilizzare Observability Analytics:

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

   Vai ad Archiviazione dei log

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

2. Per ogni bucket di log che ha una visualizzazione dei log su cui vuoi eseguire query, assicurati che nella colonna Observability Analytics disponibile sia visualizzato Apri. Se viene visualizzato Esegui l'upgrade, fai clic su Esegui l'upgrade e completa la finestra di dialogo.

Configura ruoli e autorizzazioni IAM

Questa sezione descrive i ruoli o le autorizzazioni IAM necessari per utilizzare Observability Analytics:

• Per ottenere le autorizzazioni necessarie per utilizzare Observability Analytics ed eseguire query sulle visualizzazioni dei log, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

  • Per eseguire query sui bucket di log _Required e _Default: Visualizzatore log (roles/logging.viewer)
  • Per eseguire query su tutte le visualizzazioni dei log in un progetto: Logs View Accessor (roles/logging.viewAccessor)

  Puoi limitare un'entità a una visualizzazione log specifica aggiungendo una condizione IAM alla concessione del ruolo Visualizzatore log effettuata a livello di progetto o aggiungendo un'associazione IAM al file della policy della visualizzazione log. Per saperne di più, consulta Controlla l'accesso a una visualizzazione log.

  Queste sono le stesse autorizzazioni necessarie per visualizzare le voci di log nella pagina Esplora log. Per informazioni sui ruoli aggiuntivi necessari per eseguire query sulle visualizzazioni sui bucket definiti dall'utente o per eseguire query sulla visualizzazione _AllLogs del bucket di log _Default, consulta Ruoli di Cloud Logging.

• Per ottenere le autorizzazioni necessarie per eseguire query sulle viste di analisi, chiedi all'amministratore di concederti il ruolo IAM Utente Observability Analytics (roles/observability.analyticsUser) nel progetto.

Seleziona l'interfaccia che intendi utilizzare

Console

Quando utilizzi la console Google Cloud per accedere ai servizi e alle API Google Cloud , non devi configurare l'autenticazione.

gcloud

Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente:

gcloud init

REST

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Salva una query

Tutte le query eseguite vengono salvate automaticamente per 30 giorni e sono accessibili selezionando la scheda Recenti nella pagina Observability Analytics. Puoi cercare, visualizzare, eseguire e condividere le query elencate nella scheda Recenti.

Per riutilizzare una query, aggiungere descrizioni personalizzate o condividerla con i membri del team, salva la query. Puoi cercare e ordinare le query salvate in base al nome, alla descrizione e all'etichetta di visibilità. Puoi anche modificare ed eliminare queste query. Le query salvate vengono conservate finché non le elimini.

Puoi salvare 10.000 query per progetto Google Cloud .

Nota: le query salvate utilizzando la console Google Cloud vengono archiviate nella località global. Per specificare dove vengono archiviate le query, utilizza Google Cloud CLI o l'API Cloud Logging.

Console

Per salvare una query:

1. Nella console Google Cloud , vai alla pagina Observability Analytics:

   Vai a Observability Analytics

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

2. Compila il riquadro Query con una query.

   Puoi compilare il riquadro Query inserendo una nuova query, selezionando una query dalla scheda Recenti o selezionando una query dalla scheda Salvate.

   La query può includere qualsiasi visualizzazione valida, più visualizzazioni e viste di analisi.

   Quando la query nel riquadro Query è valida, il pulsante Salva Salva è attivo.

3. Fai clic su save Salva, seleziona Salva query e compila i campi Nome e Descrizione. I valori impostati per questi campi vengono visualizzati nella scheda Salvati.

4. (Facoltativo) Per consentire a tutti gli utenti con accesso alla pagina Analisi di osservabilità per il progetto Google Cloud di visualizzare ed eseguire la query salvata, attiva l'opzione Condividi con il progetto.

   Per impostazione predefinita, questo pulsante di attivazione/disattivazione è disattivato e la visibilità è limitata a te.

5. Fai clic su Salva query.

6. (Facoltativo) Per visualizzare, ordinare ed eseguire le query salvate visibili, seleziona la scheda Salvate.

   Puoi ordinare e filtrare le query salvate in base al nome, alla descrizione e all'etichetta di visibilità. Puoi anche filtrare in base ai contenuti della query.

Puoi modificare ed eliminare le query che hai creato utilizzando le opzioni nella scheda Salvate:

• Per modificare una query, fai clic su Altre opzioni e seleziona Modifica. Puoi modificare i valori dei campi Nome e Descrizione, ma la query non può essere modificata.

• Per eliminare una query salvata, fai clic su Altre opzioni e seleziona Elimina.

gcloud

Per creare e salvare una query:

1. Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

   • DISPLAY_NAME: il nome visualizzato della query salvata.
   • LOCATION: la località della query salvata.
   • VISIBILITY: impostato su private o shared.
   • SQL_QUERY: una query SQL. Se il percorso o i campi al suo interno sono racchiusi tra singoli apici inversi (`), devi inserire un carattere di escape per questi apici inversi:

         "SELECT * FROM \`PROJECT_ID.LOCATION.my-log-bucket._AllLogs\`"
         

     o

         "SELECT * FROM \`PROJECT_ID.LOCATION._Trace.Spans._AllSpans\`"
         

     Gli apici inversi (`) sono obbligatori quando un elemento del percorso contiene un carattere punto (.).

   • ID: l'ID della query salvata. Questo ID è un input obbligatorio per i comandi che descrivono, aggiornano o eliminano una query salvata. Se non fornisci l'ID durante la creazione di una query salvata, il sistema genera un ID numerico.
   • DESCRIPTION: una descrizione testuale della query. Facoltativo.
   • PROJECT_ID: l'identificatore del progetto.

   Esegui il comando gcloud logging saved-queries create:

   Linux, macOS o Cloud Shell

   gcloud logging saved-queries create --display-name=DISPLAY_NAME \
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY \
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   Windows (PowerShell)

   gcloud logging saved-queries create --display-name=DISPLAY_NAME `
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY `
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   Windows (cmd.exe)

   gcloud logging saved-queries create --display-name=DISPLAY_NAME ^
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY ^
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   Di seguito è riportato un esempio di risposta quando l'ID fornito nel comando era my-saved-query:

   Created saved query [projects/PROJECT_ID/locations/LOCATION/savedQueries/my-saved-query].
   

   La risposta al comando create elenca il nome completo della query, che include l'ID della query. L'ID query, che in questo esempio è my-saved-query, è un input obbligatorio per i comandi di Google Cloud CLI che descrivono, eliminano o aggiornano una query salvata.

2. Per esaminare la query salvata, esegui questo comando:

    gcloud logging saved-queries list --location=- --project=PROJECT_ID
   

   Nell'espressione precedente, il valore della località è un trattino (-), che funge da carattere jolly. Puoi anche fornire una località specifica.

Esistono comandi di Google Cloud CLI per eliminare, elencare, descrivere e aggiornare le query salvate. Per saperne di più, consulta la panoramica di gcloud logging saved-queries.

REST

Puoi salvare una query utilizzando l'API Cloud Logging. Per salvare una query, utilizza il metodo savedQueries.create.

Per eseguire questo metodo:

1. Seleziona savedQueries.create.
2. Nella pagina di riferimento, utilizza Explorer API per eseguire un comando. Devi specificare il campo opsAnalyticsQuery.

L'esempio seguente illustra un corpo della richiesta di esempio, che contiene un'istanza di SavedQuery:

{
   "parent": "projects/my-project/locations/global"
   "saved_query":
   {
      "ops_analytics_query":
      {
         "sql_query_text" :
            "SELECT
            timestamp, log_name, severity, json_payload, resource, labels
            FROM
            `VIEW`
            WHERE
            timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
            ORDER BY timestamp ASC
            LIMIT 100"
      }
   "visibility": "PRIVATE"
   }
}

Condividi una query

Puoi condividere una query salvata con tutti coloro che hanno accesso al tuo progettoGoogle Cloud . Tuttavia, i ruoli IAM dell'entità determinano se la query può essere eseguita e i dati che restituisce.

Console

Quando risolvi un problema o quando vedi risultati anomali, potresti voler condividere una query e i relativi risultati con un collega. Quando visualizzi i risultati delle query nella pagina Observability Analytics, puoi copiare un URL che, una volta aperto, mostra la query eseguita e i relativi risultati.

Per condividere una query e i risultati con un collega:

1. Nella console Google Cloud , vai alla pagina Observability Analytics:

   Vai a Observability Analytics

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

2. Compila il riquadro Query con una query, quindi fai clic su Esegui query.

   Puoi compilare il riquadro Query inserendo una nuova query, selezionando una query dalla scheda Recenti o selezionando una query dalla scheda Salvate.

3. Fai clic su Condividi link.

4. Invia il link al tuo collega.

   Quando il tuo collega apre il link, viene visualizzata la pagina Observability Analytics, che mostra la query, ma non la esegue. Il tuo collega deve eseguire manualmente la query.

   La pagina Observability Analytics mostra una finestra di dialogo di avviso quando la query viene eseguita sul motore BigQuery e le risorse interrogate non si trovano nello stesso confine di proprietà. I confini della proprietà sono determinati da diversi fattori, uno dei quali è la gerarchia delle risorse utilizzate dalla query.

   Per aprire l'URL, il ruolo IAM del tuo collega nel progetto Google Cloud deve includere le autorizzazioni necessarie per visualizzare la pagina Analisi di osservabilità.

gcloud

Quando vuoi creare una query salvata che possa essere eseguita da altri, imposta il valore del campo visibility su shared:

--visibility=shared

Per modificare la visibilità di una query salvata esistente, utilizza il comando update. Per ulteriori informazioni sui comandi disponibili, consulta la panoramica di gcloud logging saved-queries.

REST

Puoi utilizzare l'API Logging per creare una query condivisa utilizzando il metodo savedQueries.create e specificando un valore SHARED nel campo visibility. Per saperne di più, consulta la pagina di riferimento per savedQueries.create.

Visualizza ed esegui query recenti o salvate

Per visualizzare o eseguire nuovamente una query, seleziona la scheda Recenti nella pagina Observability Analytics e trova la query:

• Per eseguire la query, fai clic su Esegui.
• Per visualizzare la query, utilizza le opzioni nel menu Altre opzioni.

Per visualizzare, modificare o eseguire una query salvata, seleziona la scheda Salvate nella pagina Observability Analytics e trova la query:

• Per eseguire la query, fai clic su Esegui.
• Per modificare, visualizzare o eliminare la query, utilizza le opzioni nel menu Altre opzioni.

Passaggi successivi

• Crea ed esegui query sulle viste di analisi
• Esempi di query SQL
• Crea grafici dei risultati delle query SQL
• Esegui una query su un set di dati BigQuery collegato in BigQuery