Como criar consultas de registro

Nesta página, descrevemos como criar consultas no Explorador de registros do Google Cloud para recuperar, refinar e analisar registros.

Antes de começar

Você não precisa de um espaço de trabalho para usar o Logging, a menos que esteja enviando registros do Amazon Web Services (AWS) para ele.

O Explorador de registros exibe registros de um único projeto do Google Cloud. Se você estiver usando um espaço de trabalho, o Stackdriver Logging não combinará os registros dos projetos monitorados. Selecione um projeto específico para visualizar seus registros.

Se você estiver usando um espaço de trabalho e a AWS, selecione o projeto de conector da AWS para ver os registros da AWS.

Primeiros passos

Para navegar até o Explorador de registros, faça o seguinte:

  1. Acesse o menu de navegação do Google Cloud e selecione Logging > Explorador de registros:
    Acessar o Explorador de registros
  2. Selecione um projeto do Google Cloud.
  3. No menu Upgrade, alterne de Visualizador de registros legado para Explorador de registros.

Agora você está no Explorador de registros.

Como criar consultas

O painel do criador de consultas fornece várias maneiras de recuperar registros:

  1. Menus suspensos do criador de consultas
  2. Consultas usando a linguagem do criador de consultas
  3. Guias de consulta Recentes, Salvas e Sugeridas.

query-builder-pane

Nas seções a seguir, mostramos como criar e executar consultas para recuperar registros.

Menus suspensos do criador de consultas

Os menus suspensos permitem adicionar parâmetros de consulta ao criador de consultas. É possível usar os menus suspensos para selecionar recursos, nomes de registros, gravidade de registros e intervalos de tempo. Essas opções correspondem aos campos LogEntry para todos os registros do Pacote de operações do Google Cloud.

Menus suspensos do criador de consultas

  • Recurso: permite que você especifique resource.type. É possível selecionar um único recurso de cada vez para adicionar ao Criador de consultas. Entradas usam o operador lógico AND.
  • Nome do registro: permite que você especifique logName. É possível selecionar vários nomes de registros de uma só vez para adicionar ao Criador de consultas. Ao selecionar várias entradas, o operador lógico OR é usado.
  • Gravidade: permite que você especifique gravidade. É possível selecionar vários níveis de gravidade de uma só vez para adicionar ao Criador de consultas. Ao selecionar várias entradas, o operador lógico OR é usado.

Para usar qualquer um dos menus de parâmetro de pesquisa, expanda-os e selecione um parâmetro ou vários parâmetros. Em seguida, clique em Adicionar.

Depois de criar a consulta, clique em Executar consulta para recuperar as entradas de registro que você quiser.

Consultas com restrição de tempo

Há duas maneiras de consultar registros com base no tempo:

  1. Consultar usando uma expressão de carimbo de data/hora
  2. Consultar usando o seletor de intervalo de tempo

    O Explorador de registros mostra duas maneiras de filtrar por tempo

Se você tiver uma consulta com 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.

Consultas usando a linguagem do criador de consultas

É possível usar a linguagem do criador de consultas para criar consultas no painel do Cloud Logging, bem como na API Logging ou na interface de linha de comando.

Para mais detalhes, consulte Linguagem do criador de consultas.

Veja a seguir algumas sugestões para otimizar consultas.

Otimize suas consultas

Para encontrar entradas de registro de forma mais eficiente, faça o seguinte:

  • pesquise usando campos indexados;
  • minimize o número de entradas de registro a serem pesquisadas.

Usar campos indexados

Para aproveitar o índice, especifique valores exatos para campos indexados usando o operador de igualdade. Não use correspondências de substring.

Os seguintes campos LogEntry são indexados:

As próximas seções explicam como usar esses campos indexados para minimizar o número de entradas de registro a serem consultadas.

Encontre entradas de registro rapidamente

Para tornar as pesquisas mais rápidas, reduza o número de registros, o número de entradas de registros ou o tempo das pesquisas. Melhor ainda: reduza os três.

Exemplo: use o nome de registro correto

Especifique o registro que contenha as entradas do seu interesse. Verifique uma das entradas de registro para confirmar o nome do registro real. Por exemplo, o Explorador de registros mostra que há uma seção no Compute Engine chamada "activity_log". Em uma inspeção mais detalhada das entradas do registro de atividades, o registro é, na verdade, chamado "compute.googleapis.com/activity_log".

A comparação a seguir está incorreta. Ela não gera correspondências porque usa o nome de registro errado:

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

A comparação a seguir está correta. Ela seleciona entradas de registro do registro de atividades. É preciso codificar o nome do registro por URL, como mostrado:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

Exemplo: escolha as entradas de registro corretas

Se souber que as entradas de registro que você quer pertencem a uma determinada instância de VM, especifique-a. Inspecione uma das entradas de registro que quer pesquisar para verificar os nomes corretos dos rótulos. No exemplo a seguir, instance_id é um dos marcadores indexados:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

Você especificará um valor para o tipo de recurso. Caso contrário, a comparação de instance_id não usa o índice.

Por exemplo: escolha o período correto

Especifique um período para a pesquisa. Uma maneira rápida de determinar os carimbos de data/hora úteis no formato RFC 3339 é usar o comando Gnu/Linux date:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

Use os valores desses carimbos de data/hora nas consultas a seguir. Para criar um carimbo de data/hora aceitável para o Logging, substitua o espaço entre a data e a hora pela letra T.

Por exemplo, para pesquisar nas últimas três horas:

    timestamp >= "2016-06-27T14:40:00-04:00"

Como outro exemplo, para procurar entre três e cinco horas atrás:

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

Para outro exemplo de uso de carimbo de data/hora, acesse Índices de campos temporários nessa página.

Minimizar as pesquisas globais e de substring

Evite a tentação de usar atalhos ao digitar consultas de registro.

Exemplo: não use substrings em campos indexados

Você está procurando uma entrada de registro do servidor da Web Apache2. Você sabe que os registros do Apache são denominados apache-access e apache-error. O que fazer?

  • Não use uma correspondência de substring para digitar menos:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • Use correspondências exatas ao pesquisar campos indexados:

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

Um campo indexado perde toda a rapidez quando você faz uma pesquisa de substring.

Exemplo: não use pesquisas globais

Você está pesquisando uma entrada de registro que contém "Hello, Kitty" no payload:

  • Não use uma pesquisa global. Uma das razões é que todas elas são pesquisas de substring:

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • Limite a pesquisa a um único campo, mesmo se tiver que manter a pesquisa de substring:

        textPayload:"Hello, Kitty"
    
  • Use um teste de igualdade, se possível:

        textPayload = "Hello, Kitty"
    
  • Faça referência a campos individuais em um payload se as entradas de registro tiverem payloads estruturados:

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • Use um campo indexado para restringir a pesquisa:

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

Como pesquisar exemplos

As entradas de registro mostradas são aquelas que correspondem à consulta na caixa de consulta de pesquisa. Se o menu Pular para data contiver um valor, a tela rolará para esse ponto no tempo. Veja alguns exemplos de consulta:

resource.type=gae_app

Encontra as mesmas entradas de registro que a interface básica mostraria se você tivesse selecionado Aplicativo do GAE (todos os códigos de módulo) no menu de recursos e Todos os registros no menu do nome. Para uma lista de tipos de recursos, acesse Lista de recursos monitorados.

Conforme você digita, o Explorador de registros sugere conclusões para campos, como resource.type.

resource.type=gae_app AND logName:request_log

Encontra entradas de registro para apps do App Engine a partir de nomes de registros que contenham request_log. Leve isto em conta:

  • O operador = se refere à igualdade exata. O tipo de recurso precisa ter exatamente "gae_app", exceto letras maiúsculas e minúsculas.
  • O operador :: significa "has". O campo logName precisa conter request_log, em qualquer letra maiúscula. O nome real do registro é muito mais longo. Usar : pode resultar em pesquisas mais lentas.
  • As duas comparações são mescladas por AND. Também é possível usar OR, mas AND será usado se você não incluir o operador.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Localiza entradas de registro com dois tipos de recursos: instância de VM do Compute Engine ou instância de VM do AWS EC2. As entradas de registro precisam ter severity pelo menos ERROR, o que equivale a selecionar ERROR no menu de gravidade da interface de consulta básica. Não é possível visualizar registros de vários tipos de recursos na interface de consulta básica.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Encontra todas as entradas de registro de auditoria da Atividade do administrador no projeto [PROJECT_ID]. Os registros de auditoria usam o mesmo nome em um projeto, mas têm tipos de recurso diferentes. O código do registro, cloudaudit.googleapis.com/activity precisa ser codificado pelo URL no nome do registro. Usar a igualdade na comparação acelera a pesquisa. Para mais informações, consulte Entendendo os registros de auditoria.

unicorn

Encontra entradas de registro contendo unicorn em qualquer campo, em qualquer letra maiúscula. Um termo de pesquisa que não faz parte de uma comparação de campo é uma consulta de "todos os campos".

unicorn phoenix

Encontra entradas de registro que contêm unicorn em algum campo e phoenix em algum campo.

textPayload:(unicorn phoenix)

Encontra entradas de registro com o campo textPayload que contém unicorn e phoenix em qualquer ordem, o AND está implícito entre as duas palavras.

textPayload:"unicorn phoenix"

Encontra entradas de registro com o campo textPayload que contém a string "unicorn phoenix". É o mesmo da interface de consulta básica.

NOT textPayload: "unicorn phoenix"

Localiza as entradas de registro em que o campo textPayload não contém a string "unicorn phoenix". Esse tipo de consulta reduz entradas de registro indesejadas.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Encontra entradas de registro dentro de um período de 30 minutos.

Consultas salvas

O painel do criador de consultas apresenta a guia Salvas, que possibilita acessar as consultas salvas.

Lista de consultas salvas

As consultas salvas permitem que você armazene expressões de consulta para explorar registros com mais consistência e eficiência.

Para salvar uma consulta criada no painel do criador de consultas, faça isto:

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

  2. Adicione um Nome para a consulta.

    Os nomes são limitados a 64 caracteres.

  3. Opcional: para adicionar campos de resumo à consulta, alterne para Incluir campos de resumo.

  4. Opcional: adicione uma Descrição para a consulta.

    As descrições estão limitadas a 1.000 caracteres. Não inclua informações confidenciais.

  5. Clique em Salvar consulta na caixa de diálogo.

As consultas salvas aparecem em uma lista na guia Salvas no painel do criador de consultas.

Para executar uma consulta salva, clique em Executar consulta.

Consultas recentes

O painel do criador de consultas tem uma guia 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.

A guia

Para ver suas consultas recentes, selecione a guia Recente no painel do criador de consultas. Na guia Recente, você tem as seguintes opções:

  • Executar. Executa a consulta.
  • Mais opções . Permite visualizar os parâmetros de consulta com as opções de execução da consulta ou salvá-la na lista de consultas salvas. Também é possível selecionar a consulta diretamente para ver essas opções.

    Para executar a consulta, selecione Executar.

    Para salvar a consulta, selecione Salvar como e preencha os seguintes campos:

    • Nome (obrigatório): forneça um nome.
    • 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 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 de campos.

    Selecione Salvar consulta. A consulta agora está disponível na sua lista de consultas salvas.

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

Consultas sugeridas

O Logging gera consultas sugeridas com base no entendimento dos produtos do Google Cloud que você está usando. Ele também propõe consultas que podem ajudar você a identificar problemas e fornece 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 visualizar e executar consultas sugeridas no painel do criador de consultas, faça o seguinte:

  1. Clique na guia Sugeridas.

    Guia de consultas sugeridas que mostram um conjunto de consultas

  2. Analise a descrição da consulta sugerida.

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

    a. Clique na linha.

    b. Clique em Mais e selecione Visualizar.

  4. No painel do criador de consultas, você verá a consulta e as opções para Executar ou Salvar.

    a. Para salvar a consulta, clique em Salvar. A consulta será exibida na lista Salvo, em que você poderá executar a consulta posteriormente.

    b. Para executar a consulta, clique em Executar. A consulta será exibida em Visualização da consulta no painel do criador de consultas.

  5. Depois de analisar a consulta, clique em Executar consulta. Os resultados da consulta sugerida são exibidos em Resultados da consulta.

As consultas sugeridas são criadas dinamicamente com base no contexto do projeto do Google Cloud. Os carregamentos de página sucessivos podem não mostrar as mesmas consultas na mesma ordem. Este comportamento é esperado.

Solução de problemas

Texto sem aspas

É possível omitir aspas em strings de texto que não contêm espaços em branco ou determinados caracteres especiais. Isso é chamado de texto sem aspas, e um exemplo é a palavra ERROR no exemplo anterior. A string "v1.compute.instances.insert" está entre aspas porque contém pontos. Se quiser incluir aspas dentro de uma string, insira uma barra invertida antes das aspas.

Problemas de sintaxe

Se você tiver problemas com o uso da linguagem do criador de consultas, verifique o seguinte:

  • Sua consulta obedece às regras de sintaxe, com parênteses correspondentes e aspas. Sua consulta não pode incluir comentários.

  • Os nomes dos campos de entrada de registro estão escritos corretamente.

  • As operações booleanas estão em maiúsculas (AND, OR, NOT).

  • As expressões booleanas como restrições globais ou como o lado direito das comparações precisam estar entre parênteses para maior clareza. Por exemplo, as duas consultas abaixo têm a mesma aparência, mas não são:

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • Com texto sem aspas, não pode haver nenhum caractere especial. Em caso de dúvida, adicione aspas duplas. Por exemplo, a primeira comparação abaixo é ilegal por causa do operador de substring incorporado (:). A comparação precisa ser escrita com aspas:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • A geração de registros do gcloud exige que a consulta esteja entre aspas duplas. Para usar aspas duplas com a finalidade de fazer o escape de caracteres especiais usando o comando gcloud logging, agrupe a consulta inteira com aspas simples:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • Se você estiver escrevendo uma consulta que inclua um carimbo de data e hora, selecione Sem limite no seletor de intervalo de tempo abaixo da caixa de consulta de pesquisa.