Esegui query e analizza le tracce

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

Se vuoi visualizzare o esplorare singole tracce o intervalli oppure visualizzare gli attributi collegati agli intervalli, utilizza la pagina Esplora tracce. Per informazioni su questa pagina, consulta Trovare ed esplorare le tracce.

Per le tracce, puoi eseguire query su un bucket di osservabilità denominato _Trace. È disponibile una visualizzazione, _AllSpans, per l'esecuzione di query. Per scoprire di più su come vengono archiviati i dati di traccia, consulta Panoramica dell'archiviazione.

Informazioni sui set di dati BigQuery collegati

Non hai bisogno di un set di dati BigQuery collegato per eseguire query sui dati di traccia o sui dati di traccia e di log. In questi scenari, puoi utilizzare la pagina Analisi dei log. Per informazioni sull'esecuzione di query sui dati di log, consulta Eseguire query e analizzare i log con Analisi dei log.

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

  • Unire i dati di traccia ad altri set di dati BigQuery.
  • Eseguire query sui dati di traccia da un altro servizio, ad esempio la pagina BigQuery Studio o Looker Studio.
  • Migliorare le prestazioni delle query eseguite da Analisi dei log eseguendole negli slot riservati di BigQuery.

Questo documento non descrive come creare un set di dati collegato o come configurare Analisi dei log per eseguire query sugli slot riservati. Per informazioni su questi argomenti, consulta Eseguire query su un set di dati BigQuery collegato.

Prima di iniziare

  1. Accedi al tuo Google Cloud account. 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. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the 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. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

  8. Per ottenere le autorizzazioni necessarie per caricare la pagina Analisi dei log, 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à su cui vuoi eseguire query. Questo ruolo supporta le condizioni IAM, che consentono di limitare la concessione a una visualizzazione specifica. Se non alleghi una condizione alla concessione del ruolo, l'entità può accedere a tutte le visualizzazioni di osservabilità.
    • 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.

    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.

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 le 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:

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

    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, vai alla sezione Tracce, e seleziona _Trace.Spans._AllSpans.

    Il riquadro Schema viene aggiornato. Analisi dei log 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 scoprire di più sullo schema, consulta Schema di archiviazione per i dati di traccia.

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

Eseguire query sui dati di traccia

Questa sezione descrive gli approcci che puoi utilizzare per eseguire query sui dati di 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 unioni, query nidificate e altre istruzioni SQL complesse. Per esempi, consulta Esempi di query SQL.
  • Crea una query effettuando selezioni dal menu ed 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 Google Cloud console, vai alla Analisi dei log page:

    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, vai alla sezione Tracce, e seleziona _Trace.Spans._AllSpans.

    Se non vedi una visualizzazione denominata _Trace.Spans._AllSpans, allora il tuo Google Cloud progetto 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  Builder.

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

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

    Nel riquadro Query viene visualizzata una query definita dal sistema. Se hai selezionato la modalità Query Builder, 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.

    Analisi dei log 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 ulteriori informazioni, consulta Creare grafici dei risultati delle query SQL.

    Se nella barra degli strumenti viene visualizzato Esegui in BigQuery, devi impostare Analisi dei log 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 seleziona Analytics (predefinito).

Inserire ed eseguire una query personalizzata

Per inserire una query SQL:

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

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

    • Per esempi, consulta Esempi di query SQL.

    • L'editor SQL mostra il nome completo della visualizzazione _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 non è stato possibile trovare la visualizzazione. Per informazioni su come risolvere questo errore, consulta Messaggio di errore che indica che una visualizzazione non esiste.

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

    Analisi dei log 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 ulteriori informazioni, consulta Creare grafici dei risultati delle query SQL.

    Se nella barra degli strumenti viene visualizzato Esegui in BigQuery, devi impostare Analisi dei log 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 seleziona Analytics (predefinito).

Creare, modificare ed eseguire una query

L'interfaccia Query Builder 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, puoi iniziare a utilizzare l'interfaccia Query Builder e poi passare all'editor SQL per perfezionare la query.

Analisi dei log può sempre convertire le selezioni del 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:

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

    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 su cui vuoi eseguire 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 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 ulteriori informazioni, consulta la CAST documentazione.

      • Estrarre una sottostringa di valori utilizzando le espressioni regolari. Per ulteriori informazioni, consulta la REGEXP_EXTRACT documentazione.

    • 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 alle quali 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.

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

    Analisi dei log 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 ulteriori informazioni, consulta Creare grafici dei risultati delle query SQL.

    Se nella barra degli strumenti viene visualizzato Esegui in BigQuery, devi impostare Analisi dei log 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 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 consente di organizzare i dati in gruppi in base al valore di una o più colonne, mentre l'aggregazione 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 qualcosa di simile al 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 ed esegue un tipo di aggregazione.

Questo esempio descrive come utilizzare Query Builder per raggruppare gli intervalli in base all'ora di inizio, al nome dell'intervallo e al tipo di intervallo. 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 all'ora, espandi il menu nella colonna start_time e seleziona Raggruppa per. Assicurati che il menu della 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 vengono raggruppate in base al valore troncato di start_time, al nome dell'intervallo, al tipo di intervallo e al valore della durata.

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

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

    Quando esegui la query, ogni riga corrisponde a un gruppo, composto da un'ora troncata, 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 conta il numero di voci in ogni gruppo:

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

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

La query SQL corrispondente all'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

Passaggi successivi