Salvar e compartilhar consultas SQL

Este documento descreve como salvar e compartilhar consultas criadas no Log Analytics.

Este documento pressupõe que você já conhece a Análise de Registros e como usar a página Análise de Registros para consultar seus dados de registro. Se você não conhece esses tópicos, consulte Consultar e analisar registros.

Para saber como criar gráficos com os resultados da consulta e como salvá-los em um painel personalizado, consulte Criar gráficos com os resultados da consulta SQL.

Diferenças entre as consultas salvas e as visualizações de análise

Uma consulta salva é uma consulta que você executa usando a página Análise de registros e, em seguida, salva como uma consulta. A ação de salvar permite que você execute essa consulta novamente quando quiser. Ao salvar a consulta, você tem a opção de torná-la privada para você ou torná-la visível para outras pessoas que tenham as permissões necessárias para usar a Análise de registros. Não é possível gravar uma consulta SQL em que a cláusula FROM especifica uma consulta salva.

Uma visualização de análise contém uma consulta que pode ser executada novamente quando você quiser. Para criar uma visualização de análise, escreva uma consulta SQL em uma visualização de registro e salve o resultado como uma visualização. Ao contrário das consultas salvas, não é possível tornar uma visualização de análise particular para você. É possível consultar uma visualização de análise. Esse recurso permite transformar os dados de registro do formato LogEntry em outro formato mais adequado para você. Em seguida, em vez de gravar suas consultas em uma visualização de registro, consulte a visualização de análise.

É possível salvar consultas que consultam uma visualização de registro ou de análise.

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.

Salvar uma consulta

Todas as consultas executadas são salvas automaticamente por 30 dias e podem ser acessadas selecionando a guia Recentes na página Análise 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 deixe que os colegas de equipe a acessem e executem, e salve a consulta. Você pode pesquisar e classificar as consultas salvas por nome, descrição e rótulo de visibilidade. Você também pode editar e excluir essas consultas. As consultas salvas são mantidas até que você as exclua.

É possível salvar 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:

    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. Preencha o painel Consulta com uma consulta.

    Para preencher o painel Consulta, insira uma nova consulta, selecione uma na guia Recente ou na guia Salvo.

    A consulta pode especificar visualizações de registro e de análise.

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

  3. Clique em Salvar, selecione Salvar consulta 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 tenham acesso à página Log Analytics para a visualização do projeto do Google Cloud e executem a consulta salva, ative a opção Compartilhar com o projeto.

    Por padrão, essa opção está desativada e a visibilidade é restrita a você.

  5. Clique em Salvar consulta.

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

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

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

  • 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 de savedQueries.create.

É possível executar o método savedQueries.create usando o widget APIs Explorer na página de referência do método. Para consultas do Log Analytics, especifique o campo opsAnalyticsQuery. O exemplo a seguir ilustra um corpo de solicitação de exemplo, 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_NAME_OF_LOG_VIEW`
           WHERE
           timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
           ORDER BY timestamp ASC
           LIMIT 100"
     }
     "visibility": "PRIVATE"
  }
}

Compartilhar uma consulta

É possível compartilhar uma consulta salva com todos que têm acesso ao seu projeto do Google Cloud. No entanto, os papéis do IAM do principal determinam se a consulta pode ser executada e os dados que ela retorna.

Console

Ao resolver um problema ou quando você notar resultados anormais, talvez seja necessário compartilhar uma consulta e os resultados dela com um colega de equipe. Ao visualizar os resultados da consulta na página Análise de dados de registros, você pode copiar um URL que, quando aberto, mostra a consulta executada e os resultados dela.

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:

    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. Preencha o painel Consulta com uma consulta e clique em Executar consulta.

    Para preencher o painel Consulta, insira uma nova consulta, selecione uma consulta na guia Recente ou selecione uma consulta na guia Salvo.

  3. Clique em Compartilhar link.

  4. Envie o link para seu colega de equipe.

    Quando o colega abrir o link, a página Análise de dados de registro será aberta. Essa página mostra a consulta que você executou e os resultados dela.

    Para abrir o URL, a função do IAM do seu colega de equipe no projeto do Google Cloud precisa incluir as permissões necessárias para acessar as páginas de geração de registros.

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. Para mais informações, consulte a página de referência de savedQueries.create.

Consultar e executar consultas recentes ou salvas

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

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

Para conferir, editar ou executar uma consulta salva, selecione a guia Salva na página Análise de dados de registro 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.

A seguir