Mostrar registros e erros em um painel personalizado

Neste documento, descrevemos como exibir dados de registro e dados de erros em painéis personalizados.

Para exibir dados de registro, adicione os seguintes widgets ao seu painel:

Para exibir as entradas de registro mais recentes no seu projeto atual do Google Cloud, adicione um widget de painel de registros. Também é possível configurar o painel de registros para exibir entradas de registro armazenadas em projetos do Google Cloud acessíveis por meio do escopo de métricas atual.
Para identificar padrões e tendências nos dados de registro, adicione um widget de gráfico da Análise de dados de registros, que exibe os resultados de uma consulta SQL.

Para exibir grupos de erros, adicione um painel de relatório de erros. O painel de relatório de erros exibe os grupos de erros mais recentes de um único projeto do Google Cloud.

Ao adicionar um painel de registros e um de relatório de erros a um painel personalizado, é possível ver registros e erros no mesmo contexto que as métricas. Como o painel de registros permite filtrar as entradas de registro, é possível configurá-lo para exibir apenas as entradas de registro do seu interesse. Da mesma forma, o painel de relatório de erros permite identificar erros e solucionar a causa da falha.

Explorador de registros e painéis de registros

O Explorador de registros é a maneira padrão de investigar registros. Os painéis de registros não substituem o Explorador de registros. Em vez disso, eles fornecem uma maneira de visualizar as entradas de registro no mesmo contexto das métricas.

Os painéis de registros exibem entradas de registro em linhas 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 no 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.

Os painéis de registros são pré-configurados para mostrar entradas de registro armazenadas no seu projeto atual do Google Cloud. No entanto, é possível configurar um painel de registros para mostrar as entradas de registro armazenadas em qualquer projeto no escopo das métricas atuais.

Os painéis de registros são compatíveis com a mesma linguagem de consulta que o Explorador de registros.

Os painéis de registros não são compatíveis com visualizações de armazenamento. Quando os registros estiverem disponíveis apenas por meio de uma visualização de armazenamento, use a Análise de registros. Para mais informações sobre visualizações de armazenamento, consulte Refinar o escopo.

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

Antes de começar

Para receber as permissões necessárias para adicionar um widget de registros a um painel personalizado usando o console do Google Cloud, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:
- Editor do Monitoring (roles/monitoring.editor)
- Leitor do Logging (roles/logging.viewer) em cada projeto com entradas de registro que você quer ver. Os painéis não exibem entradas de registro de projetos em que você não tem permissões para exibir registros. Para mais informações sobre os papéis necessários para visualizar entradas de registro, consulte Controle de acesso do Cloud Logging com o 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.
É possível incluir até 40 widgets no painel.

Painel "Adicionar e configurar registros"

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

Adicionar um painel de registros

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

No painel de navegação do console do Google Cloud, selecione Monitoramento e Painéis:
Acessar Painéis
Selecione um painel ou clique em Criar painel.
Na barra de ferramentas, clique em Adicionar widget.
Na caixa de diálogo Adicionar widget, selecione Registros.
Opcional: atualize a configuração padrão:
1. Adicione um título.
2. Para exibir registros de vários projetos do Google Cloud em vez de apenas do projeto atual, clique em Projetos e faça as seleções.
3. Para restringir quais registros o painel de registros exibe, insira uma consulta no campo Editor de consultas.
Para mais informações sobre as etapas anteriores, consulte Configurar um painel de registros:
Para aplicar as mudanças ao painel, clique em Apply na barra de ferramentas. Para descartar as mudanças, clique em Cancelar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Por padrão, o painel de registros exibe uma tabela de entradas de registro. Use o menu Gravidade e as configurações da barra de filtro para alterar temporariamente quais registros são exibidos. Também é possível modificar o tamanho e a posição do painel com o ponteiro.

Configurar um painel de registros

Os painéis de registros são pré-configurados para exibir todas as entradas de registro armazenadas no projeto atual do Google Cloud. No entanto, talvez você tenha interesse apenas em entradas de registro que indiquem algum tipo de condição de erro ou queira visualizar registros de vários projetos. Esta seção descreve como modificar a configuração padrão de um painel de registros.

Para configurar o título, a lista de projetos cujos registros são mostrados ou para inserir uma consulta, faça o seguinte:

Posicione o ponteiro no painel de registros para ativar a barra de ferramentas e selecione Edit widget.

A captura de tela abaixo é um exemplo do painel de configuração:

$Exemplo de um painel de configuração do painel de registros.$
Opcional: adicione um título, que é mostrado no painel de registros.
Opcional: para exibir registros de vários projetos do Google Cloud, clique em Projetos e faça as seleções.

Por padrão, apenas as entradas de registro do projeto atual do Google Cloud são exibidas. No entanto, um painel de registros pode exibir registros de qualquer projeto do Google Cloud acessível por meio do escopo de métricas atual.

Quando você não tiver permissão para conferir os registros de um projeto do Google Cloud, o menu Projetos vai mostrar a mensagem "Você não tem permissão para conferir os registros neste projeto". Para resolver o erro de permissão, entre em contato com o administrador do sistema e peça a ele que conceda a você o papel de visualizador de registros (roles/logging.viewer) no projeto.
Opcional: para restringir os registros que o painel de registros exibe, insira uma consulta no campo Editor de consultas.

Se você desativou a execução automática de consultas, clique em Executar consulta depois de inseri-la.

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 Resource ativa menus adicionais e um botão Adicionar depois que você seleciona um recurso individual. Nesse menu, você pode selecionar um tipo de recurso, um serviço para um tipo de recurso específico ou um método para um tipo de recurso. Por exemplo, para adicionar uma cláusula para o tipo de recurso auditado, selecione Recurso auditado e, em seguida, selecione Adicionar. Estas etapas adicionam a seguinte cláusula ao campo Editor de consultas:
```
 resource.type="audited_resource"
```
Da mesma forma, para adicionar uma cláusula para um serviço específico que é auditado, selecione Recurso auditado, selecione o serviço no menu Todos os serviços e, em seguida, selecione Adicionar. Veja a seguir um exemplo de cláusula criada usando esta abordagem:
```
 resource.type="audited_resource" resource.labels.service="bigquery.googleapis.com"
```
Opcional: aplique variáveis de modelo ao painel de registros. Para mais informações, consulte Adicionar filtros temporários a um painel personalizado e Aplicar um filtro permanente a um widget.
Para aplicar as mudanças ao painel, clique em Apply na barra de ferramentas. Para descartar as mudanças, clique em Cancelar.
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Filtrar as entradas de registro

Você pode modificar quais entradas de registro um painel de registros exibe. Para isso, modifique os valores dos seguintes campos ou menus:

Seletor de tempo do painel: a consulta apenas recupera entradas de registro gravadas no intervalo especificado por esse campo.
Filtro no 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 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 especificada pelo painel de registros: o campo de consulta determina quais registros são recuperados. Se você não especificar uma consulta, todos os registros no intervalo de tempo selecionado serão recuperados. Se você especificar uma consulta, o painel de registros exibirá um ícone Mostrar consulta, que exibe a consulta atual como uma dica.

Para modificar a consulta, siga um destes procedimentos:
- Para alterar permanentemente a consulta, edite o painel de registros.
- Para alterar temporariamente a consulta, use a barra de ferramentas do painel para adicionar um filtro a um rótulo de recurso. Por exemplo, se você adicionar o filtro de todo o painel cluster_name: mycluster, a consulta será atualizada para incluir resource.labels."cluster_name"="mycluster". Para mais informações, consulte Adicionar filtros temporários e Adicionar filtros permanentes.
Projeto do Google Cloud especificado pelo painel de registros: para modificar esta configuração, edite o painel de registros.

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

Filtrar entradas de registro por data

Para exibir os registros mais recentes em um 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 painel de registros 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 painel de registros não é atualizado automaticamente.

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 painel de registros para exibir somente as entradas que atendem a níveis de gravidade específicos, siga um destes procedimentos ou ambos:

Para aplicar um filtro temporário, selecione um valor para o menu Gravidade no 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.

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.

Exemplos de configurações

Veja alguns exemplos de configuração:

Para ver os registros mais recentes, defina a barra de ferramentas do painel como 1H, deixe o campo Editor de consultas vazio e deixe os campos do painel de registros como padrão.
Para exibir temporariamente apenas registros com um nível de gravidade de pelo menos "Aviso", selecione Aviso no menu Gravidade do painel de registros.

O valor do menu Gravidade do painel de registros é redefinido para Padrão quando você atualiza a página ou sai do painel.
Para configurar o painel de registros para mostrar apenas os registros com nível de gravidade "Aviso", adicione a cláusula severity=WARNING no campo Editor de consultas.

A consulta armazenada no campo Editor de consultas é salva. Mesmo ao atualizar a página ou atualizar o painel, o painel de registros só mostra os registros que correspondem ao nível de aviso especificado.
Para configurar o painel de registros a fim de mostrar somente os registros de instâncias do Compute Engine, adicione a cláusula resource.type="gce_instance" no campo Editor de consultas .

A mensagem "Nenhuma entrada encontrada correspondente ao filtro atual" é exibida quando nenhuma entrada de registro satisfaz às configurações atuais. Quando você configura uma consulta no campo Editor de consultas e também define os filtros do painel de registros, é possível que as configurações entrem em conflito. Para mais informações, consulte O painel de registros exibe a mensagem "Nenhuma entrada encontrada".

Ver entradas de registro no Explorador de registros

Os painéis de registros exibem campos de entradas de registro. Eles não exibem a entrada de registro completa. Para examinar todos os campos de uma entrada de registro, faça o seguinte:

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

O Explorador de registros é aberto em uma nova guia do navegador, e os filtros que você selecionou no painel de registros são aplicados automaticamente.
Selecione a entrada de registro que você quer ver.

Adicionar gráficos gerados a partir de 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:

No painel de navegação do console do Google Cloud, selecione Monitoramento e Painéis:
Acessar Painéis
Selecione um painel ou clique em Criar painel.
Na barra de ferramentas, clique em Adicionar widget.
Na caixa de diálogo Adicionar widget, acesse a seção Dados e selecione Análise de dados de registros.
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.
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.
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.

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:

No painel de navegação do console do Google Cloud, selecione Monitoramento e Painéis:
Acessar Painéis
Selecione um painel ou clique em Criar painel.
Na barra de ferramentas, clique em Adicionar widget.
Na caixa de diálogo Adicionar widget, acesse a seção Visualização e selecione Painel do Error Reporting.
Selecione o projeto com os grupos de erros mostrados, clique em Projetos e faça uma seleção.
Opcional: atualize o título.
Opcional: para restringir os recursos em que os erros são exibidos, faça o seguinte:
1. Clique em 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.
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.$
Para salvar o painel modificado, clique em Salvar na barra de ferramentas.

Resolver problemas

A seguir

Para informações sobre como o Cloud Monitoring fornece visibilidade para métricas e registros armazenados em vários projetos do Google Cloud, consulte Visão geral do escopo de métricas.
Para informações sobre como configurar um painel de registros usando a API Cloud Monitoring, consulte Painel com um widget LogsPanel.
Para saber mais sobre os grupos de erros, consulte a Visão geral do Error Reporting.