Configura Cloud Debugger para Java

Descripción general

En esta página se describe cómo configurar el entorno y la aplicación de Java para usar Cloud Debugger. Para algunos entornos, debes especificar explícitamente el nivel de acceso a fin de permitir que el agente de Cloud Debugger envíe datos. Te recomendamos configurar el nivel de acceso más amplio posible y, luego, usar la Administración de identidades y accesos para restringir el acceso. De acuerdo con esta práctica recomendada, debes configurar el nivel de acceso para que estén todas las API de Cloud con la opción cloud-platform.

Versiones de lenguajes y entornos de procesamiento

El Depurador de Cloud está disponible para las versiones 7, 8, 9 y 11 de Java en los siguientes entornos de procesamiento:

Entorno estándar de App Engine	Entorno flexible de App Engine	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	VM y contenedores que se ejecutan en otros lugares	Cloud Functions

Configura Cloud Debugger

Para configurar Cloud Debugger, completa las siguientes tareas:

Verifica que la API del Depurador de Cloud esté habilitada para tu proyecto.
Instala y configura Debugger en el entorno de procesamiento que usas.
Selecciona tu código fuente.

Verifica que la API de Cloud Debugger esté habilitada

Para comenzar a usar Cloud Debugger, asegúrate de que esté habilitada la API de Cloud Debugger. Cloud Debugger está habilitado de forma predeterminada para la mayoría de los proyectos.
Habilita la API de Cloud Debugger

Instantáneas y puntos de registro versión canary

Para evitar que las instantáneas y los puntos de registro se carguen en todas las instancias en ejecución al mismo tiempo, y que esto pueda provocar la eliminación del trabajo debido a un posible error en el agente de Debugger, habilita el modo de versión canary para el agente de Debugger. Cuando el modo canary está habilitado, una instantánea o punto de registro se aplica a un subconjunto de instancias en ejecución y Debugger verifica que la instantánea o el punto de registro no afecte de forma negativa a esas instancias. Una vez completada la verificación, la instantánea o el punto de registro se aplica a todas las instancias.

Para obtener información sobre cómo usar Debugger en el modo canary, consulta las páginas Instantáneas de depuración y Puntos de registro de depuración.

Habilita las instantáneas y los puntos de registro versión canary

Cuando instalas la versión más reciente del agente de Debugger, tienes la opción de habilitar o inhabilitar la versión canary. La versión canary está inhabilitada de manera predeterminada.

Cuándo habilitar las instantáneas canary y los puntos de registro

Habilita la versión canary cuando depuras estas cargas de trabajo para proteger la implementación y las cargas de trabajo importantes de producción.

Si tienes una sola instancia, puedes depurar con la versión canary habilitada, pero la instancia única se ejecuta sin realizar una actualización canary o el punto de registro.

Cuándo no habilitar las instantáneas canary y los puntos de registro

No habilites la versión canary en cargas de trabajo que tienen un tiempo de ejecución inferior a 40 segundos, por ejemplo, trabajos que usan Cloud Functions.

No habilites la versión canary si deseas un ciclo de activación de instantáneas más rápido.

Para configurar el agente de Debugger a fin de que no realice una actualización canary de las instantáneas y los puntos de registro, ve a las instrucciones de instalación de la plataforma de Google Cloud que estás usando.

Entorno estándar de App Engine

El depurador está habilitado de forma predeterminada; no se requiere configuración. En la página de Depuración en Google Cloud Console, se intentará mostrar los archivos de origen de Java que se usaron para compilar la app.

Ten en cuenta que Google Cloud Console no funcionará si la recuperación de URL está habilitada.

Para obtener más información, consulta Selecciona el código fuente de forma automática.

Entorno flexible de App Engine

El depurador está habilitado de forma predeterminada para el entorno de ejecución de Java; no se requiere configuración. En la página de Depuración en Google Cloud Console, se intentará mostrar los archivos de origen de Java que se usaron para compilar la app.

El depurador se incluye de forma predeterminada en los entornos de ejecución personalizados que usan las imágenes base que proporciona Google para Java. No se requiere configuración si se usa el punto de entrada predeterminado. En la página de Depuración en Google Cloud Console, se intentará mostrar los archivos de origen de Java que se usaron para compilar la app.

Para usar Cloud Debugger con entornos de ejecución personalizados compilados con otras imágenes base, sigue las instrucciones de configuración para Compute Engine.

Para obtener más información, consulta Selecciona el código fuente de forma automática.

Google Kubernetes Engine

GCLOUD

Para habilitar Debugger con gcloud, completa los siguientes pasos:

Crea tu clúster con uno de los niveles de acceso siguientes:
- https://www.googleapis.com/auth/cloud-platform otorga a tu clúster acceso a todas las API de Google Cloud.
- https://www.googleapis.com/auth/cloud_debugger otorga a tu clúster acceso solo a la API de Debugger. Usa este nivel de acceso para fortalecer la seguridad de tu clúster.
```
gcloud container clusters create example-cluster-name \
       --scopes=https://www.googleapis.com/auth/cloud_debugger
```
Nota: No puedes cambiar los permisos de acceso de un clúster después de su creación.
Agrega las líneas siguientes a tu Dockerfile si deseas agregar el agente de Debugger a tu app en contenedores y, luego, inicializarlo cuando se implemente la 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
```
Para instalar una versión anterior del agente, cambia la URL al siguiente valor:
```
https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz
```
Reemplaza VERSION_NUMBER por la versión del agente que deseas usar, por ejemplo, https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. La versión canary no está disponible en versiones anteriores a la 2.25. Para obtener las versiones del agente de Debugger, ve a la página de GitHub del agente de Java.
Agrega las líneas siguientes a tu Dockerfile para ejecutar el agente de Debugger:
Para depurar con la versión canary habilitada, haz lo siguiente:
```
# 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 con la versión canary NO habilitada, establece la marca enable_canary en false:
```
-Dcom.google.cdbg.breakpoints.enable_canary=false
```
Reemplaza los marcadores de posición en el comando de la siguiente manera:
- PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
- MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
- VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
- MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.

Ahora puedes usar el depurador cuando implementes tu app en contenedores.

Para que la página de Depuración en Google Cloud Console muestre automáticamente el código fuente que coincide con la aplicación implementada, consulta Selecciona el código fuente de forma automática.

CONSOLE

Para habilitar Debugger mediante Google Cloud Console, completa los siguientes pasos:

En la sección Grupos de nodos, selecciona Seguridad y, luego, Configurar acceso para cada API.
Habilita Debugger.
Opcional: Selecciona Permitir el acceso total a todas las API de Cloud.
Agrega las líneas siguientes a tu Dockerfile para ejecutar el agente de Debugger:
Para depurar con la versión canary habilitada, haz lo siguiente:
```
# 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 con la versión canary NO habilitada, establece la marca enable_canary en false:
```
-Dcom.google.cdbg.breakpoints.enable_canary=false
```
Reemplaza los marcadores de posición en el comando de la siguiente manera:
- PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
- MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
- VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
- MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.

Ahora puedes usar el depurador cuando implementes tu app en contenedores.

Compute Engine

Puedes usar Cloud Debugger con cualquier app de Java que se ejecute en una instancia de Google Compute Engine. Recomendamos que habilites Debugger en todas las instancias en ejecución de tu app.

Asegúrate de que tus instancias de VM de Compute Engine estén ejecutando:
- Una imagen de Debian Linux de 64 bits
- Java JDK versión 7, 8 o 9
Asegúrate de que tus instancias de VM de Compute Engine se creen con la opción de nivel de acceso Permitir acceso completo a todas las API de Cloud, o que tengan uno de los siguientes niveles de acceso:
- https://www.googleapis.com/auth/cloud-platform
- https://www.googleapis.com/auth/cloud_debugger
Descarga el paquete de agente ya compilado:
```
# 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 una versión anterior del agente, cambia la URL al siguiente valor:
```
https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz
```
Reemplaza VERSION_NUMBER por la versión del agente que deseas usar, por ejemplo, https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. La versión canary no está disponible en versiones anteriores a la 2.25. Para obtener las versiones del agente de Debugger, ve a la página de GitHub del agente de Java.
Agrega el agente a tu invocación de Java:
(Si usas Tomcat o Jetty, consulta la sección Servidores web).

Para depurar con la versión canary habilitada, haz lo siguiente:
```
# 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 con la versión canary NO habilitada, establece la marca enable_canary en false:
```
-Dcom.google.cdbg.breakpoints.enable_canary=false
```
Reemplaza los marcadores de posición en el comando de la siguiente manera:
- PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
- MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
- VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
- MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.

Ahora puedes usar Debugger con tu app.

Servidores web

Los servidores web de Java generalmente comienzan a través de un proceso de arranque, y cada servidor web tiene su propia manera de personalizar las opciones de Java.

Tomcat

Agrega esta línea a /etc/default/tomcat7 o /etc/default/tomcat8:

Para depurar con la versión canary habilitada, haz lo siguiente:

# 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 con la versión canary NO habilitada, establece la marca enable_canary en false:

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

Reemplaza los marcadores de posición en el comando de la siguiente manera:

PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.

Si ejecutas Tomcat en un contenedor de Docker, agrega esta línea a Dockerfile en su lugar:

Para depurar con la versión canary habilitada, haz lo siguiente:

# 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 con la versión canary NO habilitada, establece la marca enable_canary en false:

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

Reemplaza los marcadores de posición en el comando de la siguiente manera:

PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.

Jetty

Agrega estas líneas a /var/lib/jetty/start.d:

Para depurar con la versión canary habilitada, haz lo siguiente:

--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 con la versión canary NO habilitada, establece la marca enable_canary en false:

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

Reemplaza los marcadores de posición en el comando de la siguiente manera:

PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.

Cloud Run y Cloud Run for Anthos

Agrega los comandos siguientes a tu Dockerfile a fin de crear un directorio en el que instalar el agente de Debugger, descarga el archivo del agente de Debugger y extráelo en el directorio de instalación:
```
# 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 una versión anterior del agente, cambia la URL al siguiente valor:
```
https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz
```
Reemplaza VERSION_NUMBER por la versión del agente que deseas usar, por ejemplo, https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. La versión canary no está disponible en versiones anteriores a la 2.25. Para obtener las versiones del agente de Debugger, ve a la página de GitHub del agente de Java.

Ubica la invocación de Java y agrega la siguiente marca para inicializar el agente de Debugger:
Para depurar con la versión canary habilitada, haz lo siguiente:
```
# 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 con la versión canary NO habilitada, establece la marca enable_canary en false:
```
-Dcom.google.cdbg.breakpoints.enable_canary=false
```
Reemplaza los marcadores de posición en el comando de la siguiente manera:
- PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.

En la página de Depuración, selecciona la ubicación del código fuente. Para que la página de Depuración en Google Cloud Console muestre automáticamente el código fuente que coincide con la aplicación implementada, consulta Selecciona el código fuente de forma automática.

Debugger ya está listo para usar.

En el entorno local y en otros lugares

Descarga el paquete de agente ya compilado del 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

Descarga las credenciales de la cuenta de servicio.
A fin de usar el agente de Cloud Debugger para Java en máquinas que no se alojan en Google Cloud, el agente debe usar las credenciales de la cuenta de servicio de Google Cloud para autenticarse con Servicio de Cloud Debugger.

Usa la página de cuentas de servicio de Google Cloud Console a fin de crear un archivo de credenciales para una cuenta de servicio nueva o existente. La cuenta de servicio debe tener al menos la función Cloud Debugger Agent.

Coloca el archivo JSON de la cuenta de servicio junto con el agente del Depurador de Cloud para Java.
Agrega el agente a tu invocación de Java:

Para depurar con la versión canary habilitada, haz lo siguiente:
```
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 con la versión canary NO habilitada, establece la marca enable_canary en false:
```
-Dcom.google.cdbg.breakpoints.enable_canary=false
```
Reemplaza los marcadores de posición en el comando de la siguiente manera:
- PATH_TO_JAR_FILE es la ruta relativa al archivo JAR de la aplicación. P. ej.: ~/myapp.jar.
- MODULE es el nombre de la app. Por ejemplo: MyApp, Backend o Frontend.
- VERSION es la versión de la app o el ID de compilación. Por ejemplo: v1.0 o build_147. Puedes determinar el número de versión según tu proceso de lanzamiento y configurar el valor según corresponda.
- MODULE y VERSION se muestran en Google Cloud Console como MODULE - VERSION. Por ejemplo: MyApp - v1.0 o Backend - build_147.
- La variable de entorno GOOGLE_APPLICATION_CREDENTIALS se puede usar en lugar de agregar la propiedad del sistema auth.serviceaccount.jsonfile.
Nota: Ve a las prácticas recomendadas para administrar claves de cuentas de servicio a fin de conocer las prácticas recomendadas para las claves administradas por el usuario.

Ahora puedes usar Debugger con tu app.

En la página de Depuración en Google Cloud Console, se pueden mostrar los archivos de origen local, sin subir, para el desarrollo local. Consulta Selecciona el código fuente de forma manual.