Instantáneas de depuración

Una vez que implementaste o iniciaste tu app, puedes abrir Cloud Debugger en Google Cloud Console. Debugger te permite capturar y, también, inspeccionar la pila de llamadas y las variables locales en tu app sin detenerla ni ralentizarla.

Visita la página de Depuración de Cloud Console para usar Debugger.

Antes de comenzar

Debugger se puede usar con o sin acceso al código fuente de tu app. Si tu código fuente no está disponible, consulta Toma una instantánea de depuración a continuación para obtener instrucciones sobre cómo ingresar el nombre del archivo y el número de línea de forma manual.

Para acceder al código fuente que está almacenado de forma local o en un repositorio de Git, es posible que tengas que seleccionar una ubicación de código fuente.

Instantáneas

Las instantáneas capturan variables locales y la pila de llamadas en una ubicación de línea específica en el código fuente de tu app. Puedes especificar ciertas condiciones y ubicaciones para mostrar una instantánea de los datos de la app y verla en detalle a fin de depurarla.

Agente de Debugger con canary

Después de configurar una instantánea, el agente de Debugger prueba la instantánea en un subconjunto de tus instancias. Después de que el agente de Debugger verifica que la instantánea pueda ejecutarse de forma correcta, la instantánea se aplica a todas tus instancias. Esto tarda unos 40 segundos.

Después de este proceso, cuando se activa la instantánea, los resultados aparecen en los paneles Variables y Pila de llamadas. Si la instantánea se activa dentro de los 40 segundos posteriores a la configuración, verás los resultados de esas instancias en las que se aplicó la instantánea canary.

El agente de Debugger implementa varias estrategias para minimizar la cantidad de latencia generada cuando se capturan los datos.

Verás lo siguiente mientras el agente de Debugger realiza la actualización canary:

El agente de Debugger realiza actualizaciones canary de instancias

Para obtener información sobre qué hacer si el agente de Debugger falla en el modo de Canary, ve a la sección de solución de problemas en la página de instantáneas de depuración.

Para conocer qué versiones del agente de Debugger tienen la funcionalidad canary, consulta las páginas específicas del lenguaje.

Agente de Debugger sin canary

Cuando usas el agente de Debugger sin canary y configuras una instantánea, se aplica a todas las instancias en ejecución de tu app. La primera vez que una instancia ejecuta el código en la ubicación de la instantánea, el agente de Debugger toma una instantánea y la pone a disposición para su visualización. El agente de Debugger implementa varias estrategias para minimizar la cantidad de latencia generada cuando se capturan los datos.

Toma una instantánea de depuración

Console

Haz clic en el número de línea del código fuente para tomar una instantánea en esa ubicación.

  1. Asegúrate de que el panel Snapshot (Instantánea) esté seleccionado en el panel derecho.
  2. En el panel izquierdo, selecciona el archivo que contiene el código fuente que deseas mirar. El contenido del archivo seleccionado se muestra en el panel central.
  3. Haz clic en el número de línea de la ubicación del código fuente.

Navega a una ubicación de instantánea

Puedes hacer clic en varias líneas para configurar más de una ubicación de instantánea en un archivo.

Consulta la sección Opciones del código fuente para conocer otras formas de cargar tu código fuente en Debugger.

Si no hay un código fuente disponible, puedes ingresar la línea de nombre de archivo de forma manual para tomar una instantánea en el panel Instantánea (Snapshot):

Configurar una ubicación de instantánea manualmente

gcloud

Para configurar una ubicación de instantánea desde la línea de comandos:

gcloud debug snapshots create LOCATION

Aquí:

  • LOCATION es el nombre del archivo y la línea en la que se configura la instantánea. El formato es FILE:LINE. FILE puede ser el nombre del archivo o el nombre del archivo precedido por suficientes componentes de la ruta de acceso como para diferenciarlos de otros archivos con el mismo nombre. Es un error proporcionar un nombre de archivo que no sea único en el destino de depuración.

Condiciones de las instantáneas (opcional)

Una condición de instantánea es una expresión simple en el lenguaje de la aplicación (Java, Python y Go son compatibles) que debe evaluarse como verdadera para que se tome la instantánea. Las condiciones de la instantánea se evalúan cada vez que una instancia ejecuta la línea hasta que se evalúe como verdadera o se agote el tiempo de la instantánea.

El uso de las condiciones de instantáneas es opcional.

La condición es una expresión booleana completa que puede incluir operadores lógicos:

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

Console

Para especificar la condición, ingrésala en el campo Condición (Condition) en el panel Instantánea (Snapshot).

Configura una condición de instantánea

gcloud

Las condiciones se especifican con la marca --condition de snapshots create:

gcloud debug snapshots create LOCATION --condition="ultimateAnswer <= 42 && foo==bar"

Puedes usar las siguientes funciones de lenguaje para expresar condiciones:

Java

Se admiten la mayoría de las expresiones de Java, incluidas las siguientes opciones:
  • Variables locales: a == 8.
  • Operaciones numéricas y booleanas: x + y < 20.
  • Instancia y campos estáticos: this.counter == 20, this.myObj.isShutdown, myStatic o com.mycompany.MyClass.staticMember.
  • Comparaciones de strings con el operador de igualdad: myString == "abc".
  • Llamadas a la función. Solo se pueden usar funciones de solo lectura. Por ejemplo, se admite StringBuilder.indexOf(), pero no StringBuilder.append().
  • Conversión de tipos, con tipos completamente calificados: ((com.myprod.ClassImpl) myInterface).internalField

No se admiten las siguientes funciones de lenguaje:

  • La extracción de tipos numéricos, como Integer; debes usar myInteger.value en su lugar.

Python

Se admiten la mayoría de las expresiones de Python, incluidas las siguientes opciones:
  • Lectura de variables locales y globales
  • Lectura de arreglos, listas, segmentos, diccionarios y objetos
  • Llamada de métodos sencillos

No se admiten las siguientes funciones de lenguaje:

  • Llamada a funciones que asignan objetos nuevos o usan construcciones complejas
  • Creación de objetos nuevos dentro de la expresión

Go

Se admite la mayoría de las sintaxis de expresión de Go, incluidas las siguientes opciones:
  • Lectura de variables locales y globales
  • Lectura de arreglos, segmentos, mapas y estructuras

No se admiten las siguientes funciones de lenguaje:

  • Lectura de valores de interfaz
  • Tipo de conversiones y literales de composición
  • Llamadas a funciones que no sean len

Expresiones (opcional)

La función Expresiones de Debugger te permite evaluar expresiones complejas o recorrer jerarquías de objetos cuando se toma una instantánea. Las expresiones admiten las mismas funciones de lenguaje que las condiciones de instantáneas, que se describieron arriba.

El uso de expresiones es opcional.

A continuación, se describen los usos típicos de las expresiones:

  • Para ver variables estáticas o globales que no forman parte del conjunto de variables locales.
  • Para ver con facilidad las variables de miembro profundamente anidadas sin tener que expandir cada vez una variable local en el panel de Debugger.
  • Para evitar cálculos matemáticos repetitivos. Por ejemplo, el cálculo de una duración en segundos con (endTimeMillis - startTimeMillis) / 1000.0.

Para agregar una expresión:

Console

  1. Ingresa la expresión en el campo Expressions (Expresiones). Presiona la tecla de tabulación para agregar expresiones adicionales.
  2. Presiona la tecla Intro o el botón Instantánea (Snapshot).Botón de instantánea

El resultado de la expresión se muestra cuando se toma la instantánea.

Configura una expresión

gcloud

Las expresiones se definen con la marca --expression de snapshots create:

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

Observa una instantánea

Console

Los datos de la instantánea aparecen en Debugger cuando la app ejecuta el código fuente en la ubicación que especificaste. Las variables de la instancia y las locales aparecen en la sección Variables (Variables) del panel. El seguimiento de pila aparece en la sección Pila de llamadas (Call Stack) del panel.

Ver instantánea

Puedes examinar el valor de las variables locales en el momento en que se tomó la instantánea y desglosar en estructuras de datos más profundas. También puedes hacer clic en cualquier marco de pila de llamadas y examinar las variables locales en ese nivel en la pila.

Si estableciste varias ubicaciones de instantáneas en un archivo, o para ver las instantáneas que ya tomaste, expande el panel Snapshot History (Historial de instantáneas):

gcloud

A fin de recuperar la URL de Cloud Console de una instantánea desde la línea de comandos, sigue estos pasos:

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE  HighScoreService.java:105                             53bd97d4-b6c6-74fc  https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

Copia y pega el valor de la columna VIEW en tu navegador para ver la instantánea en Cloud Console.

Para ver los datos detallados de la instantánea desde la línea de comandos, sigue estos pasos:

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

Con el comando describe, se muestran el seguimiento de pila y los valores de las variables locales, y está pensado en esencia con el fin de que lo pueda leer las máquinas, en lugar de las personas.

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

Vuelve a tomar una instantánea

Una instantánea se toma solo una vez. Si deseas tomar otra instantánea de los datos de la aplicación en la misma ubicación, puedes volver a tomarla de forma manual.

Console

Para volver a tomar una instantánea, haz clic en el ícono de la cámara en la parte superior derecha del panel Instantánea (Snapshot):

Botón de instantánea

La nueva instantánea se agrega al panel Historial de instantáneas (Snapshot History). Se puede acceder a las instantáneas anteriores en esa línea desde Historial de instantáneas (Snapshot History) o desde el marcador en ese número de línea:

Instantáneas anteriores mostradas en el marcador de línea

gcloud

Para volver a tomar una instantánea desde la línea de comandos, repite el comando create que usaste al principio:

gcloud debug snapshots create LOCATION

Quita una ubicación de instantánea

Console

Para quitar una ubicación de instantánea, haz clic en la X en el marcador de instantáneas.

Ícono de instantánea

gcloud

Para borrar una instantánea de la línea de comandos:

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

Aquí:

  • ID es el valor que muestra gcloud debug snapshots list.

  • LOCATION-REGEXP es una expresión regular que define la ubicación del código de las instantáneas.

Comparte instantáneas

Puedes compartir una instantánea con otro miembro del proyecto si copias la URL de la instantánea de tu navegador o desde la salida del comando de gcloud debug snapshots list y se la compartes a otro usuario que tenga acceso a tu proyecto. También puedes guardar esta URL para referencias futuras y volver a verla a fin de ver sus resultados. Debugger usa una URL nueva para cada instantánea que se toma. Esto te permite compartir distintos conjuntos de resultados, incluso si se capturaron en la misma ubicación del código. El uso compartido caduca después de los 30 días desde que se tomó la instantánea.

Soluciona problemas

¿El agente de Debugger bloqueó las instancias?

Es posible que veas el siguiente error si el agente de Debugger falla:

El panel Variables muestra un mensaje de error

Puedes obtener falsos positivos que hacen que parezca que el agente de Debugger activó sus protecciones por los siguientes motivos:

  • Se cerró una instancia mientras el agente de Debugger realizaba una actualización canary.

    Cuando una instancia que tiene una instantánea de detección de fallos aplicada se cierra, aparece como el agente de Debugger que finalizó la instancia. Verifica que no se apaguen instancias dentro de los 40 segundos posteriores a la configuración de la instantánea. Por ejemplo, el ajuste de escala automático desde Cloud Run y App Engine, o la implementación de código nuevo pueden ser razones por las que se cierran las instancias.

Debes quitar el agente de Debugger de tus instancias y volver a instalar la versión anterior. Para volver a instalar la versión anterior, sigue las instrucciones de configuración para instalar la versión anterior del agente de Debugger.

Si el problema persiste con la versión anterior del agente, verifica que no sea un falso positivo, luego inhabilita el agente de Debugger y envía comentarios.