Cloud Debugger è deprecato e verrà chiuso il 31 maggio 2023. Per ulteriori informazioni, consulta la pagina relativa ai ritiri e alle note di rilascio.

Configurazione di Cloud Debugger per Python

Panoramica

In questa pagina viene descritto come configurare il tuo ambiente e la tua applicazione Python per utilizzare Cloud Debugger. Per alcuni ambienti, devi specificare esplicitamente l'ambito di accesso per consentire all'agente Cloud Debugger di inviare i dati. Ti consigliamo di impostare l'ambito di accesso più ampio possibile e quindi utilizzare Identity and Access Management per limitare l'accesso. In linea con questa best practice, imposta l'ambito di accesso su tutte le API Cloud con l'opzione cloud-platform.

Versioni linguistiche degli ambienti di calcolo

Cloud Debugger è disponibile per Python 3 nei seguenti ambienti di computing:

Ambiente standard di App Engine Ambiente flessibile di App Engine Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos VM e container in esecuzione altrove Cloud Functions

Configurazione di Cloud Debugger

Per configurare Cloud Debugger, completa le seguenti attività:

  1. Verifica che l'API Cloud Debugger sia abilitata per il tuo progetto.

  2. Installa e configura Debugger nell'ambiente di calcolo che stai utilizzando.

  3. Seleziona il tuo codice sorgente.

Verifica dell'abilitazione dell'API Cloud Debugger

Per iniziare a utilizzare Cloud Debugger, assicurati che l'API Cloud Debugger sia abilitata. Cloud Debugger è abilitato per impostazione predefinita per la maggior parte dei progetti.
Abilita l'API Cloud Debugger

Snapshot e punti di log canary

Per impedire il caricamento simultaneo di snapshot e punti di log in tutte le istanze in esecuzione, causando potenzialmente la rimozione del job a causa di un bug potenziale dell'agente Debugger, abilita la modalità canary per l'agente Debugger. Quando la modalità canary è abilitata, uno snapshot o un punto di log viene applicato a un sottoinsieme di istanze in esecuzione e Debugger verifica che l'istantanea o il punto di log non influisca negativamente su tali istanze. Al termine della verifica, lo snapshot o il punto di log viene applicato a tutte le istanze.

Per informazioni su come utilizzare Debugger in modalità canary, consulta le pagine relative a Debug snapshot e Debug punti di log.

Attivazione di snapshot e punti di log canary

Quando installi la versione più recente dell'agente Debugger, puoi scegliere di attivare o disattivare la versione canary. La versione canary è disattivata per impostazione predefinita.

Quando attivare snapshot e punti di log canary

Per proteggere i carichi di lavoro di deployment e critici per la produzione, abilita la versione canary durante il debug di questi carichi di lavoro.

Se hai una singola istanza, puoi eseguire il debug con la versione canary, ma l'istanza singola viene eseguita senza eliminare lo snapshot o il punto di log.

Quando non attivare snapshot canary e punti di log

Non attivare la versione canary su carichi di lavoro che hanno un tempo di esecuzione inferiore a 40 secondi, ad esempio i job che utilizzano Cloud Functions.

Non attivare la versione canary se vuoi un ciclo di attivazione degli snapshot più veloce.

Per configurare l'agente Debugger in modo che non esegua snapshot canary e punti di log, consulta le istruzioni di installazione per la piattaforma Google Cloud che stai utilizzando.

Ambiente standard di App Engine

Python 3.7 o Python 3.8

Se utilizzi Python 3.7 o Python 3.8, devi abilitare manualmente l'agente di debug eseguendo i seguenti passaggi:

  1. Assicurati che il file app.yaml contenga le seguenti righe:

    runtime: python37
    or
    runtime: python38
    
  2. Aggiungi le righe seguenti il prima possibile nel tuo codice di inizializzazione, ad esempio nella funzione principale, o in manage.py quando utilizzi il framework web Django (solo versione 1.*).

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

     breakpoint_enable_canary=False
    
  3. Aggiungi google-python-cloud-debugger a requirements.txt.

  4. Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'app di cui hai eseguito il deployment, vai a Selezione automatica del codice sorgente.

Debugger è pronto per essere utilizzato con la tua app.

Ambiente flessibile di App Engine

Puoi utilizzare Debugger con il runtime Python di App Engine o un runtime personalizzato.

  1. Assicurati che le istanze VM dell'ambiente flessibile di App Engine siano in esecuzione:

    • Immagine di Debian a 64 bit
    • Python 3
  2. Assicurati che il file app.yaml contenga le seguenti righe:

    runtime: python
    env: flex
    

    Se utilizzi un runtime personalizzato, usa runtime: custom.

  3. Aggiungi google-python-cloud-debugger a requirements.txt.

  4. Aggiungi le righe seguenti il prima possibile nel tuo codice di inizializzazione, ad esempio nella funzione principale, o in manage.py quando utilizzi il framework web Django (solo versione 1.*).

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    
  5. Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'applicazione di cui è stato eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.

Debugger è pronto per essere utilizzato con la tua app.

Google Kubernetes Engine

GCLOUD

Per attivare Debugger utilizzando gcloud, completa i seguenti passaggi:

  1. Crea il cluster con uno dei seguenti ambiti di accesso:

    • https://www.googleapis.com/auth/cloud-platform concede al cluster l'accesso a tutte le API di Google Cloud.

    • https://www.googleapis.com/auth/cloud_debugger concede al cluster l'accesso solo all'API Debugger. Utilizza questo ambito di accesso per proteggere la sicurezza del tuo cluster.

    gcloud container clusters create example-cluster-name \
           --scopes=https://www.googleapis.com/auth/cloud_debugger
    
  2. Aggiungi il pacchetto Debugger all'app:

    Se utilizzi un file requirements.txt, aggiungi la seguente riga:

      google-python-cloud-debugger
    

    Se utilizzi un Dockerfile, aggiungi la seguente riga:

      RUN pip install google-python-cloud-debugger
    
  3. Aggiungi le righe seguenti appena possibile nel codice di inizializzazione, ad esempio nella funzione principale, o in manage.py quando utilizzi il framework web Django:

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary NON abilitata, imposta il parametro breakpoint_enable_canary su False:

      breakpoint_enable_canary=False
    

Nella pagina Debug, seleziona la posizione del codice sorgente. Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'app di cui hai eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.

Il debugger è ora pronto all'uso.

CONSOLE

Per abilitare Debugger utilizzando Google Cloud Console, procedi nel seguente modo:

  1. Nella sezione Pool di nodi, seleziona Sicurezza, quindi seleziona Imposta l'accesso per ogni API.

  2. Abilita Debugger.

    L'API Debugger è abilitata per il cluster.

  3. (Facoltativo) Seleziona Consenti l'accesso completo a tutte le API Cloud.

  4. Aggiungi il pacchetto Debugger all'app:

    Se utilizzi un file requirements.txt, aggiungi la seguente riga:

    google-python-cloud-debugger
    

    Se utilizzi un Dockerfile, aggiungi la seguente riga:

    RUN pip install google-python-cloud-debugger
    
  5. Aggiungi le righe seguenti appena possibile nel codice di inizializzazione, ad esempio nella funzione principale, o in manage.py quando utilizzi il framework web Django:

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    

Nella pagina Debug, seleziona la posizione del codice sorgente. Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'app di cui hai eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.

Il debugger è ora pronto all'uso.

Compute Engine

  1. Assicurati che le istanze VM di Compute Engine siano in esecuzione:

    • Immagine di Debian a 64 bit
    • Python 3
  2. Assicurati che le istanze VM di Compute Engine siano create con l'opzione ambito di accesso Consenti l'accesso completo a tutte le API Cloud oppure disponi di uno dei seguenti ambiti di accesso:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  3. Scarica l'agente Debugger.

    Il modo più semplice per installare il debugger Python è pip:

    pip install google-python-cloud-debugger
    
  4. Aggiungi le righe seguenti il prima possibile nel tuo codice di inizializzazione, ad esempio nella funzione principale, o in manage.py quando utilizzi il framework web di Django.

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    

    Se non riesci a modificare il codice, esegui l'agente Debugger come modulo.

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    

    Sostituisci i segnaposto nel comando come indicato di seguito:

    • [MODULE] è il nome dell'app.
      Insieme alla versione, viene utilizzato per identificare il target di debug nella pagina Debug della console.
      Esempi: MyApp, Backend o Frontend.
    • [VERSION] è la versione dell'app (ad esempio, l'ID build).
      La pagina Debug della console mostra la versione in esecuzione come [MODULE] - [VERSION].
      Valori di esempio: v1.0, build_147 o v20170714.

Debugger è pronto per essere utilizzato con la tua app.

Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'applicazione di cui è stato eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.

Cloud Run e Cloud Run for Anthos

  1. Pacchetto Python.

    Se utilizzi un file requirements.txt, aggiungi la seguente riga:

    google-python-cloud-debugger
    

    In caso contrario, aggiungi la seguente riga al tuo Dockerfile:

    RUN pip install google-python-cloud-debugger
    
  2. Aggiungi le righe seguenti appena possibile nel codice di inizializzazione, ad esempio nella funzione principale, o in manage.py quando utilizzi il framework web Django:

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    

Nella pagina Debug, seleziona la posizione del codice sorgente. Per fare in modo che la pagina Debug nella console mostri automaticamente il codice sorgente corrispondente all'app di cui hai eseguito il deployment, consulta la sezione Selezionare automaticamente il codice sorgente.

Il debugger è ora pronto all'uso.

Locale e altrove

  1. Assicurati che la workstation sia in esecuzione:

    • Immagine di Debian a 64 bit
    • Python 3
  2. Scarica l'agente Debugger.

    Il modo più semplice per installare il debugger Python è pip:

    pip install google-python-cloud-debugger
    
  3. Scarica le credenziali dell'account di servizio.

    Per utilizzare l'agente Cloud Debugger per Python su macchine non ospitate da Google Cloud, l'agente deve utilizzare le credenziali dell'account di servizio Google Cloud per eseguire l'autenticazione con il servizio Cloud Debugger.

    Utilizza la pagina Account di servizio della console per creare un file delle credenziali per un account di servizio nuovo o esistente. L'account di servizio deve avere almeno il ruolo Cloud Debugger Agent.

    Inserisci il file JSON dell'account di servizio insieme all'agente Cloud Debugger per Python.

  4. Aggiungi le righe seguenti il prima possibile nel tuo codice di inizializzazione, ad esempio nella tua funzione principale, o in manage.py quando utilizzi Django Web Framework.

    Per eseguire il debug con la versione canary attivata:

    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
    

    Per eseguire il debug con la versione canary NON abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    

    Se non riesci a modificare il codice, esegui l'agente Debugger come modulo.

    Per eseguire il debug con la versione canary attivata:

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

    Per eseguire il debug con la versione canary non abilitata, imposta il parametro breakpoint_enable_canary su False:

    breakpoint_enable_canary=False
    

    Sostituisci i segnaposto nel comando come indicato di seguito:

    • [MODULE] è il nome dell'app.
      Insieme alla versione, viene utilizzato per identificare il target di debug nella pagina Debug della console.
      Esempi: MyApp, Backend o Frontend.
    • [VERSION] è la versione dell'app (ad esempio, l'ID build).
      La pagina Debug della console mostra la versione in esecuzione come [MODULE] - [VERSION].
      Valori di esempio: v1.0, build_147 o v20170714.
    • È possibile utilizzare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS anziché specificare service_account_json_file.

Debugger è pronto per essere utilizzato con la tua app.

Nella pagina Debug della console possono essere visualizzati i file di origine locali, senza caricamento, per lo sviluppo locale. Consulta Selezione manuale del codice sorgente.