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 faça seleções nos menus de filtro usando as opções incluídas nas entradas de registro. O as consultas que você cria são escritas no Linguagem de consulta do Logging.

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

Antes de começar

• Para ter as permissões necessárias na leitura de dados de registro para criar consultas, use as consultas salvas particulares, ou listar e receber consultas compartilhadas, peça ao administrador para conceder a você Leitor de registros (roles/logging.viewer) do IAM no projeto.

  Esse papel predefinido contém as permissões necessárias para ler dados de registro e criar consultas, usar consultas salvas particulares ou listar e receber consultas compartilhadas. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

  Permissões necessárias

  As seguintes permissões são necessárias para ler dados de registro para criar consultas, usar consultas salvas particulares, ou listar e receber consultas compartilhadas:

  • Usar consultas salvas particulares: logging.queries.usePrivate
  • Listar e receber consultas compartilhadas:
    • logging.queries.listShared
    • logging.queries.getShared

• Para ter as permissões necessárias para criar, atualizar e excluir consultas compartilhadas, peça ao administrador para conceder a você Papel do IAM Administrador do Logging (roles/logging.admin) no projeto.

  Esse papel predefinido contém as permissões necessárias para criar, atualizar e excluir consultas compartilhadas. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

  Permissões necessárias

  As seguintes permissões são necessárias para criar, atualizar e excluir consultas compartilhadas:

  • logging.queries.share
  • logging.queries.updateShared
  • logging.queries.deleteShared

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

Criar consultas

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

1. No console do 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 ou outro recurso do Google Cloud em que você quer acessar 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 as opções nos menus de filtro.
   • Crie ou modifique consultas usando o editor de consultas.
   • Acesse, edite ou execute as consultas nos campos Recentes, Salvos, Sugeridos e Biblioteca.

Pesquisar texto em campos de registro

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

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

• Para realizar uma pesquisa com diferenciação entre maiúsculas e minúsculas, você deve usar uma expressão regular.

• Para realizar uma pesquisa que não diferencia maiúsculas de minúsculas ao longo dos limites do token, digite o termos 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, a pesquisa 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 sem diferenciação de maiúsculas e minúsculas para uma frase ao longo de 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 entre maiúsculas e minúsculas em uma substring, quebre o texto aspas duplas. Por exemplo, "hello world" corresponde a Hello World e Hello world A mesma consulta também corresponde a hello worlds, porque o a pesquisa não é realizada ao longo de limites de token.

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

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

Operadores booleanos

Suas entradas do campo de pesquisa são convertidas em expressões booleanas que especificam uma 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 em expressões de pesquisa, observe o seguintes:

• Não é possível usar parênteses para aninhar regras. Parênteses na pesquisa são analisados como termos de pesquisa.
• Os operadores Booleanos devem estar em maiúscula. 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 de pesquisa e frases 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 as regras AND e OR na mesma expressão. Por exemplo, quando dois operadores forem misturados, a expressão a AND b OR c AND d se transformará na seguinte expressão de 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 com o operador - (menos). Por exemplo, os dois 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 - (menos) estiver fora do aspas. Por exemplo, as duas consultas a seguir são iguais:

-"response successful"

NOT "response successful"

Criar consultas com menus de filtro

Use os menus de filtro no painel Consulta para adicionar o recurso, o nome do registro, e os parâmetros de gravidade de registro no campo do editor de consultas. Essas opções correspondem aos campos LogEntry para todos os registros em a geração de registros.

As opções nos menus Recurso e Nome do registro são derivadas dos que são armazenadas pelo Cloud Logging.

• Recurso: permite especificar os atributos resource.type e associado resource.labels. É possível selecionar um único tipo de recurso usando este menu de filtros e zero ou mais rótulos de recursos para aplicar ao seu consulta. Os parâmetros do recurso são unidos pelo operador lógico AND.
• Nome do registro: permite que você especifique logName. Você pode selecionar vários nomes de registro para aplicar à consulta. Ao selecionar vários nomes de registro, o operador lógico OR é usado.
• Gravidade: permite que você especifique a gravidade. Você pode selecionar vários níveis de gravidade ao mesmo tempo para adicionar à sua 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. Abra o Menu arrow_drop_down em qualquer um dos menus de filtro no painel Consulta.

2. Refine os parâmetros de filtro.

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

   Para ver os 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 do recurso como subtexto. Para Por exemplo, para o tipo de recurso gce_instance, é exibido o nome da VM ao lado do ID da VM. Os nomes dos recursos ajudam a identificar ID do recurso, em que você pode criar consultas.

Exibir registros por intervalo de tempo

Há duas maneiras de exibir registros que foram gravados em um intervalo de tempo 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 intervalo de tempo padrão é de uma hora, mas é possível selecionar uma das opções de tempo predefinidas, especificar horários de início e término personalizados ou centralizar o período de acordo com uma data usando o seletor de intervalo de tempo. Por exemplo, se você quiser exibir os dados da última semana e, em seguida, selecione Última semana no período seletor.

Também é possível 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 consulta

Para adicionar uma expressão de carimbo de data/hora diretamente ao campo do editor de consulta, use o método Linguagem de consulta do Logging.

Se o campo do editor de consulta contiver uma expressão com carimbo de data/hora, o o seletor de intervalo de tempo está desativado e a consulta usa 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 usa o seletor de intervalo de tempo como sua restrição de intervalo de tempo.

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

Você pode usar o 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 consulta.

   Se você adicionou termos de pesquisa ao campo de pesquisa ou selecionou parâmetros nos menus de filtro, eles também aparecerão nos query-editor e são avaliadas como parte da expressão da consulta.

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

   Os registros que correspondem à consulta são listados no painel Resultados da consulta. O Histograma e Campos de registro os painéis 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 à lista de consultas Recentes, que contém as últimas 10.000 consultas únicas em um período de 30 dias.

Para acessar suas 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 esta opção. é a melhor opção.
• Executar: para executar a consulta, escolha esta opção.

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

  2. Preencha os seguintes campos:

     • Nome (obrigatório): informe um nome para a consulta. Os nomes estã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 mostrar.
     • Truncar campos de resumo (opcional): ativar Truncar campos de resumo e selecionar o número de caracteres a truncar e se o truncamento ocorre no início ou no fim do 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 armazenar expressões de consulta para você analisar melhor os registros de maneira consistente e eficiente. No painel Consulta da Análise de registros. exibe uma guia Salvas, onde é possível acessar as consultas salvas. Você também pode salve as consultas usando o método da API Logging savedQueries.create:

É possível salvar a consulta para que ela fique particular e visível apenas para você e pode compartilhá-lo com outros membros do projeto do Google Cloud. Quando você compartilhar uma consulta, ela não pertence mais a você nem a qualquer membro do projeto com as permissões necessárias pode acessar a consulta.

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

Você pode ver as consultas particulares e as que foram compartilhadas com outros membros no projeto do Google Cloud na guia Salvos:

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

Usar consultas sugeridas

O Logging gera consultas sugeridas com base no contexto da sua 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 sistemas. Por exemplo, detectar que você está usando o Google Kubernetes Engine, o Logging pode sugerir uma consulta todos os registros de erros dos contêineres.

Para visualizar e executar consultas sugeridas, selecione a guia Sugestões no Painel Consulta. A guia Suggested 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 esta opção. é a melhor opção.
• Executar: para executar a consulta, escolha esta opção.

• more_vert Mais opções: Permite exibir os detalhes da expressão de consulta com as opções para executar o a consulta ou salvá-la. Também é possível selecionar a consulta diretamente para ver essas opções.

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

  • Selecione a linha da consulta.

  • Clique em more_vert 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, Transmitir ou Salvar como:

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

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

    A consulta editada aparece na sua lista Salvas, onde você pode escolher executar a consulta mais tarde.

  • Para executar a consulta agora, clique em Executar. A consulta é executada e aparece 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:

• Os carregamentos de página sucessivos podem não mostrar as mesmas consultas na mesma ordem.
• Talvez você não veja nenhuma sugestão de consulta.
• Às vezes, a execução de uma consulta sugerida não retorna nenhum registro.

Selecionar consultas da biblioteca

O Logging oferece uma biblioteca de consultas baseadas em e produtos do Google Cloud. Essas consultas podem ajudar a encontrar registros de maneira eficiente durante sessões de solução de problemas críticas e a analisar os registros 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, aparecem categorias amplas de consultas consultas e subconjuntos de consultas com base nos produtos do Google Cloud. Para restringir a seleção de consultas exibidas, clique em um dos produtos.

   Você também pode usar o campo de pesquisa para buscar as consultas disponíveis por a categoria, a descrição ou o 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 more_vert Mais e selecione Ver.

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 na caixa de diálogo Salvar consulta.

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

   • Para executar a consulta agora, clique em Executar. A consulta é executada e aparece 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

• Exemplos de consultas