Instantáneas de depuración

Después de implementar o iniciar 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 de 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 instancias. Después de que el agente de Debugger verifique que la instantánea se puede ejecutar correctamente, esta se aplicará a todas tus instancias. El proceso demora unos 40 segundos.

Después de este proceso, cuando se activa la instantánea, los resultados aparecen en los paneles Variables y Call Stack. Si la instantánea se activa dentro de los 40 segundos posteriores a la configuración, verás los resultados de esas instancias que tenían la instantánea canary aplicada.

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

El siguiente texto se muestra cuando el agente de Debugger ejecuta una versión canary:

“Verificando la interrupción en un subconjunto de instancias de aplicaciones”.

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 de la versión 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 Instantánea esté seleccionado.
  2. Selecciona el archivo que contiene el código fuente. 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.

    Busca 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 de forma manual filename:line para tomar una instantánea en el panel Snapshot (Instantánea):

Establece una ubicación de instantánea de forma manual.

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 el punto de registro. 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, crea una instantánea. En el campo Condición, ingresa una condición y, luego, selecciona Actualizar. Si la condición se evalúa como verdadera, se activa la instantánea.

Establece 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

Comienza a usarlo

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 Expresiones (Expressions). Puedes agregar todas las expresiones que necesites.
  2. Selecciona Volver a tomar.

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

Ver 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, selecciona Volver a tomar:

Se seleccionó el botón para volver a tomar la foto.

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:

Se muestran instantáneas anteriores 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

Haz clic en Borrar para quitar una ubicación de instantánea.

Quitar la instantánea seleccionada.

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 si copias la URL de la instantánea desde tu navegador o desde el resultado del comando gcloud debug snapshots list y se la entregas 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 falló mis instancias?

Es posible que veas el siguiente error si el agente de Debugger está defectuoso:

El panel Variables muestra el mensaje de error.

Podrías obtener falsos positivos que hagan 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 canary aplicada a ella se cierra, parece que el agente de Debugger finalizó la instancia. Verifica que no se hayan apagado las 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 un código nuevo pueden ser la razón por la que se apagan las instancias.

Debes quitar el agente de Debugger de tus instancias y reinstalar la versión anterior. A fin de reinstalar 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 y, luego, inhabilita el agente de Debugger y envía comentarios.