Cloud Logging für Node.js einrichten

Für Node.js-Anwendungen werden Plug-ins für die gängigen Logging-Bibliotheken von Winston und Bunyan Winston ist eine Universalbibliothek, Implementierung verschiedener Logformatierer und -transporte. Bunyan, ist auf strukturierte JSON-Logs spezialisiert und unterstützt die Logformatierung durch über eine Pipe an die Bunyan-Befehlszeile.

Sie können die Logging-Clientbibliothek auch für direkt Node.js oder Erstellen Sie eigene Integrationen mit Ihrer bevorzugten Logging-Bibliothek. Sie können beispielsweise das Beispiel Pino-Protokoll-Framework verwenden.

Der Logging-Agent muss nicht installiert sein, um Winston oder Bunyan auf einer Compute Engine-VM-Instanz zu verwenden.

Hinweise

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. Bereiten Sie Ihre Umgebung für die Node.js-Entwicklung vor.

   Einrichtungsleitfaden für Node.js aufrufen

Logging konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie die Plug-ins für den Logging-Bibliotheken von Winston und Bunyan Für Bunyan Informationen zur Verwendung von Bunyan mit Node.js Express .

Sie können auch andere Bibliotheken oder Frameworks verwenden. Sie können beispielsweise die Methode Pino-Log-Framework Für Beispielcode, der OpenTelemetry verwendet, um sowie das Pino-Log-Framework, Traces und Messwerte mit Node.js generieren Wenn Sie Pino verwenden, müssen Sie eine Zuordnung zwischen den Pino-Elementen Schweregrade und von Cloud Logging verwendeten Schweregraden. Beispielcode finden Sie unter Pino-Logebenen zuordnen

Winston-Plug-in installieren und konfigurieren

Cloud Logging enthält ein Plug-in für die Node.js-Logging-Bibliothek von Winston. Das Logging-Plug-in für Winston bietet eine einfachere, allgemeinere Ebene für die Arbeit mit Logging.

So installieren und konfigurieren Sie das Winston-Plug-in:

1. Logging installieren Winston-Plug-in verwenden, verwenden Sie npm:

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

2. Importieren Sie das Plug-in und fügen Sie es Ihrer Winston-Konfiguration hinzu:

   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. Konfigurieren Sie das Plug-in.

   Sie können das Verhalten des Winston-Plug-ins über die Konfigurationsoptionen unterstützt von die Cloud-Clientbibliothek der Cloud Logging API für Node.js Diese Optionen können im Objekt options übergeben werden, das an den Plug-in-Konstruktor weitergeleitet wird.

Bunyan-Plug-in installieren und konfigurieren

Cloud Logging enthält ein Plug-in für die Node.js-Logging-Bibliothek von Bunyan. Das Logging-Plug-in für Bunyan bietet eine einfachere, allgemeinere Ebene für die Arbeit mit Logging.

So installieren und konfigurieren Sie das Bunyan-Plug-in:

1. Verwenden Sie npm, um das Bunyan-Plug-in für die Logging-Funktion zu installieren:

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

2. Importieren Sie das Plug-in und fügen es Ihrer Bunyan-Konfiguration hinzu:

   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. Plug-in konfigurieren

   Sie können das Verhalten des Bunyan-Plug-ins anpassen. Konfigurationsoptionen wie die die Cloud-Clientbibliothek der Cloud Logging API für Node.js Diese Optionen können im options-Objekt übergeben werden, das an die -Konstruktor.

Bunyan und Express verwenden

Sie können Bunyan mit Logging in einer Node.js-Express-Anwendung einrichten und verwenden.

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

Weitere Informationen zur Installation finden Sie in der Dokumentation zu den Cloud Logging-Bibliotheken für Node.js. Probleme können Sie über die Problemverfolgung melden.

Protokolle mit der Cloud Logging-Clientbibliothek schreiben

Informationen zur direkten Verwendung der Cloud Logging-Clientbibliothek für Node.js finden Sie unter Cloud Logging-Clientbibliotheken.

In Google Cloud ausführen

Damit eine Anwendung Logs mithilfe der Cloud Logging-Bibliotheken für Node.js schreiben kann, Dienstkonto für die zugrunde liegende Ressource muss die Logautor (roles/logging.logWriter) IAM-Rolle. In den meisten Google Cloud-Umgebungen wird die Standardeinstellung Dienstkonto mit dieser Rolle.

App Engine

Cloud Logging ist für App Engine automatisch aktiviert und das Standarddienstkonto Ihrer Anwendung hat standardmäßig die IAM-Berechtigungen zum Schreiben von Logeinträgen.

Zum Schreiben von Logeinträgen aus Ihrer Anwendung empfehlen wir die Verwendung von Bunyan oder Winston, wie auf dieser Seite beschrieben.

Weitere Informationen finden Sie unter Schreiben und Anzeigen Logs

Google Kubernetes Engine (GKE)

GKE gewährt dem Standarddienstkonto automatisch die IAM-Rolle Logautor (roles/logging.logWriter). Wenn Sie Identitätsföderation von Arbeitslasten für GKE mit diesem Standarddienstkonto, damit Arbeitslasten auf bestimmte Google Cloud APIs verwenden, ist keine weitere Konfiguration erforderlich. Wenn Sie jedoch die Identitätsföderation von Arbeitslasten für GKE mit einem benutzerdefinierten IAM-Dienstkontos erstellen und dann prüfen, ob der benutzerdefinierte Dienst Konto hat die Rolle des Logautors (roles/logging.logWriter).

Bei Bedarf können Sie auch den folgenden Befehl verwenden, um beim Erstellen des Clusters den Zugriffsbereich logging.write hinzuzufügen:

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

Compute Engine

Hinweis: Um Cloud Logging-Bibliotheken für Node.js auf einer Compute Engine-VM-Instanz verwenden zu können, muss der Cloud Logging-Agent nicht installiert sein.

Wenn Sie Compute Engine-VM-Instanzen verwenden, fügen Sie der jeweiligen Instanz den Zugriffsbereich für cloud-platform hinzu. Wenn Sie eine neue Instanz über die In der Google Cloud Console können Sie dies im Abschnitt Identität und API-Zugriff tun. des Bereichs Instanz erstellen. Verwenden Sie das Compute Engine-Standarddienstkonto oder ein anderes Dienstkonto und wählen Sie im Abschnitt Identität und API-Zugriff die Option Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus. Ganz gleich, welchen Dienst des ausgewählten Kontos müssen Sie sicherstellen, Rolle „Log-Autor“ in der Rolle „IAM & Admin des Google Cloud Console

Cloud Run-Funktionen

Cloud Run-Funktionen gewähren die Rolle Logautor ist standardmäßig aktiviert.

Die Cloud Logging-Bibliotheken für Node.js können ohne explizite Angabe von Anmeldedaten verwendet werden.

Cloud Run-Funktionen sind so konfiguriert, dass Cloud Logging automatisch verwendet wird.

Hinweis: In stdout und stderr geschriebene Logs werden automatisch an Cloud Logging gesendet, ohne dass die Cloud Logging-Bibliotheken für Node.js erforderlich sind.

Lokal und extern ausführen

So verwenden Sie die Cloud Logging-Bibliotheken für Node.js außerhalb von Google Cloud: einschließlich der Ausführung der Bibliothek auf Ihrer eigenen Workstation, auf dem oder auf den VM-Instanzen eines anderen Cloud-Anbieters, Ihre Google Cloud-Projekt-ID und den entsprechenden Dienstkonto Anmeldedaten direkt an die Cloud Logging-Bibliotheken für Node.js senden.

Bei vorhandenen Dienstkonten gehen Sie so vor:

1. Gewähren Sie dem Dienstkonto die IAM-Rolle IAM-Rolle Logautor (roles/logging.logWriter) Weitere Informationen zu IAM finden Sie unter Zugriffssteuerung.

2. Standardanmeldedaten für Anwendungen einrichten

Wenn Sie kein Dienstkonto haben, erstellen Sie eines. Weitere Informationen finden Sie unter Dienstkonten erstellen.

Allgemeine Informationen zu den Authentifizierungsmethoden finden Sie unter Terminologie: Dienstkonten.

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

Bunyan verwenden:

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

Logs ansehen

Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

Zum Log-Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.

Im Log-Explorer müssen Sie eine oder mehrere Ressourcen angeben. Die Auswahl der Ressourcen ist jedoch möglicherweise nicht offensichtlich. Hier sind ein paar Tipps für den Einstieg.

• Wenn Sie Ihre Anwendung für App Engine bereitstellen oder die App Engine-spezifischen Bibliotheken verwenden, setzen Sie die Ressource auf GAE-Anwendung.

• Wenn Sie Ihre Anwendung auf der Compute Engine bereitstellen, setzen Sie die Ressource auf GCE-VM-Instanz.

• Wenn Sie Ihre Anwendung in Google Kubernetes Engine bereitstellen, wird der Ressourcentyp der Logeinträge von der Loggingkonfiguration des Clusters bestimmt. Eine detaillierte Diskussion zu Legacy-Google Cloud Observability und Google Cloud Observability Kubernetes Monitoring-Lösungen und deren Auswirkungen auf Ressourcentyp, siehe Zu Google Cloud Observability Kubernetes Monitoring migrieren

• Wenn Ihre Anwendung die Cloud Logging API direkt nutzt, ist die Ressource von der API und Ihrer Konfiguration abhängig. Sie können in Ihrer Anwendung zum Beispiel eine Ressource angeben oder eine Standardressource verwenden.

• Wenn im Log-Explorer keine Logs zu sehen sind, wechseln Sie zum erweiterten Abfragemodus und verwenden Sie eine leere Abfrage, um alle Logeinträge zu sehen.

  1. Klicken Sie oben im Log-Explorer auf das Dreipunkt-Menü (▾) und wählen Sie In erweiterten Filter umwandeln aus, um zum erweiterten Abfragemodus zu wechseln.
  2. Löschen Sie den Inhalt, der im Filterfeld angezeigt wird.
  3. Klicken Sie auf Filter senden.

  Sie können die einzelnen Einträge prüfen, um Ihre Ressourcen zu identifizieren.

Weitere Informationen finden Sie unter Log-Explorer verwenden.