Como configurar o Stackdriver Debugger para Java

Observação: o Stackdriver Debugger está disponível para Java 7, Java 8 e Java 9.

Esta página descreve como configurar seu ambiente e seu aplicativo Java para usar o Stackdriver Debugger. Para alguns ambientes, é preciso especificar explicitamente o escopo de acesso para permitir que o agente do Stackdriver Debugger envie dados. Recomendamos definir o escopo de acesso da forma mais ampla possível e, em seguida, usar o Cloud Identity and Access Management para restringir o acesso. Para manter essa prática recomendada, defina o escopo de acesso para todas as APIs Cloud com a opção cloud-platform.

Ambiente padrão do App Engine

O depurador fica ativo por padrão. Nenhuma configuração é necessária. Na página "Depuração" do Console do GCP, haverá uma tentativa de mostrar automaticamente os arquivos Java de origem usados para criar o app.

Para saber mais, consulte Como selecionar o código-fonte automaticamente.

Ambiente flexível do App Engine

O depurador fica ativado por padrão para o Java Runtime. Nenhuma configuração é necessária. Na página "Depuração" do Console do GCP, haverá uma tentativa de mostrar automaticamente os arquivos Java de origem usados para criar o app.

O depurador é incluído por padrão nos Ambientes de execução personalizados que usam as imagens de base fornecidas pelo Google para Java. Nenhuma configuração será necessária se o ponto de entrada padrão for usado. Na página "Depuração" do Console do GCP, haverá uma tentativa de mostrar automaticamente os arquivos Java de origem usados para criar o app.

Para usar o Stackdriver Debugger com tempos de execução personalizados criados com 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

1. Crie seu cluster com um dos seguintes escopos de acesso:
   • https://www.googleapis.com/auth/cloud-platform
   • https://www.googleapis.com/auth/cloud_debugger
   Observação: não é possível alterar os escopos de acesso de um cluster após a criação.

   Para criar um cluster usando o gcloud, faça o seguinte:

   1. Atualize o gcloud para a versão mais recente (opcional):

      gcloud components update

   2. Defina o código do projeto padrão:

      gcloud config set project [PROJECT_ID]

   3. Se você estiver trabalhando com clusters zonais, defina a zona de computação padrão:

      gcloud config set compute/zone [COMPUTE_ZONE]

   4. Se você estiver trabalhando com clusters regionais, defina a região de computação padrão:

      gcloud config set compute/region [COMPUTE_REGION]

   5. Execute o comando de criação:

      gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform

   Para informações mais detalhadas, consulte Como criar um cluster.

2. Siga as instruções do Compute Engine.

Compute Engine

Você pode usar o Stackdriver Debugger com qualquer app Java executado em uma instância do Google Compute Engine. Recomendamos que ele seja ativado para todas as instâncias em execução do app.

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

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

3. Faça o download do pacote de agente pré-criado:

   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
   

4. Adicione o agente à invocação do Java:
   Se você estiver usando Tomcat ou Jetty, consulte a seção Servidores da Web:

   java -agentpath:/opt/cdbg/cdbg_java_agent.so \
     -Dcom.google.cdbg.module=MODULE \
     -Dcom.google.cdbg.version=VERSION \
     -jar PATH_TO_JAR_FILE
   

   Em que:

   • PATH_TO_JAR_FILE é o caminho relativo do arquivo JAR do app. Por exemplo: ~/myapp.jar;

   • MODULE é o nome do app. Juntamente com a versão, ele identifica o app no Console do GCP. Exemplos: MyApp, Backend ou Frontend.

   • VERSION é a versão do app (como o código da versão). O Console do GCP mostra o aplicativo em execução como MODULE - VERSION. Exemplos: v1.0, build_147 ou v20160520.

O depurador está pronto para ser usado com o app.

Para que a página "Depuração" no Console do GCP mostre 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 ao /etc/default/tomcat7 ou /etc/default/tomcat8:

JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \
  -Dcom.google.cdbg.module=MODULE \
  -Dcom.google.cdbg.version=VERSION"

Se você executar o Tomcat em um contêiner do Docker, adicione a seguinte linha ao Dockerfile:

ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \
              -Dcom.google.cdbg.module=MODULE \
              -Dcom.google.cdbg.version=VERSION

Jetty

Adicione estas linhas a /var/lib/jetty/start.d:

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so
-Dcom.google.cdbg.module=MODULE
-Dcom.google.cdbg.version=VERSION

Ambiente local e outros

1. Faça o download do pacote de agente pré-criado do depurador:

   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
   

2. Faça o download das credenciais da conta de serviço.
   Para usar o agente do Stackdriver Debugger para Java em máquinas não hospedadas pelo Google Cloud Platform, o agente deve usar as credenciais de uma conta de serviço do GCP para se autenticar com o serviço Stackdriver Debugger.

   Use a página Contas de serviço do Console do GCP para criar um arquivo de credenciais para uma conta de serviço nova ou existente. A conta de serviço precisa ter pelo menos o papel Stackdriver Debugger Agent.

   Coloque o arquivo JSON da conta de serviço ao lado do agente do depurador do Java.

3. Adicione o agente à invocação do Java:

   java -agentpath:/opt/cdbg/cdbg_java_agent.so \
     -Dcom.google.cdbg.module=MODULE \
     -Dcom.google.cdbg.version=VERSION \
     -Dcom.google.cdbg.auth.serviceaccount.enable=true
     -Dcom.google.cdbg.auth.serviceaccount.jsonfile=/opt/cdbg/gcp-svc.json
     -jar PATH_TO_JAR_FILE
   

   Em que:

   • PATH_TO_JAR_FILE é o caminho relativo do arquivo JAR do app. Por exemplo: ~/myapp.jar;

   • MODULE é o nome do app. Junto com a versão, ele identifica o app no Console do GCP. Exemplos: MyApp, Backend ou Frontend.

   • VERSION é a versão do app (como o código da versão). O Console do GCP mostra o aplicativo em execução como MODULE - VERSION. Exemplos: v1.0, build_147 ou v20160520.

   • Pode-se usar a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS em vez de adicionar a propriedade do sistema auth.serviceaccount.jsonfile.

O depurador está pronto para ser usado com o app.

A página "Depuração" no Console do GCP pode mostrar arquivos de origem locais, sem upload, para desenvolvimento local. Consulte Como selecionar o código-fonte manualmente.

Observação: você encontra o código e a documentação do agente do depurador no GitHub.