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:

  • 10.4.1 ou superior na ramificação da versão 10.x.
  • 12.0.0 ou superior na ramificação da versão 12.x.
  • 14.0.0 ou superior na ramificação da versão 14.x.
  • Para conferir a política de versão do Node.js, consulte Programação de lançamentos.

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 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. No painel de navegação do console do Google Cloud, selecione APIs e serviços, clique em Ativar APIs e serviços e ative a API Cloud Profiler:

    Acessar as configurações da API Profiler

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

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 nativo. Os binários pré-criados para este módulo nativo estão disponíveis para todas as combinações de linguagens e plataformas compatíveis. Para determinar qual binário pré-criado será instalado, o @google-cloud/profiler usa node-pre-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 painel de navegação do console do Google Cloud, selecione Profiler:

Acesse o Profiler

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 erro abaixo, 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 criação 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