Depurar snapshot

Depois de implantar ou iniciar seu aplicativo, é 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 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.

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 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.

Capturar um snapshot de depuração

Console

Clique no número da linha do código-fonte para capturar um instantâneo no local.

  1. Verifique se o painel Instantâneo está selecionado no painel à direita.
  2. No painel à esquerda, selecione o arquivo que contém o código-fonte a ser analisado. 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.

Navegar para o local de um snapshot

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

Definir o local de um snapshot manualmente

gcloud

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

gcloud debug snapshots create LOCATION

Onde:

  • 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, insira-a no campo Condição do painel Snapshot.

Definir uma condição de snapshot

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

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. Pressione a tecla de espaço para adicionar mais expressões.
  2. Pressione a tecla "Enter" ou o botão Snapshot Botão de snapshot.

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

Definir uma expressão

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.

Visualizar snapshot

É 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 instantâneo tiverem sido definidos em um arquivo, ou se você quiser ver os instantâneos capturados, expanda o painel Histórico de instantâneos:

gcloud

Para recuperar o URL do Console do Cloud para um snapshot a partir da linha de comando, use este 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 seu navegador para visualizar o snapshot no Console do 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 capturar um snapshot novamente, clique no ícone de câmera na parte superior direita do painel Snapshot:

Botão de snapshot

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:

Snapshots anteriores no marcador da 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

Para remover um local de snapshot, clique no "X" no marcador.

Ícone do snapshot

gcloud

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

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

Onde:

  • 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

É possível compartilhar um snapshot com outro membro do projeto. Basta copiar o URL de snapshot exibido no navegador ou na saída do comando gcloud debug snapshots list e informá-lo a outro usuário que tenha acesso ao projeto. Também é possível salvar esse URL para referências futuras e depois retornar para consultar 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.

Resolver problemas

O agente do Debugger travou minhas instâncias?

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

O painel

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.