Como criar perfis de aplicativos Node.js

Nesta página, descrevemos 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 Google Cloud CLI ou o console Google Cloud :

CLI da 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.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    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 o aplicativo em recursos do Google Cloud e usando a conta de serviço padrão sem modificar as concessões de função para ela, pule esta seção.

Se você fizer alguma das ações a seguir, conceda à 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 concessões de papéis dela.
  2. Você está usando uma conta de serviço criada pelo usuário.
  3. Se você estiver 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 consoleGoogle 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 esse módulo integrado estão disponíveis para Linux e Alpine Linux para Node 14 e 16. Não são necessárias dependências extras. O @google-cloud/profiler usa node-pre-gyp para determinar qual binário pré-criado será instalado.

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 do node-gyp.

Instalação

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

    npm install @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 @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 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, significa que o Dockerfile não tem algumas dependências de build:

ERR! stack Error: not found: make

Para resolver esse problema, adicione a seguinte instrução à fase 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), talvez veja 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