Query SQL di esempio per Trace

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei 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 ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questo documento contiene query di esempio che sono specifiche per l'esecuzione di query sui dati di traccia archiviati nel tuo Google Cloud progetto.

Supporto del linguaggio SQL

Le query utilizzate nella pagina Observability Analytics supportano le funzioni GoogleSQL con alcune eccezioni.

I seguenti comandi SQL non sono supportati per le query SQL emesse utilizzando la pagina Observability Analytics:

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

I seguenti elementi sono supportati solo quando esegui una query su un set di dati collegato utilizzando le pagine BigQuery Studio e Looker Studio o 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 dell'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 mostra come filtrare in base al timestamp:

-- Matches trace spans whose start_time is within the most recent 1 hour.
WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

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

Prima di iniziare

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.

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 Observability 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à su cui vuoi eseguire query. Questo ruolo supporta le condizioni IAM, che ti consentono di limitare la concessione a una visualizzazione specifica. Se non associ 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 e per 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 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. Nel riquadro Query, fai clic su  SQL, quindi copia e incolla una query nel riquadro della query SQL.

   Di seguito è riportato il formato della clausola FROM per l'esecuzione di query sulla visualizzazione _AllSpans:

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

   La clausola FROM contiene i seguenti campi:

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

Per utilizzare le query mostrate in questo documento nella pagina BigQuery Studio o per utilizzare lo strumento a riga di comando bq, quindi modifica la clausola FROM e inserisci il percorso del set di dati collegato. Ad esempio, per eseguire una query sulla _AllSpans visualizzazione 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 le informazioni comuni degli span

Per mostrare le informazioni comuni degli 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 degli 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 saperne di più sull'enumerazione, consulta la documentazione di OpenTelemetry: SpanKind.

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

Filtra le voci di traccia

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

Filtra per tipi di dati stringa

Il campo name viene memorizzato come String.

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

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

• Per analizzare solo gli span 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 span 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 span in cui è specificato kind, utilizza la seguente clausola:

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

• Per analizzare gli span il cui valore kind è uno o due, 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 memorizzare una o più strutture di dati oppure memorizzare voci ripetute della stessa struttura di dati.

Filtra 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 solo gli span 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 span 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
  

Filtra per eventi o link

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

• Per trovare gli span che hanno 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 gli span 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'
    )
  

Filtra per tipi di dati JSON

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

• Per analizzare solo gli span 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 span in cui la chiave dell'attributo denominata component ha il valore "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%'
  

Raggruppa e aggrega i dati di traccia

Questa sezione illustra come raggruppare e aggregare gli span. Se non specifichi un raggruppamento, ma specifichi 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 gli span per ora di inizio

Per raggruppare i dati per 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 TIMESTAMP_TRUNC documentazione e 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.

Conta gli span 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 segnala il numero di span 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 dello span.

Calcola la durata media di tutti gli span

Per visualizzare la durata media, dopo aver raggruppato i dati degli span per nome dello span, 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 colonne

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

• Ricerche basate su token: specifichi la località di ricerca, una query di ricerca e poi utilizzi la SEARCH funzione. Poiché la funzione SEARCH ha regole specifiche su come vengono cercati i dati, ti consigliamo di leggere la documentazione di SEARCH.

• Ricerche basate su sottostringhe: fornisci la località di ricerca, un valore letterale stringa, e poi utilizzi 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 se il valore letterale stringa esiste e FALSE in caso contrario. Il valore di ricerca deve essere un valore letterale STRING, ma non il valore letterale NULL.

Esegui query su più visualizzazioni

Le istruzioni di query analizzano una o più tabelle o espressioni e restituiscono le righe di risultati calcolate. 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 località delle visualizzazioni soddisfano una delle seguenti condizioni:

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

2. Quando le risorse di archiviazione utilizzano le chiavi di crittografia gestite dal cliente (CMEK), deve essere soddisfatta 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 da l'unione con la chiave Cloud KMS comune o con la chiave Cloud KMS predefinita dell'antenato.

Ad esempio, supponiamo di avere due visualizzazioni che si trovano nella stessa località. 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 predecessore che specifica una chiave Cloud KMS predefinita che si trova nella stessa località delle risorse di archiviazione.

  Ad esempio, supponiamo che la gerarchia delle risorse per un bucket di log e un bucket di osservabilità includa la stessa organizzazione. Puoi unire le visualizzazioni su 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 località di archiviazione.

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

La seguente query unisce i dati di log e di 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 su di essi singolarmente per raccogliere ulteriori informazioni. Inoltre, i risultati elencano la gravità della voce di log e il payload JSON.

Passaggi successivi

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

Per la documentazione di riferimento 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.