Cloud Debugger für Java einrichten

Übersicht

Auf dieser Seite wird beschrieben, wie Sie Ihre Umgebung und Ihre Java-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 die Java-Versionen 7, 8, 9 und 11 in den folgenden Rechenumgebungen 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

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.

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

Canary-Snapshots und -Logpoints

Aktivieren Sie den Canary-Modus für Debugger-Agent, damit Snapshots und Logpoints nicht auf allen ausgeführten Instanzen gleichzeitig geladen werden und der Job aufgrund eines potenziellen Programmfehlers im Debugger-Agent deaktiviert wird. Wenn der Canary-Modus aktiviert ist, wird ein Snapshot oder Logpoint auf eine Teilmenge der ausgeführten Instanzen angewendet und Debugger prüft, ob der Snapshot oder Logpoint diese Instanzen nicht beeinträchtigt. Nach Abschluss der Prüfung wird der Snapshot oder Logpoint auf alle Instanzen angewendet.

Um einen möglichen Programmfehler im Debugger-Agent zu verhindern

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-Standardumgebung

Der Debugger ist standardmäßig aktiviert. Eine Konfiguration ist nicht erforderlich. Auf der Seite Debuggen in der Cloud Console wird versucht, die Java-Quelldateien anzuzeigen, die zum Erstellen der App verwendet werden.

Beachten Sie, dass die Cloud Console nicht funktioniert, wenn der URL-Abruf aktiviert ist.

Weitere Informationen finden Sie unter Quellcode automatisch auswählen.

Flexible App Engine-Umgebung

Der Debugger ist standardmäßig für die Java-Laufzeit aktiviert. Eine Konfiguration ist nicht erforderlich. Auf der Seite Debuggen in der Cloud Console wird versucht, die Java-Quelldateien anzuzeigen, die zum Erstellen der Anwendung verwendet wurden.

Der Debugger ist standardmäßig für benutzerdefinierte Laufzeiten enthalten, die die von Google bereitgestellten Basis-Images für Java verwenden. Wenn der Standardeinstiegspunkt verwendet wird, ist keine Konfiguration erforderlich. Auf der Seite Debuggen in der Cloud Console wird versucht, die Java-Quelldateien anzuzeigen, die zum Erstellen der App verwendet werden.

Wenn Sie Cloud Debugger mit benutzerdefinierten Laufzeiten verwenden möchten, die mit anderen Basis-Images erstellt wurden, folgen Sie der Anleitung für die Einrichtung für Compute Engine.

Weitere Informationen finden Sie 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

  2. Fügen Sie Ihrem Dockerfile die folgenden Zeilen hinzu, um den Debugger-Agent zu Ihrer containerisierten Anwendung hinzuzufügen und ihn zu initialisieren, wenn die Anwendung bereitgestellt wird: 

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
RUN mkdir /opt/cdbg && \
     wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
     tar xvz -C /opt/cdbg

    Ändern Sie die URL in den folgenden Wert, um eine frühere Version des Agents zu installieren:

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    Ersetzen Sie VERSION_NUMBER durch die Version des Agents, den Sie verwenden möchten, z. B. https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. Canary-Tests sind in Versionen vor 2.25 nicht verfügbar. Die Versionen des Debugger-Agents finden Sie auf der GitHub-Seite für den Java-Agent.

  3. Fügen Sie dem Dockerfile die folgenden Zeilen hinzu, um den Debugger-Agent auszuführen:

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    # Start the agent when the app is deployed.
RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Ersetzen Sie die Platzhalter im Befehl so:

    • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

    • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

    • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

    • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

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

Mit den folgenden Schritten aktivieren Sie Debugger mithilfe der Google Cloud Console:

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

  2. Debugger aktivieren

    Die Debugger API ist für den Cluster aktiviert.

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

  4. Fügen Sie dem Dockerfile die folgenden Zeilen hinzu, um den Debugger-Agent auszuführen:

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    # Start the agent when the app is deployed.
RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Ersetzen Sie die Platzhalter im Befehl so:

    • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

    • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

    • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

    • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

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.

Compute Engine

Sie können Cloud Debugger mit jeder Java-Anwendung verwenden, die auf einer Google Compute Engine-Instanz ausgeführt wird. Wir empfehlen, Debugger für alle laufenden Instanzen Ihrer Anwendung zu aktivieren.

  1. Achten Sie darauf, dass auf Ihren Compute Engine VM-Instanzen Folgendes ausgeführt wird:

    • Ein 64-Bit-Debian-Linux-Image
    • Java JDK Version 7, 8 oder 9

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

  3. Laden Sie das vorgefertigte Agent-Paket herunter:

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
sudo mkdir /opt/cdbg
     wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
     tar xvz -C /opt/cdbg

    Ändern Sie die URL in den folgenden Wert, um eine frühere Version des Agents zu installieren:

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    Ersetzen Sie VERSION_NUMBER durch die Version des Agents, den Sie verwenden möchten, z. B. https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. Canary-Tests sind in Versionen vor 2.25 nicht verfügbar. Die Versionen des Debugger-Agents finden Sie auf der GitHub-Seite für den Java-Agent.

  4. Fügen Sie den Agent Ihrem Java-Aufruf hinzu:
    (Wenn Sie Tomcat oder Jetty verwenden, lesen Sie den Abschnitt Webserver.)

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    # Start the agent when the app is deployed.
java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Ersetzen Sie die Platzhalter im Befehl so:

    • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

    • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

    • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

    • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

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.

Webserver

Java-Webserver starten in der Regel mit einem Bootstrap-Vorgang und die Anpassung der Java-Optionen erfolgt bei jedem Webserver auf andere Art.

Tomcat

Fügen Sie diese Zeile zu /etc/default/tomcat7 oder /etc/default/tomcat8 hinzu:

So beheben Sie Fehler mit aktiviertem Canary-Test:

# Start the agent when the app is deployed.
JAVA_OPTS="${JAVA_OPTS} -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true"

Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Ersetzen Sie die Platzhalter im Befehl so:

  • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

  • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

  • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

  • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

Wenn Sie Tomcat in einem Docker-Container ausführen, fügen Sie stattdessen diese Zeile im Dockerfile ein:

So beheben Sie Fehler mit aktiviertem Canary-Test:

# Start the agent when the app is deployed.
ENV JAVA_OPTS -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.module=MODULE \
    -Dcom.google.cdbg.version=VERSION \
    -Dcom.google.cdbg.breakpoints.enable_canary=true

Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Ersetzen Sie die Platzhalter im Befehl so:

  • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

  • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

  • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

  • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

Jetty

Fügen Sie diese Zeilen /var/lib/jetty/start.d hinzu:

So beheben Sie Fehler mit aktiviertem Canary-Test:

--exec
-agentpath:/opt/cdbg/cdbg_java_agent.so \
-Dcom.google.cdbg.module=MODULE \
-Dcom.google.cdbg.version=VERSION \
-Dcom.google.cdbg.breakpoints.enable_canary=true

Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

-Dcom.google.cdbg.breakpoints.enable_canary=false

Ersetzen Sie die Platzhalter im Befehl so:

  • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

  • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

  • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

  • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

Cloud Run und Cloud Run for Anthos

  1. Fügen Sie Ihrem Dockerfile die folgenden Befehle hinzu, um ein Verzeichnis zu erstellen, in dem der Debugger-Agent installiert, das Debugger-Agent-Archiv heruntergeladen und in das Installationsverzeichnis extrahiert wird:

    # Create a directory for the Debugger. Add and unzip the agent in the directory.
RUN mkdir /opt/cdbg && \
     wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_gce.tar.gz | \
     tar xvz -C /opt/cdbg

    Ändern Sie die URL in den folgenden Wert, um eine frühere Version des Agents zu installieren:

    https://storage.googleapis.com/cloud-debugger/archive/java/VERSION_NUMBER/cdbg_java_agent_gce.tar.gz

    Ersetzen Sie VERSION_NUMBER durch die Version des Agents, den Sie verwenden möchten, z. B. https://storage.googleapis.com/cloud-debugger/archive/java/2.21/cdbg_java_agent_gce.tar.gz. Canary-Tests sind in Versionen vor 2.25 nicht verfügbar. Die Versionen des Debugger-Agents finden Sie auf der GitHub-Seite für den Java-Agent.

    Suchen Sie den Java-Aufruf und fügen Sie das folgende Flag hinzu, um den Debugger-Agent zu initialisieren.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    # Start the agent when the app is deployed.
RUN java -agentpath:/opt/cdbg/cdbg_java_agent.so \
    -Dcom.google.cdbg.breakpoints.enable_canary=true \
    -jar PATH_TO_JAR_FILE

    Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Ersetzen Sie die Platzhalter im Befehl so:

    • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

Wählen Sie auf der Seite Debugging den Speicherort Ihres Quellcodes aus. 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.

Der Debugger ist jetzt einsatzbereit.

Lokal und an anderer Stelle

  1. Laden Sie das vorgefertigte Agent-Paket des Debuggers herunter:

    mkdir /opt/cdbg
wget -qO- https://storage.googleapis.com/cloud-debugger/compute-java/debian-wheezy/cdbg_java_agent_service_account.tar.gz | \
    tar xvz -C /opt/cdbg

  2. Laden Sie Anmeldedaten für das Dienstkonto herunter.
    Wenn Sie den Cloud Debugger-Agent für Java 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.

    Fügen Sie die JSON-Datei des Dienstkontos zusammen mit dem Cloud Debugger-Agent für Java ein.

  3. Fügen Sie den Agent Ihrem Java-Aufruf hinzu:

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    java -agentpath:/opt/cdbg/cdbg_java_agent.so \
  -Dcom.google.cdbg.module=MODULE \
  -Dcom.google.cdbg.version=VERSION \
  -Dcom.google.cdbg.breakpoints.enable_canary=true \
  -Dcom.google.cdbg.auth.serviceaccount.enable=true \
  -Dcom.google.cdbg.auth.serviceaccount.jsonfile=/opt/cdbg/gcp-svc.json \
  -jar PATH_TO_JAR_FILE

    Für die Fehlerbehebung bei NICHT aktivierten Canary-Tests setzen Sie das Flag enable_canary auf false:

    -Dcom.google.cdbg.breakpoints.enable_canary=false

    Ersetzen Sie die Platzhalter im Befehl so:

    • PATH_TO_JAR_FILE ist der relative Pfad zur JAR-Datei der Anwendung. Beispiel: ~/myapp.jar.

    • MODULE ist der Name der Anwendung. Beispiel: MyApp, Backend oder Frontend.

    • VERSION ist die Anwendungsversion oder die Build-ID. Beispiel: v1.0 oder build_147. Sie können die Versionsnummer anhand Ihres Releaseprozesses ermitteln und den Wert entsprechend festlegen.

    • Sowohl MODULE als auch VERSION werden in der Google Cloud Console als MODULE - VERSION angezeigt. Beispiel: MyApp - v1.0 oder Backend - build_147.

    • Sie können die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verwenden, statt das Systemattribut auth.serviceaccount.jsonfile hinzuzufügen.

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.