Esegui query e analizza i log con Observability Analytics

Questo documento descrive come eseguire query e analizzare i dati di log utilizzando Observability Analytics, che fornisce un'interfaccia di query basata su SQL. Utilizzando SQL, puoi eseguire attività come contare le voci di log con un campo che corrisponde a un pattern. Observability Analytics fornisce un editor SQL e un sistema basato su menu per la creazione di query. Per visualizzare i risultati delle query, puoi utilizzare il formato tabellare oppure visualizzare i dati come grafico. Puoi salvare i grafici nelle dashboard personalizzate.

Puoi eseguire query su una visualizzazione di log in un bucket di log o su una visualizzazione di analisi. Quando esegui una query su una visualizzazione di log, lo schema corrisponde a quello della LogEntry struttura dei dati. Poiché il creatore di una visualizzazione di analisi determina lo schema, un caso d'uso per le visualizzazioni di analisi è trasformare i dati di log dal formato LogEntry in un formato più adatto alle tue esigenze.

Puoi anche utilizzare Observability Analytics per eseguire query sui dati di traccia. Per saperne di più, consulta Eseguire query e analizzare le tracce.

Observability Analytics non deduplica le voci di log, il che potrebbe influire sulla modalità di scrittura delle query. Inoltre, esistono alcune limitazioni quando si utilizza Observability Analytics. Per saperne di più su questi argomenti, consulta i seguenti documenti:

Informazioni sui set di dati collegati

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:

Unire i dati voce di log con altri set di dati BigQuery.
Eseguire query sui dati di log da un altro servizio, ad esempio la pagina BigQuery Studio o Looker Studio.
Migliorare le prestazioni delle query eseguite da Observability Analytics eseguendole negli slot riservati di BigQuery.
Creare una policy di avviso che monitora il risultato di una query SQL. Per saperne di più, consulta Monitorare i risultati delle query SQL con una policy di avviso.

Se scegli di creare un set di dati collegato in un bucket di log, espandi il perimetro di sicurezza dei dati di log per includere i servizi BigQuery. Ciò significa che i servizi BigQuery possono ora eseguire query sui dati di log inviando una query al set di dati collegato. Prima di creare un set di dati collegato, ti consigliamo di esaminare la sezione Sicurezza dei dati con Observability Analytics.

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:

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.
Per ogni bucket di log con una visualizzazione 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 visualizzazioni 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 visualizzazioni di log in un progetto: Accesso visualizzazione log (roles/logging.viewAccessor)
Puoi limitare un'entità a una visualizzazione di log specifica aggiungendo una condizione IAM alla concessione del ruolo Accesso visualizzazione log a livello di progetto oppure aggiungendo un'associazione IAM al file di policy della visualizzazione di log. Per saperne di più, consulta Controllare l'accesso a una visualizzazione 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 visualizzazioni nei bucket definiti dall'utente o sulla visualizzazione _AllLogs del bucket di log _Default, consulta Ruoli di Cloud Logging.
Per ottenere le autorizzazioni necessarie per eseguire query sulle visualizzazioni di analisi, chiedi all'amministratore di concederti il ruolo IAM Utente di Observability Analytics (roles/observability.analyticsUser) nel progetto.

Eseguire query sui dati di log

Questa sezione descrive gli approcci che puoi utilizzare per eseguire query sui dati di log:

Carica una query definita dal sistema, modificala ed eseguila.
Inserisci ed esegui una query personalizzata. Ad esempio, puoi incollare una query che hai o scriverne una. Le query personalizzate possono includere unioni, query nidificate e altre istruzioni SQL complesse. Per esempi, consulta Esempi di query SQL.
Crea una query effettuando selezioni di menu ed eseguila. Observability Analytics converte le selezioni in una query SQL, che puoi visualizzare e modificare.

Caricare, modificare ed eseguire la query definita dal sistema

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.

Nota: se nella pagina Observability Analytics viene visualizzato il messaggio "Inizia a utilizzare Observability Analytics", fai clic su Chiudi nella finestra.
Nel menu Visualizzazioni , vai alla Log o Visualizzazioni di analisi e seleziona la visualizzazione su cui vuoi eseguire query.

Per trovare la visualizzazione su cui eseguire query, utilizza la barra Filtra o scorri l'elenco:
- Le visualizzazioni di log sono elencate in base a BUCKET_ID.LOG_VIEW_ID, dove questi campi si riferiscono agli ID del bucket di log e della visualizzazione di log.
- Le visualizzazioni di analisi sono elencate in base a LOCATION.ANALYTICS_VIEW_ID, dove questi campi si riferiscono alla località e all'ID di una visualizzazione di analisi. Le visualizzazioni di analisi sono disponibili in Anteprima pubblica.
Esegui una delle seguenti operazioni:
- Per caricare una query definita dal sistema che si basa su Query Builder, che ti consente di definire la query con le selezioni di menu, assicurati che il riquadro Query visualizzi Query Builder. Se viene visualizzato un editor SQL, fai clic su Builder.
- Per caricare una query definita dal sistema che estrae i valori JSON, assicurati che il riquadro Query visualizzi l'editor SQL. Se questo riquadro visualizza Query Builder, fai clic su SQL.
Nel riquadro Schema , seleziona Query e fai clic su Sovrascrivi.

Il riquadro Query visualizza una query definita dal sistema. Se hai selezionato la modalità Query Builder, ma vuoi visualizzare la query SQL, fai clic su SQL.
(Facoltativo) Modifica la query.
Per eseguire la query, vai alla barra degli strumenti e seleziona Esegui query.

Observability Analytics presenta i risultati della query in una tabella. Tuttavia, puoi creare un grafico e salvare la tabella o il grafico in una dashboard personalizzata. Per saperne di più, consulta Creare grafici dei risultati delle query SQL.

Se la barra degli strumenti visualizza Esegui in BigQuery, devi passare a Observability Analytics per utilizzare il motore di query predefinito. Per apportare questa modifica, nella barra degli strumenti del riquadro Query, fai clic su Impostazioni e seleziona Analytics (predefinito).

Inserire ed eseguire una query personalizzata

Per inserire una query SQL:

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.

Nota: se nella pagina Observability Analytics viene visualizzato il messaggio "Inizia a utilizzare Observability Analytics", fai clic su Chiudi nella finestra.
Nel riquadro Query, fai clic su SQL.
- Per specificare un intervallo di tempo, ti consigliamo di utilizzare il selettore dell'intervallo di tempo. Se aggiungi una clausola WHERE che specifica il campo timestamp, questo valore sostituisce l'impostazione nel selettore dell'intervallo di tempo e il selettore viene disattivato.
- Per esempi, consulta Esempi di query SQL.
- Puoi eseguire query sulle visualizzazioni di log o sulle visualizzazioni di analisi. Utilizza il seguente formato per la clausola FROM:
  - Visualizzazioni di log:
```
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
```
  - Visualizzazioni di analisi:
```
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`
```
  I campi nelle espressioni precedenti hanno il seguente significato:
  - PROJECT_ID: l'identificatore del progetto.
  - LOCATION: la località della visualizzazione di log o della visualizzazione di analisi.
  - BUCKET_ID: il nome o l'ID del bucket di log.
  - LOG_VIEW_ID: l'identificatore della visualizzazione di log, che è limitato a 100 caratteri e può includere solo lettere, cifre, trattini bassi e trattini.
  - ANALYTICS_VIEW_ID: l'ID della visualizzazione di analisi, che è limitato a 100 caratteri e può includere solo lettere, cifre, trattini bassi e trattini.
  Se nel riquadro della query viene visualizzato un messaggio di errore che fa riferimento all'istruzione FROM, significa che non è stato possibile trovare la visualizzazione. Per informazioni su come risolvere questo errore, consulta Errore FROM clausola deve contenere esattamente una visualizzazione di log.
Per eseguire la query, vai alla barra degli strumenti e seleziona Esegui query.

Observability Analytics presenta i risultati della query in una tabella. Tuttavia, puoi creare un grafico e salvare la tabella o il grafico in una dashboard personalizzata. Per saperne di più, consulta Creare grafici dei risultati delle query SQL.

Se la barra degli strumenti visualizza Esegui in BigQuery, devi passare a Observability Analytics per utilizzare il motore di query predefinito. Per apportare questa modifica, nella barra degli strumenti del riquadro Query, fai clic su Impostazioni e seleziona Analytics (predefinito).

Creare, modificare ed eseguire una query

L'interfaccia Query Builder ti consente di creare una query effettuando selezioni dai menu. Observability Analytics converte le selezioni in una query SQL, che puoi visualizzare e modificare. Ad esempio, puoi iniziare a utilizzare l'interfaccia Query Builder e poi passare all'editor SQL per perfezionare la query.

Observability Analytics può sempre convertire le selezioni di menu dall'interfaccia Query Builder in una query SQL. Tuttavia, non tutte le query SQL possono essere rappresentate dall'interfaccia Query Builder. Ad esempio, le query con unioni non possono essere rappresentate da questa interfaccia.

Per creare una query:

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.

Nota: se nella pagina Observability Analytics viene visualizzato il messaggio "Inizia a utilizzare Observability Analytics", fai clic su Chiudi nella finestra.
Se il riquadro Query visualizza un editor SQL, seleziona Builder, che apre il riquadro Query Builder.
Utilizza il menu Origine per selezionare la visualizzazione su cui vuoi eseguire query. Le selezioni vengono mappate alla clausola FROM nella query SQL.
(Facoltativo) Utilizza i seguenti menu per limitare o formattare la tabella dei risultati:
- Cerca in tutti i campi: cerca le stringhe corrispondenti. Le selezioni vengono mappate alla clausola WHERE nella query SQL.
- Colonne: seleziona le colonne che vengono visualizzate nella tabella dei risultati. Le selezioni vengono mappate alle clausole SELECT nella query SQL.
  
  Quando selezioni un nome di campo in questo menu, si apre una finestra di dialogo. In questa finestra di dialogo puoi:
  - Utilizzare il menu per aggregare o raggruppare i dati.
    
    Per evitare errori di sintassi, qualsiasi aggregazione e raggruppamento applicato a una colonna viene applicato automaticamente anche alle altre colonne. Per un esempio di come aggregare e raggruppare le voci, consulta Raggruppare e aggregare i dati utilizzando Query Builder.
  - Trasmettere un valore di qualsiasi tipo a un altro tipo di dati specificato. Per saperne di più, consulta la CAST documentazione.
  - Estrarre una sottostringa di valori utilizzando le espressioni regolari. Per saperne di più, consulta la REGEXP_EXTRACTdocumentazione.
- Filtri: aggiungi filtri quando vuoi limitare la query agli intervalli che contengono un attributo o un ID intervallo specifico. Il menu elenca tutte le opzioni di filtro disponibili. Le selezioni vengono mappate alla clausola WHERE nella query SQL.
- Ordina per: imposta le colonne in base a cui ordinare e se l'ordinamento è crescente o decrescente. Le selezioni vengono mappate alla clausola ORDER BY nella query SQL.
- Limite: imposta il numero massimo di righe nella tabella dei risultati. Le selezioni vengono mappate alla clausola LIMIT nella query SQL.
Per eseguire la query, vai alla barra degli strumenti e seleziona Esegui query.

Observability Analytics presenta i risultati della query in una tabella. Tuttavia, puoi creare un grafico e salvare la tabella o il grafico in una dashboard personalizzata. Per saperne di più, consulta Creare grafici dei risultati delle query SQL.

Se la barra degli strumenti visualizza Esegui in BigQuery, devi passare a Observability Analytics per utilizzare il motore di query predefinito. Per apportare questa modifica, nella barra degli strumenti del riquadro Query, fai clic su Impostazioni e seleziona Analytics (predefinito).

Esempio: raggruppare e aggregare i dati utilizzando Query Builder

Quando selezioni una colonna in Query Builder, ogni campo include un menu in cui puoi aggiungere raggruppamenti e aggregazioni. Il raggruppamento ti consente di organizzare i dati in gruppi in base al valore di una o più colonne, mentre l'aggregazione ti consente di eseguire calcoli su questi gruppi per restituire un singolo valore.

Ogni campo selezionato nell'elemento Colonne ha un menu allegato con le seguenti opzioni:

Nessuno: non raggruppare o aggregare in base a questo campo.
Aggrega: raggruppa i campi elencati nell'elemento Colonne, tranne quando il campo ha una selezione Aggrega. Per questi campi, calcola il valore eseguendo un'operazione su tutte le voci in ogni raggruppamento. L'operazione potrebbe essere il calcolo della media di un campo o il conteggio del numero di voci in ogni raggruppamento.
Raggruppa per: raggruppa le voci in base a tutti i campi elencati nell'elemento Colonne.

Di seguito è riportato un esempio di come creare una query che raggruppa le voci ed esegue un tipo di aggregazione.

Questo esempio descrive come utilizzare Query Builder per raggruppare le voci di log in base a gravità e timestamp e quindi calcolare la media del campo http_request.response_size per ogni gruppo.

Per creare una query che raggruppa e aggrega i dati, effettua le seguenti selezioni dai menu di Query Builder:

Nel menu Colonne , seleziona i campi timestamp, severity e http_request.response_size.
1. Per raggruppare i dati, fai clic sul campo timestamp per aprire la finestra di dialogo delle impostazioni. In questa finestra di dialogo, seleziona l'opzione Raggruppa per e imposta la granularità di troncamento su HOUR. Il raggruppamento viene quindi applicato automaticamente a tutti gli altri campi per evitare errori di sintassi. Se sono presenti campi non validi in cui non è possibile applicare il raggruppamento, viene visualizzato un messaggio di errore. Rimuovi i campi non validi dal menu per risolvere l'errore.
2. Per eseguire l'aggregazione sul campo http_request.response_size, fai clic sul campo per aprire la finestra di dialogo delle impostazioni. In questa finestra di dialogo, seleziona Aggrega. Nel menu Aggregazione, fai clic su Media.
  
  Nota: se selezioni l'opzione Aggrega , il raggruppamento viene applicato automaticamente anche alle colonne.
Nel menu Filtri, aggiungi http_request.response_size e imposta il comparatore su IS NOT NULL. Questo filtro corrisponde alle voci di log che contengono un valore response_size.

I menu di Query Builder sono simili ai seguenti:

Per eseguire la query, vai alla barra degli strumenti e seleziona Esegui query.

I risultati di questa query sono simili ai seguenti:

+-----------------------------------+----------+---------------+
| Row | hour_timestamp              | severity | response_size |
|     | TIMESTAMP                   | STRING   | INTEGER       |
+-----+-----------------------------+----------+---------------+
| 1   | 2025-10-06 16:00:00.000 UTC | NOTICE   | 3082          |
| 2   | 2025-10-06 17:00:00.000 UTC | WARNING  | 338           |
| 3   | 2025-10-06 16:00:00.000 UTC | INFO     | 149           |

La query SQL corrispondente all'esempio precedente è la seguente:

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
  severity,
  -- Compute average response_size.
  AVG( http_request.response_size ) AS average_http_request_response_size
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a response_size.
  http_request.response_size IS NOT NULL
GROUP BY
  -- Group log entries by timestamp and severity.
  TIMESTAMP_TRUNC( timestamp, HOUR ),
  severity
LIMIT
  1000

Visualizzare lo schema

Lo schema definisce la modalità di archiviazione dei dati, inclusi i campi e i relativi tipi di dati. Queste informazioni sono importanti perché lo schema determina i campi su cui esegui query e se devi trasmettere i campi a tipi di dati diversi. Ad esempio, per scrivere una query che calcola la latenza media delle richieste HTTP, devi sapere come accedere al campo della latenza e se viene memorizzato come numero intero, ad esempio 100, o come stringa, ad esempio "100". Se i dati di latenza vengono memorizzati come stringa, la query deve trasmettere il valore a un valore numerico prima di calcolare una media.

Per identificare lo schema:

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.
Nel menu Visualizzazioni , vai alla Log o Visualizzazioni di analisi e seleziona la visualizzazione su cui vuoi eseguire query.

Il riquadro Schema viene aggiornato. Observability Analytics deduce automaticamente i campi di una colonna quando il tipo di dati è JSON. Per visualizzare la frequenza con cui questi campi dedotti vengono visualizzati nei dati, fai clic su Opzioni e seleziona Visualizza informazioni e descrizione.

Per le visualizzazioni di log, lo schema è fisso e corrisponde a LogEntry. Per le visualizzazioni di analisi, puoi modificare la query SQL per cambiare lo schema.

Passaggi successivi

Scopri di più sulle visualizzazioni di analisi.
Salva e condividi una query SQL.
Crea grafici dei risultati delle query SQL.
Esempi di query SQL.
Esegui una query su un set di dati collegato in BigQuery.