Cloud Debugger für Node.js einrichten

Übersicht

Hinweis: Cloud Debugger ist mit Node.js 9 und höher kompatibel. Wir empfehlen, die Langzeit-Supportversion zu verwenden.

Auf dieser Seite wird beschrieben, wie Sie Ihre Umgebung und Ihre Node.js-Anwendung für die Verwendung von Cloud Debugger konfigurieren. In einigen Umgebungen müssen Sie, damit der Cloud Debugger-Agent Daten senden kann, den Zugriffsbereich explizit angeben. Es wird empfohlen, den größtmöglichen Zugriffsbereich festzulegen und anschließend den Zugriff mit der Identitäts- und Zugriffsverwaltung einzuschränken. Geben Sie den Zugriffsbereich entsprechend dieser Best Practice für alle Cloud APIs mit der Option cloud-platform an.

Sprachversionen und Computing-Umgebungen

Cloud Debugger ist für Node.js 9 und höher in den folgenden Computing-Umgebungen verfügbar:

App Engine-Standardumgebung	Flexible App Engine-Umgebung	Compute Engine	Google Kubernetes Engine	Cloud Run	Cloud Run for Anthos	Andernorts ausgeführte VMs und Container	Cloud Functions

Beta

Diese Bibliothek unterliegt den Nutzungsbedingungen des Pre-GA-Angebots in den Nutzungsbedingungen der Google Cloud Platform. Pre-GA-Bibliotheken werden nur eingeschränkt unterstützt. Änderungen an diesen Bibliotheken sind möglicherweise nicht mit anderen Pre-GA-Versionen kompatibel. Weitere Informationen finden Sie unter Beschreibungen der Startphase.

Cloud Debugger einrichten

Führen Sie die folgenden Aufgaben aus, um Cloud Debugger einzurichten:

1. Prüfen Sie, ob die Cloud Debugger API für Ihr Projekt aktiviert ist.

2. Installieren und konfigurieren Sie den Debugger in der von Ihnen verwendeten Rechenumgebung.

3. Wählen Sie den Quellcode aus.

   Hinweis: Aus Leistungsgründen unterstützt der Cloud Debugger-Agent für Node.js nicht das Hinzufügen von Snapshots oder Logpoints zu Dateien im Verzeichnis node_modules.

Prüfen, ob die Cloud Debugger API aktiviert ist

Wenn Sie Cloud Debugger verwenden möchten, muss die Cloud Debugger API aktiviert sein. Cloud Debugger ist standardmäßig für die meisten Projekte aktiviert.
Cloud Debugger API aktivieren

Hinweis: Cloud Debugger ist kostenlos. Sie benötigen jedoch ein Google Cloud-Projekt mit aktivierter Abrechnung, bevor Sie Cloud Debugger verwenden können.

Canary-Snapshots und -Logpoints

Der Debugger-Agent für Node.js kann jedes Mal, wenn Sie einen Snapshot oder Logpoint festlegen, Canary-Snapshots und -Logpoints verwenden.

Der Debugger-Agent kann Snapshots und Logpoints erstellen, um große Jobs vor potenziellen Fehlern im Debugger-Agent zu schützen. Dieser Programmfehler kann den gesamten Job herunterfahren, wenn ein Snapshot oder ein Logpoint angewendet wird.

Um dies zu vermeiden, kann der Debugger jedes Mal Snapshots und Logpoints auf einem Teil Ihrer ausgeführten Instanzen erstellen, wenn diese festgelegt werden. Nachdem vom Debugger bestätigt wurde, dass der Snapshot oder Logpoint die ausgeführten Instanzen nicht beeinträchtigt, wendet der Debugger den Snapshot oder Logpoint auf alle Instanzen an.

Hinweis: Canary-Tests sind für den Node.js Debugger-Agent ab Version 5.1.0 verfügbar.

Informationen zur Verwendung des Debuggers im Canary-Modus finden Sie auf den Seiten Snapshots zur Fehlerbehebung und Logpoints zur Fehlerbehebung.

Canary-Snapshots und -Logpoints aktivieren

Wenn Sie die neueste Version des Debugger-Agents installieren, können Sie Canary-Tests aktivieren oder deaktivieren. Canary-Tests sind standardmäßig deaktiviert.

Wann Canary-Snapshots und -Logpoints aktiviert werden sollten

Um Bereitstellungs- und produktionskritische Arbeitslasten zu schützen, aktivieren Sie beim Debuggen dieser Arbeitslasten Canary-Tests.

Wenn Sie eine einzelne Instanz haben, können Sie zwar mit aktivierten Canary-Tests Fehler beheben, aber Ihre einzelne Instanz wird ausgeführt, ohne den Canary-Test am Snapshot oder Logpoint auszuführen.

Wann Canary-Snapshots und -Logpoints nicht aktiviert werden sollten

Aktivieren Sie Canary-Tests nicht für Arbeitslasten, die eine Ausführungszeit von weniger als 40 Sekunden haben, beispielsweise Jobs mit Cloud Functions.

Aktivieren Sie Canary-Tests nicht, wenn Sie einen schnelleren Auslösungszyklus für Snapshots wünschen.

Wenn Sie den Debugger-Agent so konfigurieren möchten, dass keine Snapshots und Logpoints erstellt werden, lesen Sie die Installationsanleitung für die verwendete Google Cloud Platform.

App Engine

1. Installieren Sie das Paket mit npm:

   npm install --save @google-cloud/debug-agent
   

2. Aktivieren Sie den Agent am Anfang des Hauptskripts oder des Einstiegspunkts Ihrer Anwendung (aber gegebenenfalls nach @google/cloud-trace):

   So beheben Sie Fehler mit aktiviertem Canary-Test:

   require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
   

   Wenn Sie das Debugging mit dem Canary-Release nicht aktivieren möchten, setzen Sie enableCanary auf false:

   require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
   

Der Debugger ist jetzt bereit für die Verwendung mit Ihrer App.

Wenn die Seite "Debugging" in der Cloud Console automatisch Quellcode anzeigen soll, der mit der bereitgestellten Anwendung übereinstimmt, beachten Sie die Hinweise unter Quellcode automatisch auswählen.

Google Kubernetes Engine

GCLOUD

Mit den folgenden Schritten aktivieren Sie Debugger mit gcloud:

1. Erstellen Sie Ihren Cluster mit einem der folgenden Zugriffsbereiche:

   • https://www.googleapis.com/auth/cloud-platform gewährt Ihrem Cluster Zugriff auf alle Google Cloud APIs.

   • https://www.googleapis.com/auth/cloud_debugger gewährt Ihrem Cluster nur Zugriff auf die Debugger API. Verwenden Sie diesen Zugriffsbereich, um die Sicherheit Ihres Clusters zu härten.

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

   Hinweis: Sie können die Zugriffsbereiche eines Clusters nach dem Erstellen nicht mehr ändern.

2. Fügen Sie die folgende Zeile Ihrem Dockerfile hinzu, um den Debugger-Agent hinzuzufügen:

   RUN  npm install --save @google-cloud/debug-agent
   

3. Aktivieren Sie den Agent am Anfang des Hauptskripts oder des Einstiegspunkts Ihrer Anwendung (aber gegebenenfalls nach @google/cloud-trace):

   So beheben Sie Fehler mit aktiviertem Canary-Test:

   require('@google-cloud/debug-agent').start({
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Wenn Sie das Debugging mit dem Canary-Release nicht aktivieren möchten, setzen Sie enableCanary auf false:

   enableCanary: false
   

   Dabei gilt:

   • SERVICE ist ein Name für Ihre Anwendung, z. B. MyApp, Backend oder Frontend.
   • VERSION ist eine Version, z. B. v1.0, build_147 oder v20170714.

   Wir empfehlen, diese über Umgebungsvariablen festzulegen, damit Sie den Quellcode nicht bei jeder Bereitstellung ändern müssen.

Der Debugger ist jetzt einsatzbereit, wenn Sie Ihre containerisierte Anwendung bereitstellen.

Wenn die Seite "Debugging" in der Cloud Console automatisch Quellcode anzeigen soll, der mit der bereitgestellten Anwendung übereinstimmt, beachten Sie die Hinweise unter Quellcode automatisch auswählen.

KONSOLE

Führen Sie die folgenden Schritte aus, um Debugger mithilfe der Google Cloud Console zu aktivieren:

1. Wählen Sie im Abschnitt Knotenpools die Option Sicherheit und dann Zugriff für jede API festlegen aus.

2. Aktivieren Sie Debugger.

   

3. Optional: Wählen Sie Uneingeschränkten Zugriff auf alle Cloud APIs zulassen aus.

4. Fügen Sie die folgende Zeile Ihrem Dockerfile hinzu, um den Debugger-Agent hinzuzufügen:

       RUN  npm install --save @google-cloud/debug-agent
   

5. Aktivieren Sie den Agent am Anfang des Hauptskripts oder des Einstiegspunkts Ihrer Anwendung (aber gegebenenfalls nach @google/cloud-trace):

   So beheben Sie Fehler mit aktiviertem Canary-Test:

   require('@google-cloud/debug-agent').start({
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Wenn Sie das Debugging mit dem Canary-Release nicht aktivieren möchten, setzen Sie enableCanary auf false:

   enableCanary: false
   

   Dabei gilt:

   • SERVICE ist ein Name für Ihre Anwendung, z. B. MyApp, Backend oder Frontend.
   • VERSION ist eine Version, z. B. v1.0, build_147 oder v20170714.

   Wir empfehlen, diese über Umgebungsvariablen festzulegen, damit Sie den Quellcode nicht bei jeder Bereitstellung ändern müssen.

Compute Engine

1. Stellen Sie sicher, dass Ihre Compute Engine-VM-Instanzen mit der Zugriffsbereichsoption Vollen Zugriff auf alle Cloud-APIs zulassen eingerichtet sind oder einen der folgenden Zugriffsbereiche haben:

   • https://www.googleapis.com/auth/cloud-platform
   • https://www.googleapis.com/auth/cloud_debugger

2. Installieren Sie das Paket mit npm:

   npm install --save @google-cloud/debug-agent
   

3. Aktivieren Sie den Agent am Anfang des Hauptskripts oder des Einstiegspunkts Ihrer Anwendung (aber gegebenenfalls nach @google/cloud-trace):

   So beheben Sie Fehler mit aktiviertem Canary-Test:

   require('@google-cloud/debug-agent').start({
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Wenn Sie das Debugging mit dem Canary-Release nicht aktivieren möchten, setzen Sie enableCanary auf false:

   enableCanary: false
   

   Dabei gilt:

   • SERVICE ist ein Name für Ihre Anwendung, z. B. MyApp, Backend oder Frontend.
   • VERSION ist eine Version, z. B. v1.0, build_147 oder v20170714.

   Wir empfehlen, diese über Umgebungsvariablen festzulegen, damit Sie den Quellcode nicht bei jeder Bereitstellung ändern müssen.

Der Debugger ist jetzt bereit für die Verwendung mit Ihrer App.

Wenn die Seite "Debugging" in der Cloud Console automatisch Quellcode anzeigen soll, der mit der bereitgestellten Anwendung übereinstimmt, beachten Sie die Hinweise unter Quellcode automatisch auswählen.

Cloud Run und Cloud Run for Anthos

1. Installieren Sie das Paket mit npm:

   npm install --save @google-cloud/debug-agent
   

2. Aktivieren Sie den Agent am Anfang des Hauptskripts oder des Einstiegspunkts Ihrer Anwendung (aber gegebenenfalls nach @google/cloud-trace):

   So beheben Sie Fehler mit aktiviertem Canary-Test:

   require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
   

   Wenn Sie das Debugging mit dem Canary-Release nicht aktivieren möchten, setzen Sie enableCanary auf false:

   enableCanary: false
   

   Der Debugger ist jetzt einsatzbereit, wenn Sie Ihre Anwendung bereitstellen.

Lokal und an anderer Stelle

1. Installieren Sie das Paket mit npm:

   npm install --save @google-cloud/debug-agent
   

2. Laden Sie Anmeldedaten für das Dienstkonto herunter.

   Wenn Sie den Cloud Debugger-Agent für Node.js auf einer Maschine verwenden möchten, die nicht von Google Cloud gehostet wird, muss sich der Agent mithilfe der Anmeldedaten eines Google Cloud-Dienstkontos beim Cloud Debugger-Dienst authentifizieren.

   Verwenden Sie die Cloud Console-Seite "Dienstkonten", um eine Datei mit Anmeldedaten für ein bestehendes oder neues Dienstkonto zu erstellen. Das Dienstkonto muss mindestens die Rolle Cloud Debugger Agent haben.

3. Konfigurieren und aktivieren Sie den Agent mit den heruntergeladenen Anmeldedaten.

   So beheben Sie Fehler mit aktiviertem Canary-Test:

   require('@google-cloud/debug-agent').start({
     projectId: 'your-project-id',
     keyFilename: '/path/to/key.json',
     serviceContext: {
       service: 'SERVICE',
       version: 'VERSION',
       enableCanary: true,
     }
   });
   

   Wenn Sie das Debugging mit dem Canary-Release nicht aktivieren möchten, setzen Sie enableCanary auf false:

   enableCanary: false
   

   Dabei gilt:

   • SERVICE ist ein Name für Ihre Anwendung, z. B. MyApp, Backend oder Frontend.
   • VERSION ist eine Version, z. B. v1.0, build_147 oder v20170714.

   Wir empfehlen, diese über Umgebungsvariablen festzulegen, damit Sie den Quellcode nicht bei jeder Bereitstellung ändern müssen.

Der Debugger ist jetzt bereit für die Verwendung mit Ihrer App.

Auf der Seite "Debugging" der Cloud Console können die lokalen Quelldateien ohne Hochladen für die lokale Entwicklung angezeigt werden. Weitere Informationen finden Sie unter Quellcode manuell auswählen.

Hinweis: Den Code und die Dokumentation des Debugger-Agents finden Sie auf GitHub.