Analizzare i dati di log con BigQuery

Questo documento descrive come analizzare i dati di log utilizzando i servizi BigQuery, che possono eseguire query sui set di dati BigQuery collegati. Se crei un set di dati BigQuery collegato su un bucket di log, puoi eseguire query sui dati di log utilizzando BigQuery o Data Studio. Inoltre, puoi configurare la pagina Observability Analytics per eseguire query sul motore BigQuery. Puoi creare policy di avviso che monitorano i risultati delle query SQL eseguite sul motore BigQuery.

Non puoi creare un set di dati BigQuery collegato per una vista di analisi.

Se non hai familiarità con Observability Analytics, consulta la panoramica di Observability Analytics.

Quando è necessario un set di dati collegato

Non hai bisogno di un set di dati BigQuery collegato quando vuoi eseguire query sui dati di log o sui dati di log e di traccia. In questi scenari, puoi utilizzare la pagina Observability Analytics. Puoi anche salvare e condividere le query e salvarle in una dashboard personalizzata. Per informazioni su come eseguire query sui dati di traccia, consulta Eseguire query e analizzare le tracce.

Hai bisogno di un set di dati BigQuery collegato quando vuoi eseguire una delle seguenti operazioni:

Un set di dati BigQuery collegato per un bucket di log consente a BigQuery di leggere i dati nel bucket di log.

Come i bucket di log e le visualizzazioni dei log vengono mappati agli oggetti BigQuery

Quando crei un set di dati BigQuery collegato per un bucket di log, un nuovo set di dati diventa disponibile per BigQuery. Specifichi il nome del set di dati collegato durante la procedura di collegamento. Tutte le visualizzazioni dei log all'interno del bucket di log vengono mappate automaticamente alle visualizzazioni virtuali nel set di dati. Il nome di una visualizzazione virtuale è lo stesso della visualizzazione dei log corrispondente.

Supponiamo, ad esempio, che il progetto my_project abbia un bucket di log denominato example e che questo bucket di log abbia una visualizzazione dei log denominata _AllLogs. Se crei un set di dati collegato per quel bucket di log con il nome my_dataset, la pagina Explorer di BigQuery mostra una voce my_project. Un elemento secondario della voce my_project è un set di dati con il nome my_dataset e questo set di dati elenca una visualizzazione virtuale denominata _AllLogs.

Implicazioni del controllo dell'accesso quando si utilizzano set di dati collegati

Quando un principal esegue query su una visualizzazione in un set di dati BigQuery collegato, la query viene eseguita tramite il livello di autorizzazione BigQuery, non il livello di autorizzazione Cloud Logging. Pertanto, i ruoli e le autorizzazioni BigQuery concessi al principal sul set di dati collegato determinano se può eseguire query sul set di dati.

Non puoi limitare un principal a una visualizzazione virtuale specifica all'interno di un set di dati collegato. Quando a un principal è stato concesso l'accesso al set di dati collegato, può eseguire query su ogni visualizzazione in quel set di dati.

Motori di query disponibili

Observability Analytics ti consente di eseguire le query SQL sul motore di logging predefinito o sul motore BigQuery. Se esegui una query sul motore BigQuery, viene eseguita una query sul set di dati BigQuery collegato, il che significa che le autorizzazioni BigQuery vengono convalidate.

Per saperne di più, consulta Scegliere il motore di query di Observability Analytics.

Azioni di sistema che si verificano quando crei un set di dati collegato

Quando crei un set di dati collegato, avvii un'operazione a lunga esecuzione. Nell'ambito di questa operazione si verificano diverse azioni:

  • Gli audit log registrano la richiesta di creare un link e il completamento dell'operazione.

  • Se il service account Monitoring non esiste, Google Cloud Observability lo crea.

    Per creare questo account di servizio, deve essere abilitata l'API Cloud Monitoring.

  • Google Cloud Observability richiede un account di servizio prima di poter creare un set di dati collegato. Se necessario, viene creato un account di servizio:

  • Un audit log registra la richiesta del gestore del service agent di concedere al service account Monitoring il ruolo IAM di service agent Monitoring.

Prima di iniziare

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

Configurare i bucket di log

Assicurati che i bucket di log siano stati sottoposti ad upgrade 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 visualizzazione dei 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 visualizzazioni dei log, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

    Puoi limitare un principal a una visualizzazione dei log specifica aggiungendo una condizione IAM alla concessione del ruolo Accesso visualizzazione log effettuata a livello di progetto o aggiungendo un binding IAM al file di policy della visualizzazione dei log. Per saperne di più, consulta Controllare l'accesso a una visualizzazione dei 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 visualizzazioni dei bucket definiti dall'utente o sulla visualizzazione _AllLogs del bucket di log _Default, consulta Ruoli di Cloud Logging.

  • Per ottenere le autorizzazioni necessarie per creare ed eseguire query sui set di dati collegati, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto che archivia il bucket di log:

    • Per creare e visualizzare i set di dati collegati: Autore configurazione log (roles/logging.configWriter)
    • Per eseguire query sui set di dati collegati utilizzando gli slot BigQuery:
    • Per visualizzare i set di dati collegati in BigQuery Studio, concedi tutti i ruoli menzionati in questo passaggio e il seguente ruolo. Puoi concedere questo ruolo a un set di dati o al tuo progetto: Visualizzatore dati BigQuery (roles/bigquery.dataViewer)

Abilitare le API

Abilita l'API Cloud Monitoring.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Verificare la versione di BigQuery

Se vuoi eseguire query sui dati di log dalla pagina Observability Analytics eseguendo query sugli slot BigQuery e se utilizzi progetti con Controlli di servizio VPC (Virtual Private Cloud), assicurati di utilizzare la versione Enterprise di BigQuery. Per saperne di più, consulta Informazioni sulle versioni di BigQuery.

Quando vuoi utilizzare le funzionalità di BigQuery per analizzare i tuoi dati di log, esegui l'upgrade di un bucket di log per utilizzare Observability Analytics e poi crea un set di dati collegato. Con questa configurazione, Logging archivia i dati di log, ma BigQuery può leggerli.

Google Cloud Console

Per creare un link a un set di dati BigQuery per un bucket di log esistente:

  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. Individua il bucket di log e verifica che la colonna Observability Analytics disponibile mostri Apri.

    Se questa colonna mostra Esegui l'upgrade, significa che il bucket di log non è stato sottoposto ad upgrade per utilizzare Observability Analytics. Configura Observability Analytics:

    1. Fai clic su Esegui l'upgrade.
    2. Fai clic su Conferma nella finestra di dialogo.

    Al termine dell'upgrade, vai al passaggio successivo.

  3. Nel bucket di log, fai clic su Altro, e poi su Modifica bucket.

    Viene visualizzata la finestra di dialogo Modifica bucket di log.

  4. Seleziona Crea un nuovo set di dati BigQuery che si colleghi a questo bucket e inserisci il nome del nuovo set di dati.

    Il nome del set di dati deve essere univoco per ogni Google Cloud progetto. Se inserisci il nome di un set di dati esistente, ricevi il seguente errore: Dataset name must be unique in the selected region. (Il nome del set di dati deve essere univoco nella regione selezionata).

  5. Fai clic su Fine e poi su Aggiorna bucket.

    Dopo che Logging visualizza il nome del set di dati collegato nella pagina Archiviazione dei log, potrebbero essere necessari alcuni minuti prima che BigQuery riconosca il set di dati.

gcloud

Per creare un set di dati collegato per un bucket di log sottoposto ad upgrade per utilizzare Observability Analytics, esegui il gcloud logging links create comando:

gcloud logging links create LINK_ID --bucket=BUCKET_ID --location=LOCATION

Il LINK_ID che fornisci viene utilizzato come nome del set di dati BigQuery e il valore di questo campo deve essere univoco per il tuo Google Cloud progetto.

Il comando links create è asincrono. Il valore restituito di un metodo asincrono è un Operation oggetto, che contiene informazioni sullo stato di avanzamento del metodo. Al termine del metodo, l'oggetto Operation contiene lo stato. Per saperne di più, consulta Metodi API asincroni.

Il comando links create richiede alcuni minuti per essere completato.

Ad esempio, il seguente comando crea un set di dati collegato denominato mylink per il bucket di log denominato my-bucket:

gcloud logging links create mylink --bucket=my-bucket --location=global

Il nome del set di dati deve essere univoco per ogni Google Cloud progetto. Se tenti di creare un set di dati con lo stesso nome di un set di dati esistente, ricevi il seguente errore:

BigQuery dataset with name "LINK_ID" already exists.

Se tenti di creare un set di dati collegato per un bucket di log che non è stato sottoposto ad upgrade per utilizzare Observability Analytics, viene segnalato il seguente errore:

A link can only be created for an analytics-enabled bucket.

REST

Per creare un set di dati BigQuery collegato per un bucket di log esistente sottoposto ad upgrade per utilizzare Observability Analytics, chiama il metodo asincrono projects.locations.buckets.links.create dell'API Cloud Logging.

Prepara gli argomenti per il metodo nel seguente modo:

  1. Crea il corpo della richiesta per il comando create. Il corpo della richiesta è formattato come un Link oggetto.
  2. Per il parametro di query del comando, utilizza linkId=LINK_ID. Il LINK_ID che fornisci viene utilizzato come nome del set di dati BigQuery e il valore di questo campo deve essere univoco per il tuo Google Cloud progetto.

La risposta ai metodi asincroni è un Operation oggetto. Questo oggetto contiene informazioni sullo stato di avanzamento del metodo. Al termine del metodo, l'oggetto Operation contiene lo stato. Per saperne di più, consulta Metodi API asincroni.

Il metodo links.create richiede alcuni minuti per essere completato.

Il nome del set di dati deve essere univoco per ogni Google Cloud progetto. Se tenti di creare un set di dati con lo stesso nome di un set di dati esistente, ricevi il seguente errore:

BigQuery dataset with name "LINK_ID" already exists.

Se tenti di creare un set di dati collegato per un bucket di log che non è stato sottoposto ad upgrade per utilizzare Observability Analytics, viene segnalato il seguente errore:

A link can only be created for an analytics-enabled bucket.

Eseguire query da BigQuery

Se hai un bucket di log che utilizza Observability Analytics e set di dati collegati, puoi visualizzare ed eseguire query sui set di dati collegati utilizzando la pagina BigQuery Studio. Con questa configurazione, puoi analizzare i set di dati utilizzando comandi, workflow e set di dati disponibili solo in BigQuery Studio.

Per aprire BigQuery da Observability Analytics ed eseguire query sul set di dati collegato:

  1. Assicurati che esista un set di dati collegato per il bucket di log che ospita la visualizzazione dei log su cui vuoi eseguire query:

    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. Individua il bucket di log e verifica che la colonna Set di dati collegato a BigQuery mostri un URL. Se la voce è vuota, devi creare un set di dati collegato. Per informazioni su questi passaggi, consulta Creare un set di dati BigQuery collegato.

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

    Vai a Observability Analytics

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

  3. Nell'elenco Visualizzazioni dei log, trova e seleziona la visualizzazione dei log.

  4. Nel riquadro Schema, seleziona Query.

    Il riquadro Query viene compilato con una query predefinita. Puoi anche inserire una query nel riquadro Query o modificare una query visualizzata.

  5. Nella barra degli strumenti, espandi il pulsante con l'etichetta Esegui query o Esegui su BigQuery e seleziona Apri in BigQuery.

    Si apre la pagina BigQuery Studio. L'istruzione FROM della query viene modificata per specificare il percorso della visualizzazione dei log nel set di dati collegato utilizzando la sintassi del percorso della tabella BigQuery .

    Puoi anche modificare la query visualizzata.

  6. Nella pagina BigQuery Studio, fai clic su Esegui query.

Eseguire query di Observability Analytics sugli slot BigQuery

Quando vuoi monitorare i risultati della query SQL con una policy di avviso, esegui le query sul motore BigQuery procedendo nel seguente modo:

  1. Assicurati che esista un set di dati collegato per il bucket di log che ospita la visualizzazione dei log su cui vuoi eseguire query:

    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. Individua il bucket di log e verifica che la colonna Set di dati collegato a BigQuery mostri un URL. Se la voce è vuota, allora crea un set di dati BigQuery collegato.

  2. Configura Observability Analytics per eseguire le query sul motore BigQuery:

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

      Vai a Observability Analytics

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

    2. Nell'elenco Visualizzazioni dei log , trova la visualizzazione e poi seleziona Query o inserisci una query.

      Se il riquadro della query mostra un messaggio di errore che fa riferimento all'istruzione FROM, la tabella non può essere risolta in una visualizzazione dei log specifica. Per informazioni su come risolvere questo errore, consulta Errore FROM clause must contain exactly one log view.

    3. Vai alla barra degli strumenti e verifica che venga visualizzato un pulsante con l'etichetta Esegui su BigQuery.

      Se la barra degli strumenti mostra Esegui query, allora fai clic su Impostazioni e seleziona BigQuery.

      Se il pulsante Esegui su BigQuery è disattivato, devi creare un set di dati collegato.

    4. Esegui la query.

      Puoi utilizzare le opzioni della barra degli strumenti per formattare la query, cancellarla e aprire la documentazione di riferimento di BigQuery SQL.

Passaggi successivi