Clinic.js no Node.js

O Clinic.js no Node.js é uma suíte de diagnóstico criada para investigar gargalos de CPU, event loop, operações assíncronas e memória. Ela reúne ferramentas visuais como Doctor, Bubbleprof, Flame e Heap Profiler, ajudando a transformar sintomas genéricos — API lenta, processo consumindo CPU ou memória crescendo — em hipóteses técnicas mais específicas.

Entretanto, existe um cuidado importante: o próprio projeto informa que não está sendo mantido ativamente e que sua forte dependência de detalhes internos do Node.js pode produzir incompatibilidades ou resultados imprecisos em versões recentes. Portanto, Clinic.js deve ser usado como ferramenta auxiliar, validado na versão real do runtime e combinado com recursos nativos, métricas e perfis independentes.

Neste guia, você aprenderá quando Clinic.js ainda pode ser útil, como instalar e executar seus módulos, gerar carga com Autocannon, interpretar relatórios, trabalhar em containers e decidir quando usar ferramentas nativas do Node.js.

O que é o Clinic.js?

Clinic.js é uma suíte open source de profiling originalmente desenvolvida pela NearForm. O projeto está disponível no repositório oficial do Clinic.js. Seus módulos principais são:

• Doctor: visão geral de CPU, memória, event loop e atividade;
• Bubbleprof: análise visual de operações assíncronas;
• Flame: flamegraph para identificar funções que consomem CPU;
• Heap Profiler: análise de alocações e crescimento de memória.

Para começar pela observação nativa, consulte também diagnósticos oficiais do Node.js e o artigo Diagnostic Report no Node.js.

Status de manutenção

Antes de instalar, registre a versão do Node.js e valide a compatibilidade. O README atual alerta que Clinic.js não recebe manutenção ativa e pode não funcionar corretamente. Isso não torna todos os relatórios inúteis, mas impede tratar a ferramenta como fonte única de verdade.

Use Clinic.js preferencialmente em ambiente de desenvolvimento ou staging. Compare conclusões com CPU profiler do V8, heap snapshots, métricas do processo e observabilidade da aplicação.

Instalação

npm install --global clinic

Também é possível manter a dependência no projeto:

npm install --save-dev clinic

Em equipes, a dependência local facilita fixar uma versão no lockfile:

npx clinic doctor -- node server.js

Prepare um cenário reproduzível

Um profiler precisa de carga. Inicie a aplicação com dados representativos e execute o mesmo fluxo várias vezes. Para gerar tráfego HTTP, use Autocannon no Node.js:

npx clinic doctor --autocannon [
  -c 20
  -d 30
  /api/products
] -- node server.js

O comando inicia o servidor, espera a porta abrir, executa Autocannon e processa os dados quando o processo termina.

Não finalize de forma abrupta

Clinic.js precisa encerrar a coleta e gerar os arquivos. Um encerramento forçado pode resultar em relatório incompleto. Use o fluxo indicado pela ferramenta e aguarde o processamento. Em aplicações com shutdown gracioso, confirme que o profiler não interfere na rotina.

Para preparar o encerramento, consulte Graceful Shutdown no Node.js.

Clinic Doctor

npx clinic doctor -- node server.js

Doctor combina várias métricas e tenta classificar o problema. O relatório pode destacar:

• CPU elevada;
• event loop bloqueado;
• operações assíncronas lentas;
• atividade de garbage collection;
• crescimento de memória;
• ausência de carga suficiente.

Use Doctor como triagem. Ele ajuda a escolher a próxima ferramenta, mas não substitui investigação do código e das dependências.

CPU elevada

Se o relatório aponta CPU, procure funções síncronas, serialização excessiva, regex custosa, loops grandes, compressão, criptografia e transformação de dados. Em Node.js, uma única função longa bloqueia o processamento de outras requisições na mesma thread JavaScript.

Compare o resultado com Performance Hooks no Node.js e com o profiler nativo:

node --cpu-prof server.js

O Node.js gera um perfil que pode ser aberto em ferramentas compatíveis com o formato do V8.

Clinic Flame

npx clinic flame -- node server.js

Depois de aplicar carga, o flamegraph mostra pilhas agregadas. Blocos mais largos representam mais tempo de CPU. Procure funções do seu código, bibliotecas e operações internas que dominam a largura.

Não conclua que toda função larga deve ser removida. Uma função pode aparecer porque é chamada muitas vezes e ainda assim ser necessária. Pergunte:

• a quantidade de chamadas é esperada?
• há trabalho repetido?
• o resultado pode ser cacheado?
• a operação pode usar algoritmo melhor?
• o processamento pode ir para Worker Threads?

Para paralelismo, veja Worker Threads no Node.js.

Clinic Bubbleprof

npx clinic bubbleprof -- node server.js

Bubbleprof representa grupos de atividade assíncrona como bolhas e conexões. Ele pode ajudar a visualizar tempo gasto em banco, rede, timers e callbacks. A ferramenta é útil quando a CPU não está alta, mas a resposta continua lenta.

Investigue bolhas associadas a:

• consultas sequenciais que poderiam ser paralelas;
• pool de conexões saturado;
• timeouts externos;
• retries excessivos;
• filas internas;
• promises aguardadas desnecessariamente em série.

Uma visualização não identifica automaticamente a causa. Correlacione com traces e logs estruturados. Consulte OpenTelemetry no Node.js.

Clinic Heap Profiler

npx clinic heapprofiler -- node server.js

O Heap Profiler acompanha alocações e pode indicar quais caminhos criam mais objetos. Ele é útil para investigar memória crescente, pressão de garbage collection e alocações temporárias em excesso.

Antes de chamar tudo de vazamento, diferencie:

• cache que cresce por projeto;
• buffers aguardando I/O;
• fila acumulada;
• dados mantidos por closures;
• listeners não removidos;
• objetos realmente inacessíveis que deveriam ser coletados.

Para uma análise complementar, gere snapshots nativos:

node --inspect server.js

Depois capture snapshots em momentos diferentes e compare os dominators e caminhos de retenção.

Carga representativa

O perfil deve reproduzir o problema. Se a rota lenta depende de banco, cache ou arquivos, inclua essas dependências. Um teste apenas em /health não explica gargalos de checkout, upload ou relatórios.

Para ambientes descartáveis com bancos reais, consulte Testcontainers no Node.js.

Evite medir o modo errado

Não execute um servidor de desenvolvimento com hot reload e conclua sobre produção. Use configuração equivalente:

• mesma versão do Node.js;
• mesmas flags relevantes;
• build de produção;
• variáveis equivalentes;
• mesma estratégia de cache;
• dependências externas representativas.

Profiling altera o processo

Instrumentação possui overhead. Compare números absolutos com cuidado. O objetivo principal é identificar padrões e funções dominantes, não declarar que a latência observada durante profiling será igual à produção.

Containers

Em container, monte um volume para preservar os relatórios:

docker run --rm \
  -e NO_INSIGHT=true \
  -v "$PWD/.clinic:/app/.clinic" \
  my-app \
  npx clinic flame -- node server.js

A variável NO_INSIGHT evita perguntas interativas de telemetria em alguns cenários. Garanta permissões de escrita e sinais de encerramento corretos.

Collect-only e visualização

Clinic.js pode coletar dados sem processar imediatamente:

npx clinic doctor --collect-only -- node server.js

Depois, gere a visualização:

npx clinic doctor --visualize-only caminho-do-relatorio

Esse fluxo é útil quando a coleta ocorre em ambiente separado da análise.

Plano de investigação

1. Reproduza o problema com métrica objetiva.
2. Execute Doctor para triagem.
3. Use Flame quando CPU for dominante.
4. Use Bubbleprof para atividade assíncrona.
5. Use Heap Profiler ou snapshots para memória.
6. Faça uma alteração pequena.
7. Repita exatamente o mesmo cenário.
8. Compare p50, p95, p99, throughput e recursos.

Combine com métricas

Durante a execução, acompanhe:

• uso de CPU;
• resident set size e heap;
• event loop lag;
• garbage collection;
• requisições por segundo;
• percentis de latência;
• erros e timeouts;
• conexões de banco;
• tamanho de filas.

Veja Métricas Prometheus no Node.js.

Quando não usar Clinic.js

Evite depender dele quando:

• a versão atual do Node.js apresenta incompatibilidade;
• o relatório não pode ser validado;
• o problema ocorre apenas em ambiente distribuído;
• você precisa de profiling contínuo de produção;
• há exigência de ferramenta mantida e suportada;
• o overhead altera demais o cenário.

Nesses casos, use profilers nativos, APM, eBPF, traces, heap snapshots e relatórios de diagnóstico.

Erros comuns

• Ignorar o status do projeto: resultados podem ser incompatíveis.
• Perfil sem carga: o código problemático não é executado.
• Encerrar à força: relatório pode não ser gerado.
• Otimizar pela largura sem contexto: remove trabalho necessário.
• Medir desenvolvimento: ambiente não representa produção.
• Usar uma única execução: variação pode enganar.
• Não validar com ferramentas nativas: conclusão fica frágil.

Conclusão

O Clinic.js no Node.js ainda pode ajudar a visualizar CPU, async e memória em projetos compatíveis, especialmente como ferramenta educacional e de triagem. Doctor, Flame, Bubbleprof e Heap Profiler oferecem perspectivas diferentes sobre o mesmo processo.

Porém, o estado de manutenção exige cautela. Valide a versão, reproduza o problema, compare com recursos nativos e nunca trate uma visualização isolada como diagnóstico definitivo. Quando usado dessa maneira, Clinic.js pode acelerar a investigação sem substituir a observabilidade e o profiling suportados pelo runtime.