Panoramica
In questa pagina viene spiegato 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 linea con questa best practice, imposta l'ambito di accesso su tutte le API Cloud
con l'opzione cloud-platform
.
Versioni linguistiche degli ambienti di calcolo
Cloud Debugger è disponibile per Java versione 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à:
Verifica che l'API Cloud Debugger sia abilitata per il tuo progetto.
Installa e configura Debugger nell'ambiente di calcolo che stai utilizzando.
Seleziona il tuo codice sorgente.
Verifica dell'abilitazione dell'API Cloud Debugger
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 impedire il caricamento simultaneo di snapshot e punti di log in tutte le istanze in esecuzione, causando potenzialmente la 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, uno snapshot o un punto di log viene applicato a un sottoinsieme di istanze in esecuzione e Debugger verifica che l'istantanea 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, consulta le pagine relative a Debug snapshot e Debug punti di log.
Attivazione di snapshot e punti di log canary
Quando installi la versione più recente dell'agente Debugger, puoi scegliere di attivare o disattivare la versione canary. La versione canary è disattivata per impostazione predefinita.
Quando attivare snapshot e punti di log canary
Per proteggere i carichi di lavoro di deployment e critici per la produzione, abilita la versione canary durante il debug di questi carichi di lavoro.
Se hai una singola istanza, puoi eseguire il debug con la versione canary, ma l'istanza singola viene eseguita senza eliminare lo snapshot o il punto di log.
Quando non attivare snapshot canary e punti di log
Non attivare la versione canary su carichi di lavoro che hanno un tempo di esecuzione inferiore a 40 secondi, ad esempio i job che utilizzano Cloud Functions.
Non attivare la versione canary se vuoi un ciclo di attivazione degli snapshot più veloce.
Per configurare l'agente Debugger in modo che non esegua snapshot canary e punti di log, consulta le istruzioni di installazione per la piattaforma Google Cloud che stai utilizzando.
Ambiente standard di App Engine
Il debugger è abilitato per impostazione predefinita; non è richiesta alcuna configurazione. La pagina Debug nella console tenterà di visualizzare i file di origine Java utilizzati per creare l'app.
Tieni presente che la console non funziona se è attivato il recupero dell'URL.
Per scoprire di più, consulta la sezione Selezionare automaticamente il codice sorgente.
Ambiente flessibile di App Engine
Il debugger è abilitato per impostazione predefinita per il runtime Java; non è richiesta alcuna configurazione. La pagina Debug nella console tenterà di 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 contatto predefinito non è richiesta alcuna configurazione. La pagina Debug nella console tenterà di 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 per la configurazione di Compute Engine.
Per scoprire di più, consulta la sezione Selezionare automaticamente il codice sorgente.
Google Kubernetes Engine
GCLOUD
Per attivare Debugger utilizzando gcloud
, completa i seguenti passaggi:
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 di 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
Aggiungi le seguenti righe al tuo
Dockerfile
per aggiungere l'agente Debugger all'app containerizzata e inizializzarlo 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 esempiohttps://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 di GitHub per l'agente Java.Aggiungi le seguenti righe al tuo
Dockerfile
per eseguire l'agente di 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
sufalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Sostituisci i segnaposto nel comando come indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.
Il debugger è ora pronto per l'utilizzo quando esegui il deployment della tua app containerizzata.
Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'applicazione di cui è stato eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.
CONSOLE
Per abilitare Debugger utilizzando Google Cloud Console, procedi nel seguente modo:
Nella sezione Pool di nodi, seleziona Sicurezza, quindi seleziona Imposta l'accesso per ogni API.
Abilita Debugger.
(Facoltativo) Seleziona Consenti l'accesso completo a tutte le API Cloud.
Aggiungi le seguenti righe al tuo
Dockerfile
per eseguire l'agente di 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
sufalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Sostituisci i segnaposto nel comando come indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.
Il debugger è ora pronto per l'utilizzo quando esegui il deployment della tua app containerizzata.
Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'applicazione di cui è stato eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.
Compute Engine
Puoi utilizzare Cloud Debugger con qualsiasi app Java in esecuzione su un'istanza Google Compute Engine. Ti consigliamo di abilitare Debugger su tutte le istanze in esecuzione della tua app.
Assicurati che le istanze VM di Compute Engine siano in esecuzione:
- Immagine di Debian a 64 bit
- Java JDK versione 7, 8 o 9
Assicurati che le istanze VM di Compute Engine siano create con l'opzione ambito di accesso Consenti l'accesso completo a tutte le API Cloud oppure disponi di uno dei seguenti ambiti di accesso:
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/cloud_debugger
Scarica il pacchetto dell'agente predefinito:
# 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 esempiohttps://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 di GitHub per l'agente Java.Aggiungi l'agente alla tua 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
sufalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Sostituisci i segnaposto nel comando come indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.
Il debugger è ora pronto per l'utilizzo con l'app.
Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'applicazione di cui è stato eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.
Server web
I server web Java di solito iniziano tramite un processo di bootstrap e ogni server web ha il proprio modo di 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 indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.
Se esegui Tomcat in un container Docker, aggiungi 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 indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.
Pontile
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 indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.
Cloud Run e Cloud Run for Anthos
Aggiungi i seguenti comandi al tuo
Dockerfile
per creare una directory in cui installare l'agente Debugger, scaricare l'archivio dell'agente Debugger, quindi 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 esempiohttps://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 di GitHub per l'agente Java.Individua la chiamata Java e aggiungi il seguente flag 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
sufalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Sostituisci i segnaposto nel comando come indicato di seguito:
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 mostri automaticamente il codice sorgente corrispondente all'app di cui hai eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.
Il debugger è ora pronto all'uso.
Locale e altrove
Scarica il pacchetto dell'agente 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
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 della 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
.Inserisci il file JSON dell'account di servizio insieme all'agente Cloud Debugger per Java.
Aggiungi l'agente alla tua 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
sufalse
:-Dcom.google.cdbg.breakpoints.enable_canary=false
Sostituisci i segnaposto nel comando come indicato di seguito:
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
oFrontend
.VERSION
è l'ID della versione o della build dell'app. Ad esempio:v1.0
obuild_147
. Puoi determinare il numero di versione in base alla procedura di rilascio e impostare il valore di conseguenza.Sia
MODULE
siaVERSION
sono visualizzati in Google Cloud Console comeMODULE - VERSION
. Ad esempio,MyApp - v1.0
oBackend - build_147
.È possibile utilizzare la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
invece di aggiungere la proprietà di sistemaauth.serviceaccount.jsonfile
.
Il debugger è ora pronto per l'utilizzo con l'app.
Nella pagina Debug nella console possono essere visualizzati i file di origine locali, senza caricamento, per lo sviluppo locale. Consulta Selezione manuale del codice sorgente.