Salvar e compartilhar consultas SQL

Este documento descreve como salvar e compartilhar consultas criadas na Análise de observabilidade.

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

Para saber como representar graficamente os resultados da consulta e como salvar esses gráficos em um painel personalizado, consulte Representar graficamente os resultados da consulta SQL.

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

Uma consulta salva é uma consulta que você executa usando a página Análise de observabilidade e 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 particular ou visível para outras pessoas que tenham as permissões necessárias para usar a Análise de observabilidade. 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 você pode executar novamente quando quiser. Para criar uma visualização de análise, grave 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. É possível consultar uma visualização de análise. Esse recurso permite transformar os dados de registro do formato LogEntry em outro mais adequado para você. Em seguida, em vez de gravar as consultas em uma visualização de registro, você consulta a visualização de análise.

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

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 registros 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 tem uma visualização de registro que você quer consultar, verifique se a coluna Análise de observabilidade disponível mostra Abrir. Se Fazer upgrade for mostrado, clique em Fazer 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 bucket de registros _Default, 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 de usuário da Análise de observabilidade (roles/observability.analyticsUser) do IAM no projeto.

Salvar uma consulta

Todas as consultas executadas são salvas automaticamente por 30 dias e podem ser acessadas selecionando a guia Recente na página Análise de observabilidade. É possível pesquisar, visualizar, executar e compartilhar as consultas listadas na guia Recente.

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

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

Console

Para salvar uma consulta, faça o seguinte:

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

    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.

    É possível preencher o painel Consulta inserindo uma nova consulta, selecionando uma consulta na guia Recente ou selecionando uma consulta na guia Salvos.

    A consulta pode incluir qualquer visualização válida, várias visualizações e visualizações de análise.

    Quando a consulta no painel Consulta é válida, a opção de Salvar é ativada.

  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 com acesso à página Análise de observabilidade do Google Cloud projeto visualizem 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.

    É possível 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 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 de savedQueries.create.

É possível executar o método savedQueries.create usando o APIs Explorer widget na página de referência do método. Para consultas da Análise de observabilidade, é necessário especificar o campo opsAnalyticsQuery. O exemplo a seguir ilustra 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
            `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 Google Cloud projeto. No entanto, os papéis do IAM do principal determinam se a consulta pode ser executada e os dados que ela retorna.

Console

Ao solucionar um problema ou quando você encontrar resultados anômalos, 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 observabilidade, é possível 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 Google Cloud console, acesse a Análise de dados de registros página:

    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.

    É possível preencher o painel Consulta inserindo uma nova consulta, selecionando uma consulta 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 observabilidade será aberta e mostrará, mas não executará, a consulta. Seu colega de equipe precisa executar a consulta manualmente.

    A página Análise de observabilidade mostra uma caixa de diálogo de aviso quando a consulta é executada no mecanismo do BigQuery e os recursos consultados não estão no mesmo limite de propriedade. Os limites de propriedade são determinados por vários fatores, um dos quais é a hierarquia dos recursos usados pela consulta.

    Para abrir o URL, o papel do IAM do colega de equipe no Google Cloud projeto precisa incluir as permissões necessárias para visualizar a página Análise de observabilidade.

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.

Visualizar e executar consultas recentes ou salvas

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

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

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

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

A seguir