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. As consultas que você cria são gravadas na linguagem de consulta do Logging.

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

Antes de começar

  • Para receber as permissões necessárias para ler dados de registro e criar consultas, use consultas salvas particulares, peça ao administrador para conceder a você o papel do IAM de Visualizador de registros (roles/logging.viewer) 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 permissões a seguir são necessárias para ler dados de registro para criar consultas, usar consultas salvas particulares ou listar e receber consultas compartilhadas:

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

  • Para receber as permissões necessárias para criar, atualizar e excluir consultas compartilhadas, peça ao administrador para conceder a você o Administrador de registro (roles/logging.admin) do IAM no seu 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 para o 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 a 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.
    • Crie ou modifique consultas usando o editor de consultas.
    • Visualize e execute consultas salvas, recentes e sugeridas na Biblioteca de consultas.

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 do painel Query.

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

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

  • Para realizar uma pesquisa sem distinção entre maiúsculas e minúsculas nos limites do token, insira os termos de pesquisa sem chaves invertidas 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 sem distinção entre maiúsculas e minúsculas de uma frase nos 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 sem distinção entre 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 do token.

Para acessar os termos de pesquisa na expressão da 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 do 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 ser escritos com letras 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 nenhum operador, todos os termos e frases de pesquisa serão unidos por AND. Você pode 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 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 seguinte. 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 iguais:

"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 e gravidade de registros e correlação ao campo "query-editor". 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 resource.type e 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 registro para aplicar à consulta. Ao selecionar vários nomes de registro, 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 adicionar à consulta. Ao selecionar vários níveis de gravidade, o operador lógico OR é usado.
  • Correlacionar por: permite agrupar e conferir as 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 Menu em qualquer um dos menus de filtro no painel Query.

  2. Refinar os parâmetros do filtro.

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

    Para acessar os termos de pesquisa na expressão da 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. Por exemplo, no tipo de recurso gce_instance, o nome da VM aparece ao lado do ID da VM. Os nomes dos recursos ajudam a identificar o ID de recurso correto, em que você pode criar consultas.

Conferir os registros por período

Há duas maneiras de exibir registros que foram 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 intervalo padrão é de uma hora, mas você pode selecionar opções de tempo predefinidas, especificar um horário de início e término personalizado ou centralizar o intervalo em torno de um carimbo de data/hora específico usando o seletor de intervalo de tempo. Por exemplo, se você quiser conferir os dados da semana passada, selecione Última semana no seletor de período.

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 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 consulta tiver uma expressão com um carimbo de data/hora, o seletor de intervalo de tempo será desativado e a consulta vai 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, ela 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 do editor de consultas do Explorador de registros:

  1. Se você não encontrar o campo do editor de consultas no painel Consulta, ative a opção 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 expressão da 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 à Biblioteca de consultas , que contém as últimas 10.000 consultas únicas em um período de 30 dias.

Para conferir suas consultas recentes, selecione o botão 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 esta opção.
  • Executar: escolha essa opção para executar a consulta.

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

    2. Preencha os seguintes campos:

      • Nome (obrigatório): informe 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 mostrar.
      • Truncar campos de resumo (opcional): ative 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 você pode acessar as consultas salvas. Também é possível salvar suas consultas usando o método savedQueries.create da API Logging.

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

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 a expressão de consulta no campo do editor de consultas.

  2. Preencha os seguintes campos:

    • Nome (obrigatório): informe 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 personalizados (opcional): ative Incluir campos de resumo e insira os campos de resumo que você quer mostrar.
    • Truncar campos de resumo (opcional): ative 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.
    • Compartilhar com o projeto: ative a opção Compartilhar com o projeto para compartilhar sua consulta com outros membros do projeto do Google Cloud.

  3. Clique em Salvar consulta. As consultas salvas aparecem em uma lista na guia Salvas.

Para executar uma consulta salva, clique em Executar. Para executar a consulta e transmitir os resultados, clique em Transmitir.

Para modificar uma consulta salva, selecione Mais opções e, em seguida, Editar. Você também pode selecionar a consulta, fazer modificações e salvar a consulta modificada.

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

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

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 widget APIs Explorer na página de referência do método. Para consultas do Explorador de registros, especifique o campo loggingQuery. O exemplo a seguir ilustra um corpo de solicitação de exemplo, 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"
  }
}

Para compartilhar a consulta com outros membros do projeto do Google Cloud, especifique um valor de SHARED no campo visibility.

Ver consultas salvas

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

Console

  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. Clique no botão Query library e em Saved.

É possível classificar a tabela por qualquer cabeçalho. A coluna Visibilidade indica se as consultas são compartilhadas ou privadas:

  • Compartilhadas: consultas compartilhadas com outros membros do projeto do Google Cloud.
  • Particular: consultas salvas que só você pode acessar.

API

É possível usar a API Logging para conferir consultas particulares e compartilhadas usando o método savedQueries.list.

Por exemplo, o corpo de solicitação a seguir lista todas as consultas compartilhadas do Explorador de registros com um ID de local curinga:

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

Usar consultas sugeridas

O Logging gera consultas sugeridas com base no contexto do seu 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, 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 conferir e executar consultas sugeridas, clique no botão Biblioteca de consultas e em Sugerido. Na guia Sugerido, você tem as seguintes opções:

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

  • Mais opções: permite conferir os detalhes da expressão de consulta com as opções de execução ou salvamento da consulta. 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ê encontra a consulta e as opções 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 mais tarde.

    • 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 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 encontre consultas sugeridas.
  • Às vezes, a execução de uma consulta sugerida não retorna registros.

Selecionar consultas da biblioteca

O Logging fornece uma biblioteca de consultas com base em casos de uso comuns 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 seus registros para entender melhor quais dados de registro estão disponíveis.

Para conferir e executar as consultas da biblioteca, 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. Clique no botão Biblioteca de consultas. Você vai encontrar categorias de consultas disponíveis e subconjuntos de consultas 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 da consulta.

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

    a. Clique na linha da consulta.

    b. Clique em Mais e selecione Visualizar.

  5. Na caixa de diálogo Detalhes da consulta, você encontra a consulta e as opções de 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 mais tarde.

    • 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 retornar à lista de consultas sugeridas, clique em Fechar.

A seguir