Depurar snapshot

Depois de implantar ou iniciar o app, é possível abrir o Cloud Debugger no Console do Google Cloud. Com o Debugger, você coleta e inspeciona a pilha de chamadas e as variáveis locais no seu app sem interrompê-lo ou desacelerá-lo.

Acesse a página Depuração do Console do Google Cloud para usar o Debugger.

Antes de começar

O Debugger pode ser usado com ou sem acesso ao código-fonte do seu app. Se o código-fonte não estiver disponível, consulte a seção Coletar um snapshot de depuração abaixo para ver instruções sobre como inserir manualmente o nome de arquivo e o número de linha.

Para acessar o código-fonte armazenado localmente ou em um repositório Git, talvez seja necessário selecionar um local do código-fonte.

Snapshots

Os snapshots capturam variáveis locais e a pilha de chamadas em um local de linha específico no código-fonte do seu app. É possível especificar condições e locais para retornar um snapshot dos dados do aplicativo e vê-lo em detalhes para depurar o app.

Agente do Debugger com configurações de canary

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

Após esse processo, quando o snapshot for acionado, os resultados aparecerão nos painéis Variáveis e Pilha de chamadas. Se o snapshot for acionado dentro de 40 segundos após a configuração, você verá os resultados dessas instâncias em que o snapshot do 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 snapshot, ele se aplica a todas as instâncias em execução do app. Na primeira vez que qualquer instância executa o código no local do snapshot, o agente do Debugger captura um snapshot e o disponibiliza para visualização. O agente do Debugger implementa várias estratégias para minimizar a quantidade de latência causada ao capturar os dados.

Observação: um snapshot é capturado somente uma vez durante o ambiente de execução do app. É possível realizar uma nova captura manual do snapshot para coletar um novo conjunto de dados.

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

Capturar um snapshot de depuração

Console

Clique no número de linha do código-fonte para capturar um snapshot no local.

1. Verifique se o painel Snapshot está selecionado.
2. Selecione o arquivo que contém o código-fonte. O conteúdo do arquivo selecionado é exibido no painel central.

3. Clique no número de linha em que está o local do código-fonte.

   

É possível clicar em várias linhas para definir mais de um local de snapshot em um arquivo.

Consulte a seção Opções de código-fonte para outras formas de carregar seu código-fonte no Debugger.

Se nenhum código-fonte estiver disponível, é possível inserir manualmente o "filename:line" para capturar um snapshot no painel Snapshot:

gcloud

Para definir um local do instantâneo a partir da linha de comando:

gcloud debug snapshots create LOCATION

Em que:

• LOCATION é o nome do arquivo e a linha em que o snapshot será definido. O formato é FILE:LINE, em que FILE pode ser o nome do arquivo ou o nome do arquivo precedido de componentes de caminho suficientes para diferenciar o arquivo de outros arquivos com o mesmo nome. Forneça um nome de arquivo exclusivo no destino de depuração.

Condições do instantâneo (opcional)

Uma condição do instantâneo nada mais é do que uma expressão na linguagem do app (Java, Python e Go são compatíveis) que precisa ser avaliada como verdadeira para que o instantâneo seja capturado. As condições do instantâneo são avaliadas cada vez que a linha é executada, por qualquer instância, até que a condição seja avaliada como verdadeira ou até que o instantâneo expire.

O uso de condições do instantâneo é opcional.

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

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

Console

Para especificar a condição, crie um snapshot. No campo Condição, insira uma condição e selecione Atualizar. Se a condição for avaliada como verdadeira, o snapshot será acionado.

gcloud

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

gcloud debug snapshots create LOCATION --condition="ultimateAnswer <= 42 && foo==bar"

É possível usar os recursos de linguagem a seguir para expressar condiçõ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

Expressões (opcional)

O recurso Expressões do Debugger permite que você avalie expressões complexas ou percorra hierarquias de objetos quando um snapshot for capturado. As expressões são compatíveis com os mesmos recursos de linguagem das condições do snapshot descritas anteriormente.

O uso de expressões é opcional.

Usos comuns das expressões incluem:

• Visualizar variáveis estáticas ou globais que não são parte do conjunto de variáveis locais.
• Visualizar facilmente variáveis de membros profundamente aninhadas sem precisar expandir uma variável local no painel do Debugger toda vez.
• Evitar cálculos matemáticos repetitivos. Por exemplo, calcular uma duração em segundos com (endTimeMillis - startTimeMillis) / 1000.0.

Como adicionar uma expressão:

Console

1. Insira a expressão no campo Expressão. Você pode adicionar quantas expressões forem necessárias.
2. Selecione Refazer.

O resultado da expressão é mostrado quando o snapshot é capturado.

gcloud

As expressões são definidas usando a sinalização --expression de snapshots create:

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

Ver um instantâneo

Console

Os dados de snapshot são exibidos no Debugger quando o app executa o código-fonte no local especificado. Já as variáveis de instância e de local são exibidas na seção Variáveis do painel, enquanto o rastreamento de pilha é exibido na seção Pilha de chamadas.

É possível examinar o valor das variáveis locais no momento em que o snapshot foi capturado e detalhar estruturas de dados mais profundas. Também é possível clicar em qualquer frame de pilha de chamada e analisar as variáveis locais naquele nível da pilha.

Se vários locais de snapshot tiverem sido definidos em um arquivo, ou se você quiser ver os snapshot capturados, expanda o painel Histórico de snapshot:

gcloud

Para recuperar o URL do console do Google Cloud para um snapshot a partir da linha de comando:

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE  HighScoreService.java:105                             53bd97d4-b6c6-74fc  https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

Copie e cole o valor da coluna VIEW no navegador para visualizar o snapshot no Console do Google Cloud.

Para ver os dados detalhados do snapshot a partir da linha de comando, use este comando:

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

O comando describe retorna valores de rastreamento de pilha e de variáveis locais. Além disso, ele tem como principal objetivo ser legível por máquina, em vez de legível por pessoas.

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

Recapturar snapshot

Um instantâneo só é capturado uma vez. Se você quiser capturar outro instantâneo dos dados do app no mesmo local, faça isso manualmente.

Console

Para refazer um snapshot, selecione Refazer:

O novo snapshot é adicionado ao painel Histórico de snapshots. Os snapshots anteriores daquela linha podem ser acessados no Histórico de snapshots ou no marcador do número de linha:

gcloud

Para capturar um snapshot a partir da linha de comando, repita o comando create que você usou antes:

gcloud debug snapshots create LOCATION

Remover um local de snapshot

Console

Remova um local de snapshot clicando em Excluir .

gcloud

Para excluir um instantâneo a partir da linha de comando:

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

Em que:

• ID é o valor retornado por gcloud debug snapshots list;

• LOCATION-REGEXP é uma expressão regular que define o local de código do(s) snapshot(s).

Compartilhar snapshots

Para compartilhar um snapshot, copie o URL do snapshot do navegador ou da saída do comando gcloud debug snapshots list e conceda-o a outro usuário que tenha acesso. seu projeto. Também é possível salvar esse URL para referências futuras e para consultá-lo novamente para ver os resultados. O Debugger usa um novo URL para cada snapshot capturado. Isso permite compartilhar diferentes conjuntos de resultados, ainda que sejam capturados no mesmo local no código. O compartilhamento expira 30 dias após a captura do snapshot.

Solução de problemas

O agente do Debugger travou minhas instâncias?

Talvez você veja o seguinte erro se o agente do Debugger apresentar uma falha:

Você pode receber falsos positivos que fazem parecer que o agente do Debugger acionou suas salvaguardas pelos seguintes motivos:

• Uma instância foi encerrada enquanto o agente do Debugger estava sendo configurado com canary.

  Quando uma instância que tem um snapshot de canary aplicado é encerrada, ela exibida como se o agente do Debugger a encerrasse. Verifique se nenhuma instância foi encerrada dentro de 40 segundos após a definição do snapshot. Por exemplo, o escalonamento automático do Cloud Run e do App Engine ou a implantação de novos códigos podem ser motivos para o encerramento das instâncias.

Remova o agente do Debugger das instâncias e reinstale a versão anterior. Para reinstalar a versão anterior, siga as instruções de configuração para instalar a versão anterior do agente do Debugger.

Se o problema persistir com a versão antiga do agente, verifique se ele não é um falso positivo, desative o agente do Debugger e envie feedback.