Visão geral
Nesta página, você aprende como configurar seu ambiente e seu aplicativo Java para usar o Cloud Debugger.
Para alguns ambientes, é necessário especificar explicitamente o escopo de acesso para que o agente do Cloud Debugger envie dados.
Recomendamos definir o escopo de acesso da forma mais ampla possível e depois usar o Gerenciador de identidade e acesso para restringir o acesso.
Para manter essa prática recomendada, configure o escopo de acesso para todas as APIs do Cloud com a opção cloud-platform
.
Versões de linguagem e ambientes de computação
O Cloud Debugger está disponível para as versões Java 7, 8, 9 e 11 nos seguintes ambientes de computação:
Ambiente padrão do App Engine | Ambiente flexível do App Engine | Compute Engine | Google Kubernetes Engine | Cloud Run | Cloud Run for Anthos | VMs e contêineres em execução em outra plataforma | Cloud Functions |
---|---|---|---|---|---|---|---|
Como configurar o Cloud Debugger
Para configurar o Cloud Debugger, conclua as seguintes tarefas:
Verifique se a API Cloud Debugger está ativada no projeto.
Instale e configure o Debugger no ambiente de computação que você está usando.
Selecione o código-fonte.
Como verificar se a API Cloud Debugger está ativada
Para começar a usar o Cloud Debugger, verifique se a API Cloud Debugger está ativada. O Cloud Debugger é ativado por padrão na maioria dos projetos.Ativar a API Cloud Debugger
Snapshots e logpoints do canary
Para evitar que snapshots e logpoints sejam carregados em todas as instâncias em execução ao mesmo tempo e possivelmente fazer com que o job seja removido devido a um possível bug no agente do Debugger, ative o modo canário para o Agente do Debugger. Quando o modo canário estiver ativado, um snapshot ou logpoint será aplicado a um subconjunto de instâncias em execução. Já o Debugger verifica se o snapshot ou o logpoint não afetam negativamente essas instâncias. Após a conclusão da verificação, o snapshot ou logpoint será aplicado a todas as instâncias.
Para saber como usar o Debugger no modo canário, acesse as páginas Snapshots do Debug e Logpoints do Debug.
Como ativar snapshots e logpoints de canary
Ao instalar a versão mais recente do agente do Debugger, você tem a opção de ativar ou desativar a configuração de um canary. A configuração de um canary está desativada por padrão.
Quando ativar snapshots e logpoints de canary
Para proteger cargas de trabalho essenciais de implantação e produção, ative a configuração de canário ao depurar dessas cargas de trabalho
Se você tiver uma única instância, ainda será possível depurar com a configuração de canary ativada, mas a única instância será executada sem a configuração de canary para o snapshot ou logpoint.
Quando não ativar snapshots e logpoints de canary
Não ative a configuração de canary em cargas de trabalho com tempo de execução inferior a 40 segundos, por exemplo, jobs que usam o Cloud Functions.
Não ative a configuração de canary se quiser um ciclo de acionamento de snapshots mais rápido.
Para configurar o agente do Debugger para não realizar a configuração de canary em snapshots e logpoints, acesse as instruções de instalação do Google Cloud Platform que você está usando.
Ambiente padrão do App Engine
O depurador é ativado por padrão. Nenhuma configuração é necessária. A página Debug no console tentará exibir os arquivos de origem Java usados para criar o app.
O console não funcionará se a Busca de URL estiver ativada.
Para saber mais, consulte Como selecionar o código-fonte automaticamente.
Ambiente flexível do App Engine
O Debugger fica ativado por padrão durante o tempo de execução do Java. Não é necessário configurar. A página Debug no console tentará exibir os arquivos de origem Java usados para criar o app.
O debugger é incluído por padrão para aos tempos de execução personalizados que usam as imagens de base para Java fornecidas pelo Google. Nenhuma configuração será necessária se o ponto de entrada padrão for usado. A página Debug no console tentará exibir os arquivos de origem Java usados para criar o app.
Para usar o Cloud Debugger com tempos de execução personalizados criados usando outras imagens de base, siga as instruções de configuração do Compute Engine.
Para saber mais, consulte Como selecionar o código-fonte automaticamente.
Google Kubernetes Engine
GCLOUD
Para ativar o Debugger usando a gcloud
, conclua as etapas abaixo:
Crie seu cluster com um destes escopos de acesso:
https://www.googleapis.com/auth/cloud-platform
concede ao cluster acesso a todas as APIs do Google Cloud.https://www.googleapis.com/auth/cloud_debugger
concede ao cluster acesso apenas à API Stackdriver Debugger. Use esse escopo de acesso para reforçar a segurança do seu cluster.
gcloud container clusters create example-cluster-name \ --scopes=https://www.googleapis.com/auth/cloud_debugger
Adicione as linhas a seguir ao
Dockerfile
para inserir o agente do Debugger no aplicativo em contêiner e inicializá-lo quando o app estiver implantado:# Create a directory for the Debugger. Add and unzip the agent in the directory. RUN mkdir /opt/cdbg && \ wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \ tar xvz -C /opt/cdbg
Para instalar uma versão anterior do agente, altere o URL para o seguinte valor:
https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz
Substitua
VERSION_NUMBER
pela versão do agente que você quer usar, por exemplo,https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz
. A configuração de canary não está disponível em versões anteriores à 2.25. Para receber as versões do agente do Debugger, acesse a página do GitHub para o agente Java.Adicione as linhas a seguir ao
Dockerfile
para executar o agente do Debugger:Para depurar com a configuração de canary ativada:
# Start the agent when the app is deployed. RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true \ -jar PATH_TO_JAR_FILE
Para depurar com a configuração de canary NÃO ativada, defina a sinalização
enable_canary
comofalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.
O depurador agora estará pronto para uso quando você implantar o app em contêiner.
Para que a página "Depuração" no console exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.
CONSOLE
Para ativar o Debugger usando o Console do Google Cloud, siga estas etapas:
Na seção Pool de nós, selecione Segurança e Definir acesso para cada API.
Ative o Debugger.
Opcional: selecione Permitir acesso total a todas as APIs do Cloud.
Adicione as linhas a seguir ao
Dockerfile
para executar o agente do Debugger:Para depurar com a configuração de canary ativada:
# Start the agent when the app is deployed. RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true \ -jar PATH_TO_JAR_FILE
Para depurar com a configuração de canary NÃO ativada, defina a sinalização
enable_canary
comofalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.
O depurador agora estará pronto para uso quando você implantar o app em contêiner.
Para que a página "Depuração" no console exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.
Compute Engine
É possível usar o Cloud Debugger com qualquer aplicativo Java em execução em uma instância do Google Compute Engine. Recomendamos que você ative o Debugger em todas as instâncias em execução do seu app.
Verifique se as instâncias de VM do Compute Engine estão executando:
- uma imagem do Debian Linux de 64 bits;
- o Java JDK versão 7, 8 ou 9.
Verifique se as instâncias de VM do Compute Engine foram criadas com a opção de escopo de acesso Permitir acesso completo a todas as APIs do Cloud ou se elas têm um dos seguintes escopos de acesso:
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/cloud_debugger
Faça o download do pacote de agente pré-criado:
# Create a directory for the Debugger. Add and unzip the agent in the directory. sudo mkdir /opt/cdbg wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \ tar xvz -C /opt/cdbg
Para instalar uma versão anterior do agente, altere o URL para o seguinte valor:
https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz
Substitua
VERSION_NUMBER
pela versão do agente que você quer usar, por exemplo,https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz
. A configuração de canary não está disponível em versões anteriores à 2.25. Para receber as versões do agente do Debugger, acesse a página do GitHub para o agente Java.Adicione o agente à invocação Java:
Se você estiver usando Tomcat ou Jetty, consulte a seção Servidores da Web .Para depurar com a configuração de canary ativada:
# Start the agent when the app is deployed. java -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true \ -jar PATH_TO_JAR_FILE
Para depurar com a configuração de canary NÃO ativada, defina a sinalização
enable_canary
comofalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.
O depurador está pronto para ser usado com o app.
Para que a página "Depuração" no console exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.
Servidores da Web
Geralmente, os servidores da Web do Java são iniciados por meio de um processo de bootstrap, e cada servidor da Web tem sua própria maneira de personalizar as opções do Java.
Tomcat
Adicione esta linha a /etc/default/tomcat7
ou /etc/default/tomcat8
:
Para depurar com a configuração de canary ativada:
# Start the agent when the app is deployed. JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true"
Para depurar com a configuração de canary NÃO ativada, defina a sinalização enable_canary
como false
:
-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.
Se você executar o Tomcat em um contêiner do Docker, adicione esta linha a Dockerfile
em vez disso:
Para depurar com a configuração de canary ativada:
# Start the agent when the app is deployed. ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true
Para depurar com a configuração de canary NÃO ativada, defina a sinalização enable_canary
como false
:
-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.
Jetty
Adicione estas linhas a /var/lib/jetty/start.d
:
Para depurar com a configuração de canary ativada:
--exec -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true
Para depurar com a configuração de canary NÃO ativada, defina a sinalização enable_canary
como false
:
-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.
Cloud Run e Cloud Run for Anthos
Adicione os comandos a seguir ao
Dockerfile
para criar um diretório em que instalar o agente do Debugger, fazer o download do arquivo desse agente e extraí-lo para o diretório de instalação:# Create a directory for the Debugger. Add and unzip the agent in the directory. RUN mkdir /opt/cdbg && \ wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \ tar xvz -C /opt/cdbg
Para instalar uma versão anterior do agente, altere o URL para o seguinte valor:
https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz
Substitua
VERSION_NUMBER
pela versão do agente que você quer usar, por exemplo,https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz
. A configuração de canary não está disponível em versões anteriores à 2.25. Para receber as versões do agente do Debugger, acesse a página do GitHub para o agente Java.Localize a invocação Java e adicione a seguinte sinalização para inicializar o agente do Debugger:
Para depurar com a configuração de canary ativada:
# Start the agent when the app is deployed. RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.breakpoints.enable_canary=true \ -jar PATH_TO_JAR_FILE
Para depurar com a configuração de canary NÃO ativada, defina a sinalização
enable_canary
comofalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.
Na página Depuração, selecione o local do código-fonte. Para que a página Depuração no console exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.
O depurador está pronto para ser usado.
Ambiente local e outros
Faça o download do pacote de agente pré-criado do Debugger:
mkdir /opt/cdbg wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_service_account.tar.gz | \ tar xvz -C /opt/cdbg
Faça o download das credenciais da conta de serviço.
Para usar o agente do Cloud Debugger para Java em máquinas não hospedadas pelo Google Cloud, o agente deve usar credenciais de conta de serviço do Google Cloud para autenticar com o Cloud Debugger Service.Use a página "Contas de serviço" do console para criar um arquivo de credenciais para uma conta de serviço nova ou atual. A conta de serviço precisa ter pelo menos o papel
Cloud Debugger Agent
.Coloque o arquivo JSON da conta de serviço ao lado do agente do Cloud Debugger para Java.
Adicione o agente à invocação do Java:
Para depurar com a configuração de canary ativada:
java -agentpath:/opt/cdbg/cdbg_java_agent.so \ -Dcom.google.cdbg.module=MODULE \ -Dcom.google.cdbg.version=VERSION \ -Dcom.google.cdbg.breakpoints.enable_canary=true \ -Dcom.google.cdbg.auth.serviceaccount.enable=true \ -Dcom.google.cdbg.auth.serviceaccount.jsonfile=/opt/cdbg/gcp-svc.json \ -jar PATH_TO_JAR_FILE
Para depurar com a configuração de canary NÃO ativada, defina a sinalização
enable_canary
comofalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Substitua os marcadores no comando da seguinte forma:
PATH_TO_JAR_FILE
é o caminho relativo para o arquivo JAR do app. Por exemplo:~/myapp.jar
.MODULE
é o nome do app. Por exemplo,MyApp
,Backend
ouFrontend
.VERSION
é a versão do app ou o ID do build. Por exemplo,v1.0
oubuild_147
. Você pode determinar o número da versão com base no seu processo de lançamento e definir o valor adequadamente.Tanto
MODULE
quantoVERSION
são exibidos no Console do Google Cloud comoMODULE - VERSION
. Por exemplo,MyApp - v1.0
ouBackend - build_147
.É possível usar a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
em vez de adicionar a propriedade de sistemaauth.serviceaccount.jsonfile
.
O depurador está pronto para ser usado com o app.
A página "Depuração" no console pode exibir arquivos de origem locais, sem upload, para desenvolvimento local. Consulte Como selecionar o código-fonte manualmente.