Amostras de consultas SQL

Este documento contém consultas de amostra que podem ser usadas para consultar seus dados de registro e rastreamento.

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.

Dados de registros

Se você incluir um campo timestamp na cláusula WHERE, a configuração do seletor de intervalo de tempo não será usada. O exemplo a seguir ilustra como filtrar por carimbo de data/hora:

-- Matches log entries whose timestamp is within the most recent 1 hour.
WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

Rastrear dados

Se você incluir um campo start_time na cláusula WHERE, a configuração do seletor de intervalo de tempo não será usada. O exemplo a seguir ilustra como filtrar por carimbo de data/hora:

-- Matches trace spans whose start_time is within the most recent 1 hour.
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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Ative a API Observability.

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

Ativar a 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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Ative a API Observability.

Funções necessárias para ativar APIs

Ativar a API

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 papel, o principal poderá acessar todas as visualizações de observabilidade. As visualizações de observabilidade estão no Acesso antecipado.
- 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.
- Acessador de exibição de registros (roles/logging.viewAccessor) no projeto que armazena as visualizações de registros que você quer consultar.
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

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.
No painel Consulta, clique em SQL e copie e cole uma consulta no painel de consulta SQL.
Dados de registros

Antes de copiar uma consulta, na cláusula FROM, substitua os seguintes campos:
- PROJECT_ID: o identificador do projeto.
- LOCATION: o local da visualização de registros ou da visualização de análise.
- BUCKET_ID: o nome ou ID do bucket de registros.
- LOG_VIEW_ID: o identificador da visualização de registros, que é limitado a 100 caracteres e pode incluir apenas letras, dígitos, sublinhados e hifens.
Veja a seguir o formato da cláusula FROM para uma visualização de registros:
```
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
```
Os exemplos de registros nesta página consultam uma visualização de registros. Para consultar uma visualização do Analytics, use o seguinte formato de caminho: `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`. Na expressão anterior, PROJECT_ID é o ID do projeto, e LOCATION e ANALYTICS_VIEW_ID são o local e o nome da visualização de análise.
Rastrear dados

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

Dados de registros

Por exemplo, para consultar a visualização _AllLogs no conjunto de dados vinculado chamado mydataset que está no projeto myproject, o caminho é myproject.mydataset._AllLogs.

Rastrear dados

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 entradas de registro no bucket de registros padrão

Para consultar o bucket _Default, execute a seguinte consulta:

SELECT
  timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload
FROM
  `PROJECT_ID.LOCATION._Default._AllLogs`
-- Limit to 1000 entries
LIMIT 1000

Extrair valor do campo por expressão regular

Para extrair um valor de uma string usando uma expressão regular, use a função REGEXP_EXTRACT:

SELECT
  -- Display the timestamp, and the part of the name that begins with test.
  timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Get the value of jobName, which is a subfield in a JSON structure.
  JSON_VALUE(json_payload.jobName) IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20

Para mais informações, consulte a documentação REGEXP_EXTRACT.

Para correspondências de substring, como a consulta anterior, o uso da função CONTAINS_SUBSTR resulta em uma consulta mais eficiente.

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 registro

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 entradas de registro por tipo de payload

As entradas de registro podem ter um de três tipos de payload. Para filtrar entradas de registro pelo tipo de payload, use uma destas cláusulas:

Payloads de texto

-- Matches log entries that have a text payload.
WHERE text_payload IS NOT NULL

Payloads JSON

-- Matches log entries that have a JSON payload.
WHERE json_payload IS NOT NULL

Payloads proto

-- Matches log entries that have a proto payload.
-- Because proto_payload has a data type of RECORD, this statement tests
-- whether a mandatory subfield exits.
WHERE proto_payload.type IS NOT NULL

Nos resultados da consulta, os campos json_payload e proto_payload são renderizados em JSON, que você pode navegar.

Filtrar dados de registro por carimbo de data/hora

Para filtrar entradas de registro por carimbo de data/hora, recomendamos usar o seletor de período. No entanto, também é possível especificar o timestamp na cláusula WHERE:

-- Matches log entries whose timestamp is within the most recent hour
WHERE timestamp > 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.

Filtrar por recurso

Para filtrar os dados de registro e rastreamento por recurso, adicione uma instrução resource.type à cláusula WHERE:

-- Matches log entries whose resource type is gce_instance
WHERE resource.type = "gce_instance"

Filtrar por gravidade

Para filtrar os dados de registro por gravidade, adicione uma instrução severity à cláusula WHERE:

-- Matches log entries whose severity is INFO or ERROR
WHERE severity IS NOT NULL AND severity IN ('INFO', 'ERROR')

Também é possível filtrar as entradas de registro pelo severity_number, que é um número inteiro. Por exemplo, a cláusula a seguir corresponde a todas as entradas de registro cujo nível de gravidade é pelo menos NOTICE:

-- Matches log entries whose severity level is at least NOTICE
WHERE severity_number IS NOT NULL AND severity_number > 200

Para informações sobre os valores enumerados, consulte LogSeverity.

Filtrar por nome do registro

Para filtrar os dados de registro por um nome, adicione uma instrução log_name ou log_id à cláusula WHERE:

O nome do registro especifica o caminho do recurso:

-- Matches log entries that have the following log ID.
WHERE log_name="projects/cloud-logs-test-project/logs/cloudaudit.googleapis.com%2Factivity"

O ID do registro omite o caminho do recurso:

-- Matches log entries that have the following log id.
WHERE log_id = "cloudaudit.googleapis.com/data_access"

Filtrar entradas de registro por rótulo de recurso

Os rótulos de recursos são armazenados como uma estrutura JSON. Para filtrar pelo valor de um campo em uma estrutura JSON, use a função JSON_VALUE:

SELECT
  timestamp, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries whose resource type is gce_instance and whose zone is
  -- us-central1-f. Because resource has data type JSON, you must use JSON_VALUE
  -- to get the value for subfields, like zone.
  resource.type = "gce_instance" AND
  JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC

A consulta anterior depende do formato dos rótulos de recursos, já que eles são armazenados em uma entrada de registro. Confira abaixo um exemplo do campo de recurso:

{
   type: "gce_instance"
   labels: {
      instance_id: "1234512345123451"
      project_id: "my-project"
      zone: "us-central1-f"
   }
}

Para informações sobre todas as funções que podem recuperar e transformar dados JSON, consulte Funções JSON.

Filtrar por solicitação HTTP

Para consultar apenas entradas de registro que têm um campo de solicitação HTTP, use a seguinte cláusula:

-- Matches log entries that have a HTTP request_method field.
-- Don't compare http_request to NULL. This field has a data type of RECORD.
WHERE http_request.request_method IS NOT NULL

Também é possível usar a instrução IN:

-- Matches log entries whose HTTP request_method is GET or POST.
WHERE http_request.request_method IN ('GET', 'POST')

Filtrar por status HTTP

Para consultar apenas entradas de registro com um status HTTP, use a seguinte cláusula:

-- Matches log entries that have an http_request.status field.
WHERE http_request.status IS NOT NULL

Filtrar por um campo em um tipo de dados JSON

Para consultar entradas de registro apenas quando o subcampo de um campo com um tipo de dados JSON tem um valor específico, extraia o valor usando a função JSON_VALUE:

-- Compare the value of the status field to NULL.
WHERE JSON_VALUE(json_payload.status) IS NOT NULL

A cláusula anterior é sutilmente diferente desta:

-- Compare the status field to NULL.
WHERE json_payload.status IS NOT NULL

A primeira cláusula testa se o valor do campo de status é NULL. A segunda cláusula testa se o campo de status existe. Suponha que uma exibição de registro contenha duas entradas de registro. Para uma entrada de registro, o campo json_payload tem o seguinte formato:

{
    status: {
        measureTime: "1661517845"
    }
}

Para a outra entrada de registro, o campo json_payload tem uma estrutura diferente:

{
    @type: "type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished"
    jobName: "projects/my-project/locations/us-central1/jobs/test1"
    relativeUrl: "/food=cake"
    status: "NOT_FOUND"
    targetType: "APP_ENGINE_HTTP"
}

A cláusula WHERE json_payload.status IS NOT NULL corresponde às duas entradas de registro. No entanto, a cláusula WHERE JSON_VALUE(json_payload.status) IS NOT NULL corresponde apenas à segunda entrada de registro.

Filtrar entradas de rastreamento

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 entradas de registro

Esta seção se baseia nos exemplos anteriores e ilustra como agrupar e agregar entradas de registro. Se você não especificar um agrupamento, mas especificar uma agregação, um resultado será impresso porque o SQL trata todas as linhas que atendem à cláusula WHERE como um grupo.

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

Agrupar entradas de registro por carimbo de data/hora

Para agrupar dados por carimbo de data/hora, use a função TIMESTAMP_TRUNC, que trunca um carimbo de data/hora para uma granularidade especificada, como HOUR:

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
  JSON_VALUE(json_payload.status) AS status,
  -- Count the number log entries in each group.
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a status field whose value isn't NULL.
  json_payload IS NOT NULL AND JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY
  -- Group by hour and status
  hour,status
ORDER BY hour ASC

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

Agrupar entradas de registro por recurso

A consulta a seguir mostra como agrupar entradas de registro por tipo de recurso e contar o número de entradas em cada grupo:

SELECT
   -- Count the number of log entries for each resource type
   resource.type, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
GROUP BY resource.type
LIMIT 100

Agrupar entradas de registro por gravidade

A consulta a seguir mostra como agrupar entradas de registro por gravidade e contar o número de entradas em cada grupo:

SELECT
  -- Count the number of log entries for each severity.
  severity, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100

Agrupar entradas de registro por `log_id`

A consulta a seguir mostra como agrupar entradas de registro pelo ID do registro e contar o número de entradas em cada grupo:

SELECT
  -- Count the number of log entries for each log ID.
  log_id, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100

Calcular a latência média das solicitações HTTP por URL

A consulta a seguir ilustra como agrupar entradas de registro pelo URL e local da solicitação HTTP e, em seguida, contar o número de entradas de registro em cada grupo:

SELECT
  -- Compute the average latency for each group. Because the labels field has a
  -- data type of JSON, use JSON_VALUE to get the value of checker_location.
  JSON_VALUE(labels.checker_location) AS location,
  AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries when the request_method field is GET.
  http_request IS NOT NULL AND http_request.request_method IN ('GET')
GROUP BY
  -- Group by request URL and location
  http_request.request_url, location
ORDER BY location
LIMIT 100

Calcular a média de bytes enviados para um teste de sub-rede

A consulta a seguir mostra como agrupar entradas de registro pelo local especificado nos rótulos de recursos e calcular o número de entradas de registro em cada grupo:

SELECT
  -- Compute the average number of bytes sent per location. Because labels has
  -- a data type of JSON, use JSON_VALUE to get the value of the location field.
  -- bytes_sent is a string. Must cast to a FLOAT64 before computing average.
  JSON_VALUE(resource.labels.location) AS location,
  AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  resource.type = "gce_subnetwork" AND json_payload IS NOT NULL
GROUP BY
  -- Group by location
  location
LIMIT 100

Para mais informações, consulte Funções JSON e Funções de conversão.

Contar as entradas de registro com um campo que corresponda a um padrão

Para retornar a substring que corresponde a uma expressão regular, use a função REGEXP_EXTRACT:

SELECT
  -- Extract the value that begins with test.
  -- Count the number of log entries for each name.
  REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20

Para mais exemplos, consulte a documentação do REGEXP_EXTRACT.

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.

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.

Pesquisa baseada em token em uma visualização de registro

A consulta a seguir retém apenas as linhas que têm um campo que corresponde exatamente a "35.193.12.15":

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID` AS t
WHERE
  -- Search data access audit logs for the IP address that matches 35.193.12.15.
  -- The use of backticks prevents the string from being tokenized.
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  SEARCH(t,"`35.193.12.15`")
ORDER BY timestamp ASC
LIMIT 20

Quando as crases são omitidas na string de consulta, ela é dividida com base nas regras definidas na documentação do SEARCH. Por exemplo, quando a instrução a seguir é executada, a string de consulta é dividida em quatro tokens: "35", "193", "12" e "15":

  SEARCH(t,"35.193.12.15")

A instrução SEARCH anterior corresponde a uma linha quando um único campo corresponde a todos os quatro tokens. A ordem dos tokens não importa.

É possível incluir várias instruções SEARCH em uma consulta. Por exemplo, na consulta anterior, você pode substituir o filtro no ID do registro por uma instrução como esta:

  SEARCH(t,"`cloudaudit.googleapis.com/data_access`")

A instrução anterior pesquisa todos os campos das entradas de registro na visualização de registros, enquanto a instrução original pesquisa apenas o campo log_id das entradas de registro.

Para realizar várias pesquisas em vários campos, separe as strings individuais com um espaço. Por exemplo, a instrução a seguir corresponde a linhas em que um campo contém "Hello World", "happy" e "days":

  SEARCH(t,"`Hello World` happy days")

Por fim, você pode pesquisar campos específicos em vez de uma tabela inteira. Por exemplo, a instrução a seguir pesquisa apenas as colunas chamadas text_payload e json_payload:

   SEARCH((text_payload, json_payload) ,"`35.222.132.245`")

Para informações sobre como os parâmetros da função SEARCH são processados, consulte a página de referência do BigQuery Funções de pesquisa.

Pesquisa de substring em uma visualização de registro

Por exemplo, a consulta a seguir busca todas as entradas de registro de auditoria de acesso a dados com um endereço IP específico cujos carimbos de data/hora estão em um intervalo de tempo específico. Por fim, a consulta classifica os resultados e mostra os 20 mais antigos:

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID` AS t
WHERE
  -- Search data access audit logs for the IP address that matches 35.193.12.15.
  -- CONTAINS_SUBSTR performs a contains-test.
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  CONTAINS_SUBSTR(t,"35.193.12.15")
ORDER BY timestamp ASC
LIMIT 20

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:

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.
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 duas visualizações de registros pelo ID do trace

Para combinar informações de duas tabelas, use um dos operadores join:

SELECT
  -- Do an inner join on two tables by using the span ID and trace ID.
  -- Don't join only by span ID, as this field isn't globally unique.
  -- From the first view, show the timestamp, severity, and JSON payload.
  -- From the second view, show the JSON payload.
  a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_1` a
JOIN  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_2` b
ON
  a.span_id = b.span_id AND
  a.trace = b.trace
LIMIT 100

Consultar duas visualizações de registro com uma instrução de união

Para combinar os resultados de duas ou mais instruções SELECT e descartar linhas duplicadas, use o operador UNION. Para manter linhas duplicadas, use o operador UNION ALL:

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
-- Create a union of two log views
FROM(
  SELECT * FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_1`
  UNION ALL
  SELECT * FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_2`
)
-- Sort the union by timestamp.
ORDER BY timestamp ASC
LIMIT 100

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 período, 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.

Remover entradas de registro duplicadas

O Log Analytics não remove entradas de registro duplicadas antes da execução de uma consulta. Esse comportamento é diferente de quando você consulta entradas de registro usando a Análise de registros, que remove entradas duplicadas comparando os nomes de registro, carimbos de data/hora e campos de ID de inserção.

É possível usar a validação no nível da linha para remover entradas de registro duplicadas.

Para mais informações, consulte Solução de problemas: há entradas de registro duplicadas nos resultados da Análise de dados de registros.

A seguir

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

Amostras de consultas SQL Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Compatibilidade com a linguagem SQL

Práticas recomendadas

Dados de registros

Rastrear dados

Antes de começar

Como usar as consultas nesta página

Dados de registros

Rastrear dados

Dados de registros

Rastrear dados

Casos de uso comuns

Mostrar entradas de registro no bucket de registros padrão

Extrair valor do campo por expressão regular

Mostrar todos os dados de trace

Mostrar informações de período comuns

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

Filtrar entradas de registro

Filtrar entradas de registro por tipo de payload

Filtrar dados de registro por carimbo de data/hora

Filtrar por recurso

Filtrar por gravidade

Filtrar por nome do registro

Filtrar entradas de registro por rótulo de recurso

Filtrar por solicitação HTTP

Filtrar por status HTTP

Filtrar por um campo em um tipo de dados JSON

Filtrar entradas de rastreamento

Filtrar por tipos de dados de string

Filtrar por tipos de dados inteiros

Filtrar por tipos de dados RECORD

Filtrar por status ou código de status

Filtrar por eventos ou links

Filtrar por tipos de dados JSON

Agrupar e agregar entradas de registro

Agrupar entradas de registro por carimbo de data/hora

Agrupar entradas de registro por recurso

Agrupar entradas de registro por gravidade

Agrupar entradas de registro por log_id

Calcular a latência média das solicitações HTTP por URL

Calcular a média de bytes enviados para um teste de sub-rede

Contar as entradas de registro com um campo que corresponda a um padrão

Agrupar e agregar dados de rastreamento

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

Contar intervalos por código de status

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

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

Pesquisa entre colunas

Pesquisa baseada em token em uma visualização de registro

Pesquisa de substring em uma visualização de registro

Consultar várias visualizações

Combinar duas visualizações de registros pelo ID do trace

Consultar duas visualizações de registro com uma instrução de união

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

Remover entradas de registro duplicadas

A seguir

Amostras de consultas SQL

Agrupar entradas de registro por `log_id`