É possível consultar e analisar seus dados de registro e de trace usando SQL na Análise de Observabilidade para descobrir tendências de desempenho, gerar insights agregados e exibir resultados em gráficos e tabelas.
Também é possível salvar os resultados da consulta salva nos seus painéis personalizados. Se você quiser ver entradas de registro individuais ou inspecionar traces e períodos específicos, use a página Análise de registros ou a página Análise de traces.
Sobre os conjuntos de dados vinculados do BigQuery
Não é necessário um conjunto de dados vinculado do BigQuery para consultar seus dados de registro, de trace ou ambos os tipos de dados ao usar a página Análise de Observabilidade.
Você precisa de um conjunto de dados vinculado do BigQuery quando quiser fazer o seguinte:
- Mesclar dados de registro ou de trace com outros conjuntos de dados do BigQuery.
- Consulte os dados de registro ou de trace de outro serviço, como a página do BigQuery Studio ou o Data Studio.
- Execute consultas da Análise de Observabilidade no mecanismo do BigQuery usando slots sob demanda ou slots reservados do BigQuery.
- Crie uma política de alertas que monitore o resultado de uma consulta SQL. Para mais informações, consulte Logging: monitorar os resultados da consulta SQL e Trace: monitorar os resultados da consulta SQL.
Este documento não descreve como criar um conjunto de dados vinculado do BigQuery, que é um processo específico para cada tipo de dados. Para saber como criar um conjunto de dados vinculado do BigQuery, consulte Consultar dados de registro usando um conjunto de dados vinculado do BigQuery ou Consultar dados de trace usando um conjunto de dados vinculado do BigQuery.
Antes de começar
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, 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 sem custos financeiros.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Para receber as permissões necessárias para carregar a página Análise de Observabilidade, gravar, 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 é compatível com as 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 do papel, 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 projeto - Acessador de visualizaçã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.
- Acessador de visualização de observabilidade (
Consultar dados de registro e de trace
Nesta seção, descrevemos as abordagens que podem ser usadas para consultar os dados de registro e de trace:
- Carregar uma consulta definida pelo sistema, editá-la e executá-la.
- Insira e execute uma consulta personalizada. Por exemplo, você pode colar uma consulta que já tem ou escrever uma. As consultas personalizadas podem incluir mesclagens, consultas aninhadas e outras instruções SQL complexas. Para ver exemplos, consulte Exemplos de consultas SQL.
- Crie uma consulta fazendo seleções no menu e execute-a. A Análise de Observabilidade converte suas seleções em uma consulta SQL, que pode ser visualizada e editada.
Carregar, editar e executar a consulta definida pelo sistema
-
No console Google Cloud , acesse a página manage_search Análise de observabilidade:
Acessar a análise de observabilidade
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.
No menu Visualizações, selecione uma opção.
Para encontrar a visualização a ser consultada, use a barra de filtro filter_list ou role a lista:
- As visualizações de registro, que estão listadas na seção Registros, são ordenadas pelos IDs de bucket e de visualização.
- As visualizações de análise, listadas na seção Visualizações de análise, são ordenadas por local e ID da visualização.
- Há uma visualização de trace, que está listada na seção
Traces.
Se você não encontrar uma visualização chamada
_Trace.Spans._AllSpans, seu projeto doGoogle Cloud não contém um bucket de observabilidade chamado_Trace. Para saber como resolver essa falha, consulte Falha na inicialização do armazenamento de trace.
Escolha uma destas opções:
Para carregar uma consulta definida pelo sistema que depende do Criador de consultas, que permite definir a consulta com seleções de menu, verifique se o painel Consulta exibe Criador de consultas. Se um editor de SQL for mostrado, clique em tune Builder.
Para carregar uma consulta definida pelo sistema que extrai valores JSON, verifique se o painel Consulta exibe o editor SQL. Se esse painel mostrar Criador de consultas, clique em code SQL.
No painel Esquema, selecione Consulta e clique em Substituir.
O painel Consulta mostra uma consulta definida pelo sistema. Se você selecionou o modo Criador de consultas, mas quer ver a consulta SQL, clique em code SQL.
Opcional: modifique a consulta.
Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.
A Análise de Observabilidade apresenta os resultados da consulta em uma tabela. No entanto, é possível criar um gráfico e salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Resultados da consulta SQL do gráfico.
Se a barra de ferramentas exibir Executar no BigQuery, será necessário alternar a Análise de Observabilidade para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em settings Configurações e selecione Análise (padrão).
Inserir e executar uma consulta personalizada
Para inserir uma consulta SQL, faça o seguinte:
-
No console Google Cloud , acesse a página manage_search Análise de observabilidade:
Acessar a análise de observabilidade
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 code SQL.
Para especificar um período, recomendamos que você use o seletor de período. Se você adicionar uma cláusula
WHEREque especifique o campotimestamp, esse valor vai substituir a configuração no seletor de período, e esse seletor será desativado.Para ver exemplos, consulte Exemplos de consultas SQL.
A visualização que você consulta determina o formato da cláusula
FROM:Dados de registros
É possível consultar visualizações de registro ou visualizações de análise. Use o seguinte formato para a cláusula
FROM:- Visualizações de registro:
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
- Visualizações de análise:
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`
Os campos nas expressões anteriores têm o seguinte significado:
- 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.
- ANALYTICS_VIEW_ID: o ID da visualização de análise, que é limitado a 100 caracteres e pode incluir apenas letras, dígitos, sublinhados e hifens.
Se o painel de consulta exibir uma mensagem de erro que faz referência à instrução
FROM, isso significa que a visualização não foi encontrada. Para saber como resolver essa falha, consulte A cláusula de erroFROMprecisa conter exatamente uma visualização de registro.Rastrear dados
O editor SQL exibe o nome totalmente qualificado da visualização
_Trace.Spans._AllSpans, que tem o seguinte formato:FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
Os campos na expressão anterior têm o seguinte significado:
- PROJECT_ID: o identificador do projeto.
- LOCATION: o local do bucket de observabilidade.
Se o painel de consulta exibir uma mensagem de erro que faz referência à instrução
FROM, isso significa que a visualização não foi encontrada. Para saber como resolver essa falha, consulte Mensagem de erro informando que uma visualização não existe.- Visualizações de registro:
Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.
A Análise de Observabilidade apresenta os resultados da consulta em uma tabela. No entanto, é possível criar um gráfico e salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Resultados da consulta SQL do gráfico.
Se a barra de ferramentas exibir Executar no BigQuery, será necessário alternar a Análise de Observabilidade para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em settings Configurações e selecione Análise (padrão).
Criar, editar e executar uma consulta
A interface do Criador de consultas permite criar uma consulta fazendo seleções nos menus. A Análise de Observabilidade converte suas seleções em uma consulta SQL, que pode ser visualizada e editada. Por exemplo, você pode começar usando a interface do Criador de consultas e depois mudar para o editor de SQL para refinar a consulta.
A Análise de Observabilidade sempre pode converter as seleções de menu da interface do Criador de Consultas em uma consulta SQL. No entanto, nem todas as consultas SQL podem ser representadas pela interface do Criador de consultas. Por exemplo, consultas com mesclagens não podem ser representadas por essa interface.
Para criar uma consulta, faça o seguinte:
-
No console Google Cloud , acesse a página manage_search Análise de observabilidade:
Acessar a análise de observabilidade
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.
Se o painel Consulta exibir um editor de SQL, selecione tune Criador, que abre o painel Criador de consultas.
Use o menu Origem para selecionar a visualização que você quer consultar. Suas seleções são mapeadas para a cláusula
FROMna consulta SQL.Opcional: use os seguintes menus para restringir ou formatar a tabela de resultados:
Pesquisar todos os campos: procure strings correspondentes. Suas seleções são mapeadas para a cláusula
WHEREna consulta SQL.Colunas: selecione as colunas que aparecem na tabela de resultados. Suas seleções são mapeadas para as cláusulas
SELECTna consulta SQL.Quando você seleciona um nome de campo nesse menu, uma caixa de diálogo é aberta. Nessa caixa de diálogo, você pode fazer o seguinte:
Use o menu para agregar ou agrupar seus dados.
Para evitar erros de sintaxe, qualquer agregação e agrupamento que você aplicar a uma coluna também será aplicado automaticamente a outras colunas. Para ver um exemplo de como agregar e agrupar entradas, consulte Agrupar e agregar dados usando o Criador de Consultas.
Converte um valor de qualquer tipo em outro tipo de dados especificado. Para mais informações, consulte a documentação
CAST.Extraia uma substring de valores usando expressões regulares. Para mais informações, consulte a documentação
REGEXP_EXTRACT.
Filtros: adicione filtros quando quiser restringir a consulta a períodos que contenham um atributo ou ID de período específico. O menu lista todas as opções de filtro disponíveis. Suas seleções são mapeadas para a cláusula
WHEREna consulta SQL.Classificar por: defina as colunas para classificação e se ela é crescente ou decrescente. Suas seleções são mapeadas para a cláusula
ORDER BYna consulta SQL.Limite: defina o número máximo de linhas na tabela de resultados. Suas seleções são mapeadas para a cláusula
LIMITna consulta SQL.
Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.
A Análise de Observabilidade apresenta os resultados da consulta em uma tabela. No entanto, é possível criar um gráfico e salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Resultados da consulta SQL do gráfico.
Se a barra de ferramentas exibir Executar no BigQuery, será necessário alternar a Análise de Observabilidade para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em settings Configurações e selecione Análise (padrão).
Exemplo: agrupar e agregar dados usando o Criador de Consultas
Ao selecionar uma coluna no Criador de Consultas, cada campo inclui um menu em que é possível adicionar agrupamento e agregação. O agrupamento permite organizar os dados em grupos com base no valor de uma ou mais colunas, e a agregação permite realizar cálculos nesses grupos para retornar um único valor.
Cada campo selecionado no elemento Colunas tem um menu anexado com as seguintes opções:
- Nenhum: não agrupar nem agregar por esse campo.
- Agregação: agrupa os campos listados no elemento Colunas, exceto quando o campo tem uma seleção de Agregação. Para esses campos, calcule o valor realizando uma operação em todas as entradas de cada agrupamento. A operação pode ser calcular a média de um campo ou fazer algo como contar o número de entradas em cada agrupamento.
- Agrupar por: agrupa as entradas por todos os campos listados no elemento Colunas.
Os exemplos a seguir ilustram como criar uma consulta que agrupa entradas e, em seguida, executa algum tipo de agregação.
Exemplo de agregação de dados de registro
Este exemplo mostra como usar o Criador de consultas para agrupar
entradas de registro por gravidade e carimbo de data/hora e, em seguida, calcular a média do
campo http_request.response_size para cada grupo:
No menu Colunas, selecione os campos
timestamp,severityehttp_request.response_size.Para agrupar os dados, clique no campo
timestamppara abrir a caixa de diálogo de configurações. Nessa caixa de diálogo, selecione a opção Agrupar por e defina a Granularidade de truncamento comoHOUR. O agrupamento é aplicado automaticamente a todos os outros campos para evitar erros de sintaxe. Se houver campos inválidos em que o agrupamento não pode ser aplicado, uma mensagem de erro será exibida. Remova os campos inválidos do menu para resolver esse erro.Para realizar a agregação no campo
http_request.response_size, clique nele para abrir a caixa de diálogo de configurações. Nessa caixa de diálogo, selecione Agregação. No menu Agregação, clique em Média.
No menu Filtros, adicione
http_request.response_sizee defina o comparador comoIS NOT NULL. Esse filtro corresponde a entradas de registro que contêm um valorresponse_size.Os menus do Criador de Consultas são semelhantes a este:

Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.
O resultado dessa consulta é semelhante ao seguinte:
+-----------------------------------+----------+---------------+ | Row | hour_timestamp | severity | response_size | | | TIMESTAMP | STRING | INTEGER | +-----+-----------------------------+----------+---------------+ | 1 | 2025-10-06 16:00:00.000 UTC | NOTICE | 3082 | | 2 | 2025-10-06 17:00:00.000 UTC | WARNING | 338 | | 3 | 2025-10-06 16:00:00.000 UTC | INFO | 149 |
A consulta SQL correspondente ao exemplo anterior é a seguinte:
SELECT
-- Truncate the timestamp by hour.
TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
severity,
-- Compute average response_size.
AVG( http_request.response_size ) AS average_http_request_response_size
FROM
`PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
-- Matches log entries that have a response_size.
http_request.response_size IS NOT NULL
GROUP BY
-- Group log entries by timestamp and severity.
TIMESTAMP_TRUNC( timestamp, HOUR ),
severity
LIMIT
1000
Exemplo de agregação de dados de trace
Este exemplo mostra como usar o Criador de consultas para agrupar períodos por horário de início, nome e tipo e, em seguida, calcular a duração média em nanossegundos para cada grupo:
- No menu Colunas, selecione os campos
start_time,name,kindeduration_nano. - Para truncar o horário de início para a hora, abra o menu na coluna
start_timee selecione Agrupar por. Verifique se o menu de granularidade está definido como Hora. Clique em Aplicar.
Quando você seleciona Agrupar por para qualquer coluna, o sistema agrupa as entradas por todas as colunas. Neste exemplo, as entradas são agrupadas pelo valor truncado de
start_time, pelo nome do período, pelo tipo de período e pelo valor da duração.No entanto, o objetivo deste exemplo é agrupar as entradas pelo tempo truncado, pelo nome do período e pelo tipo de período e, em seguida, para cada grupo, calcular a duração média. Na próxima etapa, você vai modificar o agrupamento e adicionar uma agregação.
Abra o menu no campo
duration_nano, selecione Agregar e defina o campo Agregação como Média.Quando você executa a consulta, cada linha corresponde a um grupo, que consiste em um horário truncado, um nome de período e um tipo de período. A entrada final em cada linha é a duração média de todas as entradas desse grupo.
O resultado dessa consulta é semelhante ao seguinte:
+-----------------------------------+----------------+----------+-----------------------+ | Row | hour_timestamp | span_name | kind | average_duration_nano | | | TIMESTAMP | STRING | INTEGER | FLOAT | +-----+-----------------------------+-----------+---------------+-----------------------+ | 1 | 2025-10-09 13:00:00.000 EDT | http.receive | 3 | 122138.22813990474 | 2 | 2025-10-09 13:00:00.000 EDT | query.request | 1 | 6740819304.390297 | 3 | 2025-10-09 13:00:00.000 EDT | client.handler | 2 | 6739339098.409376A consulta pode incluir várias agregações. Por exemplo, para adicionar uma coluna que conta o número de entradas em cada grupo, faça o seguinte:
- No elemento Colunas, clique em Adicionar coluna.
- Selecione Todas (*).
- Na caixa de diálogo, selecione Agregar, selecione Contagem para a Agregação e selecione Aplicar.
Com essa mudança, o agrupamento permanece o mesmo. As entradas são agrupadas pelo horário de início truncado, pelo nome do período e pelo tipo de período. No entanto, para cada grupo, a consulta calcula a duração média e o número de entradas.
A consulta SQL correspondente ao exemplo anterior é a seguinte:
WITH
scope_query AS (
SELECT
*
FROM
`PROJECT_ID.us._Trace.Spans._AllSpans` )
SELECT
-- Report the truncated start time, span name, span kind, average duration and number
-- of entries for each group.
TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
name AS span_name,
kind,
AVG( duration_nano ) AS average_duration_nano,
COUNT( * ) AS count_all
FROM
scope_query
GROUP BY
TIMESTAMP_TRUNC( start_time, HOUR ),
name,
kind
LIMIT
100
Mostrar o esquema
O esquema define como os dados são armazenados, o que inclui os campos e os tipos de dados. Essas informações são importantes porque o esquema determina os campos que você consulta e se é necessário converter campos em tipos de dados diferentes. Por exemplo, para escrever uma consulta que calcula a latência média de
solicitações HTTP, é preciso saber como acessar o campo de latência e se ele
é armazenado como um número inteiro, como 100, ou como uma string, como "100". Se os dados de latência forem armazenados como uma string, a consulta precisará converter o valor em um valor numérico antes de calcular uma média.
Para identificar o esquema, faça o seguinte:
-
No console Google Cloud , acesse a página manage_search Análise de observabilidade:
Acessar a análise de observabilidade
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.
No menu Visualizações, selecione uma opção.
O painel Esquema é atualizado. A Análise de Observabilidade infere automaticamente os campos de uma coluna quando o tipo de dados é JSON. Para ver com que frequência esses campos inferidos aparecem nos dados, clique em more_vert Opções e selecione Ver informações e descrição.
Dados de registros
Para visualizações de registro, o esquema é fixo e corresponde ao
LogEntry. Para visualizações de análise, é possível modificar a consulta SQL para mudar o esquema.Rastrear dados
Para aprender mais sobre o esquema, consulte Esquema de armazenamento para dados de trace.
Se você não encontrar uma visualização chamada
_Trace.Spans._AllSpans, seu projeto doGoogle Cloud não contém um bucket de observabilidade chamado_Trace. Para saber como resolver essa falha, consulte Falha na inicialização do armazenamento de trace.
Restrições
Se você quiser consultar várias visualizações, elas precisam estar no mesmo local. Por exemplo, se você armazenar duas visualizações no local us-east1, uma consulta poderá consultar as duas visualizações. Também é possível consultar duas visualizações armazenadas na
multirregião us. No entanto, se o local de uma visualização for global, ela poderá residir em qualquer local físico. Portanto, as mesclagens entre duas visualizações que
têm o local de global podem falhar.
Para ver uma lista de restrições que se aplicam aos dados de registro, consulte Análise de Observabilidade: restrições.
A seguir
- Representar os resultados da consulta SQL em um gráfico
- Salvar e compartilhar consultas
- Exemplos de consultas SQL