Salvar e compartilhar consultas SQL

Com a Análise de Observabilidade, é possível salvar e compartilhar consultas SQL para executar novamente investigações frequentes do Cloud Logging e colaborar com os membros da equipe no projeto. É possível manter as consultas salvas privadas para uso próprio ou compartilhá-las com outros membros do projeto.

Se você ainda não escreveu consultas na Análise de Observabilidade, consulte primeiro Consultar e analisar registros. Para saber como representar os resultados da consulta em um gráfico e salvar esses gráficos em um painel personalizado, consulte Representar os resultados da consulta SQL em um gráfico.

Como as consultas salvas diferem das 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 novamente essa consulta quando quiser. Ao salvar a consulta, você pode 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 escrever 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, 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. É 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 escrever suas 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 de análise.

Antes de começar

Nesta seção, descrevemos 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 console 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 registros que tenha uma visualização de registros que você queira consultar, verifique se a coluna Análise de Observabilidade disponível mostra Abrir. Se Fazer upgrade aparecer, clique em Fazer upgrade e conclua a caixa de diálogo.

Configurar papéis e permissões do IAM

Nesta seção, descrevemos os papéis ou as 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 registros, 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 registros específica adicionando uma condição do IAM à concessão do papel de acessador de visualizações de registros feita no nível do projeto ou adicionando uma vinculação do IAM ao arquivo de política da visualização de registros. Saiba mais em 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 do IAM de Análise de Observabilidade (roles/observability.analyticsUser) no projeto.

Selecione a interface que você quer usar

Console

Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

    Instale a CLI do Google Cloud.

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Salvar uma consulta

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

Para reutilizar uma consulta, adicionar descrições personalizadas ou compartilhá-la com colegas de equipe, salve-a. É possível pesquisar e classificar as 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 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 Google Cloud , acesse a página Análise de observabilidade:

    Acessar a análise de observabilidade

    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 Recentes ou selecione uma na guia Salvas.

    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, o botão Salvar é ativado.

  3. Clique em Salvar, selecione Salvar consulta salva 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 projeto do Google Cloud visualizem e executem sua 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 Salvas.

    É possível classificar e filtrar as 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 que você criou 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, mas a consulta em si não pode ser modificada.

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

gcloud

Para criar e salvar uma consulta, faça o seguinte:

  1. Antes de usar os dados do comando abaixo, faça estas substituições:

    • DISPLAY_NAME: o nome de exibição da consulta salva.
    • LOCATION: o local da consulta salva.
    • VISIBILITY: defina como private ou shared.
    • SQL_QUERY: uma consulta SQL. Se as aspas simples (`) envolverem o caminho ou os campos dentro dele, será necessário usar caracteres de escape: 
          "SELECT * FROM \`PROJECT_ID.LOCATION.my-log-bucket._AllLogs\`"

      ou

          "SELECT * FROM \`PROJECT_ID.LOCATION._Trace.Spans._AllSpans\`"

      As aspas invertidas (`) são obrigatórias quando um elemento de caminho contém um caractere de ponto (.).

    • ID: o ID da consulta salva. Esse ID é uma entrada obrigatória para comandos que descrevem, atualizam ou excluem uma consulta salva. Se você não fornecer o ID ao criar uma consulta salva, o sistema vai gerar um ID numérico.
    • DESCRIPTION: uma descrição de texto da consulta. Opcional.
    • PROJECT_ID: o identificador do projeto.

    Execute o comando gcloud logging saved-queries create:

    Linux, macOS ou Cloud Shell

    gcloud logging saved-queries create --display-name=DISPLAY_NAME \
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY \
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Windows (PowerShell)

    gcloud logging saved-queries create --display-name=DISPLAY_NAME `
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY `
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Windows (cmd.exe)

    gcloud logging saved-queries create --display-name=DISPLAY_NAME ^
 --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY ^
 --id=ID --description=DESCRIPTION --project=PROJECT_ID

    Veja a seguir um exemplo de resposta quando o ID fornecido no comando era my-saved-query:

    Created saved query [projects/PROJECT_ID/locations/LOCATION/savedQueries/my-saved-query].

    A resposta ao comando create lista o nome completo da consulta, que inclui o ID dela. O ID da consulta, que neste exemplo é my-saved-query, é uma entrada obrigatória para os comandos da Google Cloud CLI que descrevem, excluem ou atualizam uma consulta salva.

  2. Para inspecionar a consulta salva, execute o seguinte comando:

     gcloud logging saved-queries list --location=- --project=PROJECT_ID

    Na expressão anterior, o valor do local é um hífen (-), que atua como um caractere curinga. Também é possível fornecer um local específico.

Há comandos da Google Cloud CLI para excluir, listar, descrever e atualizar consultas salvas. Para mais informações, consulte Visão geral do gcloud logging saved-queries.

REST

É possível salvar uma consulta usando a API Cloud Logging. Para salvar uma consulta, use o método savedQueries.create.

Para executar esse método, faça o seguinte:

  1. Selecione savedQueries.create.
  2. Na página de referência, use o APIs Explorer para emitir um comando. 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 projeto doGoogle 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 problemas ou quando você vê resultados anômalos, talvez queira 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, exibe 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 Google Cloud , acesse a página Análise de observabilidade:

    Acessar a análise de observabilidade

    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 na guia Recentes ou selecione uma na guia Salvas.

  3. Clique em Compartilhar link.

  4. Envie o link para seu colega de equipe.

    Quando o colega de equipe abrir o link, a página Análise de Observabilidade será aberta e vai 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 deles é a hierarquia dos recursos que a consulta usa.

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

gcloud

Para criar uma consulta salva que possa ser executada por outras pessoas, defina o valor do campo visibility como shared:

--visibility=shared

Para mudar a visibilidade de uma consulta salva, use o comando update. Para mais informações sobre os comandos disponíveis, consulte a visão geral de gcloud logging saved-queries.

REST

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

Ver e executar consultas recentes ou salvas

Para visualizar ou executar novamente uma consulta, selecione a guia Recentes na página Análise de Observabilidade 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 Salvas 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 menu Mais opções.

A seguir