Query SQL di esempio per Trace

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Questo documento contiene query di esempio specifiche per l'interrogazione dei dati di traccia archiviati nel tuo progetto Google Cloud .

Supporto del linguaggio SQL

Le query utilizzate nella pagina Analisi dei log supportano le funzioni GoogleSQL con alcune eccezioni.

I seguenti comandi SQL non sono supportati per le query SQL emesse utilizzando la pagina Analisi dei log:

• Comandi DDL e DML
• Funzioni definite dall'utente JavaScript
• Funzioni BigQuery ML
• Variabili SQL

I seguenti elementi sono supportati solo quando esegui query su un set di dati collegato utilizzando le pagine BigQuery Studio e Looker Studio o utilizzando lo strumento a riga di comando bq:

• Funzioni definite dall'utente JavaScript
• Funzioni BigQuery ML
• Variabili SQL

Best practice

Per impostare l'intervallo di tempo della query, ti consigliamo di utilizzare il selettore dell'intervallo di tempo. Ad esempio, per visualizzare i dati relativi all'ultima settimana, seleziona Ultimi 7 giorni dal selettore dell'intervallo di tempo. Puoi anche utilizzare il selettore dell'intervallo di tempo per specificare un'ora di inizio e di fine, specificare un'ora da visualizzare e modificare i fusi orari.

Se includi un campo start_time nella clausola WHERE, l'impostazione del selettore dell'intervallo di tempo non viene utilizzata. L'esempio seguente filtra i dati utilizzando la funzione TIMESTAMP_SUB, che consente di specificare un intervallo di analisi a ritroso a partire dall'ora corrente:

WHERE
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

Per saperne di più su come filtrare in base all'ora, vedi Funzioni temporali e Funzioni timestamp.

Prima di iniziare

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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

Come utilizzare le query in questa pagina

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, poi copia e incolla una query nel riquadro Query SQL.

   Di seguito è riportato il formato della causa FROM per l'interrogazione della visualizzazione _AllSpans:

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

   La clausola FROM contiene i seguenti campi:

   • PROJECT_ID: l'identificatore del progetto.
   • LOCATION: la posizione del bucket di osservabilità.
   • _Trace è il nome del bucket osservabilità
   • Spans è il nome del set di dati.
   • _AllSpans è il nome della vista.
   Nota: i delimitatori del percorso sono punti, (.). Se un elemento del percorso, ad esempio il progetto Google Cloud , contiene un punto, assicurati che ogni campo del percorso sia racchiuso tra virgolette inverse singole,(`).

Per utilizzare le query mostrate in questo documento nella pagina BigQuery Studio o per utilizzare lo strumento a riga di comando bq, modifica la clausola FROM e inserisci il percorso del set di dati collegato. Ad esempio, per eseguire una query sulla visualizzazione _AllSpans nel set di dati collegato denominato my_linked_dataset che si trova nel progetto myproject, il percorso è `myproject.my_linked_dataset._AllSpans`.

Casi d'uso comuni

Questa sezione elenca diversi casi d'uso comuni che potrebbero aiutarti a creare le tue query personalizzate.

Mostra tutti i dati di traccia

Per eseguire una query sulla visualizzazione _AllSpans, esegui la seguente query:

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

Mostra informazioni sulla durata comune

Per mostrare le informazioni comuni dello span, come l'ora di inizio e la durata, esegui la seguente query:

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

Per saperne di più, consulta Espressioni condizionali.

Mostra il 50° e il 99° percentile della latenza dello span

Per mostrare il 50° e il 99° percentile della latenza per ogni servizio RPC, esegui la seguente query:

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

Per ulteriori informazioni sull'enumerazione, consulta la documentazione di OpenTelemetry: SpanKind.

Per visualizzare i risultati in formato grafico, puoi creare un grafico con la dimensione impostata su rpc_service_method. Potresti aggiungere due misure, una per la media del valore duration_nano_p50 e l'altra per la media del campo duration_nano_p99.

Filtra voci di traccia

Per applicare un filtro alla query, aggiungi una clausola WHERE. La sintassi che utilizzi in questa clausola dipende dal tipo di dati del campo. Questa sezione fornisce diversi esempi per diversi tipi di dati.

Filtrare per tipi di dati stringa

Il campo name viene memorizzato come String.

• Per analizzare solo gli intervalli in cui è specificato name, utilizza la seguente clausola:

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• Per analizzare solo gli intervalli in cui name ha il valore "POST", utilizza la seguente clausola:

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• Per analizzare solo gli intervalli in cui name contiene il valore "POST", utilizza l'operatore LIKE insieme ai caratteri jolly:

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

Filtra per tipi di dati interi

Il campo kind è un numero intero che può assumere valori compresi tra zero e cinque:

• Per analizzare solo gli intervalli in cui è specificato kind, utilizza la seguente clausola:

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

• Per analizzare gli intervalli il cui valore di kind è 1 o 2, utilizza la seguente clausola:

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

Filtra per tipi di dati RECORD

Alcuni campi nello schema di traccia hanno un tipo di dati RECORD. Questi campi possono archiviare una o più strutture di dati oppure voci ripetute della stessa struttura di dati.

Filtrare per stato o codice di stato

Il campo status è un esempio di campo il cui tipo di dati è RECORD. Questo campo memorizza una struttura di dati, con membri etichettati code e message.

• Per analizzare gli intervalli solo quando il campo status.code ha un valore di 1, aggiungi la seguente clausola:

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  Il campo status.code viene memorizzato come numero intero.

• Per analizzare gli intervalli in cui il campo status non è EMPTY, aggiungi la seguente clausola:

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

Filtrare per eventi o link

I campi events e links vengono archiviati con un tipo di dati RECORD, ma si tratta di campi ripetuti.

• Per trovare intervalli con almeno un evento, utilizza la seguente clausola:

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• Per trovare corrispondenze con gli intervalli che hanno un evento il cui campo name ha il valore message, utilizza la seguente clausola:

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

Filtrare per tipi di dati JSON

Il campo attributes è di tipo JSON. Ogni singolo attributo è una coppia chiave-valore.

• Per analizzare solo gli intervalli in cui è specificato attributes, utilizza la seguente clausola:

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• Per analizzare solo gli intervalli in cui la chiave dell'attributo denominata component ha un valore di "proxy", utilizza la seguente clausola:

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

  Puoi anche utilizzare un'istruzione LIKE insieme ai caratteri jolly per eseguire un test di contenimento:

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

Raggruppare e aggregare i dati di traccia

Questa sezione illustra come raggruppare e aggregare gli span. Se non specifica un raggruppamento, ma specifica un'aggregazione, viene stampato un risultato perché SQL considera tutte le voci che soddisfano la clausola WHERE come un unico gruppo.

Ogni espressione SELECT deve essere inclusa nei campi del gruppo o essere aggregata.

Raggruppa intervalli per ora di inizio

Per raggruppare i dati in base all'ora di inizio, utilizza la funzione TIMESTAMP_TRUNC, che tronca un timestamp a una granularità specificata, ad esempio HOUR:

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

Per saperne di più, consulta la documentazione di TIMESTAMP_TRUNC e le funzioni di data e ora.

Nota: se includi un campo start_time nella clausola WHERE, l'impostazione del selettore dell'intervallo di tempo non viene utilizzata.

Conteggio degli intervalli per codice di stato

Per visualizzare il conteggio degli span con un codice di stato specifico, esegui la seguente query:

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

Se sostituisci status.code con kind, la query precedente riporta il numero di intervalli per ogni valore dell'enumerazione kind. Analogamente, se sostituisci status.code con name, i risultati della query elencano il numero di voci per ogni nome di intervallo.

Calcola la durata media di tutti gli intervalli

Per visualizzare la durata media, dopo aver raggruppato i dati degli intervalli per nome dell'intervallo, esegui la seguente query:

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

Calcola la durata media e i percentili per nome del servizio

La seguente query calcola il conteggio degli span e varie statistiche per ogni servizio:

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

Ricerca tra le colonne

Questa sezione descrive due approcci che puoi utilizzare per eseguire ricerche in più colonne della visualizzazione su cui stai eseguendo query:

• Ricerche basate su token: specifichi la posizione di ricerca, una query di ricerca e poi utilizzi la funzione SEARCH. Poiché la funzione SEARCH ha regole specifiche per la ricerca dei dati, ti consigliamo di leggere la SEARCH documentazione.

• Ricerche basate su sottostringhe: fornisci la posizione di ricerca, una stringa letterale e poi utilizza la funzione CONTAINS_SUBSTR. Il sistema esegue un test senza distinzione tra maiuscole e minuscole per determinare se il valore letterale stringa esiste in un'espressione. La funzione CONTAINS_SUBSTR restituisce TRUE quando esiste il valore letterale stringa e FALSE in caso contrario. Il valore di ricerca deve essere un valore letterale STRING, ma non il valore letterale NULL.

Eseguire query su più viste

Le istruzioni di query analizzano una o più tabelle o espressioni e restituiscono le righe di risultati calcolati. Ad esempio, puoi utilizzare le istruzioni di query per unire i risultati delle istruzioni SELECT su tabelle o set di dati diversi in vari modi e poi selezionare le colonne dai dati combinati.

Per unire le visualizzazioni, si applicano le seguenti limitazioni:

1. Le posizioni delle visualizzazioni soddisfano uno dei seguenti requisiti:

   • Tutte le visualizzazioni hanno la stessa posizione.
   • Tutte le visualizzazioni si trovano nella posizione global o us.

2. Quando le risorse di archiviazione utilizzano le chiavi di crittografia gestite dal cliente (CMEK), deve essere vera una delle seguenti condizioni:

   • Le risorse di archiviazione che utilizzano CMEK utilizzano la stessa chiave Cloud KMS.
   • Le risorse di archiviazione che utilizzano CMEK hanno un predecessore comune e questo predecessore specifica una chiave Cloud KMS predefinita che si trova nella stessa località delle risorse di archiviazione.

   Quando una o più risorse di archiviazione utilizzano CMEK, il sistema cripta i dati temporanei generati dall'unione con la chiave Cloud KMS comune o con la chiave Cloud KMS predefinita dell'elemento principale.

Ad esempio, supponiamo di avere due viste che si trovano nella stessa posizione. Puoi unire queste visualizzazioni quando si verifica una delle seguenti condizioni:

• Le risorse di archiviazione non utilizzano CMEK.
• Una risorsa di archiviazione utilizza CMEK e l'altra no.
• Entrambe le risorse di archiviazione utilizzano CMEK e la stessa chiave Cloud KMS.

• Entrambe le risorse di archiviazione utilizzano CMEK, ma chiavi diverse. Tuttavia, le risorse condividono un antenato che specifica una chiave Cloud KMS predefinita che si trova nella stessa posizione delle risorse di archiviazione.

  Ad esempio, supponiamo che la gerarchia delle risorse per un bucket dei log e un bucket di osservabilità includa la stessa organizzazione. Puoi unire le visualizzazioni di questi bucket quando, per l'organizzazione, hai configurato le impostazioni predefinite delle risorse per Cloud Logging e per i bucket di osservabilità con la stessa chiave Cloud KMS predefinita per la posizione di archiviazione.

Unire i dati di traccia e di log utilizzando l'ID traccia

La seguente query unisce i dati di log e traccia utilizzando gli ID span e traccia:

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

La risposta della query elenca l'ID traccia e l'ID span, che ti consentono di eseguire query individualmente per raccogliere maggiori informazioni. Inoltre, i risultati elencano la gravità della voce di log e il payload JSON.

Passaggi successivi

• Salva e condividi una query SQL.
• Grafici dei risultati delle query SQL.
• Esegui una query su un set di dati collegato in BigQuery.

Per la documentazione di riferimento di SQL o altri esempi, consulta i seguenti documenti:

• Funzioni, operatori e condizioni.
• Funzioni di ricerca.
• Sintassi delle query.
• Query SQL di esempio per Cloud Logging.