Consultar e analisar registos com o Log Analytics

Este documento descreve como consultar e analisar os dados de registo através do Log Analytics, que fornece uma interface de consulta baseada em SQL. Ao usar SQL, pode realizar tarefas como contar as entradas de registo com um campo que corresponda a um padrão. O Log Analytics oferece um editor de SQL e um sistema baseado em menus para criar consultas. Para ver os resultados da consulta, pode usar o formulário tabular ou visualizar os dados como um gráfico. Pode guardar os gráficos nos painéis de controlo personalizados.

Pode consultar uma vista de registo num contentor de registos ou uma vista de análise. Quando consulta uma vista de registo, o esquema corresponde ao da estrutura de dados LogEntry. Uma vez que o criador de uma visualização de propriedade do Analytics determina o esquema, um exemplo de utilização das visualizações de propriedades do Analytics é transformar dados de registo do formato LogEntry num formato mais adequado para si.

O Log Analytics não remove entradas de registo duplicadas, o que pode afetar a forma como escreve as consultas. Além disso, existem algumas restrições quando usa o Log Analytics. Para mais informações sobre estes tópicos, consulte os seguintes documentos:

Acerca dos conjuntos de dados associados

O Log Analytics suporta a criação de conjuntos de dados do BigQuery associados, que permitem ao BigQuery ter acesso de leitura aos dados subjacentes. Se optar por criar um conjunto de dados associado, pode fazer o seguinte:

Este documento não descreve como criar um conjunto de dados associado nem como configurar o Log Analytics para executar consultas em espaços reservados. Se tiver interesse nestes tópicos, consulte o artigo Consultar um conjunto de dados associado no BigQuery.

Antes de começar

Esta secção descreve os passos que tem de concluir antes de poder usar a Log Analytics.

Configure contentores de registos

Certifique-se de que os contentores de registos foram atualizados para usar o Log Analytics:

  1. Na Google Cloud consola, aceda à página Armazenamento de registos:

    Aceda a Armazenamento de registos

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

  2. Para cada contentor de registos que tenha uma visualização de registos que quer consultar, certifique-se de que a coluna Log Analytics disponível apresenta Abrir. Se for apresentado o botão Atualizar, clique nele e preencha a caixa de diálogo.

Configure funções e autorizações do IAM

Esta secção descreve as funções ou as autorizações da IAM necessárias para usar o Log Analytics:

  • Para receber as autorizações de que precisa para usar o Log Analytics e consultar visualizações de registos, peça ao seu administrador que lhe conceda as seguintes funções de IAM no seu projeto:

    Pode restringir um principal a uma vista de registos específica adicionando uma condição de IAM à concessão da função Logs View Accessor feita ao nível do projeto ou adicionando uma associação de IAM ao ficheiro de política da vista de registos. Para mais informações, consulte o artigo Controle o acesso a uma vista de registo.

    Estas são as mesmas autorizações de que precisa para ver entradas de registo na página do Explorador de registos. Para ver informações sobre funções adicionais necessárias para consultar visualizações em contentores definidos pelo utilizador ou para consultar a visualização _AllLogs do contentor de registos _Default, consulte Funções do Cloud Logging.

  • Para receber as autorizações de que precisa para consultar visualizações de propriedade do Analytics, peça ao seu administrador para lhe conceder a função de IAM Utilizador do Observability Analytics (roles/observability.analyticsUser) no seu projeto.

Dados de registos de consultas

Esta secção descreve as abordagens que pode usar para consultar os seus dados de registo:

  • Carregar uma consulta definida pelo sistema, editar esta consulta e, em seguida, executar a consulta.
  • Introduza e execute uma consulta personalizada. Por exemplo, pode colar uma consulta que tenha ou escrever uma. As consultas personalizadas podem incluir junções, consultas aninhadas e outras declarações SQL complexas. Para ver exemplos, consulte o artigo Consultas SQL de exemplo.
  • Crie uma consulta fazendo seleções no menu e, em seguida, execute essa consulta. O Log Analytics converte as suas seleções numa consulta SQL, que pode ver e editar.

Carregue, edite e execute a consulta definida pelo sistema

  1. Na Google Cloud consola, aceda à página Log Analytics:

    Aceda ao Log Analytics

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

  2. No menu Vistas, aceda à secção Registos ou Vistas do Analytics e selecione a vista que quer consultar.

    Para encontrar a vista a consultar, use a barra de Filtro ou desloque a página pela lista:

    • As visualizações de registos são apresentadas por BUCKET_ID.LOG_VIEW_ID, em que estes campos se referem aos IDs do contentor de registos e da visualização de registos.

    • As visualizações de propriedades do Analytics são apresentadas por LOCATION.ANALYTICS_VIEW_ID, em que estes campos se referem à localização e ao ID de uma visualização de propriedade do Analytics. As vistas do Analytics estão na Pré-visualização pública.

  3. Efetue um dos seguintes passos:

    • Para carregar uma consulta definida pelo sistema que se baseia no criador de consultas, que lhe permite definir a consulta com seleções de menu, certifique-se de que o painel Consulta apresenta criador de consultas. Se for apresentado um editor de SQL, clique em  Criador.

    • Para carregar uma consulta definida pelo sistema que extrai valores JSON, certifique-se de que o painel Consulta apresenta o editor de SQL. Se este painel apresentar o criador de consultas, clique em  SQL.

  4. No painel Esquema, selecione Consulta e, de seguida, clique em Substituir.

    O painel Consulta apresenta uma consulta definida pelo sistema. Se 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, aceda à barra de ferramentas e selecione Executar consulta.

    O Log Analytics apresenta os resultados da consulta numa tabela. No entanto, pode criar um gráfico e também pode guardar a tabela ou o gráfico num painel de controlo personalizado. Para mais informações, consulte o artigo Represente graficamente os resultados da consulta SQL.

    Se a barra de ferramentas apresentar Executar no BigQuery, tem de mudar o Log Analytics para usar o motor de consultas predefinido. Para fazer esta alteração, na barra de ferramentas do painel Consulta, clique em Definições e, de seguida, selecione Analytics (predefinição).

Introduza e execute uma consulta personalizada

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

  1. Na Google Cloud consola, aceda à página Log Analytics:

    Aceda ao Log Analytics

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

  2. No painel Consulta, clique em  SQL.

    • Para especificar um intervalo de tempo, recomendamos que use o seletor time-range. Se adicionar uma cláusula WHERE que especifique o campo timestamp, esse valor substitui a definição no seletor de intervalo de tempo e esse seletor é desativado.

    • Para ver exemplos, consulte o artigo Consultas SQL de exemplo.

    • Pode consultar vistas de registos ou vistas de estatísticas. Use o seguinte formato para a cláusula FROM:

      • Visualizações de registos:

        FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

      • Visualizações de propriedades do 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: a localização da vista de registo ou da vista de estatísticas.
      • BUCKET_ID: o nome ou o ID do contentor de registos.
      • LOG_VIEW_ID: o identificador da vista de registo, que está limitado a 100 carateres e só pode incluir letras, dígitos, sublinhados e hífenes.
      • ANALYTICS_VIEW_ID: O ID da visualização de estatísticas, que está limitado a 100 carateres e só pode incluir letras, dígitos, sublinhados e hífenes.

      Se o painel de consulta apresentar uma mensagem de erro que faça referência à declaração FROM, significa que não é possível encontrar a vista. Para obter informações sobre como resolver esta falha, consulte o artigo A cláusula de erro FROM tem de conter exatamente uma vista de registo.

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

    O Log Analytics apresenta os resultados da consulta numa tabela. No entanto, pode criar um gráfico e também pode guardar a tabela ou o gráfico num painel de controlo personalizado. Para mais informações, consulte o artigo Represente graficamente os resultados da consulta SQL.

    Se a barra de ferramentas apresentar Executar no BigQuery, tem de mudar o Log Analytics para usar o motor de consultas predefinido. Para fazer esta alteração, na barra de ferramentas do painel Consulta, clique em Definições e, de seguida, selecione Analytics (predefinição).

Crie, edite e execute uma consulta

A interface do criador de consultas permite-lhe criar uma consulta fazendo seleções nos menus. O Log Analytics converte as suas seleções numa consulta SQL, que pode ver e editar. Por exemplo, pode começar por usar a interface do criador de consultas e, em seguida, mudar para o editor de SQL para refinar a sua consulta.

O Log Analytics pode sempre converter as suas seleções de menu da interface do criador de consultas numa 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 esta interface.

Para criar uma consulta, faça o seguinte:

  1. Na Google Cloud consola, aceda à página Log Analytics:

    Aceda ao Log Analytics

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

  2. Se o painel Consulta apresentar um editor de SQL, selecione Criador, que abre o painel Criador de consultas.

  3. Use o menu Origem para selecionar a vista que quer consultar. As 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:

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

    • Colunas: selecione as colunas que aparecem na tabela de resultados. As suas seleções são mapeadas para as cláusulas SELECT na consulta SQL.

      Quando seleciona um nome de campo neste menu, é apresentada uma caixa de diálogo. Nesta caixa de diálogo, pode fazer o seguinte:

      • Use o menu para agregar ou agrupar os seus dados.

        Para evitar erros de sintaxe, qualquer agregação e agrupamento que aplicar a uma coluna também é aplicado automaticamente a outras colunas. Para ver um exemplo de como agregar e agrupar entradas, consulte o artigo Agrupe e agregue dados através do criador de consultas.

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

      • Extraia uma substring de valores através de 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 específico ou um ID do intervalo. O menu apresenta todas as opções de filtro disponíveis. As suas seleções são mapeadas para a cláusula WHERE na consulta SQL.

    • Ordenar por: defina as colunas pelas quais ordenar e se a ordenação é ascendente ou descendente. As 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. As suas seleções são mapeadas para a cláusula LIMIT na consulta SQL.

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

    O Log Analytics apresenta os resultados da consulta numa tabela. No entanto, pode criar um gráfico e também pode guardar a tabela ou o gráfico num painel de controlo personalizado. Para mais informações, consulte o artigo Represente graficamente os resultados da consulta SQL.

    Se a barra de ferramentas apresentar Executar no BigQuery, tem de mudar o Log Analytics para usar o motor de consultas predefinido. Para fazer esta alteração, na barra de ferramentas do painel Consulta, clique em Definições e, de seguida, selecione Analytics (predefinição).

Exemplo: agrupe e agregue dados através do criador de consultas

Quando seleciona uma coluna no criador de consultas, cada campo inclui um menu onde pode adicionar agrupamentos e agregações. O agrupamento permite-lhe organizar os seus dados em grupos com base no valor de uma ou mais colunas, e a agregação permite-lhe fazer cálculos nestes grupos para devolver um único valor.

Cada campo que selecionar no elemento Colunas tem um menu anexado com as seguintes opções:

  • Nenhum: não agrupe nem agregue por este campo.
  • Agregado: agrupa os campos listados no elemento Colunas, exceto quando o campo tem uma seleção Agregado. 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: agrupe as entradas por todos os campos indicados no elemento Colunas.

A ilustração seguinte mostra como pode criar uma consulta que agrupa entradas e, em seguida, realiza algum tipo de agregação.

Este exemplo descreve como usar o criador de consultas para agrupar as entradas do registo por gravidade e 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 os 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 os dados, clique no campo timestamp para abrir a caixa de diálogo de definições. Nesta caixa de diálogo, selecione a opção Agrupar por e defina a Granularidade de truncagem como HOUR. Em seguida, o agrupamento é aplicado automaticamente a todos os outros campos para evitar erros de sintaxe. Se existirem campos inválidos onde não é possível aplicar o agrupamento, é apresentada uma mensagem de erro. Remova os campos inválidos do menu para resolver este erro.

    2. Para fazer a agregação no campo http_request.response_size, clique no campo para abrir a caixa de diálogo de definições. Nesta 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. Este filtro corresponde a entradas de registo que contêm um valor response_size.

    Os menus do criador de consultas têm um aspeto semelhante ao seguinte:

    Agregue e agrupe através dos menus do criador de consultas.

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

    Os resultados desta 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

Apresente o esquema

O esquema define como os dados são armazenados, o que inclui os campos e os respetivos tipos de dados. Estas informações são importantes para si porque o esquema determina os campos que consulta e se precisa de converter campos em diferentes tipos de dados. Por exemplo, para escrever uma consulta que calcule a latência média dos pedidos HTTP, tem de saber como aceder ao campo de latência e se este está armazenado como um número inteiro, como 100, ou como uma string, como "100". Se os dados de latência estiverem armazenados como uma string, a consulta tem de converter o valor num valor numérico antes de calcular uma média.

Para identificar o esquema, faça o seguinte:

  1. Na Google Cloud consola, aceda à página Log Analytics:

    Aceda ao Log Analytics

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

  2. No menu Vistas, aceda à secção Registos ou Vistas do Analytics e selecione a vista que quer consultar.

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

    Para as visualizações de registos, o esquema é fixo e corresponde a LogEntry. Para as vistas de estatísticas, pode modificar a consulta SQL para alterar o esquema.

O que se segue?