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

Este documento descreve como consultar e analisar os dados de registro armazenados em buckets de registro que foram atualizados para usar a Análise de Registros. É possível consultar registros nesses buckets usando SQL, o que permite filtrar e agregar os registros. Para conferir os resultados da consulta, use a forma tabular ou visualize os dados com gráficos. Essas tabelas e gráficos podem ser salvos 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 registro, o esquema corresponde ao da estrutura de dados LogEntry. Como o criador de uma vista de análise determina o esquema, um caso de uso de vistas de análise é transformar dados de registro do formato LogEntry em um formato mais adequado para você.

Use o Explorador de registros para conferir as entradas de registro armazenadas em buckets de registro no seu projeto, independentemente de o bucket de registro ter sido atualizado para usar a Análise de registros.

O Log Analytics não elimina entradas de registro duplicadas, o que pode afetar a forma como você escreve suas consultas. Além disso, há algumas restrições ao usar o Log Analytics. Para mais informações sobre esses tópicos, consulte os seguintes documentos:

Sobre os conjuntos de dados vinculados

A Análise de dados de registros oferece suporte à criação de conjuntos de dados vinculados do BigQuery, que permitem que o BigQuery tenha 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 ou 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

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

Configurar buckets de registros

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

  1. No console do 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 registro que tenha uma visualização de registro que você quer consultar, verifique se a coluna Log Analytics disponível mostra Aberto. Se a opção Upgrade for exibida, 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 as permissões do IAM necessários para usar o Log Analytics:

  • Para receber as permissões necessárias para usar a análise de registros e as visualizações de registro de consulta, 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 função de 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 bucket de registros _Default, consulte Papéis do Cloud Logging.

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

Consultar uma visualização de registro ou de análise

Ao resolver um problema, você pode contar as entradas de registro com um campo que corresponde a um padrão ou calcular a latência média para a solicitação HTTP. Para realizar essas ações, execute uma consulta SQL em uma visualização de registro.

Para emitir uma consulta SQL para uma visualização de registro, faça o seguinte:

  1. No console do 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 você quiser carregar a consulta padrão, faça o seguinte:

    1. No menu Visualizações, acesse a seção Logs ou Visualizações do Google Analytics e selecione a visualização que você quer consultar.

      Para encontrar uma visualização, use a barra Filtrar 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 e da visualização de registro.

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

    2. Na barra de ferramentas Esquema, clique em Consulta.

      O painel Consulta é atualizado com uma consulta SQL que consulta a visualização de análise selecionada.

  3. Para inserir uma consulta, faça o seguinte:

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

    • Para conferir exemplos, consulte Exemplos de consultas.

    • Para consultar uma visualização de registro, a cláusula FROM da consulta precisa ter o seguinte formato:

      FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

    • Para consultar uma visualização de análise, a cláusula FROM da consulta precisa ter o seguinte formato:

      FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`

    O significado dos campos nas expressões anteriores é descrito a seguir:

    • PROJECT_ID: o identificador do projeto.
    • LOCATION: o local da visualização de registro ou de análise.
    • BUCKET_ID: o nome ou ID do bucket de registro.
    • LOG_VIEW_ID: o identificador da visualização de registro, limitado a 100 caracteres e que 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.

  4. Na barra de ferramentas, verifique se o botão Executar consulta aparece.

    Se a barra de ferramentas mostrar Run in BigQuery, clique em Settings e selecione Log Analytics (default).

  5. Execute a consulta.

    A consulta é executada e o resultado dela é mostrado na guia Resultados.

    Você pode usar as opções da barra de ferramentas para formatar, limpar a consulta e abrir a documentação de referência do SQL do BigQuery.

  6. Opcional: crie um gráfico ou salve os resultados em um painel personalizado.

    Por padrão, os resultados da consulta são apresentados como uma tabela. No entanto, você pode criar um gráfico e salvar a tabela ou o gráfico em um painel personalizado.

    Para informações sobre como criar e configurar um gráfico e como salvar um resultado de consulta em um painel, consulte Resultados de consulta SQL do gráfico.

Mostrar o esquema

O esquema define a estrutura e o tipo de dados de cada campo. Essas informações são importantes porque determinam como você cria suas consultas. Por exemplo, suponha que você queira calcular a latência média das 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". Quando os dados de latência são armazenados como uma string, a consulta precisa converter o valor para um valor numérico antes de calcular uma média.

Quando o tipo de dados de uma coluna é JSON, o esquema não lista os campos disponíveis para essa coluna. Por exemplo, uma entrada de registro pode ter um campo com o nome json_payload. Quando um bucket de registro é atualizado para usar a Análise de dados de registros, esse campo é mapeado para uma coluna com um tipo de dados JSON. O esquema não indica os campos filhos da coluna. Ou seja, não é possível usar o esquema para determinar se json_payload.url é uma referência válida.

Para identificar o esquema, faça o seguinte:

  1. No console do 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 Visualizações, encontre a visualização de registro ou de análise e selecione-a.

    O esquema é exibido. Para visualizações de registro, o esquema é fixo e corresponde à estrutura de dados LogEntry. Para visualizações de análise, é possível modificar a consulta SQL para mudar o esquema.

A seguir