Configurazione di Cloud Logging per Node.js

Per le applicazioni Node.js, i plug-in vengono gestiti per le librerie di logging Winston e Bunyan. Winston è una libreria per uso generico che implementa una varietà di formattatori e trasporti di log. Bunyan, che è specializzato per i log JSON strutturati, supporta la formattazione dei log tramite il piping alla riga di comando 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. Ad esempio, puoi utilizzare l'esempio del framework di log Pino.

Non è necessario installare l'agente Logging per utilizzare Winston o Bunyan su un'istanza di macchina virtuale (VM) Compute Engine.

Prima di iniziare

  1. Accedi al tuo Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Logging API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Cloud Logging API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.
  8. Prepara l'ambiente per lo sviluppo Node.js.

    Vai alla guida alla configurazione di Node.js

Configura 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'applicazione Node.js Express.

Puoi utilizzare altre librerie o framework. Ad esempio, puoi utilizzare il framework di log Pino. Per il codice campione che utilizza OpenTelemetry per raccogliere metriche e dati di traccia e il framework di log Pino per raccogliere dati di log, consulta Esempio di strumentazione Node.js. Se utilizzi Pino, devi implementare un mapping tra i livelli di gravità di Pino e quelli utilizzati da Cloud Logging. Per il codice di esempio, consulta Mapping dei livelli di log di Pino.

Installa e configura il plug-in Winston

Cloud Logging fornisce un plug-in per la libreria di logging Winston Node.js. 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:

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

    npm install @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 da la libreria client Cloud dell'API Cloud Logging per Node.js. Queste opzioni possono essere passate nell'oggetto options passato al costruttore del plug-in.

Installa e configura il plug-in Bunyan

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

Per installare e configurare il plug-in Bunyan:

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

    npm install bunyan @google-cloud/logging-bunyan

  2. Importa il plug-in e aggiungilo alla configurazione di 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 da la libreria client Cloud dell'API Cloud Logging per Node.js. Queste opzioni possono essere passate nell'oggetto options passato al costruttore del plug-in.

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

Per ulteriori informazioni sull'installazione, consulta la documentazione delle librerie Cloud Logging per Node.js. Puoi anche segnalare i problemi utilizzando il tracker dei problemi.

Scrivi 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 possa scrivere log utilizzando le librerie Cloud Logging per Node.js, il account di servizio della risorsa sottostante deve disporre del ruolo IAM Writer di log (roles/logging.logWriter) IAM. La maggior parte degli Google Cloud ambienti configura automaticamente il account di servizio predefinito in modo che abbia questo ruolo.

App Engine

Cloud Logging è abilitato automaticamente per App Engine e il service account predefinito della tua app dispone delle autorizzazioni IAM per scrivere voci di log.

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

Per saperne di più, consulta Scrivere e visualizzare i log.

Google Kubernetes Engine (GKE)

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

Se necessario, puoi anche utilizzare il seguente comando 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 lo cloud-platform ambito di accesso a ogni istanza. Quando crei una nuova istanza tramite la Google Cloud console, puoi farlo nella sezione Identità e accesso API del riquadro Crea istanza. Utilizza il service account predefinito di Compute Engine o un altro account di servizio di tua scelta e seleziona Consenti l'accesso completo a tutte le API Cloud nella sezione Identità e accesso API. Qualunque sia il service account selezionato, assicurati che gli sia stato concesso il ruolo Writer di log nella sezione IAM e amministrazione della Google Cloud console.

Cloud Run Functions

Cloud Run Functions concede il ruolo Writer di log per impostazione predefinita.

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

Cloud Run Functions è configurato per utilizzare automaticamente Cloud Logging.

Esegui in locale e altrove

Per utilizzare le librerie Cloud Logging per Node.js al di fuori di Google Cloud, inclusa l'esecuzione della libreria sulla tua workstation, sui computer del tuo data center o sulle istanze VM di un altro provider cloud, devi configurare le Credenziali predefinite dell'applicazione (ADC) nel tuo ambiente locale per l'autenticazione alle librerie Cloud Logging per Node.js.

Per saperne di più, consulta Configura ADC per on-premise o un altro provider cloud.

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

Utilizza 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 Google Cloud console, 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 che ti aiuteranno a iniziare.

  • Se esegui il deployment dell'applicazione in App Engine o utilizzi le librerie specifiche di App Engine, imposta la risorsa su Applicazione GAE.

  • Se esegui il deployment dell'applicazione su Compute Engine, imposta la risorsa su Istanza VM GCE.

  • Se esegui il deployment dell'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 Google Cloud Observability e Google Cloud Observability Kubernetes Monitoring 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 utilizzare una risorsa predefinita.

  • Se non vedi alcun log in Esplora log, per visualizzare 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 (▾) nella parte superiore di Esplora log e seleziona Converti in filtro avanzato.
    2. Cancella i contenuti visualizzati nella casella del filtro.
    3. Fai clic su Invia filtro.

    Puoi esaminare le singole voci per identificare le tue risorse.

Per ulteriori informazioni, consulta Utilizzo di Esplora log.