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:

  • Ein Log-Bucket, das Ihre Logeinträge enthält, hat vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).
  • Der Log-Bucket erfüllt eine der folgenden Bedingungen:
    • Der Log-Bucket wird im selben Projekt gespeichert, aus dem die Logeinträge stammen.
    • Die Logeinträge wurden an ein Projekt weitergeleitet und dieses Projekt hat die Logeinträge dann in einem eigenen Log-Bucket gespeichert.
  • 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 auf dieser Seite im Abschnitt Auf Google Cloudausführen.

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

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.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Error Reporting API .

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Error Reporting API .

    Enable the API

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

    Einrichtungsleitfaden für Node.js aufrufen

    9. Clientbibliothek installieren

    Mit der Error Reporting-Bibliothek für Node.js können Sie die von Node.js-Anwendungen gemeldeten Fehler im Blick behalten und abrufen. Dabei ist es in den meisten Fällen unerheblich, wo die Anwendungen ausgeführt werden.

    1. Installieren Sie das Paket mit npm:

      npm install @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.

    Apps auf Google Cloudausführen

    Wenn Sie Fehlergruppen mit projects.events.report erstellen möchten, benötigt Ihr Dienstkonto die Rolle Error Reporting-Autor (roles/errorreporting.writer).

    Einige Google Cloud -Dienste weisen dem entsprechenden Dienstkonto automatisch die Rolle „Error Reporting Writer“ (roles/errorreporting.writer) zu. Für einige Dienste müssen Sie diese Rolle jedoch dem entsprechenden Dienstkonto zuweisen.

    Cloud Run und Cloud Run-Funktionen

    Das von Cloud Run verwendete Standarddienstkonto hat die Berechtigungen der Rolle „Error Reporting-Autor“ (roles/errorreporting.writer).

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

    Cloud Run 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.

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

    Flexible App Engine-Umgebung

    In App Engine wird Ihrem Standarddienstkonto automatisch die Rolle Error Reporting-Autor (roles/errorreporting.writer) zugewiesen.

    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.

    Google Kubernetes Engine

    So verwenden Sie Error Reporting mit Google Kubernetes Engine:

    1. Achten Sie darauf, dass dem Dienstkonto, das von Ihrem Container verwendet werden soll, die Rolle Error Reporting-Autor (roles/errorreporting.writer) zugewiesen wurde.

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

      Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    2. Erstellen Sie Ihren Cluster und gewähren Sie ihm den cloud-platform-Zugriffsbereich.

      Im folgenden Beispiel wird mit dem Befehl „create“ der Zugriffsbereich cloud-platform und ein Dienstkonto angegeben:

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

    Compute Engine

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

    1. Achten Sie darauf, dass dem Dienstkonto, das von Ihrer VM-Instanz verwendet werden soll, die Rolle Error Reporting-Autor (roles/errorreporting.writer) zugewiesen wurde.

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

      Informationen zum Zuweisen 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, für die Sie den cloud-platform-Zugriffsbereich festlegen möchten.

    4. Klicken Sie auf Beenden und dann auf Bearbeiten.

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

    6. Wählen Sie im Bereich Zugriffsbereiche die Option Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus und speichern Sie die Änderungen.

    7. Klicken Sie auf Starten/Fortsetzen.

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

    Apps in einer lokalen Entwicklungsumgebung ausführen

    Wenn Sie die Error Reporting-Bibliothek für Node.js in einer lokalen Entwicklungsumgebung verwenden möchten, z. B. wenn Sie die Bibliothek auf Ihrer eigenen Workstation ausführen, müssen Sie die lokalen Standardanmeldedaten für Anwendungen für die Error Reporting-Bibliothek für Node.js angeben. 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. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command: 

      gcloud init

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    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 ADC-Datei (Standardanmeldedaten für Anwendungen) einrichten. Weitere Informationen unter Erstellen eines API-Schlüssels in der Google Cloud Authentifizierungsdokumentation.

    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.