Configura el Depurador de Cloud para Java

Resumen

En esta página, se describe cómo configurar el entorno y la aplicación de Java para usar el Depurador de Cloud. Para algunos entornos, debes especificar de forma explícita el nivel de acceso a fin de permitir que el agente del Depurador de Cloud envíe datos. 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

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

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

Configura el Depurador de Cloud

Para configurar el Depurador de Cloud, completa las siguientes tareas:

  1. Verifica que la API del Depurador de Cloud esté habilitada para tu proyecto.

  2. Instala y configura Debugger en el entorno de procesamiento que usas.

  3. Selecciona tu código fuente.

Verifica que la API de Cloud Debugger esté habilitada

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

Instantáneas y puntos de registro versión canary

El agente de Debugger para Java puede usar instantáneas y puntos de registro de canary cada vez que configuras una instantánea o punto de registro.

El agente de Debugger puede realizar actualizaciones canary de instantáneas y puntos de registro para proteger grandes trabajos de cualquier posible error en el agente de Debugger que puede quitar todo el trabajo cuando se aplica una instantánea o un punto de registro.

Para mitigar esto, Debugger puede realizar actualizaciones canary de instantáneas y puntos de registro en un subconjunto de tus instancias en ejecución cada vez que se configuran. Después de que Debugger verifica que la instantánea o el punto de registro no afecta de manera adversa a tus instancias en ejecución, aplica la instantánea o el punto de registro 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 Cloud Console, se mostrarán los archivos fuente de Java que se usaron para compilar la app.

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 Cloud Console, se mostrarán 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 Cloud Console, se mostrarán los archivos fuente de Java que se usaron para compilar la app.

Para usar el Depurador de Cloud 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:

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

  3. 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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

    • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

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

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

CONSOLE

Para habilitar Debugger con la consola, completa los pasos siguientes:

  1. Después de seleccionar tu tipo de clúster, haz clic en Más opciones en el panel de Grupos de nodos:

    Campo de grupo de nodos que muestra el botón Más opciones encerrado en un rectángulo rojo.

  2. Selecciona una de las opciones siguientes del panel de Seguridad:

    • Permitir el acceso total a todas las API de Cloud

    • Permitir el acceso a cada API y, luego, seleccionar Habilitada para el Depurador de Cloud

  3. 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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

    • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

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

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

Compute Engine

Puedes usar el Depurador de Cloud con cualquier aplicación 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.

  1. 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
  2. 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
  3. 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 con 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.

  4. 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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

    • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

Ahora puedes usar Debugger con tu app.

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

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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

  • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

  • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

  • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

Cloud Run y Cloud Run para Anthos en Google Cloud

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

    Localiza la invocación de Java y agrega la marca siguiente 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 en la página de Depuración en Cloud Console se muestre de forma automática el código fuente que coincide con la app implementada, consulta la sección Selecciona el código fuente de forma automática.

Debugger ya está listo para usar.

En el entorno local y en otros lugares

  1. 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
    
  2. 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 Cuentas de servicio de 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.

  3. 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. Junto con la versión, este identifica la app en Cloud Console. Ejemplos: MyApp, Backend o Frontend.

    • VERSION es la versión de la app (p. ej., el ID de compilación). Cloud Console muestra la app en ejecución como MODULE - VERSION. Ejemplos: v1.0, build_147 o v20160520.

    • La variable de entorno GOOGLE_APPLICATION_CREDENTIALS se puede usar en lugar de agregar la propiedad del sistema auth.serviceaccount.jsonfile.

Ahora puedes usar Debugger con tu app.

En la página de Depuración en 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.