Node.js-Anwendungen für Error Reporting instrumentieren

Mithilfe der Error Reporting-Bibliothek für Node.js können Sie Fehlerberichte von Node.js-Anwendungen an Error Reporting senden. Verwenden Sie die Error Reporting-Bibliothek für Node.js, um Fehlergruppen für die folgenden Fälle zu erstellen:

• Ihr Log-Bucket hat vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).
• Ihre Log-Buckets befinden sich nicht in der Region global.
• Sie möchten benutzerdefinierte Fehlerereignisse melden.

Error Reporting ist in einige Google Cloud-Dienste wie Cloud Functions, App Engine, Compute Engine und Google Kubernetes Engine eingebunden. In Error Reporting sehen Sie die in Cloud Logging protokollierten Fehler der auf diesen Diensten ausgeführten Anwendungen. Weitere Informationen finden Sie unter In Google Cloud ausführen Seite.

Sie können Fehlerdaten auch mithilfe von Logging an Error Reporting senden. Informationen zu den Datenformatierungsanforderungen finden Sie unter Fehlermeldungen in Logging formatieren.

Hinweis

1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

4. Error Reporting API aktivieren.

   Aktivieren Sie die 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. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

7. Error Reporting API aktivieren.

   Aktivieren Sie die API

8. Bereiten Sie Ihre Umgebung für die Node.js-Entwicklung vor.

   Einrichtungsleitfaden für Node.js aufrufen

Clientbibliothek installieren

Mit der Error Reporting-Bibliothek für Node.js können Sie die von Node.js-Anwendungen, die praktisch überall ausgeführt werden können

1. Installieren Sie das Paket mit npm:

   npm install --save @google-cloud/error-reporting

2. Importieren Sie die Bibliothek und instanziieren Sie einen Client, um mit der Meldung von Fehlern zu starten:

   // Imports the Google Cloud client library
   const {ErrorReporting} = require('@google-cloud/error-reporting');
   
   // Instantiates a client
   const errors = new ErrorReporting();
   
   // Reports a simple error
   errors.report('Something broke!');

Weitere Informationen zur Installation finden Sie in der Dokumentation der Error Reporting-Bibliothek für Node.js. Probleme können Sie über die Problemverfolgung melden.

Clientbibliothek konfigurieren

Das Verhalten der Error Reporting-Bibliothek für Node.js kann angepasst werden. Eine Liste der möglichen Konfigurationsoptionen finden Sie in der Konfiguration der Bibliothek. Sie haben die Möglichkeit, diese Optionen im Objekt options an den Konstruktor der Bibliothek zu übergeben.

Sonstige Integrationen

Weitere Informationen zum Einbinden der Error Reporting-Bibliothek für Node.js in andere Node.js-Web-Frameworks finden Sie im Repository der Bibliothek auf GitHub.

Anwendungen in Google Cloud ausführen

Um Fehlergruppen mithilfe der projects.events.report, Ihr Dienstkonto benötigt die Rolle „Error Reporting-Autor“ (roles/errorreporting.writer):

Einige Google Cloud-Dienste gewähren automatisch Rolle „Error Reporting-Autor“ (roles/errorreporting.writer) der entsprechenden Dienstkonto. Sie müssen diese Rolle jedoch dem entsprechenden Dienst für einige Dienste.

Flexible App Engine-Umgebung

App Engine gewährt den Rolle „Error Reporting-Autor“ (roles/errorreporting.writer) automatisch mit Ihrem Standarddienstkonto verknüpft.

Die Error Reporting-Bibliothek für Node.js kann verwendet werden, ohne dass Anmeldedaten explizit angegeben werden müssen.

Error Reporting wird für Anwendungen in flexiblen App Engine-Umgebungen automatisch aktiviert. Es ist keine zusätzliche Einrichtung erforderlich.

Hinweis: In stderr geschriebene Fehlerlogs werden von Error Reporting automatisch verarbeitet, ohne dass dafür die Error Reporting-Bibliothek für Node.js direkt angewendet werden muss.

Google Kubernetes Engine

Um Error Reporting mit Google Kubernetes Engine zu verwenden, Gehen Sie so vor:

1. Prüfen Sie, ob das von Ihrem Container zu verwendende Dienstkonto gewährte Rolle „Error Reporting-Autor“ (roles/errorreporting.writer):

   Sie können dazu entweder das Compute Engine-Standarddienstkonto verwenden. oder ein benutzerdefiniertes Dienstkonto.

   Informationen zum Gewähren von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten

2. Cluster erstellen und dem Cluster die cloud-platform Zugriffsbereich.

   Der folgende Befehl zum Erstellen gibt beispielsweise die cloud-platform an. Zugriffsbereich und ein Dienstkonto:

   gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform
   

Hinweis: Nachdem Sie einen Cluster erstellt haben, können Sie sein Dienstkonto nicht mehr ändern.

Compute Engine

So verwenden Sie Error Reporting mit Compute Engine-VM-Instanzen: Gehen Sie so vor:

1. Prüfen Sie, ob das von Ihrer VM-Instanz zu verwendende Dienstkonto gewährte Rolle „Error Reporting-Autor“ (roles/errorreporting.writer):

   Sie können dazu entweder das Compute Engine-Standarddienstkonto verwenden. oder ein benutzerdefiniertes Dienstkonto.

   Informationen zum Gewähren von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten

2. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf:

   Zu Seite VM-Instanzen

   Wenn Sie diese Seite über die Suchleiste finden, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Compute Engine lautet.

3. Wählen Sie die VM-Instanz aus, die Sie erhalten möchten. cloud-platform Zugriffsbereich.

4. Klicken Sie auf Beenden und dann auf Bearbeiten.

5. Wählen Sie im Abschnitt Identität und API-Zugriff ein Dienstkonto aus, das hat die Rolle „Error Reporting-Autor“ (roles/errorreporting.writer).

6. Gehen Sie im Abschnitt Zugriffsbereiche so vor: Wählen Sie Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus und speichern Sie Ihre Änderungen.

7. Klicken Sie auf Starten/Fortsetzen.

Cloud Functions

Cloud Functions gewährt die Berechtigung Rolle „Error Reporting-Autor“ (roles/errorreporting.writer) automatisch mit Ihrem Standarddienstkonto verknüpft.

Die Error Reporting-Bibliothek für Node.js kann verwendet werden, ohne dass Anmeldedaten explizit angegeben werden müssen.

Cloud Functions ist automatisch für die Verwendung von Error Reporting konfiguriert. Unverarbeitete JavaScript-Ausnahmen werden in Logging angezeigt und von Error Reporting verarbeitet, ohne dass dafür die Error Reporting-Bibliothek für Node.js angewendet werden muss.

Hinweis: Logeinträge werden automatisch verarbeitet, wenn sie einen Stacktrace und Sie geben entweder keinen Logschweregrad oder einen Logschweregrad von mindestens ERROR an, ohne die Error Reporting-Bibliothek für Node.js zu verwenden.

Beispiel:

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

// Reports a simple error
errors.report('Something broke!');

Beispiel

Sie können einen Fehler auch manuell melden. Dazu rufen Sie die Methode report wie im folgenden Beispiel gezeigt auf:

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

// Use the error message builder to customize all fields ...
const errorEvent = errors.event();

// Add error information
errorEvent.setMessage('My error message');
errorEvent.setUser('root@nexus');

// Report the error event
errors.report(errorEvent, () => {
  console.log('Done reporting error event!');
});

// Report an Error object
errors.report(new Error('My error message'), () => {
  console.log('Done reporting Error object!');
});

// Report an error by provided just a string
errors.report('My error message', () => {
  console.log('Done reporting error string!');
});

Fehler mit Express.js melden

Mit der Error Reporting-Bibliothek für Node.js lässt sich Error Reporting in gängige Node.js-Web-Frameworks wie Express.js einbinden:

const express = require('express');

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

const app = express();

app.get('/error', (req, res, next) => {
  res.send('Something broke!');
  next(new Error('Custom error message'));
});

app.get('/exception', () => {
  JSON.parse('{"malformedJson": true');
});

// Note that express error handling middleware should be attached after all
// the other routes and use() calls. See the Express.js docs.
app.use(errors.express);

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

Anwendungen in einer lokalen Entwicklungsumgebung ausführen

So verwenden Sie die Error Reporting-Bibliothek für Node.js in einer lokalen Entwicklungsumgebung: wie das Ausführen der Bibliothek auf Ihrer eigenen Workstation, müssen Sie die Error Reporting-Bibliothek für Node.js durch die Standardanmeldedaten für lokale Anwendungen. Weitere Informationen finden Sie unter Bei Error Reporting authentifizieren.

Wenn Sie die Node.js Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

1. Installieren Sie die Google Cloud CLI.

2. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:

   gcloud init

3. Erstellen Sie lokale Anmeldedaten zur Authentifizierung für Ihr Google-Konto:

   gcloud auth application-default login

   Hinweis: Wenn die gcloud CLI eine Warnung ausgibt, dass Ihr Konto nicht die Berechtigung serviceusage.services.use hat, funktionieren einige gcloud CLI-Befehle und Clientbibliotheken möglicherweise nicht. Bitten Sie einen Administrator, Ihnen die IAM-Rolle "Service Usage-Nutzer" (roles/serviceusage.serviceUsageConsumer) zuzuweisen, und führen Sie dann den folgenden Befehl aus:

   gcloud auth application-default set-quota-project PROJECT_ID

Weitere Informationen unter Set up authentication for a local development environment.

Die projects.events.report-Methode unterstützt auch API-Schlüssel. Wenn Sie API-Schlüssel für die Authentifizierung verwenden möchten, müssen Sie keine lokale Datei mit den Standardanmeldedaten für Anwendungen einrichten. Weitere Informationen unter Erstellen eines API-Schlüssels in der Dokumentation zur Google Cloud-Authentifizierung.

Beispiel:

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

// Reports a simple error
errors.report('Something broke!');

Fehlerberichte ansehen

Rufen Sie in der Google Cloud Console die Seite Error Reporting auf:

Error Reporting aufrufen

Sie können diese Seite auch über die Suchleiste finden.

Weitere Informationen finden Sie unter Fehler anzeigen.