Como configurar o Stackdriver Debugger para Python

Alfa

Este produto ou recurso está em um estado de pré-lançamento e pode ser alterado ou ter suporte limitado. Para mais informações, consulte Estágios de lançamento do produto.

Observação: o Stackdriver Debugger está totalmente disponível para Python 2.7.

Esta página descreve como configurar seu ambiente e seu aplicativo Python para usar o Stackdriver Debugger. Para alguns ambientes, é preciso especificar explicitamente o escopo de acesso para permitir que o agente do Stackdriver Debugger envie dados. Recomendamos definir o escopo de acesso da forma mais ampla possível e, em seguida, usar o Cloud Identity and Access Management para restringir o acesso. Para manter essa prática recomendada, defina o escopo de acesso para todas as APIs Cloud com a opção cloud-platform.

Ambiente padrão do App Engine

Se você estiver usando o Python 2.7, o depurador será ativado por padrão e nenhuma configuração será necessária.

Se você estiver usando o Python 3.7, precisará ativar manualmente os agentes do depurador seguindo as instruções para o ambiente flexível do App Engine.

A página de depuração no Console do GCP exibe automaticamente os arquivos implantados que correspondem ao código-fonte do app. Para saber mais sobre a correspondência de código-fonte, consulte Como selecionar o código-fonte automaticamente.

Ambiente flexível do App Engine

Você pode usar o depurador com o tempo de execução do Python ou o tempo de execução personalizado do App Engine.

1. Verifique se as instâncias de VM do ambiente flexível do App Engine estão executando:

   • uma imagem Debian Linux de 64-bit;
   • Python 2.7 ou 3.6

2. Verifique se o arquivo app.yaml contém as seguintes linhas:

   runtime: python
   env: flex
   
   # The Python runtime uses Python 3.6 by default.
   # To use Python 2.7 add the following lines.
   # runtime_config:
   #   python_version: 2
   

   Se você estiver usando um tempo de execução personalizado, use runtime: custom.

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

4. Adicione as seguintes linhas o quanto antes ao código de inicialização, como na função principal, ou em manage.py ao usar a biblioteca do Django na Web (somente versão 1.*).

   try:
     import googleclouddebugger
     googleclouddebugger.enable()
   except ImportError:
     pass
   

O depurador está pronto para ser usado com o app.

Para que a página "Depuração" no Console do GCP mostre automaticamente o código-fonte correspondente ao aplicativo implantado, consulte Como selecionar o código-fonte automaticamente.

Google Kubernetes Engine

1. Crie seu cluster com um dos seguintes escopos de acesso:
   • https://www.googleapis.com/auth/cloud-platform
   • https://www.googleapis.com/auth/cloud_debugger
   Observação: não é possível alterar os escopos de acesso de um cluster após a criação.

   Para criar um cluster usando o gcloud, faça o seguinte:

   1. Atualize o gcloud para a versão mais recente (opcional):

      gcloud components update

   2. Defina o código do projeto padrão:

      gcloud config set project [PROJECT_ID]

   3. Se você estiver trabalhando com clusters zonais, defina a zona de computação padrão:

      gcloud config set compute/zone [COMPUTE_ZONE]

   4. Se você estiver trabalhando com clusters regionais, defina a região de computação padrão:

      gcloud config set compute/region [COMPUTE_REGION]

   5. Execute o comando de criação:

      gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform

   Para informações mais detalhadas, consulte Como criar um cluster.

2. Siga as instruções do Compute Engine.

Compute Engine

1. Verifique se as instâncias de VM do Compute Engine estão executando:

   • uma imagem Debian Linux de 64-bit;
   • Python 2.7 ou 3.7.

2. Verifique se as instâncias de VM do Compute Engine foram criadas com a opção de escopo de acesso Permitir acesso completo a todas as APIs do Cloud ou se elas têm um dos seguintes escopos de acesso:

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

3. Faça o download do agente do Debugger.

   A maneira mais fácil de instalar o Stackdriver Debugger para Python é com o pip:

   pip install google-python-cloud-debugger
   

4. Adicione as seguintes linhas o quanto antes ao código de inicialização, como na função principal, ou em manage.py ao usar a biblioteca do Django na Web.

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

   Como alternativa, se você não tem permissão para alterar o código, execute o agente do Debugger como um módulo:

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

   Sendo que, em ambos os casos, vale o seguinte:

   • [MODULE] é o nome do app.
     Juntamente com a versão, essa informação é usada para identificar o destino da depuração na respectiva página do Console do GCP.
     Exemplos: MyApp, Backend ou Frontend.
   • [VERSION] é a versão do app (por exemplo, o código da versão).
     A página "Depuração" do Console do GCP mostra a versão em execução como [MODULE] - [VERSION].
     Exemplos de valores: v1.0, build_147 ou v20170714.

O depurador está pronto para ser usado com o app.

Para que a página "Depuração" no Console do GCP mostre automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.

Ambiente local e outros

1. Verifique se sua estação de trabalho está executando:

   • uma imagem Debian Linux de 64-bit;
   • Python 2.7 ou 3.7.

2. Faça o download do agente do Debugger.

   A maneira mais fácil de instalar o Stackdriver Debugger para Python é com o pip:

   pip install google-python-cloud-debugger
   

3. Faça o download das credenciais da conta de serviço.
   Para usar o agente do Stackdriver Debugger para Python em máquinas não hospedadas pelo Google Cloud Platform, o agente deve usar as credenciais de uma conta de serviço do GCP para se autenticar com o serviço Stackdriver Debugger.

   Use a página Contas de serviço do Console do GCP para criar um arquivo de credenciais para uma conta de serviço nova ou existente. A conta de serviço precisa ter pelo menos o papel Stackdriver Debugger Agent.

   Coloque o arquivo JSON da conta de serviço ao lado do agente do Stackdriver Debugger para Python.

4. Adicione as seguintes linhas o quanto antes ao código de inicialização, como na função principal, ou em manage.py ao usar a biblioteca do Django na Web.

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

   Como alternativa, se você não tem permissão para alterar o código, execute o agente do Debugger como um módulo:

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

   Sendo que, em ambos os casos, vale o seguinte:

   • [MODULE] é o nome do app.
     Juntamente com a versão, essa informação é usada para identificar o destino da depuração na respectiva página do Console do GCP.
     Exemplos: MyApp, Backend ou Frontend.
   • [VERSION] é a versão do app (por exemplo, o código da versão).
     A página "Depuração" do Console do GCP mostra a versão em execução como [MODULE] - [VERSION].
     Exemplos de valores: v1.0, build_147 ou v20170714.
   • A variável de ambiente GOOGLE_APPLICATION_CREDENTIALS pode ser usada no lugar da especificação de service_account_json_file.

O depurador está pronto para ser usado com o app.

A página "Depuração" no Console do GCP pode mostrar arquivos de origem locais, sem upload, para desenvolvimento local. Consulte Como selecionar o código-fonte manualmente.

Observação: você encontra o código e a documentação do agente do depurador no GitHub.

Como solucionar problemas

O pacote google-python-cloud-debugger do Python requer o pacote python2.7-dev do Linux e os pacotes setuptools e wheel do Python. Esses pacotes costumam estar instalados quando você instala pip com todas as dependências sugeridas, porém, a ausência de alguns deles pode causar os erros a seguir.

1. ImportError: No module named setuptools

   O pacote setuptools do Python precisa ser instalado (por exemplo, pip install setuptools).

2. invalid command 'bdist_wheel' ou Failed building wheel for '...'

   O pacote wheel do Python precisa ser instalado (por exemplo, pip install wheel).

3. ImportError: libpython2.7.so.1.0: cannot open shared object file: No such file or directory

   O pacote python2.7-dev do Linux precisa ser instalado. Por exemplo, apt-get install python2.7-dev.