Consultar e visualizar registros na Análise de dados de registros

Neste documento, descrevemos como consultar e visualizar registros armazenados em buckets de registros que são atualizados para usar a Análise de dados de registros. Você pode consultar registros nesses buckets usando SQL, que permite filtrar e agregar seus registros. Para informações sobre os recursos da Análise de dados de registros do Cloud Logging, consulte Visão geral da análise de registros.

Ao fazer upgrade de um bucket de registros para usar a Análise de registros, você não restringe o acesso à Análise de registros. É possível continuar a solucionar problemas e visualizar entradas de registro individuais nesses buckets usando a Análise de registros.

Para informações sobre como fazer upgrade de um bucket de registros para usar a Análise de dados de registros, consulte os documentos a seguir:

Antes de começar

  1. Para receber as permissões necessárias para usar a Análise de dados de registros e realizar atividades como a criação de conjuntos de dados vinculados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

    Também é possível receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

  2. Para as visualizações de registro que você quer consultar, acesse a página Armazenamento de registros e verifique se os buckets que armazenam essas visualizações foram atualizados para usar a Análise de dados de registros. Se necessário, faça upgrade do bucket de registros.

    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 Geração de registros.

  3. Opcional: se você quiser consultar seus dados de registro usando um conjunto de dados do BigQuery, crie um conjunto de dados vinculado do BigQuery.

Consultar uma visualização de registros

Ao solucionar um problema, convém contar as entradas de registro com um campo que corresponda a um padrão ou calcular a latência média para uma solicitação HTTP. É possível realizar essas ações executando uma consulta SQL em uma visualização de registros.

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

  1. No console do Google Cloud, acesse a página Análise de dados de registros:

    Acessar a Análise de dados de registros

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

  2. Na lista Visualizações de registro, encontre a visualização e selecione Consulta. O painel Consulta é preenchido com uma consulta padrão, que inclui o nome da tabela consultada.

    Também é possível inserir uma consulta no painel Consulta ou editar uma consulta exibida.

    Para definir o intervalo de tempo da consulta, use o seletor de intervalo de tempo ou adicione uma cláusula WHERE que especifique o campo timestamp. Recomendamos que você use o seletor de intervalo de tempo para especificar o período.

    Se você especificar um carimbo de data/hora na consulta, ele modificará o intervalo de tempo selecionado no seletor de intervalo de tempo, e o seletor será desativado. Para usar o seletor de intervalo de tempo, remova as expressões de carimbo de data/hora da cláusula WHERE na consulta.

  3. Na barra de ferramentas, clique em Executar consulta.

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

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

Exibir o esquema de uma visualização

O esquema de uma visualização de registro define a estrutura e o tipo de dados de cada campo. Essas informações são importantes porque determinam como você cria as 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 está 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 em 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 ela. Por exemplo, uma entrada de registro pode ter um campo com o nome json_payload. Quando um bucket de registros é 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 de uma visualização, faça o seguinte:

  1. No console do Google Cloud, acesse a página Análise de dados de registros:

    Acessar a Análise de dados de registros

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

  2. Na lista Visualizações de registro, encontre a visualização e selecione o nome dela.

    O esquema da tabela será exibido. Você pode usar o campo Filtro para localizar campos específicos. Não é possível modificar o esquema.

Salvar uma consulta

Todas as consultas feitas são salvas automaticamente por 30 dias e podem ser acessadas ao selecionar a guia Recentes na página Análise de dados de registros. É possível pesquisar, visualizar, executar e compartilhar as consultas listadas na guia Recentes.

Se você quiser manter uma consulta disponível para uso futuro, anote-a com informações úteis ou permita que colegas de equipe visualizem e executem sua consulta. Em seguida, salve a consulta. É possível pesquisar e classificar suas consultas salvas por nome, descrição e rótulo de visibilidade. Também é possível editar e excluir essas consultas. As consultas salvas são retidas até que você as exclua.

É possível salvar até 10.000 consultas por projeto do Google Cloud.

Console

Para salvar uma consulta, faça o seguinte:

  1. No console do Google Cloud, acesse a página Análise de dados de registros:

    Acessar a Análise de dados de registros

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

  2. Preencha o painel Consulta com uma consulta.

    Preencha o painel Consulta inserindo uma nova consulta, selecionando uma na guia Recente ou selecionando uma consulta na guia Salvos.

    Quando a consulta no painel Consulta é válida, o botão Salvar é ativado.

  3. Clique em Salvar e preencha os campos Nome e Descrição. Os valores definidos para esses campos são mostrados na guia Salvos.

  4. Opcional: para permitir que todos com acesso à página Análise de dados de registros da visualização do projeto do Google Cloud e executar a consulta salva, ative a opção Compartilhar com o projeto.

    Essa opção fica desativada por padrão, e a visibilidade é restrita a você.

  5. Clique em Salvar consulta.

  6. Opcional: para visualizar, classificar e executar consultas salvas visíveis para você, selecione a guia Salvos.

    É possível classificar e filtrar suas consultas salvas por nome, descrição e rótulo de visibilidade. Também é possível filtrar pelo conteúdo da consulta.

É possível editar e excluir as consultas criadas usando as opções na guia Salvos:

  • Para editar uma consulta, clique em Mais opções e selecione Editar. É possível modificar os valores dos campos Nome e Descrição. No entanto, a consulta em si não pode ser modificada.

  • Para excluir uma consulta salva, clique em Mais opções e selecione Excluir.

API

Para salvar uma consulta usando a API Logging, use o método savedQueries.create. Para mais informações sobre esse método, os parâmetros e os dados de resposta, consulte a página de referência para savedQueries.create.

É possível executar o método savedQueries.create usando o widget do APIs Explorer na página de referência do método. Para consultas da Análise de dados de registros, você precisa especificar o campo opsAnalyticsQuery. Veja no exemplo a seguir um corpo de solicitação de amostra, que contém uma instância de SavedQuery:

{
  "parent": "projects/my-project/locations/global"
  "saved_query":
  {
     "ops_analytics_query":
     {
        "sql_query_text" :
           "SELECT
           timestamp, log_name, severity, json_payload, resource, labels
           FROM
           `TABLE`
           WHERE
           timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
           ORDER BY timestamp ASC
           LIMIT 100"
     }
     "visibility": "PRIVATE"
  }
}

Compartilhar uma consulta

Console

Ao solucionar um problema ou encontrar resultados anômalos, você pode querer compartilhar uma consulta e seus resultados com um colega de equipe. Quando você visualiza os resultados da consulta na página Análise de dados de registros, pode copiar um URL que, quando aberto, exibe a consulta executada e os resultados.

Para compartilhar uma consulta e os resultados com um colega de equipe, faça o seguinte:

  1. No console do Google Cloud, acesse a página Análise de dados de registros:

    Acessar a Análise de dados de registros

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

  2. Preencha o painel Consulta com uma consulta e clique em Executar consulta.

    Preencha o painel Consulta inserindo uma nova consulta, selecionando uma na guia Recente ou selecionando uma consulta na guia Salvos.

  3. Clique em Compartilhar link.

  4. Envie o link para seu colega de equipe.

    Quando seu colega de equipe abrir o link, a página Análise de dados de registros será aberta. Essa página exibe a consulta que você executou e os resultados da consulta.

    Para abrir o URL, o papel do Identity and Access Management do seu colega de equipe no projeto do Google Cloud precisa incluir as permissões necessárias para visualizar as páginas do Logging.

API

É possível usar a API Logging para criar uma consulta compartilhada usando o método savedQueries.Create e especificando um valor de SHARED no campo visibility.

Consultar e executar consultas recentes ou salvas

Para visualizar ou executar novamente uma consulta, selecione a guia Recente na página Análise de dados de registros e encontre a consulta:

  • Para executar a consulta, clique em Executar.
  • Para ver a consulta, use as opções no menu Mais opções.

Para visualizar, editar ou executar uma consulta salva, selecione a guia Salva na página Análise de dados de registros e encontre a consulta:

  • Para executar a consulta, clique em Executar.
  • Para editar, visualizar ou excluir a consulta, use as opções no menu Mais opções.

Consultar registros usando o BigQuery

Quando você tem um bucket de registros que foi atualizado para usar a Análise de dados de registros, também é possível visualizar seus dados no BigQuery criando um conjunto de dados vinculado do BigQuery. Com essa configuração, é possível usar o BigQuery para unir seus dados de registro, que podem ser acessados por meio do conjunto de dados vinculado, com outros dados da empresa. Para mais informações sobre como criar um conjunto de dados vinculado, consulte Conceder ao BigQuery acesso de leitura a um bucket de registros.

Para consultar um conjunto de dados vinculado, faça o seguinte:

  1. No console do Google Cloud, acesse a página Análise de dados de registros:

    Acessar a Análise de dados de registros

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

  2. Na lista Visualizações de registro, encontre a visualização e selecione Consulta. O painel Consulta é preenchido com uma consulta padrão.

    Também é possível inserir uma consulta no painel Consulta ou editar uma consulta exibida.

  3. Na barra de ferramentas, clique em Executar no BigQuery.

    A página do BigQuery Studio é aberta. A instrução FROM da consulta é modificada para especificar o caminho para a visualização no conjunto de dados vinculado usando a sintaxe do caminho da tabela do BigQuery.

    Você também pode editar a consulta exibida.

  4. Clique em Executar consulta.

A seguir