Criar e salvar consultas usando a linguagem de consulta do Logging

Neste documento, descrevemos como recuperar e analisar registros quando você usa a Análise de registros gravando consultas no campo do editor de consultas e fazendo seleções nos menus de filtro usando as opções incluídas nas entradas de registro. As consultas criadas são escritas na linguagem de consulta do Logging.

Também é possível salvar suas consultas na página Análise de registros ou usando o método savedQueries.create da API Logging.

Antes de começar

  • Para criar consultas, você precisa ter permissões para ler dados de registro. Essas permissões estão incluídas no papel Leitor do Logging (roles/logging.viewer). Para detalhes sobre as permissões do IAM necessárias, consulte Permissões para o console do Google Cloud.

  • Para salvar consultas, seu papel do Identity and Access Management precisa incluir a permissão logging.queries.{list, create, get, update, delete}.

  • Para compartilhar consultas, seu papel do Identity and Access Management precisa incluir a permissão logging.queries.share. Essa permissão está incluída nos papéis de Proprietário (roles/owner) e Administrador do Logging (roles/logging.admin).

    Para uma lista de permissões associadas a cada papel do Logging, consulte Papéis do Logging.

Criar consultas

Para criar consultas usando o console do Google Cloud, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione Logging e clique em Análise de registros:

    Acessar a Análise de registros

  2. Selecione o projeto ou outro recurso do Google Cloud com os registros que você quer exibir.

    Para visualizar os registros que você está enviando de uma conta da Amazon Web Services (AWS) para o Logging, selecione o projeto de conector da AWS no seletor de recursos do console do Google Cloud e use a Análise de registros. O projeto de conector da AWS armazena o Amazon Resource Name (ARN) da sua conta da AWS e vincula sua conta da AWS aos serviços do Google Cloud. Para mais informações, consulte Coletar métricas de contas da AWS.
  3. Use o painel Consulta para criar sua consulta.

    Painel de consultas da Análise de registros.

    O painel Consulta oferece várias maneiras de criar e executar expressões de consulta:

    • Pesquise texto em todos os campos de registro.
    • Selecione as opções nos menus de filtro.
    • Criar ou modificar consultas usando o editor de consultas.
    • Confira, edite ou execute as consultas nas guias Recentes, Salvos, Sugeridos e Biblioteca.

Pesquisar texto nos campos de registro

Para pesquisar texto em todos os campos de registro e encontrar todas as entradas de registro correspondentes, insira os termos de pesquisa no campo de pesquisa:

O campo de pesquisa da Análise de registros no painel de consulta.

É possível pesquisar palavras e frases, e os termos de pesquisa podem incluir operadores booleanos e expressões regulares:

  • Para realizar uma pesquisa sem diferenciar maiúsculas de minúsculas nos limites do token, insira os termos de pesquisa sem acentos graves ou aspas duplas.

    Por exemplo, para pesquisar entradas de registro que contenham a palavra hello e a palavra world, digite hello world. Esse comando, que é convertido em SEARCH("hello world"), corresponde a entradas de registro que contêm os tokens hello e world em qualquer ordem. Como a pesquisa não diferencia maiúsculas de minúsculas, ela também corresponde a uma entrada de registro que contém os tokens Hello e World. A pesquisa não corresponde ao token worlds.

  • Para realizar uma pesquisa indiferente a maiúsculas para uma frase ao longo dos limites do token, coloque a frase entre crases.

    Por exemplo, para pesquisar a frase hello world, digite `hello world`. Esse comando, que é convertido em SEARCH("`hello world`"), corresponde a entradas de registro que contêm o token hello world. A pesquisa não corresponde ao token hello worlds.

  • Para realizar uma pesquisa indiferente a maiúsculas, coloque o texto entre aspas duplas. Por exemplo, "hello world" corresponde a Hello World e Hello world. A mesma consulta também corresponde a hello worlds porque a pesquisa não é realizada em limites de token.

Para acessar seus termos de pesquisa dentro da expressão de consulta, ative Mostrar consulta.

Depois de digitar os termos de pesquisa, clique em Executar consulta ou pressione a tecla Enter. Os resultados da consulta são exibidos no painel Resultados da consulta.

Operadores booleanos

As entradas do campo de pesquisa são convertidas em expressões booleanas que especificam um subconjunto de todas as entradas de registro no recurso selecionado do Google Cloud.

O campo de pesquisa é compatível com o uso dos operadores booleanos AND, OR e NOT. Ao usar operadores booleanos nas expressões de pesquisa, observe o seguinte:

  • Não é possível usar parênteses para aninhar regras. Todos os parênteses na expressão de pesquisa são analisados como termos de pesquisa.
  • Os operadores booleanos devem ser maiúsculos. and, or e not com letras minúsculas são analisados como termos de pesquisa, não como operadores.

Se você não incluir operadores, todos os termos e frases de pesquisa serão unidos por AND. É possível omitir o operador AND entre os termos de pesquisa.

Os operadores AND e OR são operadores de curto-circuito (em inglês). É possível combinar regras AND e OR na mesma expressão. Por exemplo, quando os dois operadores são combinados, a expressão a AND b OR c AND d se transforma na seguinte expressão da linguagem de consulta do Logging:

"a"
"b" OR "c"
"d"

O operador NOT tem a precedência mais alta, seguido por OR e AND, nessa ordem.

O operador NOT executa uma negação do termo subsequente. Por exemplo, NOT error retorna entradas de registro que não contêm error. Também é possível substituir o operador NOT pelo operador - (menos). Por exemplo, as duas consultas a seguir são iguais:

"response" AND "successful" AND NOT "error"
"response successful" -"error"

Essa lógica também funciona com uma frase, se o operador - (menos) estiver fora das aspas. Por exemplo, as duas consultas a seguir são iguais:

-"response successful"
NOT "response successful"

Criar consultas com menus de filtro

É possível usar os menus de filtro no painel Consulta para adicionar parâmetros de recurso, nome e gravidade de registros ao campo do editor de consultas. Essas opções correspondem aos campos LogEntry para todos os registros no Logging.

As opções nos menus Recurso e Nome do registro exibem apenas os registros armazenados no Cloud Logging.

Menus de filtro do editor de consultas

  • Recurso: permite especificar o resource.type e o resource.labels associado. É possível selecionar um único tipo de recurso usando esse menu de filtro e zero ou mais rótulos de recursos para aplicar à consulta. Os parâmetros do recurso são unidos pelo operador lógico AND.
  • Nome do registro: permite que você especifique logName. É possível selecionar vários nomes de registros para aplicar à consulta. Ao selecionar vários nomes de registros, o operador lógico OR é usado.
  • Gravidade: permite que você especifique a gravidade. É possível selecionar vários níveis de gravidade ao mesmo tempo para aplicar à consulta. Ao selecionar vários níveis de gravidade, o operador lógico OR é usado.

Para usar qualquer um dos menus de filtro, faça o seguinte:

  1. Expanda o Menu em qualquer um dos menus de filtro no painel Consulta.

  2. Refine os parâmetros de filtro.

  3. Clique em Aplicar. Os parâmetros vão aparecer no campo editor de consultas.

    Para acessar seus termos de pesquisa dentro da expressão de consulta, ative Mostrar consulta.

  4. Depois de analisar a consulta, clique em Executar consulta. Os resultados são exibidos no painel Resultados da consulta.

Para determinados tipos de recursos do Compute Engine, como gce_instance e gce_network, você vê o nome do recurso com o ID do recurso como subtexto. Por exemplo, para o tipo de recurso gce_instance, você vê o nome da VM ao lado do ID da VM. Os nomes dos recursos ajudam a identificar o ID correto para criar consultas.

Mostrar registros por intervalo de tempo

Há duas maneiras de exibir registros que foram gravados em um período específico:

  1. Use o seletor de período.
  2. Inclua uma expressão de carimbo de data/hora no campo editor de consultas.

Usar o seletor de intervalo de tempo

O período padrão é de uma hora, mas é possível selecionar uma das opções predefinidas, especificar um horário personalizado de início e término ou centralizar o período em torno de um carimbo de data/hora específico usando o seletor de período. Por exemplo, se você quiser consultar os dados da última semana, selecione Última semana no seletor de período.

Também é possível definir suas preferências de fuso horário com o seletor de período.

Incluir uma expressão de carimbo de data/hora no campo do editor de consultas

Para adicionar uma expressão de carimbo de data/hora diretamente ao campo do editor de consultas, use a linguagem de consulta do Logging.

Se o campo do editor de consultas contiver uma expressão com um carimbo de data/hora, o seletor de intervalo de tempo será desativado e a consulta usará a expressão de carimbo de data/hora como a restrição de intervalo de tempo. Se uma consulta não usar uma expressão de carimbo de data/hora, a consulta usará o seletor de intervalo de tempo como a restrição de intervalo de tempo.

Gravar consultas avançadas usando a linguagem de consulta do Logging

É possível usar a linguagem de consulta do Logging para criar consultas mais avançadas no campo "Editor de consultas" da Análise de registros:

  1. Se o campo "Editor de consultas" não aparecer no painel Consulta, ative Mostrar consulta.

  2. Insira as expressões de consulta diretamente no campo do editor de consultas.

    Se você tiver adicionado termos de pesquisa no campo de pesquisa ou selecionado algum parâmetro nos menus de filtro, eles também vão aparecer no campo do editor de consultas e serão avaliados como parte da expressão de consulta.

  3. Depois de revisar sua consulta, clique em Executar consulta.

    Os registros que correspondem à sua consulta são listados no painel Resultados da consulta. Os painéis Histograma e Campos de registro também são ajustados de acordo com a expressão de consulta.

Para exemplos de consultas comuns que podem ser usadas, veja Amostra de consultas usando o Explorador de registros.

Usar consultas recentes

Quando você executa qualquer consulta, ela é adicionada à sua lista de consultas Recentes, que contém as últimas 10.000 consultas exclusivas em um período de 30 dias.

Para acessar as consultas recentes, selecione a guia Recentes no painel Consulta. Na guia Recentes, você tem as seguintes opções:

  • Stream: para executar a consulta e transmitir os resultados, escolha essa opção.
  • Executar: para executar a consulta, escolha esta opção.
  • Mais opções: permite visualizar a expressão de consulta com as opções para executar a consulta ou salvá-la na sua lista de consultas salvas. Também é possível selecionar a consulta diretamente para ver essas opções.

    Para salvar a consulta, faça o seguinte:

    1. Clique em Salvar como. A caixa de diálogo Salvar consulta é aberta.
    2. Preencha os seguintes campos:

      • Nome (obrigatório): insira um nome para sua consulta. Os nomes são limitados a 64 caracteres.
      • Descrição (opcional): forneça uma descrição para ajudar a identificar a finalidade da consulta.
      • Incluir campos de resumo (opcional): ative a opção Incluir campos de resumo e insira os campos de resumo que você quer exibir.
      • Truncar campos de resumo (opcional): ative a opção Truncar campos de resumo, selecione o número de caracteres que você quer truncar e se o truncamento ocorre no início ou no fim dos campos.
    3. Clique em Salvar consulta. A consulta agora está disponível na sua lista de consultas salvas.

Você também pode classificar e filtrar as consultas recentes. O filtro corresponde ao texto na sua expressão de consulta.

Salvar consultas

As consultas salvas permitem armazenar expressões de consulta para ajudar você a explorar seus registros de maneira mais consistente e eficiente. O painel Consulta da Análise de registros apresenta a guia Salvas, em que é possível acessar as consultas salvas. Também é possível salvar suas consultas usando o método savedQueries.create da API Logging.

Console

Para salvar uma expressão de consulta criada no campo do editor de consultas, faça o seguinte:

  1. Clique em Salvar no painel Consulta. A caixa de diálogo Salvar consulta é aberta, com sua expressão de consulta no campo do editor de consultas.

  2. Preencha os seguintes campos:

    • Nome (obrigatório): insira um nome para sua consulta. Os nomes são limitados a 64 caracteres.
    • Descrição (opcional): forneça uma descrição para ajudar a identificar a finalidade da consulta.
    • Incluir campos de resumo personalizados (opcional): ative a opção Incluir campos de resumo e insira os campos de resumo que você quer mostrar.
    • Truncar campos de resumo (opcional): ative a opção Truncar campos de resumo, selecione o número de caracteres que você quer truncar e se o truncamento ocorre no início ou no fim dos campos.
  3. Clique em Salvar consulta. As consultas salvas aparecem em uma lista na guia Salvos.

Para executar uma consulta salva, clique em Executar. Para executar a consulta e fazer streaming dos resultados, clique em Fazer streaming.

Você também pode classificar e filtrar as consultas salvas. O filtro corresponde ao texto na sua expressão de consulta.

API

Para salvar uma consulta usando a API Logging, use o método savedQueries.create. Para saber mais 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 do APIs Explorer na página de referência do método. Para consultas da Análise de registros, especifique o campo loggingQuery. 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"
"savedQueryId": "compute-query"
{
  "displayName": "compute-admin-activity-query",
  "description": "Queries for Compute Engine Admin Activity logs.",

  "loggingQuery":
    {
      "filter": resource.type="gce_instance" AND log_id("cloudaudit.googleapis.com/activity"),
    },
  "visibility": "PRIVATE"
}
}

Compartilhar consultas

As consultas compartilhadas permitem que os usuários de um projeto do Google Cloud compartilhem as consultas salvas entre si. Para ver as consultas compartilhadas, acesse a guia Salvos.

Para saber os papéis e as permissões necessários para visualizar e editar consultas compartilhadas, consulte Permissões do console do Google Cloud. Os usuários com o papel do IAM roles/logging.admin ou roles/editor podem editar as consultas compartilhadas de outros usuários.

Criar uma consulta compartilhada

Console

É possível compartilhar consultas que já foram salvas ou compartilhar uma nova.

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

  1. Insira uma consulta no campo editor de consultas.

  2. Clique em Salvar.

  3. Preencha os campos da caixa de diálogo Salvar consulta.

  4. Ative Compartilhar com o projeto.

  5. Clique em Salvar consulta.

Sua consulta agora está compartilhada com outros usuários do projeto do Google Cloud.

Para compartilhar uma consulta já salva, faça o seguinte:

  1. Selecione a guia Salvos.

  2. Selecione Mais opções e, em seguida, Editar ou selecione a consulta diretamente.

  3. Na caixa de diálogo Editar consulta, ative a opção Compartilhar com projeto e clique em Atualizar consulta.

Sua consulta agora está compartilhada com outros usuários do projeto do Google Cloud.

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.

Acessar consultas compartilhadas

Console

Para visualizar rapidamente todas as consultas compartilhadas, classifique a coluna Visibilidade para mostrar as consultas compartilhadas primeiro:

  1. Selecione a guia Salvos.

  2. Clique em Todos.

  3. Classifique a coluna Visibilidade.

A coluna Visibilidade indica se e como as consultas são compartilhadas:

  • Compartilhados por mim: consultas que você salvou e compartilhou com outros usuários do projeto do Google Cloud.
  • Compartilhadas: consultas que outros usuários do projeto do Google Cloud compartilharam.
  • Particular: consultas que você salvou e não compartilhou com outros usuários do projeto do Google Cloud.

Ver somente suas consultas

Para acessar as consultas salvas que você criou ou compartilhou, clique em Mine. Será exibida uma lista de consultas criadas e salvas. Na coluna Visibilidade, é possível ver suas consultas privadas não compartilhadas. As consultas que você compartilhou são indicadas por Compartilhadas por mim.

Usar consultas sugeridas

O Logging gera consultas sugeridas com base no contexto do projeto do Google Cloud, como os produtos do Google Cloud que você está usando. As consultas sugeridas podem ajudar a identificar problemas e fornecer insights sobre a integridade geral dos seus sistemas. Por exemplo, ao detectar que você está usando o Google Kubernetes Engine, o Logging pode sugerir uma consulta que encontra todos os registros de erros dos seus contêineres.

Para visualizar e executar consultas sugeridas, selecione a guia Suggested no painel Consulta. A guia Sugestão mostra uma lista de consultas, cada uma com descrições e as seguintes opções:

  • Stream: para executar a consulta e transmitir os resultados, escolha essa opção.
  • Executar: para executar a consulta, escolha esta opção.
  • Mais opções: permite visualizar os detalhes da expressão de consulta com as opções para executar a consulta ou salvá-la. Também é possível selecionar a consulta diretamente para ver essas opções.

    Para analisar os detalhes de uma consulta sugerida, siga um destes procedimentos:

    • Selecione a linha da consulta.

    • Clique em Mais e selecione Visualizar. A caixa de diálogo Detalhes da consulta é aberta.

    Na caixa de diálogo Detalhes da consulta, você vê a consulta e as opções para Executar, Fazer streaming ou Salvar como:

    • Para salvar a consulta, faça o seguinte:

      1. Clique em Salvar como.
      2. Preencha os campos da caixa de diálogo Salvar consulta.

      A consulta editada aparece na lista Salvos, e você pode executar a consulta mais tarde.

    • Para executar a consulta agora, clique em Executar. A consulta é executada e aparece no campo "query-editor".

    • Para executar a consulta agora e transmitir os resultados, clique em Fazer streaming.

    • Para fechar a caixa de diálogo e retornar à lista de consultas sugeridas, clique em Fechar.

Observe os seguintes comportamentos esperados:

  • Carregamentos de página sucessivos podem não mostrar as mesmas consultas na mesma ordem.
  • Não há nenhuma consulta sugerida.
  • Às vezes, a execução de uma consulta sugerida não retorna registros.

Selecionar consultas da biblioteca

O Logging oferece uma biblioteca de consultas com base em casos de uso comuns e produtos do Google Cloud. Essas consultas podem ajudar você a encontrar registros com eficiência durante sessões críticas de solução de problemas e a explorá-los para entender melhor quais dados de registro estão disponíveis.

Para visualizar e executar as consultas da biblioteca, faça o seguinte:

  1. Selecione a guia Biblioteca no painel Consulta.

  2. Na coluna Todas as consultas, são exibidas categorias amplas de consultas e subconjuntos de consultas disponíveis com base nos produtos do Google Cloud. Para restringir a seleção de consultas exibidas, clique em qualquer um dos produtos.

    Também é possível usar o campo de pesquisa para pesquisar as consultas disponíveis por categoria, descrição ou conteúdo da expressão de consulta.

  3. Para revisar uma expressão de consulta, siga um destes procedimentos:

    a. Clique na linha da consulta.

    b. Clique em Mais e selecione Visualizar.

  4. Na caixa de diálogo Detalhes da consulta, você vê a consulta e as opções para Executar, Fazer streaming ou Salvar como:

    • Para salvar a consulta, faça o seguinte:

      1. Clique em Salvar como.
      2. Preencha os campos da caixa de diálogo Salvar consulta.

      A consulta editada aparece na lista Salvos, e você pode executar a consulta mais tarde.

    • Para executar a consulta agora, clique em Executar. A consulta é executada e aparece no campo "query-editor".

    • Para executar a consulta agora e transmitir os resultados, clique em Fazer streaming.

    • Para fechar a caixa de diálogo e retornar à lista de consultas sugeridas, clique em Fechar.

A seguir