Cloud Debugger für Python einrichten

Überblick

Auf dieser Seite wird beschrieben, wie Sie Ihre Umgebung und Ihre Python-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 Python 3 in den folgenden Rechenumgebungen verfügbar:

App Engine-Standardumgebung Flexible App Engine-Umgebung Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos in Google Cloud 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 für die meisten Projekte standardmäßig aktiviert.
Cloud Debugger API aktivieren

Canary-Snapshots und -Logpoints

Der Debugger-Agent für Python 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.

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

Python 3.7 oder Python 3.8

Wenn Sie Python 3.7 oder Python 3.8 verwenden, müssen Sie den Debugger-Agent mithilfe der folgenden Schritte manuell aktivieren:

  1. Die Datei app.yaml muss die folgenden Zeilen enthalten:

    runtime: python37
    or
    runtime: python38
    
  2. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework (nur Version 1.*) verwenden.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

     breakpoint_enable_canary=False
    
  3. Fügen Sie google-python-cloud-debugger zu requirements.txt hinzu.

  4. Wenn die Seite Debugging in der Cloud Console automatisch Quellcode anzeigen soll, der mit der bereitgestellten Anwendung übereinstimmt, gehen Sie zu Quellcode automatisch auswählen.

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

Flexible App Engine-Umgebung

Sie können den Debugger mit der Python-Laufzeit von App Engine oder einer benutzerdefinierten Laufzeit verwenden.

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

    • Ein 64-Bit-Debian-Linux-Image
    • Python 3
  2. Die Datei app.yaml muss die folgenden Zeilen enthalten:

    runtime: python
    env: flex
    

    Wenn Sie eine benutzerdefinierte Laufzeit nutzen, verwenden Sie runtime: custom.

  3. Fügen Sie google-python-cloud-debugger zu requirements.txt hinzu.

  4. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework (nur Version 1.*) verwenden.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    
  5. 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 bereit für die Verwendung mit Ihrer Anwendung.

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 das Debugger-Paket Ihrer Anwendung hinzu:

    Wenn Sie eine Datei requirements.txt verwenden, fügen Sie folgende Zeile hinzu:

      google-python-cloud-debugger
    

    Wenn Sie ein Dockerfile verwenden, fügen Sie die folgende Zeile hinzu:

      RUN pip install google-python-cloud-debugger
    
  3. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework verwenden:

    So beheben Sie Fehler mit aktiviertem Canary-Test:

      try:
        import googleclouddebugger
        googleclouddebugger.enable(
          breakpoint_enable_canary=True
        )
      except ImportError:
        pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests NICHT aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

      breakpoint_enable_canary=False
    

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.

KONSOLE

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

  1. Klicken Sie nach der Auswahl des Clustertyps im Bereich Node pools (Knotenpools) auf More options (Weitere Optionen):

    Das Feld

  2. Wählen Sie im Bereich Sicherheit eine der folgenden Optionen aus:

    • Uneingeschränkten Zugriff auf alle Cloud APIs zulassen.

    • Zugriff für jede API festlegen. Wählen Sie anschließend Aktiviert für Cloud Debugger aus.

  3. Fügen Sie das Debugger-Paket Ihrer Anwendung hinzu:

    Wenn Sie eine Datei requirements.txt verwenden, fügen Sie folgende Zeile hinzu:

    google-python-cloud-debugger
    

    Wenn Sie ein Dockerfile verwenden, fügen Sie die folgende Zeile hinzu:

    RUN pip install google-python-cloud-debugger
    
  4. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework verwenden:

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    

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.

Compute Engine

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

    • Ein 64-Bit-Debian-Linux-Image
    • Python 3
  2. Prüfen Sie, ob 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 den Debugger-Agent herunter.

    Am einfachsten installieren Sie den Python-Debugger mit [pip][pip]:

    pip install google-python-cloud-debugger
    
  4. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework verwenden.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        module='[MODULE]',
        version='[VERSION]'
        breakpoint_enable_canary=True
      )
    except ImportError:
      pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    

    Wenn Sie den Code nicht ändern können, kann der Debugger-Agent als Modul ausgeführt werden.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    python -m googleclouddebugger \
          --module=[MODULE] \
          --version=[VERSION] \
          --breakpoint_enable_canary=True
          -- \
          myapp.py
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    

    Ersetzen Sie die Platzhalter im Befehl so:

    • [MODULE] ist der Name Ihrer Anwendung.
      Zusammen mit der Version wird dadurch das Debugging-Ziel auf der Seite Debugging der Cloud Console angegeben.
      Beispiele: MyApp, Backend oder Frontend.
    • [VERSION] ist die Anwendungsversion, z. B. die Build-ID.
      Auf der Seite Debugging der Cloud Console wird die ausgeführte Version als [MODULE] - [VERSION] angezeigt.
      Beispielwerte: v1.0, build_147 oder v20170714.

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

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 in Google Cloud

  1. Python-Paket.

    Wenn Sie eine Datei requirements.txt verwenden, fügen Sie folgende Zeile hinzu:

    google-python-cloud-debugger
    

    Falls nicht, fügen Sie die folgende Zeile zu Ihrem Dockerfile hinzu:

    RUN pip install google-python-cloud-debugger
    
  2. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework verwenden:

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
        breakpoint_enable_canary=True
      )
    
    except ImportError:
      pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    

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. Achten Sie darauf, dass auf Ihrer Workstation Folgendes ausgeführt wird:

    • Ein 64-Bit-Debian-Linux-Image
    • Python 3
  2. Laden Sie den Debugger-Agent herunter.

    Am einfachsten installieren Sie den Python-Debugger mit [pip][pip]{: .external}:

    pip install google-python-cloud-debugger
    
  3. Laden Sie Anmeldedaten für das Dienstkonto herunter.

    Wenn Sie den Cloud Debugger-Agent für Python 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 Python ein.

  4. Fügen Sie die folgenden Zeilen so früh wie möglich in Ihren Initialisierungscode ein, z. B. in Ihre Hauptfunktion oder in manage.py, wenn Sie das Django-Web-Framework verwenden.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    try:
      import googleclouddebugger
      googleclouddebugger.enable(
          module='[MODULE]',
          version='[VERSION]',
          breakpoint_enable_canary=True
          service_account_json_file='/opt/cdbg/gcp-svc.json')
    except ImportError:
      pass
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests NICHT aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    

    Wenn Sie den Code nicht ändern können, kann der Debugger-Agent als Modul ausgeführt werden.

    So beheben Sie Fehler mit aktiviertem Canary-Test:

    python \
        -m googleclouddebugger \
        --module=[MODULE] \
        --version=[VERSION] \
        --breakpoint_enable_canary=True
        --service_account_json_file=/opt/cdbg/gcp-svc.json \
        -- \
        myapp.py
    

    Wenn Sie Fehler beheben möchten, bei denen Canary-Tests nicht aktiviert sind, setzen Sie den Parameter breakpoint_enable_canary auf False:

    breakpoint_enable_canary=False
    

    Ersetzen Sie die Platzhalter im Befehl so:

    • [MODULE] ist der Name Ihrer Anwendung.
      Zusammen mit der Version wird dadurch das Debugging-Ziel auf der Seite Debugging der Cloud Console angegeben.
      Beispiele: MyApp, Backend oder Frontend.
    • [VERSION] ist die Anwendungsversion, z. B. die Build-ID.
      Auf der Seite Debugging der Cloud Console wird die ausgeführte Version als [MODULE] - [VERSION] angezeigt.
      Beispielwerte: v1.0, build_147 oder v20170714.
    • Sie können die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS verwenden, statt service_account_json_file anzugeben.

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

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