Configurer Cloud Logging pour Node.js

Les plug-ins des applications Node.js sont gérés pour les bibliothèques de journalisation populaires Winston et Bunyan. Winston est une bibliothèque à usage général qui met en œuvre une variété de formateurs et de transports de journaux. Bunyan, qui est spécialisé dans les journaux JSON structurés, permet de mettre en forme les journaux en les transmettant à la ligne de commande Bunyan.

Vous pouvez également utiliser directement la bibliothèque cliente Logging pour Node.js, ou créer vos propres intégrations avec la bibliothèque de journalisation de votre choix. Vous pouvez par exemple utiliser l'exemple de framework de journalisation Pino.

Vous n'avez pas besoin d'installer l'agent Logging pour utiliser Winston ou Bunyan sur une instance de machine virtuelle (VM) Compute Engine.

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. Préparez votre environnement au développement de Node.js.

   Accéder au guide de configuration de Node.js

Configurer la journalisation

Cette section explique comment installer et configurer les plug-ins pour les bibliothèques de journalisation Winston et Bunyan. Pour Bunyan, des informations sont fournies sur l'utilisation de Bunyan avec une application Express Node.js.

Vous pouvez utiliser d'autres bibliothèques ou frameworks. Vous pouvez par exemple utiliser le framework de journalisation Pino. Pour obtenir un exemple de code qui utilise OpenTelemetry pour collecter des métriques et des données de trace, et le framework de journalisation Pino pour collecter des données de journal, consultez l'exemple d'instrumentation Node.js. Si vous utilisez Pino, vous devez implémenter un mappage entre les niveaux de gravité Pino et ceux utilisés par Cloud Logging. Pour obtenir un exemple de code, consultez la section Mapper les niveaux de journalisation Pino.

Installer et configurer le plug-in Winston

Cloud Logging fournit un plug-in pour la bibliothèque de journalisation Winston Node.js. Ce plug-in propose une couche simple de niveau supérieur permettant de travailler avec Logging.

Pour installer et configurer le plug-in Winston, procédez comme suit :

1. Pour installer le plug-in Winston de Logging, utilisez npm :

   npm install @google-cloud/logging-winston winston

2. Importez le plug-in et ajoutez-le à votre configuration 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. Configurez votre plug-in.

   Vous pouvez personnaliser le comportement du plug-in Winston à l'aide des mêmes options de configuration compatibles avec la bibliothèque cliente Cloud de l'API Cloud Logging pour Node.js. Ces options peuvent être transmises dans l'objet options, qui est lui-même transmis au constructeur du plug-in.

Installer et configurer le plug-in Bunyan

Cloud Logging fournit un plug-in pour la bibliothèque de journalisation Node.js Bunyan. Ce plug-in propose une couche simple de niveau supérieur permettant de travailler avec Logging.

Pour installer et configurer le plug-in Bunyan, procédez comme suit :

1. Pour installer le plug-in Bunyan de Logging, utilisez npm :

   npm install bunyan @google-cloud/logging-bunyan

2. Importez le plug-in et ajoutez-le à votre configuration 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. Configurez votre plug-in.

   Vous pouvez personnaliser le comportement du plug-in Bunyan à l'aide des options de configuration compatibles avec la bibliothèque cliente Cloud de l'API Cloud Logging pour Node.js. Ces options peuvent être transmises dans l'objet options, qui est lui-même transmis au constructeur du plug-in.

Utiliser Bunyan et Express

Vous pouvez configurer et utiliser Bunyan avec Logging dans une application Express 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();

Pour plus d'informations sur l'installation, consultez la documentation sur les bibliothèques Cloud Logging pour Node.js. Vous pouvez également signaler d'éventuels problèmes à l'aide de l' outil de suivi des problèmes.

Écrire des journaux avec la bibliothèque cliente Cloud Logging

Pour savoir comment utiliser directement la bibliothèque cliente Cloud Logging pour Node.js, consultez la page Bibliothèques clientes Cloud Logging.

Exécuter sur Google Cloud

Pour qu'une application écrive des journaux à l'aide des bibliothèques Cloud Logging pour Node.js, le compte de service de la ressource sous-jacente doit disposer du rôle IAMroles/logging.logWriter Rédacteur de journaux (). La plupart des Google Cloud environnements configurent automatiquement le compte de service par défaut pour qu'il dispose de ce rôle.

App Engine

Cloud Logging est automatiquement activé pour App Engine et le compte de service par défaut de votre application dispose des autorisations IAM par défaut permettant d'écrire des entrées de journal.

Pour écrire des entrées de journal depuis votre application, nous vous recommandons d'utiliser Bunyan ou Winston, comme décrit sur cette page.

Pour en savoir plus, consultez la section Écrire et afficher des journaux.

Google Kubernetes Engine (GKE)

GKE attribue automatiquement le rôle IAM Rédacteur de journaux (roles/logging.logWriter) au compte de service par défaut. Si vous utilisez Workload Identity Federation for GKE avec ce compte de service par défaut pour permettre aux charges de travail d'accéder à des Google Cloud API spécifiques, aucune configuration supplémentaire n'est requise. Toutefois, si vous utilisez Workload Identity Federation for GKE avec un compte de service IAM personnalisé, assurez-vous que le compte de service personnalisé dispose du rôle Rédacteur de journaux (roles/logging.logWriter).

Si nécessaire, vous pouvez également utiliser la commande suivante pour ajouter le niveau d'accès logging.write lors de la création du cluster :

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

Compute Engine

Remarque : Pour utiliser les bibliothèques Cloud Logging pour Node.js sur une instance de VM Compute Engine, il n'est pas nécessaire d'installer l'agent Cloud Logging.

Lorsque vous utilisez des instances de VM Compute Engine, ajoutez le cloud-platform niveau d'accès à chaque instance. Lorsque vous créez une instance via la Google Cloud console, vous pouvez le faire dans la section Identité et accès à l'API du panneau Créer une instance. Utilisez le compte de service par défaut de Compute Engine ou un autre compte de service de votre choix, puis sélectionnez Autoriser l'accès complet à l'ensemble des API Cloud dans la section Identité et accès à l'API. Quel que soit le compte de service sélectionné, vérifiez qu'il dispose du rôle Rédacteur de journaux dans la section IAM et administration de la Google Cloud console.

Cloud Run Functions

Cloud Run Functions attribue le rôle Rédacteur de journaux par défaut.

Il est possible d'utiliser les bibliothèques Cloud Logging pour Node.js sans avoir à fournir explicitement des identifiants.

Cloud Run Functions est configuré pour utiliser Cloud Logging automatiquement.

Remarque : Les journaux écrits sur stdout et stderr sont automatiquement envoyés à Cloud Logging, sans que vous ayez besoin d'utiliser les bibliothèques Cloud Logging pour Node.js.

Exécuter en local et depuis un autre emplacement

Pour utiliser les bibliothèques Cloud Logging pour Node.js en dehors de Google Cloud, y compris en les exécutant sur votre propre poste de travail, sur les ordinateurs de votre centre de données ou sur les instances de VM d'un autre fournisseur cloud, vous devez configurer les Identifiants par défaut de l'application (ADC) dans votre environnement local pour vous authentifier auprès des bibliothèques Cloud Logging pour Node.js.

Pour en savoir plus, consultez Configurer les Identifiants par défaut de l'application pour un autre fournisseur de services cloud ou sur site.

Utiliser 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',
});

Utiliser 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',
});

Afficher les journaux

Dans la Google Cloud console, accédez à la page Explorateur de journaux :

Accéder à l'explorateur de journaux

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Logging.

Dans l'explorateur de journaux, vous devez spécifier une ou plusieurs ressources, mais leur sélection peut ne pas être évidente. Voici quelques conseils pour vous aider à faire vos premiers pas :

• Si vous déployez votre application sur App Engine ou utilisez les bibliothèques propres à App Engine, définissez votre ressource sur Application GAE.

• Si vous déployez votre application sur Compute Engine, définissez la ressource sur Instance de VM GCE.

• Si vous déployez votre application sur Google Kubernetes Engine, la configuration de la journalisation de votre cluster détermine le type de ressource des entrées de journal. Pour en savoir plus sur l'ancienne suite Google Cloud Observability et sur les solutions Kubernetes Monitoring de Google Cloud Observability, ainsi que sur l'incidence de ces options sur le type de ressource, consultez la page Migrer vers les solutions Kubernetes Monitoring de Google Cloud Observability.

• Si votre application utilise directement l'API Cloud Logging, la ressource dépend de l'API et de votre configuration. Par exemple, dans votre application, vous pouvez spécifier une ressource ou utiliser une ressource par défaut.

• Si aucun journal ne s'affiche dans l'explorateur de journaux, passez en mode de requête avancée et utilisez une requête vide pour voir toutes les entrées de journal.

  1. Pour passer en mode de requête avancée, cliquez sur le menu (▾) en haut de l'explorateur de journaux, puis sélectionnez Convertir en filtre avancé.
  2. Effacez le contenu qui apparaît dans le champ de filtre.
  3. Cliquez sur Envoyer le filtre.

  Vous pouvez examiner les entrées individuelles pour identifier vos ressources.

Pour en savoir plus, consultez la page Utiliser l'explorateur de journaux.