Como configurar o Cloud Debugger para Node.js

Visão geral

Nesta página, descrevemos como configurar o ambiente e o aplicativo Node.js 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 Node.js 6 e versões mais recentes 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 no Google Cloud 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

O agente do Debugger para Node.js pode usar snapshots e logpoints de canário sempre que você definir um snapshot ou logpoint.

O agente do Debugger cria snapshots e logpoints do canary para proteger grandes jobs de qualquer bug em potencial no agente do Debugger, o que pode remover todo o job quando um snapshot ou logpoint for aplicado.

Para atenuar isso, o Debugger cria snapshot e logpoints do canary em um subconjunto de instâncias em execução sempre que elas são definidas. Depois que o Debugger verifica se o snapshot ou o logpoint não afeta negativamente as instâncias em execução, o Debugger aplica o snapshot ou logpoint 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.

App Engine

  1. Use o npm (em inglês) para instalar o pacote:

    npm install --save @google-cloud/debug-agent
    
  2. Ative o agente na parte superior do script principal ou do ponto de entrada do seu app. No entanto, se você também estiver usando @google/cloud-trace, ative o agente após ele:

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

    Para depurar com o canário não ativado, defina enableCanary como false:

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: false}});
    

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

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

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 a linha a seguir ao Dockerfile para inserir o agente do Debugger:

    RUN  npm install --save @google-cloud/debug-agent
    
  3. Ative o agente na parte superior do script principal ou do ponto de entrada do seu app. No entanto, se você também estiver usando @google/cloud-trace, ative o agente após ele:

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

    Para depurar com o canário não ativado, defina enableCanary como false:

    enableCanary: false
    

    Onde:

    • SERVICE é um nome para o app, como MyApp, Backend ou Frontend;
    • VERSION é uma versão, como v1.0, build_147 ou v20170714.

    Recomendamos configurar isso a partir de variáveis de ambiente para que você não precise alterar o código-fonte a cada implantação.

O depurador agora estará pronto para uso quando você implantar o app em contêiner.

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

CONSOLE

Para ativar o Debugger usando o Console, conclua as etapas a seguir:

  1. Depois de selecionar o tipo de cluster, clique em Mais opções no painel Pool de nós:

    Opções de pools de nós

  2. Selecione uma das opções abaixo no painel Segurança:

    • Permitir acesso completo a todas as APIs do Cloud.

    • Permitir o acesso de cada API e, em seguida, selecionar Ativado para o Cloud Debugger.

  3. Adicione a linha a seguir ao Dockerfile para inserir o agente do Debugger:

        RUN  npm install --save @google-cloud/debug-agent
    
  4. Ative o agente na parte superior do script principal ou do ponto de entrada do seu app. No entanto, se você também estiver usando @google/cloud-trace, ative o agente após ele:

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION'
        enableCanary: true,
      }
    });
    

    Para depurar com o canário não ativado, defina enableCanary como false:

    enableCanary: false
    

    Onde:

    • SERVICE é um nome para o app, como MyApp, Backend ou Frontend;
    • VERSION é uma versão, como v1.0, build_147 ou v20170714.

    Recomendamos configurar isso a partir de variáveis de ambiente para que você não precise alterar o código-fonte a cada implantação.

Compute Engine

  1. Verifique se as instâncias 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 escopos de acesso a seguir:

    • https://www.googleapis.com/auth/cloud-platform
    • https://www.googleapis.com/auth/cloud_debugger
  2. Use o npm (em inglês) para instalar o pacote:

    npm install --save @google-cloud/debug-agent
    
  3. Ative o agente na parte superior do script principal ou do ponto de entrada do seu app. No entanto, se você também estiver usando @google/cloud-trace, ative o agente após ele:

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

    require('@google-cloud/debug-agent').start({
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

    Para depurar com o canário não ativado, defina enableCanary como false:

    enableCanary: false
    

    Onde:

    • SERVICE é um nome para o app, como MyApp, Backend ou Frontend;
    • VERSION é uma versão, como v1.0, build_147 ou v20170714.

    Recomendamos configurar isso a partir de variáveis de ambiente para que você não precise alterar o código-fonte a cada implantação.

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

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

Cloud Run e Cloud Run para Anthos no Google Cloud

  1. Use o npm (em inglês) para instalar o pacote:

    npm install --save @google-cloud/debug-agent
    
  2. Ative o agente na parte superior do script principal ou do ponto de entrada do seu app. Porém, se você também estiver usando @google/cloud-trace, ative o agente após ele:

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

    require('@google-cloud/debug-agent').start({serviceContext: {enableCanary: true}});
    

    Para depurar com o canário não ativado, defina enableCanary como false:

    enableCanary: false
    

    O depurador agora estará pronto para uso quando você implantar o aplicativo.

Ambiente local e outros

  1. Use o npm (em inglês) para instalar o pacote:

    npm install --save @google-cloud/debug-agent
    
  2. Faça o download das credenciais da conta de serviço.

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

    Acesse a página Contas de serviço do Console do 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.

  3. Configure e ative o agente com as credenciais salvas.

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

    require('@google-cloud/debug-agent').start({
      projectId: 'your-project-id',
      keyFilename: '/path/to/key.json',
      serviceContext: {
        service: 'SERVICE',
        version: 'VERSION',
        enableCanary: true,
      }
    });
    

    Para depurar com o canário não ativado, defina enableCanary como false:

    enableCanary: false
    

    Onde:

    • SERVICE é um nome para o app, como MyApp, Backend ou Frontend;
    • VERSION é uma versão, como v1.0, build_147 ou v20170714.

    Recomendamos configurar isso a partir de variáveis de ambiente para que você não precise alterar o código-fonte a cada implantação.

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

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