Configurazione di Cloud Debugger per Java

Panoramica

In questa pagina viene descritto come configurare il tuo ambiente e la tua applicazione Java per utilizzare Cloud Debugger. Per alcuni ambienti devi specificare esplicitamente l'ambito di accesso per consentire all'agente Cloud Debugger di inviare i dati. Ti consigliamo di impostare l'ambito di accesso più ampio possibile e quindi utilizzare Identity and Access Management per limitare l'accesso. In base a questa best practice, imposta l'ambito di accesso su tutte le API Cloud con l'opzione cloud-platform.

Versioni linguistiche e ambienti di calcolo

Cloud Debugger è disponibile per le versioni Java 7, 8, 9 e 11 nei seguenti ambienti di computing:

Ambiente standard di App Engine Ambiente flessibile di App Engine Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos VM e container in esecuzione altrove Cloud Functions

Configurazione di Cloud Debugger

Per configurare Cloud Debugger, completa le seguenti attività:

  1. Verifica che l'API Cloud Debugger sia abilitata per il tuo progetto.

  2. Installa e configura il debugger nell'ambiente di calcolo che stai utilizzando.

  3. Seleziona il codice sorgente.

La verifica dell'API Cloud Debugger è abilitata

Per iniziare a utilizzare Cloud Debugger, assicurati che l'API Cloud Debugger sia abilitata. Cloud Debugger è abilitato per impostazione predefinita per la maggior parte dei progetti.
Abilita l'API Cloud Debugger

Snapshot e punti di log canary

Per evitare il caricamento simultaneo di snapshot e punti di log su tutte le istanze in esecuzione e con la possibile causa della rimozione del job a causa di un bug potenziale dell'agente Debugger, abilita la modalità canary per l'agente Debugger. Quando la modalità canary è abilitata, viene applicato uno snapshot o un punto di log a un sottoinsieme di istanze in esecuzione e Debugger verifica che lo snapshot o il punto di log non influisca negativamente su tali istanze. Al termine della verifica, lo snapshot o il punto di log viene applicato a tutte le istanze.

Per informazioni su come utilizzare Debugger in modalità canary, vai alle pagine Istantanea debug e Punti di log di debug.

Abilitazione di snapshot e punti di log canary

Quando installi la versione più recente dell'agente Debugger, puoi attivare o disattivare la versione canary. Le versioni canary sono disattivate per impostazione predefinita.

Quando abilitare snapshot canary e punti di log

Per proteggere i carichi di lavoro critici di deployment e critici, abilita le versioni canary durante il debug di questi carichi di lavoro.

Se hai una singola istanza, puoi comunque eseguire il debug con la versione canary abilitata, ma l'istanza singola viene eseguita senza eliminare lo snapshot o il punto di log.

Quando non abilitare snapshot e punti di log canary

Non consentire la canary su carichi di lavoro con un tempo di esecuzione inferiore a 40 secondi, ad esempio job che utilizzano Cloud Functions.

Non attivare la versione canary se vuoi un ciclo di attivazione degli snapshot più rapido.

Per configurare l'agente Debugger in modo che non esegua snapshot canary e punti di log, vai alle istruzioni di installazione della piattaforma Google Cloud che stai utilizzando.

Ambiente standard di App Engine

Il debugger è abilitato per impostazione predefinita; non è necessaria alcuna configurazione. La pagina Debug nella console Google Cloud proverà a visualizzare i file di origine Java utilizzati per creare l'app.

Tieni presente che Google Cloud Console non funziona se è abilitato Recupero URL.

Per scoprire di più, consulta Selezionare il codice sorgente automaticamente.

Ambiente flessibile di App Engine

Il debugger è abilitato per impostazione predefinita per il runtime Java; non è richiesta alcuna configurazione. La pagina Debug nella console Google Cloud proverà a visualizzare i file di origine Java utilizzati per creare l'app.

Il debugger è incluso per impostazione predefinita per i runtime personalizzati che utilizzano le immagini di base fornite da Google per Java. Se viene utilizzato il punto di ingresso predefinito, non è necessaria alcuna configurazione. La pagina Debug nella console Google Cloud proverà a visualizzare i file di origine Java utilizzati per creare l'app.

Per utilizzare Cloud Debugger con runtime personalizzati creati utilizzando altre immagini di base, segui le istruzioni di configurazione di Compute Engine.

Per scoprire di più, consulta Selezionare il codice sorgente automaticamente.

Google Kubernetes Engine

GCLOUD

Per attivare Debugger utilizzando gcloud, completa i seguenti passaggi:

  1. Crea il cluster con uno dei seguenti ambiti di accesso:

    • https://www.googleapis.com/auth/cloud-platform concede al cluster l'accesso a tutte le API Google Cloud.

    • https://www.googleapis.com/auth/cloud_debugger concede al cluster l'accesso solo all'API Debugger. Utilizza questo ambito di accesso per proteggere la sicurezza del tuo cluster.

    gcloud container clusters create example-cluster-name \
       --scopes=https://www.googleapis.com/auth/cloud_debugger

  2. Aggiungi le righe seguenti a Dockerfile per aggiungere l'agente Debugger all'app containerizzata e inizializzarla al momento del deployment dell'app: 

    # 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

    Per installare una versione precedente dell'agente, modifica l'URL nel valore seguente:

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    Sostituisci VERSION_NUMBER con la versione dell'agente che vuoi utilizzare, ad esempio https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. La versione canary non è disponibile nelle versioni precedenti alla 2.25. Per ottenere le versioni dell'agente Debugger, vai alla pagina GitHub per l'agente Java.

  3. Aggiungi le righe seguenti a Dockerfile per eseguire l'agente debug:

    Per eseguire il debug con la versione canary attivata:

    # 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

    Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Sostituisci i segnaposto nel comando come segue:

    • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

    • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

    • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

    • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

Il debugger è ora pronto per l'uso durante il deployment dell'app containerizzata.

Per fare in modo che la pagina Debug nella console Google Cloud mostri automaticamente il codice sorgente corrispondente all'app di cui è stato eseguito il deployment, consulta la sezione Selezionare il codice sorgente automaticamente.

CONSOLE

Per attivare Debugger utilizzando Google Cloud Console, completa i seguenti passaggi:

  1. Nella sezione Pool di nodi, seleziona Sicurezza, quindi seleziona Imposta l'accesso per ogni API.

  2. Abilita Debugger.

    L'API Debugger è abilitata per il cluster.

  3. (Facoltativo) Seleziona Consenti l'accesso completo a tutte le API di Cloud.

  4. Aggiungi le righe seguenti a Dockerfile per eseguire l'agente debug:

    Per eseguire il debug con la versione canary attivata:

    # 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

    Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Sostituisci i segnaposto nel comando come segue:

    • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

    • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

    • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

    • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

Il debugger è ora pronto per l'uso durante il deployment dell'app containerizzata.

Per fare in modo che la pagina Debug nella console Google Cloud mostri automaticamente il codice sorgente corrispondente all'app di cui è stato eseguito il deployment, consulta la sezione Selezionare il codice sorgente automaticamente.

Compute Engine

Puoi utilizzare Cloud Debugger con qualsiasi app Java in esecuzione su un'istanza di Google Compute Engine. Ti consigliamo di abilitare Debugger su tutte le istanze in esecuzione della tua app.

  1. Assicurati che le istanze VM di Compute Engine siano in esecuzione:

    • Immagine di Debian Linux a 64 bit
    • JDK Java versione 7, 8 o 9

  2. Assicurati che le istanze VM di Compute Engine vengano create con l'opzione dell'ambito di accesso Consenti l'accesso completo a tutte le API di Cloud o hanno uno dei seguenti ambiti di accesso:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger

  3. Scarica il pacchetto di agenti predefiniti:

    # 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

    Per installare una versione precedente dell'agente, modifica l'URL nel valore seguente:

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    Sostituisci VERSION_NUMBER con la versione dell'agente che vuoi utilizzare, ad esempio https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. La versione canary non è disponibile nelle versioni precedenti alla 2.25. Per ottenere le versioni dell'agente Debugger, vai alla pagina GitHub per l'agente Java.

  4. Aggiungi l'agente alla chiamata Java:
    Se utilizzi Tomcat o Jetty, consulta la sezione Server web.

    Per eseguire il debug con la versione canary attivata:

    # 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

    Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Sostituisci i segnaposto nel comando come segue:

    • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

    • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

    • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

    • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

Il debugger è ora pronto per essere utilizzato con la tua app.

Per fare in modo che la pagina Debug nella console Google Cloud mostri automaticamente il codice sorgente corrispondente all'app di cui è stato eseguito il deployment, consulta la sezione Selezionare il codice sorgente automaticamente.

Server web

I server web Java di solito iniziano tramite un processo bootstrap e ognuno di essi ha il proprio modo per personalizzare le opzioni Java.

Tomcat

Aggiungi questa riga a /etc/default/tomcat7 o /etc/default/tomcat8:

Per eseguire il debug con la versione canary attivata:

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

Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Sostituisci i segnaposto nel comando come segue:

  • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

  • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

  • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

  • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

Se esegui Tomcat in un container Docker, aggiungi invece questa riga a Dockerfile:

Per eseguire il debug con la versione canary attivata:

# 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

Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Sostituisci i segnaposto nel comando come segue:

  • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

  • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

  • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

  • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

Molo

Aggiungi queste righe a /var/lib/jetty/start.d:

Per eseguire il debug con la versione canary attivata:

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

Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Sostituisci i segnaposto nel comando come segue:

  • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

  • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

  • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

  • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

Cloud Run e Cloud Run for Anthos

  1. Aggiungi i comandi seguenti al Dockerfile per creare una directory in cui installare l'agente Debugger, scaricare l'archivio agente Debugger ed estrarlo nella directory di installazione:

    # 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

    Per installare una versione precedente dell'agente, modifica l'URL nel valore seguente:

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    Sostituisci VERSION_NUMBER con la versione dell'agente che vuoi utilizzare, ad esempio https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. La versione canary non è disponibile nelle versioni precedenti alla 2.25. Per ottenere le versioni dell'agente Debugger, vai alla pagina GitHub per l'agente Java.

    Individua la chiamata Java e aggiungi il flag seguente per inizializzare l'agente Debugger:

    Per eseguire il debug con la versione canary attivata:

    # 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

    Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Sostituisci i segnaposto nel comando come segue:

    • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

Nella pagina Debug, seleziona la posizione del codice sorgente. Per fare in modo che la pagina Debug nella console Google Cloud mostri in modo automatico il codice sorgente corrispondente all'app di cui hai eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.

Il debugger è ora pronto per l'uso.

Locale e altrove

  1. Scarica il pacchetto di agenti predefinito del 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

  2. Scarica le credenziali dell'account di servizio.
    Per utilizzare l'agente Cloud Debugger per Java su macchine non ospitate da Google Cloud, l'agente deve utilizzare le credenziali dell'account di servizio Google Cloud per eseguire l'autenticazione con il servizio Cloud Debugger.

    Utilizza la pagina Account di servizio di Google Cloud Console per creare un file delle credenziali per un account di servizio nuovo o esistente. L'account di servizio deve avere almeno il ruolo Cloud Debugger Agent.

    Posiziona il file JSON dell'account di servizio insieme all'agente Cloud Debugger per Java.

  3. Aggiungi l'agente alla chiamata Java:

    Per eseguire il debug con la versione canary attivata:

    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

    Per eseguire il debug con la versione canary NON abilitata, imposta il flag enable_canary su false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Sostituisci i segnaposto nel comando come segue:

    • PATH_TO_JAR_FILE è il percorso relativo al file JAR dell'app, ad esempio: ~/myapp.jar.

    • MODULE è il nome dell'app. Ad esempio: MyApp, Backend o Frontend.

    • VERSION è la versione o l'ID della build dell'app. Ad esempio: v1.0 o build_147. Puoi determinare il numero di versione in base al processo di rilascio e impostare il valore di conseguenza.

    • Sia MODULE sia VERSION sono visualizzati in Google Cloud Console come MODULE - VERSION. Ad esempio, MyApp - v1.0 o Backend - build_147.

    • La variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS può essere utilizzata, invece di aggiungere la proprietà di sistema auth.serviceaccount.jsonfile.

Il debugger è ora pronto per essere utilizzato con la tua app.

Nella pagina Debug nella console Google Cloud puoi visualizzare i file di origine locali, senza caricamento, per lo sviluppo locale. Consulta Selezione manuale del codice sorgente.