Configura Cloud Trace para Node.js

Resumen

En esta página, se describe cómo configurar el entorno y la aplicación de Node.js para usar el Depurador de Cloud. 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 Node.js 6 y versiones posteriores 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 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

Instantáneas y puntos de registro versión canary

El agente de Debugger para Node.js 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.

App Engine

  1. Usa npm para instalar el paquete:

    npm install --save @google-cloud/debug-agent
    
  2. Habilita el agente en la parte superior de la secuencia de comandos principal o el punto de entrada de tu app (pero después de @google/cloud-trace, si también lo usas):

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

    Para depurar con canary no habilitado, establece enableCanary en false:

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
    

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.

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 la línea siguiente a tu Dockerfile con el fin de agregar el agente de Debugger:

    RUN  npm install --save @google-cloud/debug-agent
    
  3. Habilita el agente en la parte superior de la secuencia de comandos principal o el punto de entrada de tu app (pero después de @google/cloud-trace, si también lo usas):

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

    Para depurar con canary no habilitado, establece enableCanary en false:

    enableCanary: false
    

    En el comando anterior, se muestra lo siguiente:

    • SERVICE es el nombre de tu app, como MyApp, Backend o Frontend.
    • VERSION es una versión, como v1.0, build_147 o v20170714.

    Recomendamos configurarlas desde las variables de entorno para que no tengas que cambiar el código fuente con cada implementación.

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 Google Cloud Console, sigue estos pasos:

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

  2. Habilita Debugger.

    La API de Debugger está habilitada para el clúster.

  3. Opcional: Seleccione Permitir el acceso completo a todas las API de Cloud.

  4. Agrega la línea siguiente a tu Dockerfile con el fin de agregar el agente de Debugger:

        RUN  npm install --save @google-cloud/debug-agent
    
  5. Habilita el agente en la parte superior de la secuencia de comandos principal o el punto de entrada de tu app (pero después de @google/cloud-trace, si también lo usas):

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

    Para depurar con canary no habilitado, establece enableCanary en false:

    enableCanary: false
    

    En el comando anterior, se muestra lo siguiente:

    • SERVICE es el nombre de tu app, como MyApp, Backend o Frontend.
    • VERSION es una versión, como v1.0, build_147 o v20170714.

    Recomendamos configurarlas desde las variables de entorno para que no tengas que cambiar el código fuente con cada implementación.

Compute Engine

  1. Asegúrate de que tus instancias 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
  2. Usa npm para instalar el paquete:

    npm install --save @google-cloud/debug-agent
    
  3. Habilita el agente en la parte superior de la secuencia de comandos principal o el punto de entrada de tu app (pero después de @google/cloud-trace, si también lo usas):

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

    Para depurar con canary no habilitado, establece enableCanary en false:

    enableCanary: false
    

    En el comando anterior, se muestra lo siguiente:

    • SERVICE es el nombre de tu app, como MyApp, Backend o Frontend.
    • VERSION es una versión, como v1.0, build_147 o v20170714.

    Recomendamos configurarlas desde las variables de entorno para que no tengas que cambiar el código fuente con cada implementación.

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.

Cloud Run y Cloud Run para Anthos en Google Cloud

  1. Usa npm para instalar el paquete:

    npm install --save @google-cloud/debug-agent
    
  2. Habilita el agente en la parte superior de la secuencia de comandos principal o el punto de entrada de su app (pero después de @google/cloud-trace, si también lo usas):

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

    Para depurar con canary no habilitado, establece enableCanary en false:

    enableCanary: false
    

    Puedes usar el depurador cuando implementes tu app.

En el entorno local y en otros lugares

  1. Usa npm para instalar el paquete:

    npm install --save @google-cloud/debug-agent
    
  2. Descarga las credenciales de la cuenta de servicio.

    Con el propósito de usar el agente del Depurador de Cloud para Node.js 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 de 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 de Cloud Debugger Agent.

  3. Configura y habilita al agente con las credenciales descargadas:

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

    require('@google-cloud/debug-agent').start({
      projectId: 'your-project-id',
      keyFilename: '/path/to/key.json',
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

    Para depurar con canary no habilitado, establece enableCanary en false:

    enableCanary: false
    

    En el comando anterior, se muestra lo siguiente:

    • SERVICE es el nombre de tu app, como MyApp, Backend o Frontend.
    • VERSION es una versión, como v1.0, build_147 o v20170714.

    Recomendamos configurarlas desde las variables de entorno para que no tengas que cambiar el código fuente con cada implementación.

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.