Configurazione di Cloud Logging per Node.js

Per le applicazioni Node.js, vengono gestiti i plug-in per le popolari librerie di logging Bunyan e Winston.

Winston è una libreria generale che implementa una varietà di formatter e trasporti di log.

Bunyan è specializzato in log JSON strutturati. La formattazione del log può essere eseguita nella 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.

Non è necessario installare l'agente Logging per utilizzare le librerie Bunyan e Winston su un'istanza VM di Compute Engine.

Prima di iniziare

Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Attiva Cloud Logging API.

Abilita l'API

Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

Vai al selettore progetti

Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Attiva Cloud Logging API.

Abilita l'API

Prepara l'ambiente per lo sviluppo in Node.js.
Vai alla guida alla configurazione di Node.js

Utilizzo di Bunyan

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

Installazione del plug-in

Il modo più semplice per installare il plug-in Bunyan di Logging è con npm:
```
npm install --save bunyan @google-cloud/logging-bunyan
```

Importa il plug-in e aggiungilo alla tua 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%');

Configurazione del plug-in

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

Uso di Bunyan ed Express

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

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

Utilizzo di Winston

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

Installazione del plug-in

Il modo più semplice per installare il plug-in Winston di Logging è con npm:
```
npm install --save @google-cloud/logging-winston winston
```

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%');

Configurazione del plug-in

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

Per ulteriori informazioni sull'installazione, consulta la documentazione relativa alle librerie di Cloud Logging per Node.js. Puoi anche segnalare i problemi utilizzando Issue Tracker.

Scrivere log con la libreria client di Cloud Logging

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

Esegui su Google Cloud

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

App Engine

Cloud Logging è abilitato automaticamente per App Engine e l'account di servizio predefinito della tua app dispone per impostazione predefinita delle autorizzazioni IAM per la scrittura di voci di log.

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

Per ulteriori informazioni, consulta Scrittura e visualizzazione dei log.

Google Kubernetes Engine (GKE)

GKE concede automaticamente all'account di servizio predefinito il ruolo IAM Writer log (roles/logging.logWriter). Se utilizzi Workload Identity con questo account di servizio predefinito per consentire ai carichi di lavoro di accedere a specifiche API Google Cloud, non è necessaria alcuna configurazione aggiuntiva. Tuttavia, se utilizzi Workload Identity con un account di servizio IAM personalizzato, assicurati che l'account di servizio personalizzato abbia il ruolo di Writer log (roles/logging.logWriter).

Se necessario, puoi anche utilizzare il comando seguente per aggiungere l'ambito di accesso logging.write durante la creazione del cluster:

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

Compute Engine

Quando utilizzi le istanze VM di Compute Engine, aggiungi l'ambito di accesso cloud-platform a ogni istanza. Quando crei una nuova istanza tramite la console Google Cloud, puoi farlo nella sezione Identità e accesso API del riquadro Crea istanza. Utilizza l'account di 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 nella sezione Identità e accesso API. Qualunque account di servizio seleziona, assicurati che gli sia stato concesso il ruolo Writer log nella sezione IAM e amministrazione della console Google Cloud.

Cloud Functions

Cloud Functions concede il ruolo Writer log per impostazione predefinita.

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

Cloud Functions è configurato per l'utilizzo automatico di Cloud Logging.

Esegui in locale e altrove

Per utilizzare le librerie Cloud Logging per Node.js al di fuori di Google Cloud, compresa l'esecuzione della libreria sulla tua workstation, sui computer del tuo data center o sulle istanze VM di un altro cloud provider, devi fornire l'ID progetto Google Cloud e le credenziali dell'account di servizio appropriate direttamente alle librerie Cloud Logging per Node.js.

Per gli account di servizio esistenti:

Concedi all'account di servizio il ruolo IAM Writer log (roles/logging.logWriter). Per ulteriori informazioni sui ruoli IAM, consulta Controllo dell'accesso.
Configura le credenziali predefinite dell'applicazione.

Se non hai un account di servizio, creane uno. Per informazioni su questo processo, consulta Creare account di servizio.

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

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

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

Visualizza i log

Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:

Vai a Esplora log

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

Se esegui il deployment della tua applicazione in App Engine o utilizzi le librerie 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, la configurazione di logging del cluster determina il tipo di risorsa delle voci di log. Per una discussione dettagliata sulle soluzioni legacy di Google Cloud per l'osservabilità e sull'osservabilità di Google Cloud, e su come queste opzioni influiscono sul tipo di risorsa, consulta Migrazione a Google Cloud Observability Kubernetes Monitoring.
Se la tua applicazione utilizza direttamente l'API Cloud Logging, la risorsa dipenderà dall'API e dalla tua configurazione. Ad esempio, nella tua applicazione puoi specificare una risorsa o utilizzarne una predefinita.
Se non vedi log in Esplora log, per vedere tutte le voci di log passa alla modalità di query avanzata e utilizza una query vuota.
1. Per passare alla modalità di query avanzata, fai clic su menu (&blacktriangledown;) nella parte superiore di Esplora log, quindi 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 Utilizzo di Esplora log.