Logpoints de depuração

Após implantar ou iniciar o 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.

Acesse a página Depuração do Console do Google 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 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, como localmente ou em um repositório Git, por exemplo, será necessário selecionar o local do 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. Se você colocar um logpoint em uma linha que receba muito tráfego, o Debugger limitará o logpoint para reduzir o impacto no aplicativo.

Dica: o Google Cloud Shell dá acesso de linha de comando aos recursos de nuvem no navegador. É possível executar comandos logpoints do Cloud Shell sem precisar instalar a CLI gcloud.

Observação: os logpoints podem não estar disponíveis durante a inicialização, enquanto o depurador é inicializado em segundo plano.

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.

O texto a seguir é exibido quando o agente do Debugger é canário:

"Verificar o ponto de interrupção em um subconjunto de instâncias de aplicativos."

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.

Observação: um logpoint é feito apenas uma vez durante o tempo de execução do app. É possível refazer o logpoint manualmente para capturar um novo conjunto de dados.

Observação: logpoints podem não estar disponíveis durante a inicialização, enquanto o agente do Debugger é inicializado em segundo plano.

Como adicionar um logpoint de depuração

Console

Para adicionar um logpoint a partir do Console do Google Cloud:

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 da linha no local para adicionar um logpoint e selecione Criar logpoint.
4. Preencha a mensagem entre o campo logpoint("") e clique no botão "Adicionar". É possível colocar uma expressão entre colchetes, como {chars}, para registrar o valor.

Se nenhum código-fonte estiver disponível, será possível inserir manualmente o objetivo como filename:line e outros detalhes no painel Logpoint:

gcloud

Para adicionar um logpoint a partir da linha de comando:

gcloud debug logpoints create LOCATION MESSAGE

Em que:

• 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 a mensagem "Instrução de geração de registros adicionada" no nível de registro info (que é o nível de registro padrão para logpoints):

gcloud debug logpoints create main.py:28 \
  "Logging statement added"

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.

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

Java

A maioria das expressões Java é compatível, incluindo:

• 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:

• Unboxing de tipos numéricos, como Integer. Use myInteger.value.

Python

A maioria das expressões Python é compatível, incluindo:

• 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 é compatível, incluindo:

• 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
• Inserir conversões e literais compostos
• Chamadas de função diferentes de 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

Digite a condição na instrução 'if'

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 main.py:28 

  --condition="chars > 1" 

  --log-level="info" 

  "Logging statement added"

No exemplo acima, o logpoint verifica o comprimento de chars quando a linha 28 do aplicativo é executada. Se o valor for maior que 1, uma mensagem de nível info será adicionada ao registro.

Como visualizar a saída

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

App Engine

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

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

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. Depois disso, é possível ver os registros no Explorador de registros.

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. Selecione Menu e escolha Excluir logpoint.

gcloud

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

gcloud debug logpoints delete main.py:28

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

LOCATION                   CONDITION            LOG_LEVEL  LOG_MESSAGE_FORMAT                                             ID
main.py:28                                      INFO       Logging statement added.                                       53aaa3bd8d2d7-b76f-feb5d

Do you want to continue (Y/n)?  Y
Deleted 1 logpoint.