Mostrar registros e erros em um painel personalizado

Neste documento, descrevemos os widgets que podem ser adicionados aos painéis personalizados para você conferir os dados de registros e erros no mesmo contexto dos dados de métricas. O widget do painel de registros exibe entradas de registro. O widget do painel de relatório de erros exibe os grupos de erros mais recentes. Os dois widgets fornecem informações que podem ser úteis na solução de problemas. O widget de gráfico da Análise de dados de registros, que exibe os resultados de uma consulta SQL, permite identificar tendências nos dados de registro.

Análise de registros e widget do painel de registros

A Análise de registros é a maneira padrão de investigar registros. Adicionar um widget de painel de registros a um painel não altera a maneira como você usa a Análise de registros. Como os widgets do painel de registros podem ser adicionados a painéis personalizados, eles oferecem uma maneira de visualizar as entradas de registro no mesmo contexto que as métricas.

A Análise de registros e o widget do painel de registros oferecem suporte à mesma linguagem de consulta e exibem apenas as entradas de registro que você tem permissão para visualizar. Os papéis do Identity and Access Management (IAM) nos recursos que armazenam as entradas de registro que estão sendo buscadas são usados para determinar se é possível visualizá-las.

A Análise de registros e o widget do painel de registros são pré-configurados para buscar, nos buckets de registros, as entradas de registro originadas no projeto atual do Google Cloud ou roteadas para o projeto atual. É possível configurar quais entradas de registro são buscadas. Por exemplo, você pode especificar que as entradas de registro de uma visualização de registros são buscadas para exibição.

Os widgets do painel de registros exibem uma entrada de registro por linha, com colunas para gravidade, carimbo de data/hora e um resumo da entrada de registro. Para visualizar a representação formatada em JSON de uma entrada de registro, clique no botão Visualizar detalhes do registro. A estrutura de cada resumo de entrada varia de acordo com o tipo de registro. Por exemplo, a imagem a seguir mostra duas entradas de registro:

Uma imagem de duas entradas de registro no widget do painel de registros.

Na imagem anterior, a primeira entrada de registro exibe informações sobre uma solicitação de serviço. O resumo mostra informações sobre o serviço, um endereço de e-mail e uma versão formatada em string da estrutura JSON da entrada. A segunda entrada exibe os resultados de uma solicitação e mostra apenas uma frase resumindo a ação que ocorreu.

Para informações gerais sobre o Cloud Logging, consulte os seguintes recursos:

Antes de começar

Para ter as permissões necessárias para adicionar um widget de painel de registros a um painel personalizado usando o console do Google Cloud e configurá-lo para exibir entradas de registro em projetos ou visualizações de registro, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Mostrar entradas de registro em um painel

Nesta seção, descrevemos como adicionar e configurar um widget do painel de registros usando o console do Google Cloud. Para informações sobre como usar a API Cloud Monitoring, consulte Painel com um widget LogsPanel.

Um widget de painel de registros é pré-configurado para buscar entradas de registro originadas no seu projeto do Google Cloud e aquelas roteadas para seu projeto do Google Cloud. No entanto, é possível configurar quais entradas de registro o widget do painel de registros busca em buckets de registros. Por exemplo, é possível configurar o widget para exibir apenas entradas de registro que indicam algum tipo de condição de erro ou apenas essas entradas de registro em uma visualização de registro.

É possível incluir até 40 widgets no painel.

Para adicionar um widget de painel de registros ao painel usando o console, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Painéis:

    Acessar Painéis

  2. Selecione um painel ou clique em Criar painel.
  3. Na barra de ferramentas, clique em  Adicionar widget.
  4. Na caixa de diálogo Adicionar widget, selecione  Registros.
  5. Opcional: para atualizar o título, insira o novo título no campo Título do widget.

  6. Opcional: para modificar quais entradas de registro são buscadas, siga um destes procedimentos:

    • Para buscar entradas de registro de um projeto diferente ou de vários projetos, na entrada Projeto, expanda Projeto atual e preencha a caixa de diálogo. O menu lista todos os projetos do Google Cloud no escopo de métricas atual.

      Se uma entrada no menu incluir o texto "Você não tem permissão no nível do projeto para ver os registros neste projeto", você não tem as permissões necessárias para conferir as entradas de registro do projeto do Google Cloud.

    • Para buscar entradas de registro incluídas nas visualizações de registros em buckets de registros, faça o seguinte:

      1. Na entrada Escopo por, expanda Projeto e depois selecione Armazenamento.
      2. Na entrada Visualizações do Storage, expanda Projeto atual e preencha a caixa de diálogo. O menu lista as visualizações de registros nos buckets de registros no projeto do Google Cloud. Para selecionar visualizações de registros em buckets em outros projetos do Google Cloud, no menu, clique em Importar projeto, selecione um projeto e selecione uma ou mais visualizações de registro. Só é possível importar projetos que estejam incluídos no escopo de métricas atual.

  7. Opcional: para restringir os registros que o widget do painel de registros exibe, insira uma consulta no campo Editor de consultas e, se tiver desativado a execução automática das consultas, clique em Executar consulta. Para uma breve introdução às consultas, consulte Exemplos de consulta.

  8. Opcional: aplique variáveis de modelo ao widget do painel de registros. Para mais informações, consulte Adicionar filtros temporários a um painel personalizado e Aplicar um filtro permanente a um widget.

  9. Para aplicar as mudanças ao painel, clique em Apply na barra de ferramentas. Para descartar as mudanças, clique em Cancelar.

  10. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

    O widget do painel de registros exibe uma tabela das entradas de registro buscadas que também correspondem à sua consulta. Também é possível usar a barra de filtro para alterar temporariamente as entradas de registro exibidas pelo widget. Para mais informações, consulte a seção Filtrar as entradas de registro.

Exemplos de consultas

Para preencher o campo Editor de consultas, insira o texto nele ou faça seleções nos menus. O campo Editor de consultas usa a mesma linguagem de consulta que o Explorador de registros. Para informações sobre solução de problemas, consulte Problemas de sintaxe.

Os menus Gravidade e Nome do registro permitem que você selecione várias opções. Veja a seguir um exemplo de instrução de consulta que corresponde a vários níveis de gravidade:

severity=(WARNING OR ERROR OR CRITICAL OR ALERT OR EMERGENCY)

O menu Recurso permite filtrar por recurso. É possível selecionar um tipo de recurso, como Recurso auditado, ou navegar pelas janelas para selecionar um método específico.

Por exemplo, para adicionar uma consulta para Recurso auditado, faça o seguinte:

  1. Expanda o menu Recurso.
  2. Pesquise e selecione Recurso auditado.

  3. Clique em Aplicar.

    Estas etapas adicionam a seguinte cláusula ao campo do Editor de consultas:

    resource.type="audited_resource"

Da mesma forma, para adicionar uma consulta aos registros de auditoria do Cloud Functions, faça o seguinte:

  1. Expanda o menu Recurso.
  2. Pesquise e selecione Recurso auditado.
  3. No menu de serviços, selecione Cloud Functions.

  4. Clique em Aplicar.

    Estas etapas adicionam a seguinte cláusula ao campo do Editor de consultas:

    resource.type="audited_resource" resource.labels.service="cloudfunctions.googleapis.com"

Filtrar as entradas de registro

É possível modificar as entradas de registro exibidas por um widget do painel de registros. Para isso, modifique os valores dos seguintes campos ou menus:

  • Seletor de tempo do painel: o widget do painel de registros só recupera as entradas de registro gravadas no intervalo especificado por esse campo.

  • Filtro no widget do painel de registros: o filtro especificado é aplicado após a conclusão da consulta. O valor desse campo é mantido apenas para a sessão atual.

  • Menu Gravidade no widget do painel de registros: o filtro por nível de gravidade é aplicado após a conclusão da consulta. O valor desse campo é mantido apenas para a sessão atual.

  • Consulta no widget do painel de registros: o widget do painel de registros exibe apenas as entradas de registro que correspondem à consulta. Se você não especificar uma consulta, todos os registros no intervalo de tempo selecionado serão exibidos. Se você especificar uma consulta, o widget do painel de registros exibirá um ícone Mostrar consulta, que exibe a consulta atual como uma dica.

    Para modificar a consulta, edite o widget do painel de registros.

  • Projeto do Google Cloud no widget do painel de registros: para modificar essa configuração, edite o widget do painel de registros.

  • Filtros do painel: quando existem filtros do painel, a configuração de filtro é aplicada à consulta do widget do painel de registros. Por exemplo, se você adicionar o filtro do painel cluster_name: mycluster, a consulta será atualizada para incluir resource.labels."cluster_name"="mycluster". Para mais informações sobre filtros do painel, consulte Adicionar filtros temporários e Adicionar filtros permanentes.

O restante desta seção fornece mais informações sobre como filtrar as entradas de registro.

Exemplo: filtrar entradas de registro por data

Para exibir os registros mais recentes em um widget do painel de registros, use os campos de tempo na barra de ferramentas do painel. Por exemplo, selecione 1H. Desde que você não selecione um período personalizado, o widget sempre vai mostrar os registros mais recentes, mesmo quando eles forem anteriores ao período selecionado.

Ao investigar um incidente, é possível restringir as entradas de registro às entradas que estão em um intervalo de tempo específico. Para configurar as entradas de registro para mostrar os registros que estão em um intervalo de tempo fixo, siga um ou ambos os procedimentos a seguir:

  • Escolha um período usando o seletor de intervalo de tempo.
  • Insira uma cláusula timestamp no campo Editor de consultas do painel de configuração e selecione Aplicar filtro.

Quando você especifica um intervalo de tempo, o widget do painel de registros não é atualizado automaticamente.

Exemplo: filtrar entradas de registro por gravidade

Quando você está monitorando a depuração de uma situação de falha, convém ver apenas mensagens de erro e ocultar da exibição todas as outras entradas de registro. Para configurar um widget do painel de registros para exibir apenas as entradas de registro que satisfaçam níveis específicos de gravidade, siga um ou ambos os procedimentos a seguir:

  • Para aplicar um filtro temporário, selecione um valor para o menu Gravidade no widget do painel de registros. Esse menu especifica um nível de gravidade mínimo. Por exemplo, um valor de "Aviso" resulta na recuperação de entradas de registro com uma gravidade "Erro", mas aquelas com uma gravidade de "Aviso" não são recuperadas. Por padrão, o valor desse campo é definido como Default, o que inclui todas as entradas de registro.

    A configuração do menu Gravidade é descartada quando você sai do painel.

  • Para aplicar um filtro permanente, insira uma cláusula severity no campo Editor de consultas no painel de configuração e selecione Aplicar filtro.

Exemplo: filtrar entradas de registro por string ou frase

Filtrar entradas de registro por string ou frase específica permite eliminar a visualização de entradas de registro que não são de interesse. Por exemplo, para visualizar entradas de registro que incluem um endereço de e-mail específico, filtre por esse endereço.

  • Para aplicar um filtro temporário para visualizar apenas as entradas de registros que contêm uma palavra ou frase específica, use o campo Filtro. O contém-test é indiferente a maiúsculas.

    Se você adicionar vários filtros, somente os registros que corresponderem a todos os filtros serão mostrados porque um AND implícito é inserido entre filtros adjacentes. No entanto, é possível inserir explicitamente um operador OR:

    • Por exemplo, quando você adicionar os filtros Get e Compute, serão exibidas entradas de registro que contêm as duas palavras.

    • Por exemplo, quando você adiciona os filtros Get, OR e Compute, as entradas de registro que contêm Get ou Compute são exibidas.

    O valor do campo Filtro não é persistente.

  • Para aplicar um filtro permanente, modifique a consulta armazenada no campo Editor de consultas e selecione Aplicar filtro. Para informações sobre a sintaxe da consulta, veja a Linguagem de consulta do Logging.

    Por exemplo, para exibir somente essas entradas de registro com um campo MESSAGE cujo valor contém a string "lamp", adicione a cláusula jsonPayload.MESSAGE:"lamp" ao Editor de consultas.

Ver entradas de registro no Explorador de registros

Os widgets do painel de registros exibem os principais campos das entradas de registro, mas não exibem a entrada de registro completa. Para examinar todos os campos de uma entrada de registro, faça o seguinte:

  1. No widget do painel de registros, selecione Ver na Análise de registros.

  2. Na caixa de diálogo, selecione o projeto do Google Cloud em que o Explorador de registros será aberto.

    A Análise de registros é aberta em uma nova guia do navegador, e os filtros selecionados no widget do painel de registros são aplicados automaticamente.

  3. Selecione a entrada de registro que você quer ver.

Mostrar gráficos gerados com base em uma consulta da Análise de dados de registros

Nesta seção, descrevemos como configurar e salvar um gráfico gerado por uma consulta da Análise de dados de registros em um painel personalizado. A Análise de dados de registros permite pesquisar e agregar registros para gerar insights úteis usando consultas SQL.

Além de usar a página da Análise de dados de registros para configurar e salvar gráficos em um painel, é possível salvar um gráfico diretamente no Monitoring da seguinte maneira:

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Painéis:

    Acessar Painéis

  2. Selecione um painel ou clique em Criar painel.
  3. Na barra de ferramentas, clique em  Adicionar widget.
  4. Na caixa de diálogo Adicionar widget, acesse a seção Dados e selecione Análise de dados de registros.
  5. No painel Configurar widget, configure os dados para exibição no gráfico criando uma consulta usando SQL e, em seguida, clique em Executar consulta.

  6. Opcional: na guia Resultados, personalize a configuração do gráfico usando o painel Exibição.

    No painel Display, você pode mudar o tipo de gráfico e personalizar quais linhas e colunas são representadas nos gráficos. Para isso, altere a dimensão, a medida e o detalhamento:

    • Dimensão: a dimensão precisa ser uma coluna de carimbo de data/hora, numérica ou de string. Por padrão, a dimensão é definida como a primeira coluna com base em carimbo de data/hora no esquema. Se nenhum carimbo de data/hora estiver presente na consulta, a primeira coluna de string será selecionada como a dimensão. Também é possível personalizar a dimensão no painel Exibição de gráfico. Quando uma coluna de carimbo de data/hora é selecionada como a dimensão, o gráfico mostra as mudanças nos dados ao longo do tempo.

    • Medir: é possível selecionar várias medidas no painel Exibição de gráfico. Ao selecionar uma medida, você também precisa selecionar a função de agregação a ser executada nos valores agrupados, como count, sum, average e percentile-99. Por exemplo, count-distinct retorna o número de valores exclusivos em uma determinada coluna.

    • Detalhamento: para dividir uma única série de dados em várias com base em outra coluna, adicione um detalhamento.

    Para mais informações sobre como personalizar a configuração do gráfico, consulte Personalizar a configuração do gráfico.

  7. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Os gráficos da Análise de dados de registros também podem ser editados depois de salvos em um painel. Para saber mais, consulte Modificar a configuração de um widget.

Exibir erros em um painel

Nesta seção, descrevemos como adicionar e configurar um painel de Error Reporting usando o console do Google Cloud. Para saber como adicionar um painel de relatório de erros a um painel usando a API Cloud Monitoring, consulte Painel com um widget ErrorReportingPanel.

Para adicionar um painel de relatório de erros ao painel usando o console, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Painéis:

    Acessar Painéis

  2. Selecione um painel ou clique em Criar painel.
  3. Na barra de ferramentas, clique em  Adicionar widget.
  4. Na caixa de diálogo Adicionar widget, acesse a seção Visualização e selecione Painel do Error Reporting.
  5. Selecione o projeto com os grupos de erros mostrados, expanda Projetos e faça uma seleção.
  6. Opcional: atualize o título.

  7. Opcional: para restringir os recursos em que os erros são exibidos, faça o seguinte:

    1. abra Todos os recursos e selecione um recurso.

    2. Depois de selecionar um recurso, selecione Apply ou use os outros menus para refinar os critérios do filtro:

      • Para mostrar erros de recursos do App Engine, selecione Serviços do GAE e clique em Aplicar.

      • Para mostrar erros de um serviço específico do App Engine, selecione Serviços do GAE, escolha o serviço e clique em Aplicar.

  8. Para aplicar as mudanças ao painel, clique em Apply na barra de ferramentas. Para descartar as mudanças, clique em Cancelar.

    O exemplo a seguir mostra um painel de relatório de erros:

    Exemplo de um painel de configuração do painel de Error Reporting.

  9. Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Resolver problemas

A seguir