Como configurar o Cloud Debugger para Python

Visão geral

Esta página descreve como configurar seu ambiente e aplicativo Python para usar o Cloud Debugger. Para alguns ambientes, é necessário especificar explicitamente o escopo de acesso para que o agente do Cloud Debugger envie dados. Recomendamos definir o escopo de acesso da forma mais ampla possível e depois usar o Gerenciador de identidade e acesso para restringir o acesso. Para manter essa prática recomendada, configure o escopo de acesso para todas as APIs do Cloud com a opção cloud-platform.

Versões de linguagem e ambientes de computação

O Cloud Debugger está disponível para Python 3 nos seguintes ambientes de computação:

Ambiente padrão do App Engine Ambiente flexível do App Engine Compute Engine Google Kubernetes Engine Cloud Run Cloud Run for Anthos VMs e contêineres em execução em outra plataforma Cloud Functions

Como configurar o Cloud Debugger

Para configurar o Cloud Debugger, conclua as seguintes tarefas:

  1. Verifique se a API Cloud Debugger está ativada no projeto.

  2. Instale e configure o Debugger no ambiente de computação que você está usando.

  3. Selecione o código-fonte.

Como verificar se a API Cloud Debugger está ativada

Para começar a usar o Cloud Debugger, verifique se a API Cloud Debugger está ativada. O Cloud Debugger é ativado por padrão na maioria dos projetos.
Ativar a API Cloud Debugger

Snapshots e logpoints do canary

Para evitar que snapshots e logpoints sejam carregados em todas as instâncias em execução ao mesmo tempo e possivelmente fazer com que o job seja removido devido a um possível bug no agente do Debugger, ative o modo canário para o Agente do Debugger. Quando o modo canário estiver ativado, um snapshot ou logpoint será aplicado a um subconjunto de instâncias em execução. Já o Debugger verifica se o snapshot ou o logpoint não afetam negativamente essas instâncias. Após a conclusão da verificação, o snapshot ou logpoint será aplicado a todas as instâncias.

Para saber como usar o Debugger no modo canário, acesse as páginas Snapshots do Debug e Logpoints do Debug.

Como ativar snapshots e logpoints de canary

Ao instalar a versão mais recente do agente do Debugger, você tem a opção de ativar ou desativar a configuração de um canary. A configuração de um canary está desativada por padrão.

Quando ativar snapshots e logpoints de canary

Para proteger cargas de trabalho essenciais de implantação e produção, ative a configuração de canário ao depurar dessas cargas de trabalho

Se você tiver uma única instância, ainda será possível depurar com a configuração de canary ativada, mas a única instância será executada sem a configuração de canary para o snapshot ou logpoint.

Quando não ativar snapshots e logpoints de canary

Não ative a configuração de canary em cargas de trabalho com tempo de execução inferior a 40 segundos, por exemplo, jobs que usam o Cloud Functions.

Não ative a configuração de canary se quiser um ciclo de acionamento de snapshots mais rápido.

Para configurar o agente do Debugger para não realizar a configuração de canary em snapshots e logpoints, acesse as instruções de instalação do Google Cloud Platform que você está usando.

Ambiente padrão do App Engine

Python 3.7 ou Python 3.8

Se você estiver usando o Python 3.7 ou o Python 3.8, ative o agente do Debugger manualmente seguindo as etapas a seguir:

  1. Verifique se o arquivo app.yaml contém estas linhas:

    runtime: python37
    or
    runtime: python38
    
  2. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django (apenas versão 1.*).

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

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

  4. Para que a página Depuração no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao app implantado, acesse Como selecionar o código-fonte automaticamente.

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

Ambiente flexível do App Engine

É possível usar o Debugger com o ambiente de execução Python do App Engine ou um ambiente de execução personalizado.

  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 3
  2. Verifique se o arquivo app.yaml contém estas linhas:

    runtime: python
    env: flex
    

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

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

  4. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django (apenas versão 1.*).

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    
  5. Para que a página Depuração no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.

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

Google Kubernetes Engine

GCLOUD

Para ativar o Debugger usando a gcloud, conclua as etapas abaixo:

  1. Crie seu cluster com um destes escopos de acesso:

    • https://www.googleapis.com/auth/cloud-platform concede ao cluster acesso a todas as APIs do Google Cloud.

    • https://www.googleapis.com/auth/cloud_debugger concede ao cluster acesso apenas à API Stackdriver Debugger. Use esse escopo de acesso para reforçar a segurança do seu cluster.

    gcloud container clusters create example-cluster-name \
           --scopes=https://www.googleapis.com/auth/cloud_debugger
    
  2. Adicione o pacote do Debugger ao seu app:

    Se você usar um arquivo requirements.txt, adicione esta linha:

      google-python-cloud-debugger
    

    Se você usar um Dockerfile, adicione esta linha:

      RUN pip install google-python-cloud-debugger
    
  3. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django:

    Para depurar com a configuração de canary ativada:

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

    Para depurar com o canário NÃO ativado, defina o parâmetro breakpoint_enable_canary como False:

      breakpoint_enable_canary=False
    

Na página Depuração, selecione o local do código-fonte. Para que a página Depuração no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.

O Debugger está pronto para ser usado.

CONSOLE

Para ativar o Debugger usando o Console do Google Cloud, siga estas etapas:

  1. Na seção Pool de nós, selecione Segurança e Definir acesso para cada API.

  2. Ative o Debugger.

    A API Debugger está ativada para o cluster.

  3. Opcional: selecione Permitir acesso total a todas as APIs do Cloud.

  4. Adicione o pacote do Debugger ao seu app:

    Se você usar um arquivo requirements.txt, adicione esta linha:

    google-python-cloud-debugger
    

    Se você usar um Dockerfile, adicione esta linha:

    RUN pip install google-python-cloud-debugger
    
  5. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django:

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    

Na página Depuração, selecione o local do código-fonte. Para que a página Depuração no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.

O Debugger está pronto para ser usado.

Compute Engine

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

    • uma imagem Debian Linux de 64-bit;
    • Python 3
  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 destes 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 Debugger em Python é com pip:

    pip install google-python-cloud-debugger
    
  4. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django.

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    

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

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    

    Substitua os marcadores no comando da seguinte forma:

    • [MODULE] é o nome do seu app.
      Isso, junto com a versão, é usado para identificar o destino de depuração na página Depuração do Console do Google Cloud.
      Por exemplo, MyApp, Backend ou Frontend;
    • [VERSION] é a versão do app, por exemplo, o ID da compilação.
      A página Depuração do Console do Google Cloud exibe a versão em execução como [MODULE] - [VERSION].
      Exemplo de valores: v1.0, build_147 ou v20170714;

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

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

Cloud Run e Cloud Run for Anthos

  1. Pacote Python.

    Se você usar um arquivo requirements.txt, adicione esta linha:

    google-python-cloud-debugger
    

    Caso contrário, adicione esta linha ao seu Dockerfile:

    RUN pip install google-python-cloud-debugger
    
  2. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django:

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    

Na página Depuração, selecione o local do código-fonte. Para que a página Depuração no Console do Google Cloud exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.

O Debugger está pronto para ser usado.

Ambiente local e outros

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

    • uma imagem Debian Linux de 64-bit;
    • Python 3
  2. Faça o download do agente do Debugger.

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

    pip install google-python-cloud-debugger
    
  3. Faça o download das credenciais da conta de serviço.

    Para usar o agente do Cloud Debugger para Python em máquinas não hospedadas pelo Google Cloud, o agente precisa usar credenciais de conta de serviço do Google Cloud para autenticar com o Cloud Debugger Service.

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

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

  4. Adicione as linhas a seguir assim que possível em seu código de inicialização, como em sua função principal, ou em manage.py ao usar o framework da Web Django:

    Para depurar com a configuração de canary ativada:

    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
    

    Para depurar com o canário NÃO ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    

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

    Para depurar com a configuração de canary ativada:

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

    Para depuração com canário não ativado, defina o parâmetro breakpoint_enable_canary como False:

    breakpoint_enable_canary=False
    

    Substitua os marcadores no comando da seguinte forma:

    • [MODULE] é o nome do seu app.
      Isso, junto com a versão, é usado para identificar o destino de depuração na página Depuração do Console do Google Cloud.
      Por exemplo, MyApp, Backend ou Frontend;
    • [VERSION] é a versão do app, por exemplo, o ID da compilação.
      A página Depuração do Console do Google Cloud exibe a versão em execução como [MODULE] - [VERSION].
      Exemplo de valores: v1.0, build_147 ou v20170714;
    • É possível usar a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS em vez de especificar service_account_json_file.

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

A página Debug no Console do Google Cloud pode exibir arquivos de origem locais, sem upload, para desenvolvimento local. Consulte Como selecionar o código-fonte manualmente.