Consultar e analisar registros com a Análise de dados de registros

Neste documento, descrevemos como consultar e analisar dados de registros usando a Análise de dados de registros, que oferece uma interface de consulta baseada em SQL. Usando SQL, é possível realizar tarefas como contar as entradas de registro com um campo que corresponda a um padrão. A Análise de dados de registros oferece um editor de SQL e um sistema baseado em menus para criar consultas. Para ver os resultados da consulta, use o formato tabular ou visualize os dados como um gráfico. É possível salvar os gráficos nos seus painéis personalizados.

É possível consultar uma visualização de registros em um bucket de registros ou uma visualização de análise. Quando você consulta uma visualização de registros, o esquema corresponde ao da estrutura de dados LogEntry. Como o criador de uma vista do Google Analytics determina o esquema, um caso de uso para as vistas do Google Analytics é transformar dados de registro do formato LogEntry em um formato mais adequado para você.

A Análise de dados de registros não remove entradas duplicadas, o que pode afetar a forma como você escreve as consultas. Além disso, há algumas restrições ao usar a Análise de dados de registros. Para mais informações sobre esses temas, consulte os documentos a seguir:

Sobre conjuntos de dados vinculados

A Análise de dados de registros permite a criação de conjuntos de dados vinculados do BigQuery, que dão ao BigQuery acesso de leitura aos dados subjacentes. Se você optar por criar um conjunto de dados vinculado, poderá fazer o seguinte:

Este documento não descreve como criar um conjunto de dados vinculado nem como configurar o Log Analytics para executar consultas em slots reservados. Se você tiver interesse nesses tópicos, consulte Consultar um conjunto de dados vinculado no BigQuery.

Antes de começar

Nesta seção, descrevemos as etapas que você precisa concluir antes de usar a análise de registros.

configurar buckets de registros

Confirme se os buckets de registros foram atualizados para usar a Análise de registros:

  1. No console Google Cloud , acesse a página Armazenamento de registros:

    Acessar o armazenamento de registros

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

  2. Para cada bucket de registros com uma visualização que você quer consultar, verifique se a coluna Análise de Dados de Registros disponível mostra Abrir. Se a opção Fazer upgrade aparecer, clique nela e conclua a caixa de diálogo.

Configurar permissões e papéis do IAM

Nesta seção, descrevemos os papéis ou as permissões do IAM necessários para usar a análise de registros:

  • Para receber as permissões necessárias para usar a Análise de registros e consultar visualizações de registros, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    É possível restringir um principal a uma visualização de registros específica adicionando uma condição do IAM à concessão de papel de leitor de acesso à visualização de registros feita no nível do projeto ou adicionando uma vinculação do IAM ao arquivo de política da visualização de registros. Para mais informações, consulte Controlar o acesso a uma visualização de registro.

    Essas são as mesmas permissões necessárias para visualizar entradas de registro na página Análise de registros. Para informações sobre outros papéis necessários para consultar visualizações em buckets definidos pelo usuário ou para consultar a visualização _AllLogs do bucket de registros _Default, consulte Papéis do Cloud Logging.

  • Para receber as permissões necessárias para consultar visualizações de análise, peça ao administrador para conceder a você o papel Usuário da análise de observabilidade (roles/observability.analyticsUser) do IAM no seu projeto.

Consultar dados de registro

Nesta seção, descrevemos as abordagens que podem ser usadas para consultar seus dados de registros:

  • Carregue uma consulta definida pelo sistema, edite e execute.
  • Insira e execute uma consulta personalizada. Por exemplo, você pode colar ou escrever uma consulta. As consultas personalizadas podem incluir junções, consultas aninhadas e outras instruções SQL complexas. Para exemplos, consulte Amostras de consultas SQL.
  • Crie uma consulta fazendo seleções no menu e execute-a. A Análise de dados de registros converte suas seleções em uma consulta SQL, que pode ser visualizada e editada.

Carregar, editar e executar a consulta definida pelo sistema

  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 menu Visualizações, acesse a seção Logs ou Visualizações do Analytics e selecione a visualização que você quer consultar.

    Para encontrar a visualização a ser consultada, use a barra Filtrar ou role a lista para baixo:

    • As visualizações de registros são listadas por BUCKET_ID.LOG_VIEW_ID, em que esses campos se referem aos IDs do bucket de registros e da visualização de registros.

    • As vistas do Google Analytics são listadas por LOCATION.ANALYTICS_VIEW_ID, em que esses campos se referem ao local e ao ID de uma vista do Google Analytics. As visualizações do Google Analytics estão no Acesso antecipado.

  3. 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 mostra Criador de consultas. Se um editor de SQL for mostrado, clique em  Criador.

    • Para carregar uma consulta definida pelo sistema que extrai valores JSON, verifique se o painel Consulta mostra o editor de SQL. Se esse painel mostrar Criador de consultas, clique em  SQL.

  4. 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  SQL.

  5. Opcional: modifique a consulta.

  6. Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.

    O Log Analytics 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 Criar consulta SQL SQL.

    Se a barra de ferramentas mostrar Executar no BigQuery, mude o Log Analytics para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em Configurações e selecione Analytics (padrão).

Inserir e executar uma consulta personalizada

Para inserir uma consulta SQL, faça o seguinte:

  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.

    • Para especificar um período, recomendamos que você use o seletor de período. Se você adicionar uma cláusula WHERE que especifica o campo timestamp, esse valor vai substituir a configuração no seletor de período, que será desativado.

    • Para exemplos, consulte Amostras de consultas SQL.

    • É possível consultar visualizações de registros ou visualizações de análise. Use o seguinte formato para a cláusula FROM:

      • Visualizações de registros:

        FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

      • Vistas do Google Analytics:

        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 do Google Analytics, que é limitado a 100 caracteres e pode incluir apenas letras, dígitos, sublinhados e hifens.

      Se o painel de consulta mostrar uma mensagem de erro que faz referência à instrução FROM, a visualização não poderá ser encontrada. Para informações sobre como resolver essa falha, consulte A cláusula de erro FROM precisa conter exatamente uma visualização de registro.

  3. Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.

    O Log Analytics 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 Criar consulta SQL SQL.

    Se a barra de ferramentas mostrar Executar no BigQuery, mude o Log Analytics para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em Configurações e selecione Analytics (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 dados de registros 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 sua consulta.

A Análise de dados de registros sempre pode converter suas 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 junções não podem ser representadas por essa interface.

Para criar uma consulta, faça o seguinte:

  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. Se o painel Consulta mostrar um editor de SQL, selecione Criador, que abre o painel Criador de consultas.

  3. Use o menu Origem para selecionar a visualização que você quer consultar. Suas seleções são mapeadas para a cláusula FROM na consulta SQL.

  4. Opcional: use os seguintes menus para restringir ou formatar a tabela de resultados:

    • Pesquisar todos os campos: pesquise strings correspondentes. Suas seleções são mapeadas para a cláusula WHERE na consulta SQL.

    • Colunas: selecione as colunas que aparecem na tabela de resultados. Suas seleções são mapeadas para as cláusulas SELECT na 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 aplicados a uma coluna também são aplicados automaticamente a outras colunas. Para ver um exemplo de como agregar e agrupar entradas, consulte Agrupar e agregar dados usando o builder de consultas.

      • Transmita um valor de qualquer tipo para 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 intervalos que contenham um atributo ou ID de intervalo específico. O menu lista todas as opções de filtro disponíveis. Suas seleções são mapeadas para a cláusula WHERE na consulta SQL.

    • Ordenar por: defina as colunas a serem usadas para ordenar e se a classificação será crescente ou decrescente. Suas seleções são mapeadas para a cláusula ORDER BY na 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 LIMIT na consulta SQL.

  5. Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.

    O Log Analytics 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 Criar consulta SQL SQL.

    Se a barra de ferramentas mostrar Executar no BigQuery, mude o Log Analytics para usar o mecanismo de consulta padrão. Para fazer essa mudança, na barra de ferramentas do painel Consulta, clique em Configurações e selecione Analytics (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 seus 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 agrupe nem agregue por esse campo.
  • Agregar: agrupa os campos listados no elemento Colunas, exceto quando o campo tem uma seleção Agregar. 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 contar o número de entradas em cada agrupamento.
  • Agrupar por: agrupa as entradas por todos os campos listados no elemento Colunas.

O exemplo a seguir ilustra como criar uma consulta que agrupa entradas e realiza algum tipo de agregação.

Este exemplo descreve 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.

Para criar uma consulta que agrupa e agrega seus dados, faça as seguintes seleções nos menus do criador de consultas:

  1. No menu Colunas, selecione os campos timestamp, severity e http_request.response_size.

    1. Para agrupar seus dados, clique no campo timestamp e abra 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 como HOUR. 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 vai aparecer. Remova os campos inválidos do menu para resolver esse erro.

    2. Para fazer 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 Agregar. No menu Agregação, clique em Média.

  2. No menu Filtros, adicione http_request.response_size e defina o comparador como IS NOT NULL. Esse filtro corresponde a entradas de registro que contêm um valor response_size.

    Os menus do Criador de consultas são parecidos com estes:

    Agregue e agrupe usando os menus do Criador de consultas.

  3. Para executar a consulta, acesse a barra de ferramentas e selecione Executar consulta.

    Os resultados dessa consulta são semelhantes a este:

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

Mostrar o esquema

O esquema define como os dados são armazenados, incluindo os campos e os tipos de dados deles. Essas informações são importantes porque o esquema determina os campos que você consulta e se é necessário converter campos para diferentes tipos de dados. Por exemplo, para escrever uma consulta que calcula a latência média de solicitações HTTP, você precisa 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:

  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 menu Visualizações, acesse a seção Logs ou Visualizações do Analytics e selecione a visualização que você quer consultar.

    O painel Esquema é atualizado. O Log Analytics infere automaticamente os campos de uma coluna quando o tipo de dados é JSON. Para saber com que frequência esses campos inferidos aparecem nos seus dados, clique em Opções e selecione Ver informações e descrição.

    Para visualizações de registros, o esquema é fixo e corresponde ao LogEntry. Para visualizações de análise, é possível modificar a consulta SQL para mudar o esquema.

A seguir