Exemplos de consultas SQL para o Trace

Pré-lançamento

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Este documento contém exemplos de consultas específicas para dados de rastreamento armazenados no seu projeto Google Cloud .

Compatibilidade com a linguagem SQL

As consultas usadas na página Análise de dados de registros são compatíveis com funções do GoogleSQL, com algumas exceções.

Os seguintes comandos SQL não são compatíveis com consultas SQL emitidas usando a página Análise de dados de registros:

• Comandos DDL e DML
• Funções JavaScript definidas pelo usuário
• Funções do BigQuery ML
• Variáveis SQL

Os itens a seguir só são compatíveis quando você consulta um conjunto de dados vinculado usando as páginas BigQuery Studio e Looker Studio ou a ferramenta de linha de comando bq:

• Funções JavaScript definidas pelo usuário
• Funções do BigQuery ML
• Variáveis SQL

Práticas recomendadas

Para definir o período da consulta, recomendamos que você use o seletor de período. Por exemplo, se você quiser ver os dados da semana passada, selecione Últimos 7 dias no seletor de período. Você também pode usar o seletor de período para especificar um horário de início e de término, definir um horário para visualizar e mudar os fusos horários.

Se você incluir um campo start_time na cláusula WHERE, a configuração do seletor de período não será usada. O exemplo a seguir filtra os dados usando a função TIMESTAMP_SUB, que permite especificar um intervalo de retorno do tempo atual:

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

Para mais informações sobre como filtrar por hora, consulte Funções de tempo e Funções de carimbo de data/hora.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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. Para receber as permissões necessárias para carregar a página Análise de dados de registros, escrever, executar e salvar consultas particulares nos dados de trace, peça ao administrador para conceder a você os seguintes papéis do IAM:

   • Acessador de visualização de observabilidade (roles/observability.viewAccessor) nas visualizações de observabilidade que você quer consultar. Esse papel aceita condições do IAM, que permitem restringir a concessão a uma visualização específica. Se você não anexar uma condição à concessão de função, o principal poderá acessar todas as visualizações de observabilidade.
   • Usuário do Analytics de observabilidade (roles/observability.analyticsUser) no seu projeto. Esse papel contém as permissões necessárias para salvar e executar consultas particulares e compartilhadas.
   • Visualizador de registros (roles/logging.viewer) no seu projeto.

   Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

   Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Como usar as consultas nesta página

1. No console Google Cloud , acesse a página Análise de dados de registros:

   Acesse Análise de registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. No painel Consulta, clique em  SQL e copie e cole uma consulta no painel de consulta SQL.

   Veja a seguir o formato da causa FROM para consultar a visualização _AllSpans:

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

   A cláusula FROM contém os seguintes campos:

   • PROJECT_ID: o identificador do projeto.
   • LOCATION: o local do bucket de observabilidade.
   • _Trace é o nome do bucket de observabilidade.
   • Spans é o nome do conjunto de dados.
   • _AllSpans é o nome da visualização.
   Observação: os delimitadores do caminho são pontos, (.). Se um elemento de caminho, como o projeto Google Cloud , contiver um ponto, verifique se todos os campos de caminho estão entre acentos graves simples, (`).

Para usar as consultas mostradas neste documento na página do BigQuery Studio ou usar a ferramenta de linha de comando bq, edite a cláusula FROM e insira o caminho para o conjunto de dados vinculado. Por exemplo, para consultar a visualização _AllSpans no conjunto de dados vinculado chamado my_linked_dataset que está no projeto myproject, o caminho é `myproject.my_linked_dataset._AllSpans`.

Casos de uso comuns

Esta seção lista vários casos de uso comuns que podem ajudar você a criar suas consultas personalizadas.

Mostrar todos os dados de trace

Para consultar a visualização _AllSpans, execute a seguinte consulta:

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

Mostrar informações de período comuns

Para mostrar informações comuns de intervalo, como o horário de início e a duração, execute a consulta a seguir:

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

Para saber mais, consulte Expressões condicionais.

Mostrar os percentis 50 e 99 da latência do intervalo

Para mostrar o 50º e o 99º percentis da latência de cada serviço de RPC, execute a seguinte consulta:

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

Para mais informações sobre a enumeração, consulte a documentação OpenTelemetry: SpanKind.

Para ver os resultados em um gráfico, crie um com a dimensão definida como rpc_service_method. Você pode adicionar duas métricas, uma para a média do valor duration_nano_p50 e outra para a média do campo duration_nano_p99.

Filtrar entradas de rastreamento

Para aplicar um filtro à sua consulta, adicione uma cláusula WHERE. A sintaxe usada nessa cláusula depende do tipo de dados do campo. Esta seção fornece vários exemplos para diferentes tipos de dados.

Filtrar por tipos de dados de string

O campo name é armazenado como um String.

• Para analisar apenas os intervalos em que name é especificado, use a seguinte cláusula:

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

• Para analisar apenas os intervalos em que name tem o valor "POST", use a seguinte cláusula:

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

• Para analisar apenas os intervalos em que name contém o valor "POST", use o operador LIKE com caracteres curinga:

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

Filtrar por tipos de dados inteiros

O campo kind é um número inteiro que pode assumir valores entre zero e cinco:

• Para analisar apenas os intervalos em que kind é especificado, use a seguinte cláusula:

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

• Para analisar intervalos cujo valor de kind é um ou dois, use a seguinte cláusula:

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

Filtrar por tipos de dados RECORD

Alguns campos no esquema de rastreamento têm um tipo de dados RECORD. Esses campos podem armazenar uma ou mais estruturas de dados ou entradas repetidas da mesma estrutura de dados.

Filtrar por status ou código de status

O campo status é um exemplo de campo cujo tipo de dados é RECORD. Esse campo armazena uma estrutura de dados com membros rotulados como code e message.

• Para analisar apenas intervalos quando o campo status.code tem um valor de 1, adicione a seguinte cláusula:

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

  O campo status.code é armazenado como um número inteiro.

• Para analisar intervalos em que o campo status não é EMPTY, adicione a seguinte cláusula:

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

Filtrar por eventos ou links

Os campos events e links são armazenados com um tipo de dados RECORD, mas são campos repetidos.

• Para corresponder a intervalos que têm pelo menos um evento, use a seguinte cláusula:

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

• Para corresponder a intervalos que têm um evento cujo campo name tem o valor message, use a seguinte cláusula:

  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'
    )
  

Filtrar por tipos de dados JSON

O campo attributes é do tipo JSON. Cada atributo individual é um par de chave-valor.

• Para analisar apenas os intervalos em que attributes é especificado, use a seguinte cláusula:

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

• Para analisar apenas os intervalos em que a chave de atributo chamada component tem um valor de "proxy", use a seguinte cláusula:

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

  Você também pode usar uma instrução LIKE com caracteres curinga para realizar um teste de contém:

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

Agrupar e agregar dados de rastreamento

Esta seção mostra como agrupar e agregar intervalos. Se você não especificar um agrupamento, mas especificar uma agregação, um resultado será impresso porque o SQL trata todas as entradas que atendem à cláusula WHERE como um grupo.

Todas as expressões SELECT precisam ser incluídas nos campos de grupo ou agregadas.

Agrupar períodos por horário de início

Para agrupar dados por horário de início, use a função TIMESTAMP_TRUNC, que trunca um carimbo de data/hora em uma granularidade especificada, como 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

Para mais informações, consulte a documentação do TIMESTAMP_TRUNC e as funções de data e hora.

Observação: se você incluir um campo start_time na cláusula WHERE, a configuração do seletor de intervalo de tempo não será usada.

Contar intervalos por código de status

Para mostrar a contagem de intervalos com um código de status específico, execute a seguinte consulta:

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 você substituir status.code por kind, a consulta anterior vai informar o número de intervalos para cada valor da enumeração kind. Da mesma forma, se você substituir status.code por name, os resultados da consulta vão listar o número de entradas para cada nome de intervalo.

Calcular a duração média de todos os intervalos

Para mostrar a duração média, depois de agrupar os dados de período por nome, execute a seguinte consulta:

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

Calcular a duração média e os percentis por nome do serviço

A consulta a seguir calcula a contagem de períodos e várias estatísticas para cada serviço:

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

Pesquisa entre colunas

Nesta seção, descrevemos duas abordagens que podem ser usadas para pesquisar várias colunas da visualização que você está consultando:

• Pesquisas baseadas em token: você especifica o local da pesquisa, uma consulta de pesquisa e usa a função SEARCH. Como a função SEARCH tem regras específicas sobre como os dados são pesquisados, recomendamos que você leia a documentação do SEARCH.

• Pesquisas com base em substrings: você informa o local da pesquisa, um literal de string e usa a função CONTAINS_SUBSTR. O sistema realiza um teste que não diferencia maiúsculas de minúsculas para determinar se o literal de string existe em uma expressão. A função CONTAINS_SUBSTR retorna TRUE quando o literal de string existe e FALSE caso contrário. O valor da pesquisa precisa ser um literal STRING, mas não o literal NULL.

Consultar várias visualizações

As instruções de consulta verificam uma ou mais tabelas ou expressões e retornam as linhas de resultados calculadas. Por exemplo, é possível usar instruções de consulta para mesclar os resultados de instruções SELECT em diferentes tabelas ou conjuntos de dados de várias maneiras e, em seguida, selecionar as colunas dos dados combinados.

Para unir visualizações, as seguintes restrições se aplicam:

1. Os locais das visualizações atendem a uma das seguintes condições:

   • Todas as visualizações têm o mesmo local.
   • Todas as visualizações estão no local global ou us.

2. Quando os recursos de armazenamento usam chaves de criptografia gerenciadas pelo cliente (CMEK), uma das seguintes condições é verdadeira:

   • Os recursos do Storage que usam a CMEK usam a mesma chave do Cloud KMS.
   • Os recursos de armazenamento que usam a CMEK têm um ancestral comum, e esse ancestral especifica uma chave padrão do Cloud KMS que está no mesmo local dos recursos de armazenamento.

   Quando um ou mais recursos de armazenamento usam a CMEK, o sistema criptografa os dados temporários gerados pela junção com a chave comum do Cloud KMS ou a chave padrão do Cloud KMS do ancestral.

Por exemplo, suponha que você tenha duas visualizações no mesmo local. Em seguida, você pode combinar essas visualizações quando uma das seguintes condições for verdadeira:

• Os recursos de armazenamento não usam a CMEK.
• Um recurso de armazenamento usa a CMEK e o outro não.
• Ambos os recursos de armazenamento usam a CMEK e a mesma chave do Cloud KMS.

• Os dois recursos de armazenamento usam CMEK, mas com chaves diferentes. No entanto, os recursos compartilham um ancestral que especifica uma chave padrão do Cloud KMS no mesmo local que os recursos de armazenamento.

  Por exemplo, suponha que a hierarquia de recursos de um bucket de registros e um bucket de observabilidade inclua a mesma organização. É possível unir visualizações nesses buckets quando, para essa organização, você configurou as configurações de recursos padrão do Cloud Logging e dos buckets de observabilidade com a mesma chave padrão do Cloud KMS para o local de armazenamento.

Combinar dados de rastreamento e de registros usando o ID de rastreamento

A consulta a seguir une dados de registro e trace usando os IDs de período e trace:

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

A resposta da consulta lista o ID do trace e do intervalo, que permitem consultar cada um deles individualmente para coletar mais informações. Além disso, os resultados listam a gravidade da entrada de registro e do payload JSON.

A seguir

• Salvar e compartilhar uma consulta SQL.
• Representar os resultados da consulta SQL em um gráfico.
• Consulte um conjunto de dados vinculado no BigQuery.

Para documentação de referência do SQL ou outros exemplos, consulte os seguintes documentos:

• Funções, operadores e condicionais.
• Funções de pesquisa.
• Sintaxe de consulta.
• Exemplos de consultas SQL para o Cloud Logging.