Como configurar o Cloud Debugger para Node.js

Visão geral

Observação: o Cloud Debugger é compatível com o Node.js versão 9 e mais recentes. Recomendamos usar a versão de suporte a longo prazo.

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	VMs e contêineres em execução em outra plataforma	Cloud Functions

Beta

Essa biblioteca é coberta pelos Termos de ofertas pré-GA dos Termos de Serviço do Google Cloud. As bibliotecas pré-GA podem ter suporte limitado, e as mudanças nessas bibliotecas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

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.

   Observação: por motivos de desempenho, o agente do Cloud Debugger para Node.js não suporta a adição de snapshots ou logpoints a arquivos no diretório node_modules.

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

Observação: o uso do Cloud Debugger é gratuito. No entanto, você precisa de um projeto do Google Cloud com o faturamento ativado antes de usar o 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.

Observação:o canário está disponível para o agente do Node.js Debugger versão 5.1.0 e mais recente.

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 npm 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 aplicativo.

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.

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
   

   Observação: não é possível alterar os escopos de acesso de um cluster após a criação.

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
   

   Em que:

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

   Recomendamos fazer essa configuração a partir de variáveis de ambiente. Assim, não será necessário alterar o código-fonte em 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 Google Cloud exiba automaticamente o código-fonte correspondente ao app implantado, consulte Como selecionar o código-fonte automaticamente.

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.

   

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

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

       RUN  npm install --save @google-cloud/debug-agent
   

5. 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
   

   Em que:

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

   Recomendamos fazer essa configuração a partir de variáveis de ambiente. Assim, não será necessário alterar o código-fonte em 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 seguintes escopos de acesso:

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

2. Use npm 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
   

   Em que:

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

   Recomendamos fazer essa configuração a partir de variáveis de ambiente. Assim, não será necessário alterar o código-fonte em cada implantação.

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

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. Use npm 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 npm 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.

   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 existente. 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
   

   Em que:

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

   Recomendamos fazer essa configuração a partir de variáveis de ambiente. Assim, não será necessário alterar o código-fonte em cada implantação.

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

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.

Observação: encontre o código e a documentação do agente do Debugger no GitHub (em inglês).