Como criar perfis de aplicativos Node.js

Esta página explica como modificar seu aplicativo Node.js para capturar dados de criação de perfil e enviá-los para seu projeto do Google Cloud. Para informações gerais sobre criação de perfil, consulte Conceitos de criação de perfil.

Tipos de perfil para Node.js:

  • Heap
  • Tempo decorrido

Versões compatíveis com a linguagem Node.js:

Versões compatíveis com o agente de criação de perfil:

  • A versão mais recente do agente é compatível. Em geral, lançamentos com mais de um ano não são compatíveis. Recomendamos que você use a versão do agente lançada mais recentemente.

Sistemas operacionais compatíveis:

  • Linux. A criação de perfil de aplicativos Node.js é compatível com kernels do Linux cuja biblioteca padrão C é implementada com glibc ou musl. Saiba mais sobre informações de configuração específicas aos kernels do Linux Alpine em Como executar no Linux Alpine.

Ambientes compatíveis:

Como ativar a API Profiler

Antes de usar o agente de criação de perfil, garanta que a API Profiler subjacente esteja ativada. É possível verificar o status da API e ativá-la, se necessário, usando a CLI do Google Cloud ou o Console do Google Cloud:

CLI gcloud

  1. Se você ainda não instalou a CLI do Google Cloud na sua estação de trabalho, consulte a documentação da CLI do Google Cloud.

  2. Execute este comando:

    gcloud services enable cloudprofiler.googleapis.com

Para ver mais informações, consulte gcloud services.

Console do Google Cloud

  1. Enable the required API.

    Enable the API

  2. Se a mensagem API ativada for exibida, quer dizer que a API já está ativada. Caso contrário, clique no botão Ativar.

Conceder papel do IAM à conta de serviço

Se você estiver implantando seu aplicativo em recursos do Google Cloud e se você estiver usando a conta de serviço padrão e não tiver modificado as permissões de função para essa conta de serviço, pule esta seção.

Se você fizer qualquer uma das ações a seguir, precisará conceder à conta de serviço o papel do IAM de Agente do Cloud Profiler (roles/cloudprofiler.agent):

  1. Você está usando a conta de serviço padrão, mas modificou as permissões de função dela.
  2. Você está usando uma conta de serviço criada pelo usuário.
  3. Você está usando a Identidade da carga de trabalho, conceda o papel de agente do Cloud Profiler à conta de serviço do Kubernetes.

É possível conceder um papel do IAM a uma conta de serviço usando o console do Google Cloud ou a Google Cloud CLI. Por exemplo, é possível usar o comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
    --member serviceAccount:MY_SVC_ACCT_ID@GCP_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudprofiler.agent

Antes de usar o comando anterior, substitua o seguinte:

  • GCP_PROJECT_ID: o ID do projeto.
  • MY_SVC_ACCT_ID: o nome da conta de serviço

Para mais informações, consulte Gerenciar o acesso a projetos, pastas e organizações.

Como usar o Cloud Profiler

Em todos os ambientes compatíveis, use o Profiler instalando o pacote @google-cloud/profiler, adicionando uma declaração require ao aplicativo e implantando-o da maneira habitual.

Antes de instalar @google-cloud/profiler

O pacote @google-cloud/profiler depende de um módulo integrado. Os binários pré-criados para este módulo integrado estão disponíveis para Linux e Alpine Linux para Node 14 e 16. Nenhuma dependência extra é necessária. O @google-cloud/profiler usa node-pre-gyp para determinar qual binário pré-criado instalar.

Ao usar @google-cloud/profiler em outros ambientes que não têm binários pré-criados, o módulo node-gyp é usado para criar binários. Para informações sobre as dependências necessárias para criar binários com node-gyp, consulte a documentação de instalação de node-gyp.

Instalação

Para instalar a versão mais recente do Cloud Profiler, faça o seguinte:

    npm install --save @google-cloud/profiler

Se você também estiver usando o agente do Trace, ao modificar o aplicativo, importe o pacote do Profiler após o pacote do agente do Trace (@google-cloud/trace-agent).

Compute Engine

No Compute Engine:

  1. Instale a versão mais recente do Cloud Profiler:

    npm install --save @google-cloud/profiler

  2. Modifique o código require do aplicativo para criar um objeto serviceContext que atribua a service o nome do serviço para o qual você está criando um perfil. Opcionalmente, você pode atribuir a version a versão do serviço para o qual você está criando um perfil. Veja Argumentos de versão e nome de serviço para saber mais sobre estas opções de configuração:

    require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});

GKE;

Para o GKE:

  1. Modifique o Dockerfile para instalar o pacote do Profiler:

    FROM node:10
...
RUN npm install @google-cloud/profiler

  2. Modifique o código require do aplicativo para criar um objeto serviceContext que atribua a service o nome do serviço para o qual você está criando um perfil. Opcionalmente, você pode atribuir a version a versão do serviço para o qual você está criando um perfil. Veja Argumentos de versão e nome de serviço para saber mais sobre estas opções de configuração:

    require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});

App Engine

Para o ambiente flexível e o ambiente padrão do App Engine, o código require se parece com o seguinte:

require('@google-cloud/profiler').start();

No App Engine, os parâmetros service e version são derivados do ambiente. Portanto, não é necessário especificá-los. Assim, você não precisa criar um objeto serviceContext.

Análise de dados

Depois que o Profiler coletar dados, será possível visualizá-los e analisá-los usando a interface dele.

No console do Google Cloud, acesse a página Profiler:

Acessar o Profiler

Também é possível encontrar essa página usando a barra de pesquisa.

Argumentos de versão e nome de serviço

Ao carregar o agente do Profiler, você especifica um argumento de nome de serviço e um opcional de versão para configurá-lo.

Com o nome de serviço, o Profiler pode coletar dados de criação de perfil de todas as réplicas desse serviço. O criador de perfil garante uma taxa de coleta de um perfil por minuto, em média. Isso é para todos os nomes de serviço em cada combinação de zona e versão.

Por exemplo, se você tiver um serviço com duas versões executadas em réplicas em três zonas, o criador de perfil produzirá uma média de seis perfis por minuto para esse serviço.

Se você usar nomes de serviço diferentes nas réplicas, o serviço terá perfis criados com mais frequência do que o necessário, com uma sobrecarga correspondente maior.

Ao selecionar um nome de serviço:

  • escolha um que represente claramente o serviço na arquitetura do aplicativo. Essa seleção não é tão importante se você executa apenas um serviço ou aplicativo. Ela é mais importante se o aplicativo é executado como um conjunto de microsserviços, por exemplo;

  • não use nenhum valor específico do processo, como o código, na string do nome de serviço;

  • a string do nome de serviço precisa corresponder a esta expressão regular:

    ^[a-z0-9]([-a-z0-9_.]{0,253}[a-z0-9])?$

Uma boa diretriz é usar uma string estática como imageproc-service como o nome do serviço.

A versão de serviço é opcional. Se você especificá-la, o Profiler poderá agregar informações de criação de perfil de várias instâncias e exibi-las corretamente. É possível usá-la para marcar diferentes versões dos serviços conforme eles são implantados. Com a IU do Profiler, você filtra os dados por versão de serviço. Assim, é possível comparar o desempenho de versões mais antigas e mais recentes do código.

O valor do argumento da versão do serviço é uma string de formato livre. No entanto, os valores desse argumento geralmente se parecem com números de versão. Por exemplo, 1.0.0 ou 2.1.2.

Geração de registros do agente

O agente de criação de perfil mostra informações de registro. Para ativar a geração de registros, defina a opção logLevel ao iniciar o agente. Os valores logLevel compatíveis são:

  • 0: desativa toda a geração de registros do agente;
  • 1: ativa a geração de registros de erros;
  • 2: ativa a geração de registros de avisos (padrão);
  • 3: ativa a geração de registros de informações;
  • 4: ativa a geração de registros de depuração.

Defina o valor logLevel no mesmo objeto que fornece o contexto do serviço:

require('@google-cloud/profiler').start({
    serviceContext: { ... }
    logLevel:       3
});

Como executar com o Alpine Linux

O agente de criação de perfil do Node.js para Alpine Linux é compatível apenas com as configurações do Google Kubernetes Engine.

Erro de build

Se você executar npm install e o build falhar com o seguinte erro, seu Dockerfile não terá algumas dependências de build:

ERR! stack Error: not found: make

Para resolver esse problema, adicione a seguinte instrução ao estágio de build do Dockerfile:

RUN apk add python3 g++ make

Erro de autenticação

Se você usar imagens do Docker executadas com o Linux Alpine (como golang:alpine ou apenas alpine), você poderá encontrar o seguinte erro de autenticação:

connection error: desc = "transport: authentication handshake failed: x509: failed to load system roots and no roots provided"

Para ver o erro, você precisa ativar a geração de registros do agente.

O erro indica que as imagens do Docker com o Alpine Linux não têm os certificados SSL raiz instalados por padrão. Esses certificados são necessários para que o agente de criação de perfil se comunique com a API Profiler. Para resolver esse erro, adicione o seguinte comando apk ao seu Dockerfile:

FROM alpine
...
RUN apk add --no-cache ca-certificates

Depois, será necessário recriar e reimplantar o aplicativo.

Problemas conhecidos

O agente de criação de perfil para Node.js interfere na saída normal do programa. Pode levar até uma hora para que o programa seja encerrado depois que todas as tarefas forem concluídas. Quando você emite um SIGINT, por exemplo, usando Ctrl-C, isso faz com que o processo seja encerrado normalmente.

A seguir