Eseguire query e analizzare la telemetria con Analisi dei log

Questo documento descrive come eseguire query e analizzare i dati di log e traccia utilizzando Analisi dei log, che fornisce un'interfaccia di query basata su SQL. SQL ti consente di eseguire analisi aggregate, che possono aiutarti a generare insight e identificare tendenze. Per visualizzare i risultati della query, utilizza il modulo tabellare o visualizza i dati con i grafici. Puoi anche salvare queste tabelle e questi grafici nelle dashboard personalizzate.

Informazioni sui set di dati BigQuery collegati

Non hai bisogno di un set di dati BigQuery collegato per eseguire query sui dati di log, sui dati di traccia o su entrambi i tipi di dati quando utilizzi la pagina Log Analytics.

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

  • Unire i dati di log o di traccia ad altri set di dati BigQuery.
  • Esegui query sui dati di log o di traccia da un altro servizio, ad esempio la pagina BigQuery Studio o Looker Studio.
  • Migliora le prestazioni delle query eseguite da Analisi dei log eseguendole negli slot riservati BigQuery.
  • Crea una policy di avviso che monitori il risultato di una query SQL. Questa funzionalità è supportata solo quando vengono eseguite query sui dati di log. Per saperne di più, consulta Monitorare i risultati delle query SQL con una policy di avviso.

Questo documento non descrive come creare un set di dati collegato, che richiede un processo specifico per il tipo di dati. Per scoprire come creare un set di dati collegato, consulta Eseguire query sui dati dei log utilizzando un set di dati collegato o Eseguire query sui dati di traccia utilizzando un set di dati collegato.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Abilita l'API Observability.

    Ruoli richiesti per abilitare le API

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

    Abilitare l'API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Abilita l'API Observability.

    Ruoli richiesti per abilitare le API

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

    Abilitare l'API

    8.

  8. Per ottenere le autorizzazioni necessarie per caricare la pagina Log Analytics, scrivere, eseguire e salvare query private sui dati di traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM:

    • Observability View Accessor (roles/observability.viewAccessor) sulle visualizzazioni di osservabilità che vuoi interrogare. Questo ruolo supporta le condizioni IAM, che ti consentono di limitare la concessione a una visualizzazione specifica. Se non colleghi una condizione alla concessione del ruolo, l'entità può accedere a tutte le visualizzazioni di osservabilità. Le visualizzazioni di osservabilità sono in Anteprima pubblica.
    • Observability Analytics User (roles/observability.analyticsUser) sul tuo progetto. Questo ruolo contiene le autorizzazioni necessarie per salvare ed eseguire query private ed eseguire query condivise.
    • Visualizzatore log (roles/logging.viewer) sul tuo progetto
    • Logs View Accessor (roles/logging.viewAccessor) sul progetto che memorizza le visualizzazioni log su cui vuoi eseguire query.

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Esegui query sui dati di log e di traccia

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

  • 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 join, query nidificate e altre istruzioni SQL complesse. Per esempi, vedi Query SQL di esempio.
  • Crea una query selezionando le opzioni del menu e poi eseguila. Analisi dei log converte le selezioni in una query SQL, che puoi visualizzare e modificare.

Caricare, modificare ed eseguire la query definita dal sistema

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

    Vai ad Analisi dei log

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

  2. Nel menu Visualizzazioni, seleziona una visualizzazione.

    Per trovare la visualizzazione da interrogare, utilizza la barra Filtro o scorri l'elenco:

    • Le visualizzazioni dei log, elencate nella sezione Log, sono ordinate in base agli ID bucket e visualizzazione.

    • Le viste Analytics, elencate nella sezione Viste Analytics, sono ordinate per posizione e ID della vista. Le visualizzazioni di osservabilità sono in Anteprima pubblica.

    • Esiste una sola visualizzazione delle tracce, elencata nella sezione Tracce. Le visualizzazioni di osservabilità sono in Anteprima pubblica.

      Se non vedi una visualizzazione denominata _Trace.Spans._AllSpans, il tuo progettoGoogle Cloud non contiene un bucket di osservabilità denominato _Trace. Per informazioni su come risolvere questo errore, consulta Inizializzazione dell'archiviazione delle tracce non riuscita.

  3. Esegui una delle seguenti operazioni:

    • Per caricare una query definita dal sistema che si basa su Query Builder, che consente di definire la query con le selezioni del menu, assicurati che nel riquadro Query sia visualizzato Query Builder. Se viene visualizzato un editor SQL, fai clic su  Generatore.

    • Per caricare una query definita dal sistema che estrae i valori JSON, assicurati che il riquadro Query mostri l'editor SQL. Se in questo riquadro viene visualizzato Generatore di query, fai clic su  SQL.

  4. Nel riquadro Schema, seleziona Query e poi fai clic su Sovrascrivi.

    Il riquadro Query mostra una query definita dal sistema. Se hai selezionato la modalità Generatore di query, ma vuoi visualizzare la query SQL, fai clic su  SQL.

  5. (Facoltativo) Modifica la query.

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

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

    Se la barra degli strumenti mostra Esegui in BigQuery, devi impostare Log Analytics in modo che utilizzi il motore di query predefinito. Per apportare questa modifica, nella barra degli strumenti del riquadro Query, fai clic su Impostazioni e poi seleziona Analytics (impostazione predefinita).

Inserire ed eseguire una query personalizzata

Per inserire una query SQL:

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

    Vai ad Analisi dei log

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

  2. 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 questo selettore viene disattivato.

    • Per esempi, vedi Query SQL di esempio.

    • La visualizzazione che interroghi determina il formato della clausola FROM:

      Dati di log

      Puoi eseguire query sulle visualizzazioni dei log o sulle visualizzazioni di Analytics. Utilizza il seguente formato per la clausola FROM:

      • Visualizzazioni log:

        FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

      • Viste Analytics:

        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 posizione della visualizzazione dei log o della visualizzazione di analisi.
      • BUCKET_ID: il nome o l'ID del bucket di log.
      • LOG_VIEW_ID: l'identificatore della visualizzazione dei log, che è limitato a 100 caratteri e può includere solo lettere, cifre, trattini bassi e trattini.
      • ANALYTICS_VIEW_ID: l'ID della visualizzazione Analytics, 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 la visualizzazione non è stata trovata. Per informazioni su come risolvere questo errore, consulta La clausola Error FROM deve contenere esattamente una visualizzazione del log.

      Dati di Trace

      L'editor SQL mostra il nome completo della vista _Trace.Spans._AllSpans, che ha il seguente formato:

      FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

      I campi nell'espressione precedente hanno il seguente significato:

      Se nel riquadro della query viene visualizzato un messaggio di errore che fa riferimento all'istruzione FROM, significa che la visualizzazione non è stata trovata. Per informazioni su come risolvere questo errore, consulta Messaggio di errore che indica che una vista non esiste.

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

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

    Se la barra degli strumenti mostra Esegui in BigQuery, devi impostare Log Analytics in modo che utilizzi il motore di query predefinito. Per apportare questa modifica, nella barra degli strumenti del riquadro Query, fai clic su Impostazioni e poi seleziona Analytics (impostazione predefinita).

Creare, modificare ed eseguire una query

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

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

Per creare una query:

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

    Vai ad Analisi dei log

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

  2. Se nel riquadro Query viene visualizzato un editor SQL, seleziona Builder, che apre il riquadro Query Builder.

  3. Utilizza il menu Origine per selezionare la visualizzazione per cui vuoi eseguire una query. Le selezioni vengono mappate alla clausola FROM nella query SQL.

  4. (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 da visualizzare nella tabella dei risultati. Le tue selezioni vengono mappate alle clausole SELECT nella query SQL.

      Quando selezioni un nome campo in questo menu, si apre una finestra di dialogo. In questa finestra di dialogo, puoi:

      • Utilizza il menu per aggregare o raggruppare i dati.

        Per evitare errori di sintassi, qualsiasi aggregazione e raggruppamento che applichi 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.

      • Trasforma un valore di qualsiasi tipo in un altro tipo di dati specificato. Per saperne di più, consulta la documentazione relativa a CAST.

      • Estrai una sottostringa di valori utilizzando le espressioni regolari. Per saperne di più, consulta la documentazione relativa a REGEXP_EXTRACT.

    • 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 tue selezioni vengono mappate alla clausola WHERE nella query SQL.

    • Ordina per: imposta le colonne in base alle quali ordinare e se l'ordinamento è crescente o decrescente. Le tue selezioni vengono mappate alla clausola ORDER BY nella query SQL.

    • Limite: imposta il numero massimo di righe nella tabella dei risultati. Le tue selezioni vengono mappate alla clausola LIMIT nella query SQL.

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

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

    Se la barra degli strumenti mostra Esegui in BigQuery, devi impostare Log Analytics in modo che utilizzi il motore di query predefinito. Per apportare questa modifica, nella barra degli strumenti del riquadro Query, fai clic su Impostazioni e poi seleziona Analytics (impostazione predefinita).

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 di 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 viene illustrato come creare una query che raggruppa le voci e poi esegue un tipo di aggregazione.

Dati di log

Questo esempio descrive come utilizzare Query Builder per raggruppare le voci di log per gravità e timestamp, 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:

  1. 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à 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.

  2. 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:

    Aggrega e raggruppa utilizzando i menu di Query Builder.

  3. 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 per l'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

Dati di Trace

Questo esempio descrive come utilizzare Query Builder per raggruppare gli span in base all'ora di inizio, al nome dello span e al tipo di span. Poi, per ogni gruppo, la query calcola la durata media in nanosecondi.

Per creare questa query:

  1. Nel menu Colonne, seleziona i campi start_time, name, kind e duration_nano.
  2. Per troncare l'ora di inizio, espandi il menu nella colonna start_time e seleziona Raggruppa per. Assicurati che il menu di granularità sia impostato su Ora.

  3. Fai clic su Applica.

    Quando selezioni Raggruppa per per una colonna, il sistema raggruppa le voci in base a tutte le colonne. In questo esempio, le voci sono raggruppate in base al valore troncato di start_time, al nome dello span, al tipo di span e al valore della durata.

    Tuttavia, l'obiettivo di questo esempio è raggruppare le voci in base all'ora troncata, al nome dello span e al tipo di span e, per ogni gruppo, calcolare la durata media. Nel passaggio successivo, modifichi il raggruppamento e aggiungi un'aggregazione.

  4. Espandi il menu nel campo duration_nano, seleziona Aggrega e poi imposta il campo Aggregazione su Media.

    Quando esegui la query, ogni riga corrisponde a un gruppo, che consiste in un orario troncato, un nome di intervallo e un tipo di intervallo. L'ultima voce di ogni riga è la durata media di tutte le voci del gruppo.

    I risultati di questa query sono simili ai seguenti:

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duation_nano  |
|     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
+-----+-----------------------------+-----------+---------------+-----------------------+
| 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
| 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
| 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376

  5. La query può includere più aggregazioni. Ad esempio, per aggiungere una colonna che conteggia il numero di voci in ogni gruppo, procedi nel seguente modo:

    1. Nell'elemento Colonne, fai clic su Aggiungi colonna.
    2. Seleziona Tutti (*).
    3. Nella finestra di dialogo, seleziona Aggrega, poi Conteggio per Aggregazione e infine Applica.

    Con questa modifica, il raggruppamento rimane invariato. Le voci sono raggruppate per ora di inizio troncata, nome dell'intervallo e tipo di intervallo. Tuttavia, per ogni gruppo, la query calcola la durata media e il numero di voci.

La query SQL corrispondente per l'esempio precedente è la seguente:

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.global._Trace._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

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 per te perché lo schema determina i campi che interroghi e se devi eseguire il cast dei campi in tipi di dati diversi. Ad esempio, per scrivere una query che calcola la latenza media delle richieste HTTP, devi sapere come accedere al campo latenza e se è memorizzato come numero intero, ad esempio 100, o come stringa, ad esempio "100". Se i dati di latenza sono memorizzati come stringa, la query deve eseguire il cast del valore in un valore numerico prima di calcolare una media.

Per identificare lo schema:

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

    Vai ad Analisi dei log

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

  2. Nel menu Visualizzazioni, seleziona una visualizzazione.

    Il riquadro Schema viene aggiornato. Log 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.

    Dati di log

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

    Dati di Trace

    Per informazioni sullo schema, vedi Schema di archiviazione per i dati di traccia.

    Se non vedi una visualizzazione denominata _Trace.Spans._AllSpans, il tuo progettoGoogle Cloud non contiene un bucket di osservabilità denominato _Trace. Per informazioni su come risolvere questo errore, consulta Inizializzazione dell'archiviazione delle tracce non riuscita.

Limitazioni

Se vuoi eseguire query su più visualizzazioni, queste devono trovarsi nella stessa posizione. Ad esempio, se memorizzi due viste nella posizione us-east1, una query può eseguire query su entrambe le viste. Puoi anche eseguire query su due viste archiviate nella multi-regione us. Tuttavia, se la località di una visualizzazione è global, la visualizzazione può risiedere in qualsiasi posizione fisica. Pertanto, i join tra due viste che hanno la posizione di global potrebbero non riuscire.

Per un elenco delle limitazioni applicate ai dati dei log, consulta Log Analytics: Restrictions.

Passaggi successivi