Configura Cloud Logging para Node.js

En el caso de las aplicaciones de Node.js, los complementos se mantienen para las bibliotecas de registro populares Winston y Bunyan. Winston es una biblioteca de uso general que implementa una variedad de transportes y formateadores de registro. Bunyan, que se especializa en registros JSON estructurados, admite el formato de registro a través de la canalización a la línea de comandos de Bunyan.

También puedes usar la biblioteca cliente de Logging para Node.js directamente o crear tus propias integraciones con la biblioteca de registro que prefieras. Por ejemplo, puedes usar el ejemplo del framework de registro de Pino.

No es necesario que el agente de Logging esté instalado para usar Winston o Bunyan en una instancia de máquina virtual (VM) de Compute Engine.

Antes de comenzar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Logging API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud Logging API.

   Enable the API

8. Prepara el entorno para el desarrollo en Node.js.

   Ir a la guía de configuración de Node.js

Configura el registro

En esta sección, se describe cómo instalar y configurar los complementos de las bibliotecas de registro Winston y Bunyan. En el caso de Bunyan, se proporciona información para usarlo con una aplicación Express de Node.js.

Puedes usar otras bibliotecas o frameworks. Por ejemplo, puedes usar el framework de registro de Pino. Si deseas ver un código de muestra que usa OpenTelemetry para recopilar métricas y datos de seguimiento, y el framework de registro de Pino para recopilar datos de registro, consulta Genera seguimientos y métricas con Node.js. Si usas Pino, debes implementar una asignación entre los niveles de gravedad de Pino y los que usa Cloud Logging. Para obtener ejemplos de código, consulta Cómo asignar niveles de registro de Pino.

Instala y configura el complemento Winston

Cloud Logging proporciona un complemento destinado a la biblioteca Winston de Logging para Node.js. El complemento de Logging para Winston proporciona una capa más simple y de nivel superior a fin de trabajar con Logging.

Para instalar y configurar el complemento Winston, haz lo siguiente:

1. Para instalar el complemento LoggingWinston, usa npm:

   npm install --save @google-cloud/logging-winston winston

2. Importa el complemento y agrégalo a tu configuración de Winston:

   const winston = require('winston');
   
   // Imports the Google Cloud client library for Winston
   const {LoggingWinston} = require('@google-cloud/logging-winston');
   
   const loggingWinston = new LoggingWinston();
   
   // Create a Winston logger that streams to Cloud Logging
   // Logs will be written to: "projects/YOUR_PROJECT_ID/logs/winston_log"
   const logger = winston.createLogger({
     level: 'info',
     transports: [
       new winston.transports.Console(),
       // Add Cloud Logging
       loggingWinston,
     ],
   });
   
   // Writes some log entries
   logger.error('warp nacelles offline');
   logger.info('shields at 99%');

3. Configura el complemento.

   Puedes personalizar el comportamiento del complemento Winston con las mismas opciones de configuración compatibles con la biblioteca cliente de Cloud de la API de Cloud Logging para Node.js. Estas opciones se pueden pasar en el objeto options que se pasa al constructor del complemento.

Instala y configura el complemento Bunyan

Cloud Logging proporciona un complemento para la biblioteca de Logging de Node.js de Bunyan. El complemento de Logging para Bunyan proporciona una capa más simple y de nivel superior a fin de trabajar con Logging.

Para instalar y configurar el complemento Bunyan, haz lo siguiente:

1. Para instalar el complemento de Bunyan de Logging, usa npm:

   npm install --save bunyan @google-cloud/logging-bunyan

2. Importa el complemento y agrégalo a tu configuración de Bunyan:

   const bunyan = require('bunyan');
   
   // Imports the Google Cloud client library for Bunyan
   const {LoggingBunyan} = require('@google-cloud/logging-bunyan');
   
   // Creates a Bunyan Cloud Logging client
   const loggingBunyan = new LoggingBunyan();
   
   // Create a Bunyan logger that streams to Cloud Logging
   // Logs will be written to: "projects/YOUR_PROJECT_ID/logs/bunyan_log"
   const logger = bunyan.createLogger({
     // The JSON payload of the log as it appears in Cloud Logging
     // will contain "name": "my-service"
     name: 'my-service',
     streams: [
       // Log to the console at 'info' and above
       {stream: process.stdout, level: 'info'},
       // And log to Cloud Logging, logging at 'info' and above
       loggingBunyan.stream('info'),
     ],
   });
   
   // Writes some log entries
   logger.error('warp nacelles offline');
   logger.info('shields at 99%');

3. Configura el complemento.

   Puedes personalizar el comportamiento del complemento Bunyan con las mismas opciones de configuración compatibles con la biblioteca cliente de Cloud de la API de Cloud Logging para Node.js. Estas opciones se pueden pasar en el objeto options que se pasa al constructor del complemento.

Usa Bunyan y Express

Puedes configurar y usar Bunyan con Logging en una aplicación Express de Node.js.

// Imports the Google Cloud client library for Bunyan.
const lb = require('@google-cloud/logging-bunyan');

// Import express module and create an http server.
const express = require('express');

async function startServer() {
  const {logger, mw} = await lb.express.middleware({
    logName: 'samples_express',
  });
  const app = express();

  // Install the logging middleware. This ensures that a Bunyan-style `log`
  // function is available on the `request` object. This should be the very
  // first middleware you attach to your app.
  app.use(mw);

  // Setup an http route and a route handler.
  app.get('/', (req, res) => {
    // `req.log` can be used as a bunyan style log method. All logs generated
    // using `req.log` use the current request context. That is, all logs
    // corresponding to a specific request will be bundled in the Stackdriver
    // UI.
    req.log.info('this is an info log message');
    res.send('hello world');
  });

  const port = process.env.PORT || 8080;

  // `logger` can be used as a global logger, one not correlated to any specific
  // request.
  logger.info({port}, 'bonjour');

  // Start listening on the http server.
  const server = app.listen(port, () => {
    console.log(`http server listening on port ${port}`);
  });

  app.get('/shutdown', (req, res) => {
    res.sendStatus(200);
    server.close();
  });
}

startServer();

Para obtener más información sobre la instalación, consulta la documentación de las bibliotecas de Cloud Logging para Node.js. También puedes informar problemas con el seguimiento de problemas.

Cómo escribir registros con la biblioteca cliente de Cloud Logging

Si quieres obtener información sobre cómo usar directamente la biblioteca cliente de Cloud Logging para Node.js, consulta Bibliotecas cliente de Cloud Logging.

Ejecuta en Google Cloud

Para que una aplicación escriba registros con las bibliotecas de Cloud Logging para Node.js, la cuenta de servicio del recurso subyacente debe tener el rol de IAM Escritor de registros (roles/logging.logWriter). La mayoría de los entornos de Google Cloud configuran automáticamente la cuenta de servicio predeterminada para que tenga este rol.

App Engine

Cloud Logging se habilita automáticamente para App Engine, y la cuenta de servicio predeterminada de tu app tiene los permisos de IAM de forma predeterminada para escribir entradas de registro.

Para escribir entradas de registro desde tu app, te recomendamos que uses Bunyan o Winston como se describe en esta página.

Para obtener más información, consulta Escribe y visualiza registros.

Google Kubernetes Engine (GKE)

GKE otorga automáticamente a la cuenta de servicio predeterminada el rol de IAM Escritor de registros (roles/logging.logWriter). Si usas Workload Identity Federation for GKE con esta cuenta de servicio predeterminada para permitir que las cargas de trabajo accedan a APIs específicas de Google Cloud, no se requiere ninguna configuración adicional. Sin embargo, si usas Workload Identity Federation for GKE con una cuenta de servicio de IAM personalizada, asegúrate de que la cuenta de servicio personalizada tenga el rol de escritor de registros (roles/logging.logWriter).

Si es necesario, también puedes usar el siguiente comando para agregar el permiso de acceso logging.write cuando creas el clúster:

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

Nota: Si quieres usar las bibliotecas de Cloud Logging para Node.js en una instancia de VM de Compute Engine, no necesitas instalar el agente de Cloud Logging.

Cuando uses las instancias de VM de Compute Engine, agrega el permiso de acceso cloud-platform a cada instancia. Cuando crees una instancia nueva a través de la consola de Google Cloud, puedes hacerlo en la sección Identidad y acceso a la API del panel Crear instancia. Usa la cuenta de servicio predeterminada de Compute Engine o una cuenta de servicio diferente y selecciona Permitir acceso total a las API de Cloud en la sección Identidad y acceso a la API. Asegúrate de que la cuenta de servicio que selecciones tenga la función de escritor de registros en la sección IAM y administración de la consola de Google Cloud.

Funciones de Cloud Run

Las funciones de Cloud Run otorgan el rol de escritor de registros de forma predeterminada.

Las bibliotecas de Cloud Logging para Node.js se pueden usar sin necesidad de proporcionar credenciales de forma explícita.

Las funciones de Cloud Run están configuradas para usar Cloud Logging automáticamente.

Nota: Los registros que se escriben en stdout y stderr se envían de forma automática a Cloud Logging sin la necesidad de usar las bibliotecas de Cloud Logging para Node.js.

Ejecuta de forma local y en otros lugares

Para usar las bibliotecas de Cloud Logging para Node.js fuera de Google Cloud, incluso ejecutar la biblioteca en tu propia estación de trabajo, en las computadoras de tu centro de datos o en las instancias de VM de otro proveedor de servicios en la nube, debes proporcionar el ID de tu proyecto de Google Cloud y las credenciales de la cuenta de servicio correspondientes directamente a las bibliotecas de Cloud Logging para Node.js.

Para cuentas de servicio existentes, haz lo siguiente:

1. Otorga a la cuenta de servicio el rol de IAM de Escritor de registros (roles/logging.logWriter). Para obtener más información sobre los roles de IAM, consulta Control de acceso.

2. Configura credenciales predeterminadas de la aplicación.

Si no tienes una cuenta de servicio, créala. Para obtener información sobre este proceso, consulta Crea cuentas de servicio.

Si deseas obtener información general sobre los métodos que puedes usar para la autenticación, consulta Terminología: cuentas de servicio.

Usa Winston:

// Imports the Google Cloud client library for Winston
const {LoggingWinston} = require('@google-cloud/logging-winston');

// Creates a client
const loggingWinston = new LoggingWinston({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Usa Bunyan:

// Imports the Google Cloud client library for Bunyan
const {LoggingBunyan} = require('@google-cloud/logging-bunyan');

// Creates a client
const loggingBunyan = new LoggingBunyan({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Consulta los registros

En la consola de Google Cloud, ve a la página Explorador de registros.

Ir al Explorador de registros

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

En el Explorador de registros, debes especificar uno o más recursos, aunque la selección de recursos puede no ser obvia. Aquí encontrarás algunas sugerencias que te ayudarán a comenzar:

• Si implementas tu aplicación en App Engine o utilizas las bibliotecas específicas de App Engine, configura tu recurso como Aplicación de GAE.

• Si implementas tu aplicación en Compute Engine, configura el recurso como Instancia de VM de GCE.

• Si implementas tu aplicación en Google Kubernetes Engine, la configuración de registro de tu clúster determina el tipo de recurso de las entradas de registro. Para obtener información detallada sobre Google Cloud Observability heredado y las soluciones de Kubernetes Monitoring de Google Cloud Observability, y cómo esas opciones afectan el tipo de recurso, consulta Cómo migrar a Kubernetes Monitoring de Google Cloud Observability.

• Si la aplicación usa la API de Cloud Logging directamente, el recurso depende de la API y de tu configuración. Por ejemplo, en la aplicación, puedes especificar un recurso o usar un recurso predeterminado.

• Si no ves ningún registro en el Explorador de registros, cambia al modo de consulta avanzada y usa una consulta vacía para ver todas las entradas de registro.

  1. Para cambiar al modo de consulta avanzada, haz clic en menú (▾) en la parte superior del visor de registros y selecciona Convertir a filtro avanzado.
  2. Borra el contenido que aparece en el cuadro de filtro.
  3. Haz clic en Enviar filtro.

  Puedes examinar las entradas individuales para identificar tus recursos.

Para obtener más información, consulta Usa el Explorador de registros.