Mostrar registros e erros em um painel personalizado

Adicionar widgets de registro e erro a um painel personalizado no Cloud Monitoring permite correlacionar entradas de registro e erros de aplicativos com suas métricas de desempenho. É possível usar o widget do painel de registros para inspecionar entradas de registro individuais, o widget do painel do Error Reporting para rastrear grupos de erros recentes e um widget de gráfico da Análise de Observabilidade para visualizar tendências de consultas SQL.

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 dashboard não muda a forma 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 das métricas.

A Análise de registros e o widget do painel de registros são compatíveis com a mesma linguagem de consulta e exibem apenas as entradas de registro que você tem permissão para visualizar. Seus papéis do Identity and Access Management (IAM) nos recursos que armazenam as entradas de registro determinam se você pode ver as entradas armazenadas.

A Análise de registros e o widget do painel de registros são pré-configurados para pesquisar entradas de registro nos recursos listados no escopo do registro padrão. Se esse escopo não estiver acessível, elas vão pesquisar as entradas de registro que se originam no projeto selecionado. Quando um projeto é selecionado, os resultados da pesquisa incluem as entradas de registro que são roteadas para o projeto por um coletor em outro projeto e, em seguida, armazenadas em um bucket de registros. É possível configurar quais recursos são pesquisados para entradas de registro. Por exemplo, é possível pesquisar entradas de registro por visualização de registros.

Os widgets do painel de registros mostram uma entrada de registro por linha, com colunas para gravidade, carimbo de data/hora e um resumo da entrada de registro. Para ver a representação em formato JSON de uma entrada de registro, clique no botão Ver 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 mostra 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 mostra os resultados de uma solicitação e apenas uma frase que resume a ação realizada.

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 painel de registros a um painel personalizado usando o console do Google Cloud e configurá-lo para exibir entradas de registro em projetos ou em visualizações de registro, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

Mostrar entradas de registro em um painel

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

É possível colocar até 100 widgets em um painel.

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

  1. No console Google Cloud , acesse a página  Painéis:

    Acesse Painéis

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
  3. Selecione um painel ou clique em Criar painel.
  4. Na barra de ferramentas, clique em  Adicionar widget.
  5. Na caixa de diálogo Adicionar widget, selecione  Registros.
  6. Opcional: para atualizar o título, insira o novo título no campo Título do widget.

  7. Configure quais recursos são pesquisados para entradas de registro:

    • Para pesquisar por projeto, defina a entrada Escopo por como Projeto, expanda a entrada Projetos e conclua a caixa de diálogo.

      O menu Projetos lista todos os projetos Google Cloud no escopo de métricas atual. Se uma entrada no menu incluir o texto "Você não tem permissão para envolvidos no projeto para visualizar os registros neste projeto", significa que você não tem as permissões necessárias para visualizar as entradas de registro disponíveis nesse projeto do Google Cloud .

      As entradas de registro mostradas incluem aquelas que se originam no projeto doGoogle Cloud e as que são encaminhadas para o projeto doGoogle Cloud por um gravador em outro projeto.

    • Para pesquisar entradas de registro por visualizações de registro em buckets de registro, defina a entrada Escopo por como Armazenamento, expanda a entrada Visualizações de armazenamento e preencha a caixa de diálogo.

      O menu Visualizações de armazenamento lista as visualizações de registros em buckets de registros no projeto do Google Cloud selecionado.

      Para selecionar visualizações de registros em buckets de registros em outros projetos do Google Cloud , no menu, clique em Importar projeto, selecione um projeto e, em seguida, selecione uma ou mais visualizações de registros. Só é possível importar projetos que estão incluídos nas métricas de escopo atuais.

    • Para buscar os recursos incluídos em um escopo do registro, que pode incluir projetos e visualizações de registro, defina a entrada Escopo por como Escopo do registro e, em seguida, expanda a entrada Escopos do registro e selecione um escopo do registro.

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

    Uma consulta pode ter no máximo 2.000 caracteres.

  9. Opcional: atualize a consulta ou a configuração do widget para que dependa de variáveis. Quando você muda o valor da variável, o widget também é atualizado. Para sintaxe e outras informações, consulte Adicionar variáveis à consulta.

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

  11. Para salvar o dashboard modificado, clique em Salvar na barra de ferramentas.

    O widget do painel de registros mostra uma tabela de entradas de registro. Você também pode usar a barra de filtros do widget para mudar temporariamente as entradas de registro que ele mostra. 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. Você pode selecionar um tipo de recurso, como Recurso auditado, ou navegar pelos menus para escolher um método específico.

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

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

  3. Clique em Aplicar.

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

    resource.type="audited_resource"

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

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

  4. Clique em Aplicar.

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

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

Adicionar variáveis à consulta

É possível usar variáveis na consulta ou em outros campos no widget do painel de registros. Quando você muda o valor da variável, os dados mostrados pelo widget também mudam.

Para adicionar uma variável à consulta, faça o seguinte:

  1. Crie uma variável. No console do Google Cloud , use a opção Configurações de um painel para criar, editar e visualizar variáveis. Também é possível usar a API Cloud Monitoring.

  2. Para aplicar uma variável à sua consulta, use uma das seguintes formas:

    • Para variáveis baseadas em rótulos, use ${label_based_variable.value}.
    • Para variáveis com base em valor, use ${value_based_variable}.

    Por exemplo, suponha que você crie a variável somente valor value_only_severity_variable e a configure para ter um de três valores: ERROR, INFO e NOTICE. Você também adiciona a seguinte instrução à consulta:

    severity =~ "${value_only_severity_variable}"

    Veja a seguir o formulário renderizado:

    severity =~ "^(ERROR|INFO|NOTICE)$"

    Para mais informações sobre variáveis e como aplicá-las ao widget do painel de registros ou a outros widgets, consulte Atualizar a consulta de um widget.

Para saber como usar uma variável para mostrar ou ocultar um widget, consulte Definir a visibilidade de um widget.

Filtrar as entradas de registro

Para mudar quais entradas de registro um widget do painel de registros mostra, modifique os valores dos seguintes campos ou menus:

  • Seletor de tempo do painel: por padrão, o widget do painel de registros recupera apenas as entradas de registro gravadas no intervalo especificado por esse campo. Se você quiser um intervalo diferente, aplique um filtro que inclua uma cláusula timestamp. O widget do painel de registros não é compatível com uma substituição de período.

  • Campo Filtro no widget do painel de registros: o filtro especificado é aplicado depois que a consulta é concluída. O valor desse campo é retido 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 é retido 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 mostrados. Se você especificar uma consulta, o widget do painel de registros vai mostrar um ícone Mostrar consulta, que exibe a consulta atual como uma dica.

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

  • Google Cloud projeto 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 do filtro é aplicada à consulta do widget do painel de registros. Por exemplo, se você adicionar o filtro de painel cluster_name: mycluster, a consulta será atualizada para incluir resource.labels."cluster_name"="mycluster". Para mais informações sobre filtros de 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 mostrar os logs mais recentes em um widget de painel de logs, use os campos de tempo na barra de ferramentas do painel. Por exemplo, é possível definir o seletor de período da barra de ferramentas como 1H. Se você não selecionar um período personalizado, o widget sempre vai mostrar os registros mais recentes, mesmo que sejam mais antigos do que o período selecionado.

Ao investigar um alerta, talvez você queira restringir as entradas de registro a um intervalo de tempo específico. Para configurar as entradas de registro para mostrar apenas os registros em um intervalo de tempo fixo, faça uma ou ambas as ações a seguir:

  • Selecione um período usando o seletor de período.
  • 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

Ao depurar uma falha, talvez você queira ver apenas as mensagens de erro e ocultar todas as outras entradas de registro da tela. Para configurar um widget de painel de registros para mostrar apenas as entradas de registro que satisfazem níveis de gravidade específicos, faça uma ou ambas as ações a seguir:

  • Para aplicar um filtro temporário, selecione um valor no menu Gravidade do 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 uma string ou frase

Ao filtrar entradas de registro por uma string ou frase específica, é possível ocultar 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 teste de conteúdo não diferencia maiúsculas de minú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, você pode 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 na Análise de Registros

Os widgets do painel "Registros" mostram os campos principais das entradas de registro, não 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 você quer abrir a Análise de registros.

    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 uma consulta da Análise de observabilidade

Nesta seção, descrevemos como configurar e salvar um gráfico gerado de uma consulta da Análise de Observabilidade em um painel personalizado. Com a Análise de Observabilidade, é possível pesquisar e agregar registros para gerar insights úteis usando consultas SQL.

Além de usar a página da Análise de Observabilidade para configurar e salvar gráficos em um painel, você pode salvar um gráfico da Análise de Observabilidade diretamente no Monitoring fazendo o seguinte:

  1. No console Google Cloud , acesse a página  Painéis:

    Acesse Painéis

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
  3. Selecione um painel ou clique em Criar painel.
  4. Na barra de ferramentas, clique em  Adicionar widget.
  5. Na caixa de diálogo Adicionar widget, acesse a seção Dados e selecione Análise de Observabilidade.

  6. Na caixa de diálogo Configurar widget, configure os dados a serem exibidos e clique em Executar consulta.

    Para selecionar os dados que serão exibidos, crie uma consulta SQL ou selecione uma consulta salva ou recente. As visualizações de registro e as visualizações de análise que podem ser consultadas estão listadas na seção Visualizações e esquema. Ao clicar em uma fonte de dados, uma lista de campos dela aparece no cabeçalho Esquema.

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

    No painel Exibição, é possível mudar o tipo de gráfico e personalizar quais linhas e colunas são representadas, alterando a dimensão, a medida e o detalhamento:

    • 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 baseada em carimbo de data/hora no esquema. Se não houver um carimbo de data/hora 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 do gráfico. Quando uma coluna de carimbo de data/hora é selecionada como a dimensão, o gráfico mostra como os dados mudam ao longo do tempo. Quando uma coluna de string é selecionada como a dimensão de um gráfico de barras, é possível classificar os dados em ordem crescente ou decrescente, o que classifica a dimensão por ordem lexical. Também é possível manter a ordem de classificação "padrão", que classifica a dimensão com base nos valores da medida correspondente em ordem decrescente.

    • Medição: é possível selecionar várias medições no painel Exibição do gráfico. Ao selecionar uma métrica, você também precisa escolher a função de agregação a ser realizada 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 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.

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

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

Mostrar erros em um painel

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

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

  1. No console Google Cloud , acesse a página  Painéis:

    Acesse Painéis

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Na barra de ferramentas do console do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
  3. Selecione um painel ou clique em Criar painel.
  4. Na barra de ferramentas, clique em  Adicionar widget.
  5. Na caixa de diálogo Adicionar widget, acesse a seção Visualização e selecione Painel do Error Reporting.
  6. Expanda Projetos e selecione um projeto.
  7. Opcional: atualize o título.

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

    1. Expanda Todos os recursos e selecione um recurso.

    2. Depois de selecionar um recurso, clique em Aplicar ou use os outros menus para refinar os critérios de 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.

  9. Para aplicar as mudanças ao painel, clique em Aplicar 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 de relatórios de erros.

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

Resolver problemas

A seguir