Consultar e analisar registros com a Análise de observabilidade

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

Você pode consultar uma visualização de registro em um bucket de registro ou uma visualização de análise. Ao consultar uma visualização de registro, o esquema corresponde ao da estrutura de dados LogEntry. Como o criador de uma visualização de análise determina o esquema, um caso de uso para visualizações de análise é transformar dados de registro do formato LogEntry em um formato mais adequado para você.

Também é possível usar a Análise de observabilidade para consultar os dados de trace. Para mais informações, consulte Consultar e analisar traces.

A Análise de observabilidade não remove entradas de registro duplicadas, o que pode afetar a forma como você grava as consultas. Além disso, há algumas restrições ao usar a Análise de observabilidade. Para mais informações sobre esses tópicos, consulte os seguintes documentos:

Sobre conjuntos de dados vinculados

Não é necessário um conjunto de dados vinculado do BigQuery ao consultar dados de registro ou dados de registro e trace. Para esses cenários, use a página Análise de observabilidade. Também é possível salvar e compartilhar consultas, além de salvar a consulta em um painel personalizado. Para informações sobre como consultar os dados de trace, consulte Consultar e analisar traces.

Você precisa de um conjunto de dados vinculado do BigQuery quando quiser fazer o seguinte:

Se você optar por criar um conjunto de dados vinculado em um bucket de registros, o limite de segurança dos dados de registro será expandido para incluir os serviços do BigQuery. Ou seja, os serviços do BigQuery agora podem consultar os dados de registro emitindo uma consulta para o conjunto de dados vinculado. Antes de criar um conjunto de dados vinculado, recomendamos que você revise a Segurança de dados com a Análise de observabilidade.

Antes de começar

Esta seção descreve as etapas que você precisa concluir antes de usar a Análise de observabilidade.

configurar buckets de registros

Verifique se os buckets de registro foram atualizados para usar a Análise de observabilidade:

  1. No Google Cloud console, 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 que tenha uma visualização de registro que você quer consultar, verifique se a coluna Análise de observabilidade disponível mostra Abrir. Se Upgrade for mostrado, clique em Upgrade e conclua a caixa de diálogo.

Configurar papéis e permissões do IAM

Esta seção descreve os papéis ou permissões do IAM necessários para usar a Análise de observabilidade:

  • Para receber as permissões necessárias para usar a Análise de observabilidade e consultar visualizações de registro, 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 registro específica adicionando uma condição do IAM à concessão de papel do Acessador de 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 registro. 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 _Default bucket de registros, 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 do IAM de Usuário da Análise de observabilidade (roles/observability.analyticsUser) no projeto.

Consultar dados de registro

Esta seção descreve as abordagens que podem ser usadas para consultar os dados de registro:

  • Carregue uma consulta definida pelo sistema, edite-a e execute-a.
  • Insira e execute uma consulta personalizada. Por exemplo, cole uma consulta que você tenha ou escreva uma. 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 de 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

  1. No Google Cloud console, acesse a página 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.

  2. No menu Visualizações, acesse o Registros ou Visualizações de análise e selecione a visualização que você quer consultar.

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

    • As visualizações de registro 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 registro.
    • As visualizações de análise são listadas por LOCATION.ANALYTICS_VIEW_ID, em que esses campos se referem ao local e ao ID de uma visualização de análise. As visualizações de análise 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 Consulta painel mostra Criador de consultas. Se um editor de SQL for mostrado, então 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 Criador de consultas modo, mas quer visualizar 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.

    A Análise de observabilidade apresenta os resultados da consulta em uma tabela. No entanto, é possível criar um gráfico e também salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Representar os resultados da consulta SQL em um gráfico.

    Se a barra de ferramentas mostrar Executar no BigQuery, será necessário mudar 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 Configurações e selecione Análise (padrão).

Inserir e executar uma consulta personalizada

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

  1. No Google Cloud console, acesse a página 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.

  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, e esse seletor será desativado.

    • Para exemplos, consulte Amostras de consultas SQL.

    • É 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 registro 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 registro, 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 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 Erro FROM clause precisa conter exatamente uma visualização de registro.

  3. 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 também salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Representar os resultados da consulta SQL em um gráfico.

    Se a barra de ferramentas mostrar Executar no BigQuery, será necessário mudar 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 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 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, as consultas com junções não podem ser representadas por essa interface.

Para criar uma consulta, faça o seguinte:

  1. No Google Cloud console, acesse a página 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.

  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. As 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: pesquisa strings correspondentes. As seleções são mapeadas para a cláusula WHERE na consulta SQL.

    • Colunas: selecione as colunas que aparecem na tabela de resultados. As 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 os dados.

        Para evitar erros de sintaxe, qualquer agregação e agrupamento aplicado a uma coluna também é aplicado automaticamente a outras colunas. Para um exemplo de como agregar e agrupar entradas, consulte Agrupar e agregar dados usando o Criador de consultas.

      • Transmita um valor de qualquer tipo para outro tipo de dados especificado. Para mais informações, consulte a CAST documentação.

      • Extraia uma substring de valores usando expressões regulares. Para mais informações, consulte a REGEXP_EXTRACT documentação.

    • 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. As seleções são mapeadas para a cláusula WHERE na consulta SQL.

    • Classificar por: defina as colunas a serem classificadas e se a classificação é crescente ou decrescente. As 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. As 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.

    A Análise de observabilidade apresenta os resultados da consulta em uma tabela. No entanto, é possível criar um gráfico e também salvar a tabela ou o gráfico em um painel personalizado. Para mais informações, consulte Representar os resultados da consulta SQL em um gráfico.

    Se a barra de ferramentas mostrar Executar no BigQuery, será necessário mudar 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 Configurações e selecione Análise (padrão).

Exemplo: agrupar e agregar dados usando o Criador de consultas

Quando você seleciona 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 agrupe nem agregue por esse campo.
  • Agregar: agrupe os campos listados no elemento Colunas, exceto quando o campo tiver 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 para calcular a média de um campo ou para fazer algo como contar o número de entradas em cada agrupamento.
  • Agrupar por: agrupe as entradas por todos os campos listados no elemento Colunas.

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:

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

    1. Para agrupar os dados, clique no campo timestamp para 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 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 possa ser aplicado, uma mensagem de erro será exibida. Remova os campos inválidos do menu para resolver esse erro.

    2. Para realizar a agregação no campo http_request.response_size, clique no campo 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 semelhantes aos seguintes:

    Agregue e agrupe por 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 aos seguintes:

    +-----------------------------------+----------+---------------+
| 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. Essas informações são importantes porque o esquema determina os campos que você consulta e se é necessário transmitir campos para diferentes tipos de dados. Por exemplo, para escrever uma consulta que calcula a latência média de solicitações HTTP, é necessário saber como acessar o campo de latência e se ele está 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á transmitir o valor para um valor numérico antes de calcular uma média.

Para identificar o esquema, faça o seguinte:

  1. No Google Cloud console, acesse a página 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.

  2. No menu Visualizações, acesse o Registros ou Visualizações de análise e selecione a visualização que você quer consultar.

    O painel Esquema é atualizado. A Análise de observabilidade infere automaticamente os campos de uma coluna quando o tipo de dados é JSON. Para conferir a frequência com que esses campos inferidos aparecem nos dados, clique Opções e selecione Ver informações e descrição.

    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.

A seguir