Configurazione di Cloud Logging per Node.js

Per le applicazioni Node.js, i plug-in vengono mantenuti per le librerie di logging Winston e Bunyan più diffuse. Winston è una libreria generica che implementa una serie di formattatori e trasporti di log. Bunyan, che è specializzato per i log JSON strutturati, supporta la formattazione dei log tramite il pipelining alla riga di comando di Bunyan.

Puoi anche utilizzare direttamente la libreria client di logging per Node.js o creare le tue integrazioni con la libreria di logging che preferisci. Puoi utilizzare ad esempio il framework di log Pino.

L'agente Logging non deve essere installato per utilizzare Winston o Bunyan su un'istanza di macchina virtuale (VM) Compute Engine.

Prima di iniziare

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 l'ambiente per lo sviluppo Node.js.

   Vai alla guida alla configurazione di Node.js

Configurazione logging

Questa sezione descrive come installare e configurare i plug-in per le librerie di logging Winston e Bunyan. Per Bunyan, vengono fornite informazioni su come utilizzare Bunyan con un Node.js Express un'applicazione.

Puoi usare altre librerie o framework. Ad esempio, puoi utilizzare Framework di log Pino. Per il codice campione che usa OpenTelemetry per raccogliere metriche e dati di traccia e il framework di log Pino per raccogliere log consulta Generare tracce e metriche con Node.js. Se utilizzi Pino, devi implementare una mappatura tra i livelli di gravità di Pino e quelli utilizzati da Cloud Logging. Per esempio di codice, consulta Mappatura dei livelli di log di Pino.

Installazione e configurazione del plug-in Winston

Cloud Logging fornisce un plug-in per Winston Node.js Libreria di logging. Il plug-in Logging per Winston fornisce un livello più semplice e di livello superiore per lavorare con Logging.

Per installare e configurare il plug-in Winston, procedi nel seguente modo:

1. Per installare il plug-in LoggingWinston, utilizza npm:

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

2. Importa il plug-in e aggiungilo alla configurazione di 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 il plug-in.

   Puoi personalizzare il comportamento del plug-in Winston utilizzando le stesse opzioni di configurazione supportate dalla libreria client dell'API Cloud Logging per Node.js. Queste opzioni possono essere passate nell'oggetto options passato al constructor del plug-in.

Installa e configura il plug-in Bunyan

Cloud Logging fornisce un plug-in per la libreria di logging Node.js Bunyan. Il plug-in Logging per Bunyan offre un'interfaccia più semplice, di livello superiore per l'uso di Logging.

Per installare e configurare il plug-in Bunyan, procedi nel seguente modo:

1. Per installare il plug-in LoggingBunyan, utilizza npm:

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

2. Importa il plug-in e aggiungilo alla configurazione 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 il plug-in.

   Puoi personalizzare il comportamento del plug-in Bunyan utilizzando le stesse opzioni di configurazione supportate nella libreria client cloud dell'API Cloud Logging per Node.js. Queste opzioni possono essere trasmesse nell'oggetto options passato al plug-in come costruttore.

Usa Bunyan ed Express

Puoi configurare e utilizzare Bunyan con Logging in Node.js Express un'applicazione.

// 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();

Per ulteriori informazioni sull'installazione, vedi documentazione relativa Librerie Cloud Logging per Node.js. Puoi anche segnalare i problemi utilizzando il tracker dei problemi.

Scrivi i log con la libreria client di Cloud Logging

Per informazioni sull'utilizzo diretto della libreria client Cloud Logging per Node.js, consulta la sezione Librerie client Cloud Logging.

Esegui su Google Cloud

Affinché un'applicazione scriva log utilizzando le librerie Cloud Logging per Node.js, è necessario l'account di servizio per la risorsa sottostante deve avere Ruolo Autore log (roles/logging.logWriter) IAM. La maggior parte degli ambienti Google Cloud configura automaticamente per avere questo ruolo.

App Engine

Cloud Logging è abilitato automaticamente per App Engine e default service account ha le autorizzazioni IAM per scrivere voci di log per impostazione predefinita.

Per scrivere voci di log dalla tua app, ti consigliamo di usare Bunyan o Winston come descritto in questa pagina.

Per ulteriori informazioni, consulta la sezione Scrittura e visualizzazione. log.

Google Kubernetes Engine (GKE)

GKE concede automaticamente allo account di servizio predefinito il ruolo IAM Scrittore di log (roles/logging.logWriter). Se utilizzi la federazione delle identità per i carichi di lavoro per GKE con questo account di servizio predefinito per consentire ai carichi di lavoro di accedere ad API Google Cloud specifiche, non è richiesta alcuna configurazione aggiuntiva. Tuttavia, se utilizzi la federazione delle identità per i carichi di lavoro per GKE con un account di servizio IAM personalizzato, assicurati che l'account di servizio personalizzato abbia il ruolo di autore di log (roles/logging.logWriter).

Se necessario, puoi anche utilizzare il seguente comando per aggiungere logging.write quando crei il cluster:

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

Compute Engine

Nota: per utilizzare le librerie Cloud Logging per Node.js su un'istanza VM di Compute Engine, Non devi installare l'agente Cloud Logging.

Quando utilizzi istanze VM di Compute Engine, aggiungi cloud-platform di ambito di accesso a ogni istanza. Quando crei una nuova istanza tramite Console Google Cloud, puoi farlo nella sezione Identità e accesso API. del riquadro Crea istanza. Usa il servizio predefinito di Compute Engine o un altro account di servizio a tua scelta e seleziona Consenti l'accesso completo a tutte le API Cloud in Identità e accesso API . Qualunque account di servizio tu selezioni, assicurati che sia stato concesso il ruolo Scrittore di log nella sezione IAM e amministrazione della console Google Cloud.

Funzioni Cloud Run

Le funzioni Cloud Run assegnano il ruolo Writer log. per impostazione predefinita.

Le librerie Cloud Logging per Node.js possono essere utilizzate senza dover fornire esplicitamente e credenziali.

Le funzioni Cloud Run sono configurate per utilizzare automaticamente Cloud Logging.

Nota: i log scritti in stdout e stderr vengono inviati automaticamente a Cloud Logging senza che tu debba utilizzare le librerie Cloud Logging per Node.js.

Esegui localmente e altrove

Per utilizzare le librerie di Cloud Logging per Node.js al di fuori di Google Cloud, compresa l'esecuzione della libreria sulla tua workstation, sul data center computer o sulle istanze VM di un altro cloud provider, fornisci l'ID progetto Google Cloud e i dati account di servizio e credenziali direttamente alle librerie Cloud Logging per Node.js.

Per gli account di servizio esistenti:

1. Concedi all'account di servizio l'accesso IAM Ruolo IAM Autore di log (roles/logging.logWriter). Per ulteriori informazioni sui ruoli IAM, consulta Controllo dell'accesso.

2. Configura Credenziali predefinite dell'applicazione.

Se non hai un account di servizio, creane uno. Per informazioni su questa procedura, vedi Creare account di servizio.

Per informazioni generali sui metodi che puoi utilizzare per l'autenticazione, vedi Terminologia: account di servizio.

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

Visualizza i log

Nella console Google Cloud, vai alla pagina Esplora log:

Vai a Esplora log

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

In Esplora log devi specificare una o più risorse, ma la selezione delle risorse potrebbe non essere ovvia. Ecco alcuni suggerimenti per aiutarti a data di inizio:

• Se esegui il deployment della tua applicazione in App Engine o utilizzi specifiche di App Engine, imposta la risorsa su Applicazione GAE.

• Se esegui il deployment della tua applicazione su Compute Engine, imposta la risorsa su istanza VM GCE.

• Se esegui il deployment della tua applicazione su Google Kubernetes Engine, configurazione di logging del cluster determina il tipo di risorsa del log le voci corrispondenti. Per una discussione dettagliata sulle soluzioni di monitoraggio Kubernetes di Google Cloud Observability precedenti e di Google Cloud Observability e su come queste opzioni influiscono sul tipo di risorsa, consulta Eseguire la migrazione a Google Cloud Observability Kubernetes Monitoring.

• Se la tua applicazione utilizza direttamente l'API Cloud Logging, La risorsa dipende dall'API e dalla configurazione. Ad esempio: nella tua applicazione, puoi specificare una risorsa o utilizzarne una predefinita.

• Se non vedi alcun log in Esplora log, per vedere tutte le voci di log, passare alla modalità di query avanzata e utilizzare una query vuota.

  1. Per passare alla modalità di query avanzata, fai clic su Menu (▾) nella parte superiore di Esplora log e seleziona Converti in filtro avanzato.
  2. Cancella i contenuti visualizzati nella casella dei filtri.
  3. Fai clic su Invia filtro.

  Puoi esaminare le singole voci per identificare le risorse.

Per ulteriori informazioni, consulta Utilizzare Esplora log.