Pyroscope no Node.js

Pyroscope no Node.js permite coletar perfis continuamente e analisar onde a aplicação consome CPU ou aloca memória ao longo do tempo. Diferente de um perfil manual capturado durante alguns segundos, continuous profiling mantém uma série temporal de amostras, facilitando comparar versões, ambientes, rotas e períodos antes ou depois de um incidente.

O SDK Node.js do Grafana Pyroscope envia perfis para um servidor próprio ou Grafana Cloud Profiles. A interface apresenta flamegraphs, comparação entre períodos e filtros por labels. Com configuração cuidadosa, a ferramenta ajuda a localizar regressões sem depender de reproduzir exatamente o problema em uma máquina local.

Neste guia, você aprenderá a executar Pyroscope, instalar o SDK, configurar perfis de wall time, CPU e heap, usar labels estáticas e dinâmicas, controlar overhead, proteger credenciais e integrar profiles com traces e logs.

O que é continuous profiling?

Continuous profiling coleta amostras de forma recorrente enquanto a aplicação opera. Cada amostra registra pilhas de execução ou alocação. O backend agrega as pilhas em intervalos e permite consultas históricas.

Benefícios:

• detectar regressão entre releases;
• analisar CPU em incidentes intermitentes;
• comparar serviços ou regiões;
• identificar funções dominantes;
• acompanhar mudanças no consumo;
• correlacionar profiles com traces.

Para profiles pontuais, veja Flamegraphs no Node.js.

SDK oficial para Node.js

A documentação de Pyroscope para Node.js apresenta o pacote @pyroscope/nodejs, opções de configuração, labels e autenticação.

Executando Pyroscope localmente

Uma forma simples é usar container:

docker run --rm \
  --name pyroscope \
  -p 4040:4040 \
  grafana/pyroscope:latest

Em ambientes controlados, fixe uma versão específica em vez de latest. A interface fica em http://localhost:4040.

Instalação do SDK

npm install @pyroscope/nodejs

O pacote inclui componentes nativos. Confirme suporte à plataforma, arquitetura e versão do Node.js usada no projeto.

Configuração básica

const Pyroscope = require('@pyroscope/nodejs');

Pyroscope.init({
  serverAddress: 'http://localhost:4040',
  appName: 'orders-api'
});

Pyroscope.start();

Inicialize o profiler no começo do processo, antes da carga principal.

Wall profiling e CPU

Para coletar tempo de CPU dentro do wall profiler:

Pyroscope.init({
  serverAddress: process.env.PYROSCOPE_SERVER_ADDRESS,
  appName: 'orders-api',
  wall: {
    collectCpuTime: true
  }
});

Wall time mostra o tempo decorrido, incluindo espera e execução. CPU time destaca tempo efetivamente consumido pelo processador. Use ambos de acordo com o tipo de investigação.

Configuração por variáveis

PYROSCOPE_APPLICATION_NAME=orders-api
PYROSCOPE_SERVER_ADDRESS=http://pyroscope:4040
PYROSCOPE_FLUSH_INTERVAL_MS=60000
PYROSCOPE_WALL_COLLECT_CPU_TIME=true

Não grave usuário, senha ou token em arquivos versionados. Consulte Gestão de Segredos no Node.js.

Autenticação

Pyroscope.init({
  serverAddress: process.env.PYROSCOPE_SERVER_ADDRESS,
  appName: 'orders-api',
  basicAuthUser: process.env.PYROSCOPE_BASIC_AUTH_USER,
  basicAuthPassword: process.env.PYROSCOPE_BASIC_AUTH_PASSWORD
});

Em Grafana Cloud, use credenciais específicas com escopo mínimo. Faça rotação e nunca registre o valor em logs.

Labels estáticas

Pyroscope.init({
  serverAddress: process.env.PYROSCOPE_SERVER_ADDRESS,
  appName: 'orders-api',
  tags: {
    environment: process.env.NODE_ENV,
    region: process.env.REGION,
    version: process.env.APP_VERSION
  }
});

Labels devem ter cardinalidade controlada. Ambiente, região, equipe e versão são úteis. Não use user ID, request ID ou order ID.

Labels dinâmicas

Pyroscope.wrapWithLabels(
  { operation: 'order.create' },
  () => createOrder(input)
);

Labels dinâmicas permitem separar caminhos de código. Use valores categóricos e estáveis, como tipo de operação ou fila.

Não use dados únicos

Labels de alta cardinalidade criam muitas séries e aumentam custo. Evite:

• IDs;
• URLs completas;
• mensagens de erro;
• nomes de arquivo enviados por usuário;
• timestamps;
• e-mails.

Heap profiling

O SDK possui opções como intervalo de amostragem e profundidade de stack:

Pyroscope.init({
  serverAddress: process.env.PYROSCOPE_SERVER_ADDRESS,
  appName: 'orders-api',
  heapSamplingIntervalBytes: 524288,
  heapStackDepth: 64
});

Um intervalo menor coleta mais detalhes e aumenta overhead. Ajuste apenas após medir.

Perfis e memory leaks

Profiles de alocação ajudam a encontrar caminhos que criam muitos objetos, mas não mostram necessariamente retenção. Para descobrir por que objetos permanecem vivos, combine com heap snapshots.

Consulte Memory Leaks no Node.js.

Flamegraph

No flamegraph:

• largura representa quantidade de amostras;
• altura representa profundidade;
• self indica custo da própria função;
• total inclui funções chamadas abaixo;
• comparação mostra aumento ou redução.

Não interprete cores como severidade sem verificar o modo da interface.

Comparando versões

Use a label version e compare dois intervalos:

• versão anterior;
• versão atual;
• mesma rota ou operação;
• carga semelhante.

Procure funções cujo consumo aumentou. Depois confirme com métricas de latência e throughput.

Antes e depois de uma otimização

Um fluxo confiável:

1. registre baseline;
2. identifique função dominante;
3. faça uma mudança pequena;
4. implante em canary;
5. compare profiles;
6. verifique p95 e p99;
7. observe memória e erros;
8. promova ou reverta.

Veja Canary Deploy no Node.js.

Profiles e traces

Grafana pode vincular traces a profiles em integrações suportadas. Um trace lento leva ao perfil do processo durante aquele período, ajudando a diferenciar:

• espera por rede;
• CPU em serialização;
• contenção;
• garbage collection;
• trabalho em biblioteca.

Para tracing, consulte Jaeger no Node.js.

Profiles e logs

Use labels comuns de baixa cardinalidade, como serviço, ambiente e versão. Logs podem apontar o horário e a versão do incidente; o profile mostra o consumo naquele intervalo.

Veja Grafana Loki no Node.js.

Overhead

Todo profiler consome recursos. Meça:

• CPU adicional;
• memória;
• tamanho dos dados;
• tempo de exportação;
• impacto em p99;
• spans ou profiles descartados.

Faça benchmark com e sem profiling usando Autocannon no Node.js.

Ajustando frequência

Opções relevantes incluem:

• flushIntervalMs;
• heapSamplingIntervalBytes;
• heapStackDepth;
• wall.samplingDurationMs;
• wall.samplingIntervalMicros;
• wall.collectCpuTime.

Valores mais agressivos aumentam detalhe e overhead. Comece com defaults.

Source maps

Aplicações TypeScript ou bundladas podem precisar mapear arquivos gerados para fontes originais. Configure o source mapper quando suportado e proteja o acesso ao código-fonte.

Worker Threads

Verifique como o SDK coleta profiles de workers na versão atual. Um profile apenas da thread principal pode não representar trabalho CPU-bound transferido. Teste explicitamente.

Consulte Worker Threads no Node.js.

Cluster e múltiplos processos

Cada processo precisa ser identificado de forma útil, mas não use PID como label de longo prazo sem necessidade. Agregue por serviço e versão, e use host ou instância somente quando investigar distribuição desigual.

Kubernetes

Em Kubernetes:

• injete endereço e credenciais por Secret;
• use labels de ambiente e versão;
• configure egress;
• monitore overhead por pod;
• garanta shutdown para flush;
• evite cardinalidade por pod em consultas padrão.

Grafana Alloy em pull mode

A documentação menciona modo pull com Grafana Alloy. Essa abordagem pode centralizar coleta e reduzir configuração no SDK em cenários suportados. Avalie compatibilidade e requisitos de exposição do endpoint.

Shutdown

Integre o encerramento do profiler à rotina da aplicação conforme a API da versão. Dê tempo limitado para flush e não bloqueie indefinidamente.

Veja Graceful Shutdown no Node.js.

Debug

DEBUG=pyroscope node server.js

Use logs de debug apenas temporariamente e verifique se não contêm credenciais.

Alertas

Continuous profiling é mais adequado para investigação do que alertas diretos. Alertas primários devem vir de métricas como CPU, latência, erros e memória. Quando disparam, o profile ajuda a explicar a causa.

Retenção

Defina prazo de retenção conforme custo e necessidade de comparação. Perfis antigos são úteis para investigar regressões sazonais, mas armazenar indefinidamente aumenta custo.

Segurança

• Use TLS.
• Proteja credenciais.
• Restrinja a UI.
• Evite labels com dados pessoais.
• Separe tenants.
• Audite acesso.
• Atualize SDK e servidor.

Erros comuns

• Labels com IDs: cardinalidade cresce.
• Ativar tudo sem medir: overhead inesperado.
• Confundir alocação com retenção: diagnóstico de leak fica incorreto.
• Usar latest em produção: atualização não controlada.
• Credencial no código: risco de vazamento.
• Comparar cargas diferentes: regressão pode ser falsa.
• Ignorar workers: profile fica incompleto.

Fluxo recomendado

1. Execute Pyroscope localmente.
2. Integre SDK com defaults.
3. Adicione serviço, ambiente e versão.
4. Meça overhead.
5. Valide flamegraphs sob carga.
6. Implante em poucas réplicas.
7. Compare métricas e profiles.
8. Expanda gradualmente.

Conclusão

Pyroscope no Node.js adiciona uma dimensão histórica ao profiling. Em vez de capturar CPU apenas durante um teste manual, a equipe pode comparar versões e períodos para localizar regressões e funções dominantes.

Comece com labels de baixa cardinalidade, defaults conservadores e medição de overhead. Combine profiles com métricas, traces e logs, e use snapshots quando a investigação for sobre retenção de memória. Com esse conjunto, continuous profiling ajuda a explicar por que uma aplicação ficou mais lenta ou mais cara ao longo do tempo.