Salvare e condividere query SQL

Questo documento descrive come salvare e condividere le query create in Observability Analytics.

Questo documento presuppone che tu abbia familiarità con Observability Analytics e con l'utilizzo della pagina Observability Analytics per eseguire query sui dati di log. Se non hai familiarità con questi argomenti, consulta Eseguire query e analizzare i log.

Per scoprire come rappresentare graficamente i risultati delle query e come salvare questi grafici in una dashboard personalizzata, consulta Rappresentare graficamente i risultati delle query SQL.

Differenza 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 di nuovo questa query quando vuoi. Quando salvi la query, puoi 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 di nuovo quando vuoi. Per creare una vista di analisi, scrivi una query SQL su una vista di log e poi salva 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 a un altro formato più adatto alle tue esigenze. Poi, invece di scrivere le query su una vista di log, esegui query sulla vista di analisi.

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

Prima di iniziare

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

Configurare i bucket di log

Assicurati di aver eseguito l'upgrade dei bucket di log per utilizzare Observability Analytics:

  1. Nella Google Cloud console, 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 con una vista di log su cui vuoi eseguire query, assicurati che la colonna Observability Analytics disponibile mostri Apri. Se viene visualizzato Esegui l'upgrade, fai clic su Esegui l'upgrade e completa la finestra di dialogo.

Configurare 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 viste di log, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    • Per eseguire query sui bucket di log _Required e _Default: Visualizzatore log (roles/logging.viewer)
    • Per eseguire query su tutte le viste di log in un progetto: Accessore vista log (roles/logging.viewAccessor)

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

    Si tratta delle stesse autorizzazioni necessarie per visualizzare le voci di log nella pagina Esplora log. Per informazioni sui ruoli aggiuntivi necessari per eseguire query sulle viste nei bucket definiti dall'utente o sulla vista _AllLogs del _Default bucket di log, 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 di Observability Analytics (roles/observability.analyticsUser) nel progetto.

Salvare 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.

Se vuoi mantenere una query disponibile per un utilizzo futuro, annotala con informazioni utili o consenti ai colleghi di visualizzarla ed eseguirla, quindi 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 Google Cloud progetto.

Console

Per salvare una query:

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

    Vai ad Analisi dei log

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

  2. Inserisci una query nel riquadro Query.

    Puoi inserire una query nel riquadro Query inserendo una nuova query, selezionando una query dalla scheda Recenti o selezionando una query dalla scheda Salvate.

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

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

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

  4. (Facoltativo) Per consentire a tutti gli utenti con accesso alla pagina Observability Analytics del Google Cloud progetto di visualizzare ed eseguire la query salvata, attiva il pulsante Condividi con il progetto.

    Per impostazione predefinita, questo pulsante è 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 create utilizzando le opzioni della scheda Salvate:

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

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

API

Per salvare una query utilizzando l'API Logging, utilizza il metodo savedQueries.create. Per saperne di più 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 Explorer API widget nella pagina di riferimento del metodo. Per le query di Observability Analytics, 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"
   }
}

Condividere una query

Puoi condividere una query salvata con tutti gli utenti che hanno accesso al tuo Google Cloud progetto. Tuttavia, i ruoli IAM del principal determinano se la query può essere eseguita e i dati restituiti dalla query.

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 relativi risultati con un collega:

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

    Vai ad Analisi dei log

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

  2. Inserisci una query nel riquadro Query e fai clic su Esegui query.

    Puoi inserire una query nel 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, la pagina Observability Analytics si apre e visualizza 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 su cui viene eseguita la query non si trovano nello stesso limite di proprietà. I limiti di proprietà sono determinati da diversi fattori, uno dei quali è la gerarchia delle risorse utilizzate dalla query.

    Per aprire correttamente l'URL, il ruolo IAM del tuo collega nel Google Cloud progetto deve includere le autorizzazioni necessarie per visualizzare la pagina Observability Analytics.

API

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.

Visualizzare ed eseguire query recenti o salvate

Per visualizzare o eseguire di nuovo 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 Altre opzioni menu.

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 Altre opzioni menu.

Passaggi successivi