Configura Cloud Debugger para Python

Alfa

Esta biblioteca está cubierta por las Condiciones de las Ofertas de Fase Previa a la DG de las Condiciones del Servicio de Google Cloud. Es posible que las bibliotecas de fase previa a la DG tengan asistencia limitada, y los cambios en las bibliotecas que se encuentren en fase previa a la DG podrían no ser compatibles con otras versiones en fase previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Descripción general

En esta página se describe cómo configurar el entorno y la aplicación de PHP 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 Cloud Debugger está disponible para Python 3 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:

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

Nota: Cloud Debugger es de uso gratuito. Sin embargo, necesitas un proyecto de Google Cloud con la facturación habilitada antes de que puedas usar 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.

Nota: La prueba canary está disponible para la versión 2.15 y posteriores del agente de Debugger para Python.

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

Python 3.7 o Python 3.8

Si usas Python 3.7 o Python 3.8, debes habilitar el agente de Debugger de forma manual mediante los siguientes pasos:

1. Asegúrate de que tu archivo app.yaml contenga las líneas siguientes:

   runtime: python37
   or
   runtime: python38
   

2. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal, o en manage.py cuando usas el marco de trabajo web de Django (solo en versión 1.*).

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
       breakpoint_enable_canary=True
     )
   except ImportError:
     pass
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

    breakpoint_enable_canary=False
   

3. Agregar google-python-cloud-debugger a requirements.txt.

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

Ahora puedes usar Debugger con tu app.

Entorno flexible de App Engine

Puedes utilizar el depurador con el entorno de ejecución de Python o el entorno de ejecución personalizado de App Engine.

1. Asegúrate de que tus instancias de VM del entorno flexible de App Engine estén ejecutando:

   • Una imagen de Debian Linux de 64 bits
   • Python 3

2. Asegúrate de que tu archivo app.yaml contenga las líneas siguientes:

   runtime: python
   env: flex
   

   Si usas un entorno de ejecución personalizado, usa runtime: custom.

3. Agregar google-python-cloud-debugger a requirements.txt.

4. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal, o en manage.py cuando usas el marco de trabajo web de Django (solo en versión 1.*).

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
       breakpoint_enable_canary=True
     )
   except ImportError:
     pass
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

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

Ahora puedes usar Debugger con tu app.

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
   

   Nota: No puedes cambiar los permisos de acceso de un clúster después de su creación.

2. Agrega el paquete de Debugger a tu app:

   Si usas un archivo requirements.txt, agrega la línea siguiente:

     google-python-cloud-debugger
   

   Si usas un Dockerfile, agrega la línea siguiente:

     RUN pip install google-python-cloud-debugger
   

3. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal o en manage.py cuando uses el marco de trabajo web de Django:

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

     try:
       import googleclouddebugger
       googleclouddebugger.enable(
         breakpoint_enable_canary=True
       )
     except ImportError:
       pass
   

   Para depurar con la versión canary NO habilitada, establece el parámetro breakpoint_enable_canary en False:

     breakpoint_enable_canary=False
   

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.

CONSOLE

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

1. En la sección Grupos de nodos, selecciona Seguridad y, luego, Configurar acceso para cada API.

2. Habilita Debugger.

   

3. Opcional: Selecciona Permitir el acceso total a todas las API de Cloud.

4. Agrega el paquete de Debugger a tu app:

   Si usas un archivo requirements.txt, agrega la línea siguiente:

   google-python-cloud-debugger
   

   Si usas un Dockerfile, agrega la línea siguiente:

   RUN pip install google-python-cloud-debugger
   

5. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal o en manage.py cuando uses el marco de trabajo web de Django:

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
       breakpoint_enable_canary=True
     )
   except ImportError:
     pass
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

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.

Compute Engine

1. Asegúrate de que tus instancias de VM de Compute Engine estén ejecutando:

   • Una imagen de Debian Linux de 64 bits
   • Python 3

2. Asegúrate de que tus instancias de VM de Compute Engine se creen con la opción de nivel de acceso Permitir el acceso total 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 agente de Debugger.

   La manera sencilla de instalar el Debugger de Python es con pip:

   pip install google-python-cloud-debugger
   

4. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal, o en manage.py cuando uses el marco de trabajo web Django.

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
       module='[MODULE]',
       version='[VERSION]'
       breakpoint_enable_canary=True
     )
   except ImportError:
     pass
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

   Si no puedes cambiar el código, ejecuta el agente de Debugger como un módulo.

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

   python -m googleclouddebugger \
         --module=[MODULE] \
         --version=[VERSION] \
         --breakpoint_enable_canary=True
         -- \
         myapp.py
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

   Nota: Cuando ejecutas Debugger como módulo, el valor de --breakpoint_enable_canary es una string. Cualquier valor que no sea True, se trata como False.

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

   • [MODULE] es el nombre de tu aplicación.
     Esto, junto con la versión, se usa para identificar el destino de depuración en la página Depuración de Google Cloud Console.
     Ejemplos: MyApp, Backend o Frontend.
   • [VERSION] es la versión de la app (por ejemplo, el ID de compilación).
     La página Depuración de Google Cloud Console muestra la versión en ejecución como [MODULE] - [VERSION].
     Valores de ejemplo: v1.0, build_147 o v20170714.

Ahora puedes usar Debugger con tu app.

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.

Cloud Run y Cloud Run for Anthos

1. Paquete de Python.

   Si usas un archivo requirements.txt, agrega la línea siguiente:

   google-python-cloud-debugger
   

   Si no, agrega la línea siguiente a tu Dockerfile:

   RUN pip install google-python-cloud-debugger
   

2. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal o en manage.py cuando uses el marco de trabajo web de Django:

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
       breakpoint_enable_canary=True
     )
   
   except ImportError:
     pass
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

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

1. Asegúrate de que tu estación de trabajo esté ejecutando:

   • Una imagen de Debian Linux de 64 bits
   • Python 3

2. Descarga el agente de Debugger.

   La manera sencilla de instalar el Debugger de Python es con pip:

   pip install google-python-cloud-debugger
   

3. Descarga las credenciales de la cuenta de servicio.
   

   Con el propósito de usar el agente del Depurador de Cloud para Python en máquinas que no aloja Google Cloud, el agente debe usar las credenciales de una cuenta de servicio de Google Cloud para autenticarse con el servicio del Depurador de Cloud.

   Usa la página 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 Python.

4. Agrega las líneas siguientes lo antes posible en tu código de inicialización, como en la función principal, o en manage.py cuando usas el marco de trabajo web de Django.

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

   try:
     import googleclouddebugger
     googleclouddebugger.enable(
         module='[MODULE]',
         version='[VERSION]',
         breakpoint_enable_canary=True
         service_account_json_file='/opt/cdbg/gcp-svc.json')
   except ImportError:
     pass
   

   Para depurar con la versión canary NO habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

   Si no puedes cambiar el código, ejecuta el agente de Debugger como un módulo.

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

   python \
       -m googleclouddebugger \
       --module=[MODULE] \
       --version=[VERSION] \
       --breakpoint_enable_canary=True
       --service_account_json_file=/opt/cdbg/gcp-svc.json \
       -- \
       myapp.py
   

   Para depurar con la versión canary no habilitada, establece el parámetro breakpoint_enable_canary en False:

   breakpoint_enable_canary=False
   

   Nota: Cuando ejecutas Debugger como módulo, el valor de --breakpoint_enable_canary es una string. Cualquier valor que no sea True, se trata como False.

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

   • [MODULE] es el nombre de tu aplicación.
     Esto, junto con la versión, se usa para identificar el destino de depuración en la página Depuración de Google Cloud Console.
     Ejemplos: MyApp, Backend o Frontend.
   • [VERSION] es la versión de la app (por ejemplo, el ID de compilación).
     La página Depuración de Google Cloud Console muestra la versión en ejecución como [MODULE] - [VERSION].
     Valores de ejemplo: v1.0, build_147 o v20170714.
   • Se puede usar la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, en lugar de especificar service_account_json_file.

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.

Nota: Puedes buscar el código y la documentación del agente de Debugger en GitHub.