Criação de perfis de aplicações Node.js

Esta página descreve como modificar a sua aplicação Node.js para capturar dados de criação de perfis e enviar esses dados para o seu projeto do Google Cloud. Google CloudPara ver informações gerais acerca da criação de perfis, consulte o artigo Conceitos de criação de perfis.

Tipos de perfis para Node.js:

  • Memória
  • Tempo entre o início e o fim da tarefa

Versões de linguagem Node.js compatíveis:

Versões do agente de criação de perfis suportadas:

  • A versão mais recente do agente é suportada. Geralmente, as versões com mais de um ano não são suportadas. Recomendamos que use a versão do agente lançada mais recentemente.

Sistemas operativos compatíveis:

  • Linux. A criação de perfis de aplicações Node.js é suportada para kernels Linux cuja biblioteca C padrão seja implementada com glibc ou com musl. Para ver informações de configuração específicas dos kernels do Linux Alpine, consulte o artigo Execução no Linux Alpine.

Ambientes suportados:

Ativar a API Profiler

Antes de usar o agente de criação de perfis, certifique-se de que a API Profiler subjacente está ativada. Pode verificar o estado da API e ativá-la, se necessário, através da CLI do Google Cloud ou da Google Cloud consola:

CLI gcloud

  1. Se 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 o seguinte comando:

    gcloud services enable cloudprofiler.googleapis.com

Para mais informações, consulte gcloud services.

Google Cloud consola

  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 for apresentada a mensagem API ativada, significa que a API já está ativada. Caso contrário, clique no botão Ativar.

Conceda a função do IAM à conta de serviço

Se estiver a implementar a sua aplicação em Google Cloud recursos e se estiver a usar a conta de serviço predefinida e não tiver modificado as concessões de funções para essa conta de serviço, pode ignorar esta secção.

Se realizar qualquer uma das seguintes ações, tem de conceder à conta de serviço a função do IAM de agente do Cloud Profiler (roles/cloudprofiler.agent):

  1. Está a usar a conta de serviço predefinida, mas modificou as concessões de funções.
  2. Está a usar uma conta de serviço criada pelo utilizador.
  3. Está a usar a identidade da carga de trabalho. Conceda a função de agente do Cloud Profiler à conta de serviço do Kubernetes.

Pode conceder uma função de IAM a uma conta de serviço através da Google Cloud consola ou da CLI do Google Cloud. Por exemplo, pode 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 seu projeto.
  • MY_SVC_ACCT_ID: o nome da sua conta de serviço.

Para ver informações detalhadas, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Usar o Cloud Profiler

Em todos os ambientes suportados, usa o Profiler instalando o pacote @google-cloud/profiler, adicionando uma declaração require à sua aplicação e, em seguida, implementando a aplicação da forma habitual.

Antes de instalar o @google-cloud/profiler

O pacote @google-cloud/profiler depende de um módulo incorporado. Estão disponíveis binários pré-criados para este módulo integrado para Linux e Alpine Linux para o Node 14 e 16. Não são necessárias dependências adicionais. O @google-cloud/profiler usa o node-pre-gyp para determinar que ficheiro binário pré-criado instalar.

Quando usar o @google-cloud/profiler noutros ambientes que não tenham binários pré-criados, o módulo node-gyp é usado para criar binários. Para obter informações sobre as dependências necessárias para criar ficheiros binários com o 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 também estiver a usar o agente de rastreio, quando modificar a sua aplicação, importe o pacote do Profiler após o pacote do agente de rastreio (@google-cloud/trace-agent).

Compute Engine

Para o Compute Engine, faça o seguinte:

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

    npm install @google-cloud/profiler

  2. Modifique o código require da aplicação para criar um objeto serviceContext que atribua a service o nome do serviço que está a ser analisado. Opcionalmente, pode atribuir à versão do serviço que está a ser analisado.version Consulte Argumentos de nome e versão do serviço para mais informações sobre estas opções de configuração:

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

GKE

Para o GKE, faça o seguinte:

  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 da aplicação para criar um objeto serviceContext que atribua a service o nome do serviço que está a ser analisado. Opcionalmente, pode atribuir à versão do serviço que está a ser analisado.version Consulte Argumentos de nome e versão do serviço para mais informações 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 do App Engine e o ambiente padrão do App Engine, o código require é semelhante ao seguinte:

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

No App Engine, os parâmetros service e version são derivados do ambiente, pelo que não tem de os especificar. Por isso, não precisa de criar um objeto serviceContext.

Analisar dados

Depois de o Perfilador recolher dados, pode ver e analisar estes dados através da interface do Perfilador.

Na Google Cloud consola, aceda à página Profiler:

Aceda ao Profiler

Também pode encontrar esta página através da barra de pesquisa.

Argumentos de nome e versão do serviço

Quando carrega o agente do Profiler, especifica um argumento service-name e um argumento service-version opcional para o configurar.

O nome do serviço permite que o Profiler recolha dados de criação de perfis para todas as réplicas desse serviço. O serviço de criação de perfis garante uma taxa de recolha de um perfil por minuto, em média, para cada nome de serviço em todas as combinações de versões e zonas de serviço.

Por exemplo, se tiver um serviço com duas versões em execução em réplicas em três zonas, o criador de perfis cria uma média de 6 perfis por minuto para esse serviço.

Se usar nomes de serviços diferentes para as suas réplicas, o serviço é perfilado com mais frequência do que o necessário, com uma sobrecarga correspondentemente mais elevada.

Ao selecionar um nome do serviço:

  • Escolha um nome que represente claramente o serviço na arquitetura da sua aplicação. A escolha do nome do serviço é menos importante se executar apenas um único serviço ou aplicação. É mais importante se a sua aplicação for executada como um conjunto de microsserviços, por exemplo.

  • Certifique-se de que não usa valores específicos do processo, como um ID do processo, na string service-name.

  • A string service-name tem de 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 do serviço é opcional. Se especificar a versão do serviço, o Profiler pode agregar informações de criação de perfis de várias instâncias e apresentá-las corretamente. Pode ser usado para marcar diferentes versões dos seus serviços à medida que são implementadas. A IU do Profiler permite-lhe filtrar os dados por versão do serviço. Desta forma, pode comparar o desempenho de versões mais antigas e mais recentes do código.

O valor do argumento service-version é uma string de forma livre, mas os valores deste argumento têm normalmente o aspeto de números de versão, por exemplo, 1.0.0 ou 2.1.2.

Registo do agente

O agente de criação de perfis pode comunicar informações de registo. Para ativar o registo, defina a opção logLevel ao iniciar o agente. Os valores logLevel suportados são:

  • 0: desativa todo o registo do agente.
  • 1: ativa o registo de erros.
  • 2: ativa o registo de avisos (predefinição).
  • 3: ativa o registo de informações.
  • 4: ativa o registo 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
});

Execução com o Linux Alpine

O agente de criação de perfis do Node.js para o Linux Alpine só é suportado para configurações do Google Kubernetes Engine.

Erro de compilação

Se executar npm install e a compilação falhar com o seguinte erro, significa que o seu Dockerfile tem algumas dependências de compilação em falta:

ERR! stack Error: not found: make

Para resolver este problema, adicione a seguinte declaração à fase de compilação do Dockerfile:

RUN apk add python3 g++ make

Erro de autenticação

Se usar imagens do Docker executadas com o Linux Alpine (como golang:alpine ou apenas alpine), pode ver o seguinte erro de autenticação:

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

Tenha em atenção que, para ver o erro, tem de ter o registo do agente ativado.

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

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

Em seguida, tem de recriar e voltar a implementar a aplicação.

Problemas conhecidos

O agente de criação de perfis para Node.js interfere com a saída normal do programa. Pode demorar até uma hora para que o programa termine depois de todas as tarefas no programa terem sido concluídas. Quando emite um SIGINT, por exemplo, através de Ctrl-C, o processo termina de forma adequada.

O que se segue?