Logpoints de depuração

Depois de implantar ou iniciar seu aplicativo, é possível abrir o Cloud Debugger no Console do Google Cloud. O Cloud Debugger permite injetar registros em serviços em execução sem reiniciar ou interferir na função normal do serviço. Isso pode ser útil para depurar problemas de produção sem a necessidade de adicionar log statements e fazer uma nova implantação.

Visite a página Depurar do Console do Cloud para usar o Google Cloud Debugger.

Antes de começar

O Cloud Debugger pode ser usado com ou sem acesso ao código-fonte do aplicativo. Se o código-fonte não estiver disponível, consulte a seção Como adicionar um logpoint de depuração abaixo para instruções sobre a inserção manual do nome de arquivo e do número de linha.

Se seu código-fonte estiver armazenado no Google Cloud Repositories, ele é automaticamente exibido na visualização de depuração.

Para acessar o código-fonte armazenado em outro local, por exemplo, localmente ou em um repositório git, será necessário selecionar um local de código-fonte.

Logpoints

Com os logpoints, você pode inserir a geração de registros em serviços em execução sem precisar reiniciar e sem interferir no funcionamento do serviço. Toda vez que uma instância executa o código no local do logpoint, o Cloud Debugger registra uma mensagem. A saída é enviada ao registro específico do ambiente de destino. No App Engine, por exemplo, a saída é enviada para o registro de solicitação no Cloud Logging.

Os logpoints permanecem ativos por 24 horas após serem criados ou até que sejam excluídos ou que o serviço seja reimplantado.

Agente do Debugger com configurações de canary

Depois de definir um logpoint, o agente do Debugger o testa em um subconjunto das instâncias. Depois que o agente do Debugger verifica se o logpoint pode ser executado com sucesso, ele é aplicado a todas as instâncias. Isso leva cerca de 40 segundos.

Após esse processo, quando o logpoint for acionado, o agente do Debugger registrará a mensagem. Se o logpoint for acionado dentro de 40 segundos após a configuração, o agente do Debugger registrará a mensagem das instâncias em que o logpoint de canary foi aplicado.

O agente do Debugger implementa várias estratégias para minimizar a quantidade de latência causada ao capturar os dados.

Você verá o seguinte enquanto o agente do Debugger estiver sendo configurado com canary:

O agente do Debugger está realizando a configuração de canary das instâncias

Para saber o que fazer se o agente do Debugger falhar no modo canary, acesse a Seção de solução de problemas na página de snapshots de depuração.

Para saber quais versões do agente do Debugger têm a funcionalidade de canary, consulte as páginas específicas de cada idioma.

Agente do Debugger sem configuração de canary

Quando você usa o agente do Debugger sem configuração de canary e define um logpoint, ele se aplica a todas as instâncias em execução do apo. Na primeira vez que qualquer instância executa o código no local do logpoint, o agente do Debugger registra a mensagem. O agente do Debugger implementa várias estratégias para minimizar a quantidade de latência causada ao capturar os dados.

Como adicionar um logpoint de depuração

Console

Para adicionar um logpoint a partir do Console do Cloud, siga estas etapas:

  1. Verifique se a guia Logpoint está selecionada no painel à direita.
  2. No painel à esquerda, selecione o arquivo que contém o código-fonte a que você quer adicionar um logpoint. O conteúdo do arquivo será exibido no painel central.
  3. Clique no número de linha no local para adicionar um logpoint.
  4. Preencha a mensagem entre o campo logpoint("") e clique no botão "Adicionar". É possível colocar uma expressão entre colchetes, como {newScore.score}, para registrar o valor.

Como adicionar o logpoint in-line


Se nenhum código-fonte estiver disponível, será possível inserir manualmente "filename:line" e outros detalhes no painel Logpoint: Como adicionar um logpoint manualmente

gcloud

Para adicionar um logpoint a partir da linha de comando:

gcloud debug logpoints create LOCATION MESSAGE

Onde:

  • LOCATION é o nome do arquivo e a linha em que foi definido o logpoint. O formato é FILE:LINE, em que FILE pode ser apenas o nome do arquivo ou o nome do arquivo precedido por componentes de caminho suficientes para diferenciá-lo de outros arquivos com o mesmo nome. Forneça um nome de arquivo exclusivo no destino de depuração;
  • MESSAGE é a mensagem que você quer registrar.

O exemplo a seguir registra o valor de score no nível de registro info (que é o padrão para logpoints):

gcloud debug logpoints create HighScoreService.java:105 \
  "User {name} scored {newScore.score}"

Quando a linha 105 de HighScoreService.java executes for executada, a mensagem será registrada com os valores das variáveis name e newScore.score inseridos na string de saída.

Formato da mensagem do logpoint

A mensagem de um logpoint determina o que é registrado na saída. As expressões permitem que você avalie e registre valores de interesse. Qualquer item na mensagem entre chaves, como {myObj.myFunc()} ou {a + b}, será substituído pelo valor dessa expressão na saída. A mensagem User {name} scored {newScore.score} no exemplo acima registrará uma saída semelhante a User user1 scored 99.

É possível usar os seguintes recursos de idioma para as expressões:

Java

A maioria das expressões em Java é compatível, incluindo estas:
  • Variáveis locais: a == 8.
  • Operações numéricas e booleanas: x + y < 20.
  • Campos estáticos e de instância: this.counter == 20, this.myObj.isShutdown, myStatic ou com.mycompany.MyClass.staticMember.
  • Comparações de strings com o operador de igualdade: myString == "abc".
  • Chamadas de funções. Apenas as funções somente leitura podem ser usadas. Por exemplo, StringBuilder.indexOf() é suportado, mas StringBuilder.append() não é.
  • Transmissão de tipo, com tipos totalmente qualificados: ((com.myprod.ClassImpl) myInterface).internalField.

O seguinte recurso de linguagem não é compatível:

  • Conversão unboxing de tipos numéricos, como Integer. Use myInteger.value em vez disso.

Python

A maioria das expressões em Python é compatível, inclusive estas:
  • Leitura de variáveis locais e globais
  • Leitura de matrizes, listas, conjuntos, dicionários e objetos
  • Execução de métodos simples

Os seguintes recursos de linguagem não são compatíveis:

  • Execução de funções que alocam novos objetos ou usam executores complexos
  • Criação de novos objetos dentro da expressão

Go

A maioria das sintaxes de expressão em Go (em inglês) é compatível, incluindo estas:
  • Leitura de variáveis locais e globais
  • Leitura de matrizes, conjuntos, mapas e structs

Os seguintes recursos de linguagem não são compatíveis:

  • Leitura a partir de valores da interface
  • Conversões de tipo e literais compostos
  • Chamadas de função que não sejam len

Condição de logpoint

Uma condição de logpoint é uma expressão simples na linguagem do aplicativo que precisa ser avaliada como verdadeira para que o logpoint seja registrado. As condições do logpoint são avaliadas cada vez que a linha é executada, por qualquer instância, até que o logpoint expire ou seja excluído.

A condição é uma expressão booleana completa que pode incluir operadores lógicos:

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

Os mesmos recursos de linguagem compatíveis com as expressões estão disponíveis para as condições.

Console

Insira a condição na instrução "if":

Definir uma condição in-line

Se nenhum código-fonte estiver disponível, será possível especificar a condição no painel Logpoint.

gcloud

As condições são expressas usando a sinalização --condition de logpoints create:

gcloud debug logpoints create HighScoreService.java:105 
--condition="newScore.score > 40"
--log-level="warning"
"Suspiciously high score ({newScore.score}) from user {name}"

No exemplo acima, o logpoint verifica o valor de newScore.score quando a linha 105 do aplicativo é executada. Se o valor for maior que 40, um aviso é adicionado ao registro.

Como visualizar a saída

A saída do logpoint é enviada ao registro específico do ambiente de destino.

App Engine

Os logpoints definidos nos aplicativos do App Engine enviam a saída para o log da solicitação no Cloud Logging.

É possível visualizar os registros no painel "Registros" ou no Visualizador de registros dedicado.

Logpoint no painel de registros

Compute Engine

Os logpoints definidos nos apps do Compute Engine enviam a saída para o mesmo local dos log statements comuns. Por exemplo, em Python, o módulo de geração de registros padrão envia a própria saída para stdout, mas pode ser configurado para gravar em um arquivo específico.

É possível configurar o agente de geração de registros para encaminhar esses registros para o Cloud Logging. A partir de então, é possível ver os registros no visualizador de registros.

Como excluir logpoints

Os logpoints ficam inativos, param de registrar mensagens após 24 horas e são excluídos automaticamente após 30 dias. É possível excluir manualmente os logpoints, que interromperão a geração de registros e os removerão do histórico para que não sejam usados para referência futura. No entanto, a exclusão de um logpoint não excluirá as mensagens de registro geradas anteriormente.

Console

Para excluir um logpoint manualmente, use o menu flutuante no painel Histórico de logpoint.

Como excluir um logpoint

gcloud

Para excluir um logpoint manualmente, especifique o ID dele ou use expressões regulares no local do código:

gcloud debug logpoints delete HighScoreService.java:105

Debug target not specified. Using default target: default-1
This command will delete the following logpoints:

LOCATION                   CONDITION            LOG_LEVEL  LOG_MESSAGE_FORMAT                                             ID
HighScoreService.java:105                       INFO       User {name} scored {newScore.score}.                           53aaa3bd8d2d7-b76f-feb5d
HighScoreService.java:105  newScore.score > 40  WARNING    Suspiciously high score ({newScore.score}) from user {name}  53aaa3bsdffd7-b56f-fasfg

Do you want to continue (Y/n)?  Y
Deleted 2 logpoints.