Configura Cloud Trace para Node.js

Descripción general

Nota: Cloud Debugger es compatible con Node.js 9 y versiones posteriores. Recomendamos usar la versión de asistencia a largo plazo.

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

Beta

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.

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.

   Nota: Por motivos de rendimiento, el agente de Cloud Debugger para Node.js no admite la adición de instantáneas o puntos de registro en archivos del directorio node_modules.

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 el agente de Node.js Debugger versión 5.1.0 y posteriores.

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

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

   Aquí:

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

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

   Aquí:

   • 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
   

   Aquí:

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

   Aquí:

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