Criar e salvar consultas usando a linguagem de consulta do Logging

Neste documento, descrevemos como recuperar e analisar registros ao usar a Análise de registros. Para isso, escreva consultas no campo do editor de consultas e selecione opções de filtro predefinidas. As consultas criadas são escritas na linguagem de consulta do Logging.

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

Antes de começar

O papel Visualizador de registros (roles/logging.viewer) fornece acesso para visualizar registros. Por exemplo, ao receber essa função, você pode escrever e executar consultas. Também é possível salvar consultas como particulares e executar consultas particulares e compartilhadas. No entanto, essa função não permite salvar nem modificar consultas compartilhadas. Se você quiser salvar ou modificar consultas compartilhadas, verifique se recebeu o papel de administrador do Logging (roles/logging.admin), que oferece acesso total ao Cloud Logging.

Escolha uma destas opções:

• Para receber as permissões necessárias para escrever e executar consultas, executar e salvar consultas particulares e executar consultas compartilhadas, peça ao administrador para conceder a você o papel do IAM de Leitor de registros (roles/logging.viewer) no seu projeto.

• Para receber as permissões necessárias para escrever e executar consultas, executar e salvar consultas particulares, além de executar, criar e gerenciar consultas compartilhadas, peça ao administrador para conceder a você o papel do IAM de Administrador do Logging (roles/logging.admin) no seu projeto.

Para mais informações sobre as permissões necessárias do IAM, consulte Permissões para o console Google Cloud .

Criar consultas

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

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

   Acessar a 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. Selecione o projeto Google Cloud ou outro recurso Google Cloudpara o qual você quer ver os registros.

3. Use o painel Consulta para criar sua consulta.

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

   • Pesquise texto em todos os campos de registro.
   • Selecione opções nos menus de filtro.
   • Escrever ou modificar consultas usando o editor de consultas.
   • Veja e execute consultas salvas, recentes e sugeridas na menu_book Biblioteca de consultas.

Pesquisar texto em campos de registro

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

Você pode pesquisar palavras e frases, e seus termos de pesquisa podem incluir operadores booleanos e expressões regulares:

• Para fazer uma pesquisa que diferencia maiúsculas de minúsculas, use uma expressão regular.

• Para realizar uma pesquisa sem diferenciação de maiúsculas e minúsculas ao longo dos limites de token, insira os termos de pesquisa sem crases 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 fazer uma pesquisa de uma frase sem diferenciar maiúsculas de minúsculas ao longo dos limites de 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 sem diferenciação de maiúsculas e minúsculas de uma substring, 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 ao longo dos limites de token.

Para ver seus termos de pesquisa na expressão de consulta, ative Mostrar consulta.

Depois de inserir 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 Google Cloud selecionado.

O campo de pesquisa aceita 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 precisam estar em maiúsculas. 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. É possível combinar regras AND e OR na mesma expressão. Por exemplo, quando os dois operadores são misturados, 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 realiza 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 - (sinal de subtração). Por exemplo, as duas consultas a seguir são as mesmas:

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

"response successful" -"error"

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

-"response successful"

NOT "response successful"

Criar consultas com menus de filtro

Use os menus de filtro no painel Consulta para adicionar parâmetros de recursos, nomes, gravidade e correlação 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 são derivadas das entradas de registro armazenadas pelo Cloud Logging.

• 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 identificadores de recursos a serem aplicados à consulta. Os parâmetros de 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 à sua 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 à sua consulta. Ao selecionar vários níveis de gravidade, o operador lógico OR é usado.
• Correlacionar por: permite agrupar e visualizar entradas de registro em um formato "pai-filho". Para mais informações, consulte Correlacionar entradas de registro.

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

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

2. Refine os parâmetros do filtro.

3. Clique em Aplicar. Os parâmetros aparecem no campo do editor de consultas.

   Para ver seus termos de pesquisa na expressão de consulta, ative Mostrar consulta.

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

Para determinados tipos de recursos do Compute Engine, como gce_instance e gce_network, o nome do recurso aparece com o ID como um subtítulo. Por exemplo, para o tipo de recurso gce_instance, o nome da VM aparece ao lado do ID dela. Os nomes dos recursos ajudam a identificar o ID correto, em que você pode criar consultas.

Ver registros por período

Há duas maneiras de mostrar registros gravados em um período específico:

1. Use o seletor de intervalo de tempo.
2. Inclua uma expressão de carimbo de data/hora no campo do editor de consultas.

Usar o seletor de intervalo de tempo

O período padrão é de uma hora, mas você pode selecionar entre as opções predefinidas, especificar um horário de início e término personalizado ou centralizar o período em uma marca de tempo específica usando o seletor de período. Por exemplo, se você quiser ver os dados da semana passada, selecione Última semana no seletor de período.

Você também pode definir suas preferências de fuso horário usando 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 restrição de intervalo de tempo. Se uma consulta não usar uma expressão de carimbo de data/hora, ela usará o seletor de intervalo de tempo como a restrição de intervalo de tempo.

Escrever 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 do editor de consultas da Análise de registros:

1. Se você não vir o campo do editor de consultas no painel Consulta, ative Mostrar consulta.

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

   Se você adicionou termos de pesquisa no campo de pesquisa ou selecionou parâmetros nos menus de filtro, eles também aparecem no campo do editor de consultas e são avaliados como parte da sua expressão de consulta.

3. Depois de analisar a consulta, clique em Executar consulta.

   Os registros que correspondem à consulta são listados no painel Resultados da consulta. Os painéis Histograma e Campos de registro também se ajustam de acordo com a expressão da 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 uma consulta, ela é adicionada à menu_book Biblioteca de consultas, que contém as últimas 10.000 consultas únicas em um período de 30 dias.

Para ver suas consultas recentes, selecione o botão menu_book Biblioteca de consultas na barra de ferramentas principal. Para consultas recentes, você tem as seguintes opções:

• Streaming: para executar a consulta e transmitir os resultados, escolha essa opção.
• Executar: escolha essa opção para executar a consulta.

• more_vert Mais opções: permite visualizar a expressão de consulta com as opções de execução ou salvamento na 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. A caixa de diálogo Salvar consulta será aberta.

  2. Preencha os seguintes campos:

     • Nome (obrigatório): forneça um nome para a 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 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 e selecione o número de caracteres a serem truncados 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.

Também é possível classificar e filtrar suas consultas recentes. O filtro corresponde ao texto na expressão da consulta.

Salvar e compartilhar consultas

As consultas salvas permitem que você armazene expressões de consulta para explorar registros com mais consistência e eficiência. A Análise de registros tem uma Biblioteca de consultas, onde é possível acessar as consultas salvas. Também é possível salvar suas consultas usando o método da API Logging savedQueries.create.

Você pode salvar sua consulta como privada e visível apenas para você ou compartilhá-la com outros membros do projeto Google Cloud . Depois de compartilhar uma consulta, ela não será mais de sua propriedade, e qualquer membro do projeto com as permissões necessárias poderá acessá-la.

{
  "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"
  }
}

Ver consultas salvas

Para ver as consultas particulares e as compartilhadas com outros membros no projeto Google Cloud , clique no botão menu_book Biblioteca de consultas:

{
  "parent": "name": projects/PROJECT_ID/locations/-
  "visibility": "SHARED"
  "filter": "explorer"
}

Usar consultas sugeridas

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

Para ver e executar consultas sugeridas, clique no botão menu_book Biblioteca de consultas e em Sugeridas. Na guia Sugerido, você tem as seguintes opções:

• Streaming: para executar a consulta e transmitir os resultados, escolha essa opção.
• Executar: escolha essa opção para executar a consulta.

• more_vert Mais opções: permite visualizar os detalhes da expressão de consulta com as opções de execução ou salvamento. Também é possível selecionar a consulta diretamente para ver essas opções.

  Para analisar os detalhes de uma consulta sugerida, siga uma destas instruções:

  • Selecione a linha da consulta.

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

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

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

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

    A consulta editada aparece na lista Salvo, em que você pode escolher executar a consulta depois.

  • Para executar a consulta agora, clique em Executar. A consulta é executada e aparece no campo do editor de consultas.

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

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

Observe os seguintes comportamentos esperados:

• Os carregamentos de página sucessivos podem não mostrar as mesmas consultas na mesma ordem.
• Talvez não apareçam consultas sugeridas.
• Às vezes, executar 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 de maneira eficiente durante sessões de solução de problemas urgentes e a explorar seus registros para entender melhor quais dados do Logging estão disponíveis.

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

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

   Acessar a 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. Selecione o projeto Google Cloud ou outro recurso Google Cloudpara o qual você quer ver os registros.

3. Clique no botão menu_book Biblioteca de consultas. Você vê categorias de consultas disponíveis e subconjuntos de consultas com base em produtos Google Cloud. Para restringir a seleção de consultas, clique em qualquer um dos produtos.

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

4. Para analisar uma expressão de consulta, faça o seguinte:

   a. Clique na linha da consulta.

   b. Clique em more_vert Mais e selecione Visualizar.

5. Na caixa de diálogo Detalhes da consulta, você verá a consulta e as opções para Executar, Transmitir ou Salvar como:

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

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

     A consulta editada aparece na lista Salvo, em que você pode escolher executar a consulta depois.

   • Para executar a consulta agora, clique em Executar. A consulta é executada e aparece no campo do editor de consultas.

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

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

A seguir

• Exemplos de consultas