Exemplos de consultas SQL para o Trace

Visualizar

Esse produto ou recurso está sujeito aos "Termos de 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 consultas de amostra que são específicas para consultar dados de trace armazenados no seu Google Cloud projeto.

Suporte à linguagem SQL

As consultas usadas na página Análise de observabilidade oferecem suporte a funções do GoogleSQL com algumas exceções.

Os comandos SQL a seguir não são aceitos para consultas SQL emitidas usando a página Análise de observabilidade:

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

Os itens a seguir só são aceitos 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 definidas pelo usuário do Javascript
• 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, para conferir 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 término, especificar 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 retrospectiva a partir do horário atual:

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

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

Antes de começar

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos 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 Observability Analytics , 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 oferece suporte a 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 papel, o principal poderá acessar todas as visualizações de observabilidade.
   • Usuário da análise de observabilidade (roles/observability.analyticsUser) no seu projeto. Esse papel contém as permissões necessárias para salvar e executar consultas particulares e executar consultas compartilhadas.
   • Leitor 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 personalizados papéis ou outros predefinidos papéis.

Como usar as consultas nesta página

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

   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.

   A seguir, mostramos 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 caracteres de ponto, (.). Se um elemento de caminho como o Google Cloud projeto contiver um caractere de ponto, então verifique se cada campo de caminho está entre aspas simples invertidas, (`).

Para usar as consultas mostradas neste documento na página 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 _AllSpans visualização 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 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 comuns de extensão

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

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 de extensão

Para mostrar os percentis 50 e 99 da latência de cada serviço 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 do OpenTelemetry: SpanKind.

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

Filtrar entradas de trace

Para aplicar um filtro à 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 uma String.

• Para analisar apenas as extensões em que name é especificado, use a seguinte cláusula:

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

• Para analisar apenas as extensões 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 as extensões em que name contém o valor "POST", use o operador LIKE com curingas:

  -- 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 as extensões em que kind é especificado, use a seguinte cláusula:

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

• Para analisar extensões cujo valor kind seja 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 trace têm um tipo de dados RECORD. Esses campos podem armazenar uma ou mais estruturas de dados ou armazenar 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. Este campo armazena uma estrutura de dados, com membros rotulados como code e message.

• Para analisar apenas as extensões 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 extensões 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 extensões 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 extensões 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 as extensões 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 as extensões 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 curingas 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 trace

Esta seção ilustra como agrupar e agregar extensões. 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.

Toda expressão SELECT precisa ser incluída nos campos de grupo ou agregada.

Agrupar extensões 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 para 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 TIMESTAMP_TRUNC e 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 período não será usada.

Contar extensões por código de status

Para mostrar a contagem de extensões 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 extensões 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 extensão.

Calcular a duração média de todas as extensões

Para mostrar a duração média, depois de agrupar os dados de período por nome de período, 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

Esta seção descreve 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 SEARCH função. Como a função SEARCH tem regras específicas sobre como os dados são pesquisados, recomendamos que você leia a documentação SEARCH.

• Pesquisas baseadas em substrings: você fornece 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, você pode 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 um dos seguintes requisitos:

   • 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 de armazenamento que usam CMEK usam a mesma chave do Cloud KMS.
   • Os recursos de armazenamento que usam CMEK têm um ancestral comum, e esse ancestral especifica uma chave padrão Cloud KMS que está no mesmo local que os recursos de armazenamento.

   Quando um ou mais recursos de armazenamento usam CMEK, o sistema criptografa os dados temporários gerados por a uniã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 que residem no mesmo local. Em seguida, você pode unir essas visualizações quando qualquer uma das seguintes condições for verdadeira:

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

• Os dois recursos de armazenamento usam CMEK, mas chaves diferentes. No entanto, os recursos compartilham um ancestral que especifica uma chave padrão do Cloud KMS que está 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. Você pode unir visualizações nesses buckets quando, para essa organização, tiver configurado as configurações de recursos padrão para o Cloud Logging e para buckets de observabilidade com a mesma chave padrão do Cloud KMS para o local de armazenamento.

Unir dados de trace e de registro usando o ID de trace

A consulta a seguir une dados de registro e de trace usando os IDs de extensão e de 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 de trace e de período, que permite consultar individualmente para coletar mais informações. Além disso, os resultados listam a gravidade da entrada de registro e o payload JSON.

A seguir

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

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

• Funções, operadores e condicionais.
• Funções de pesquisa.
• Sintaxe da consulta.
• Consultas SQL de amostra para o Cloud Logging.