clinic.js Suite

Q: Posso usar clinic com NestJS?

Sim. Aponte o clinic para seu main.js compilado ou node --import tsx src/main.ts. Desabilite Swagger e logging detalhado durante a captura.

Q: clinic funciona no Node 24?

Sim. Instale o clinic mais recente globalmente. Fixe o Node 24.18.0 para corresponder à produção.

Profile seus serviços Node.js com as ferramentas clinic.js da NearForm - Doctor para saúde holística, Flame para hotspots de CPU e Bubbleprof para atrasos de I/O assíncronos.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npm install -g clinic
clinic doctor -- node dist/server.js
# Em outro terminal, gere carga:
npx autocannon -c 50 -d 30 http://localhost:3000/health
# Pressione Ctrl+C no servidor - Doctor abre um relatório HTML

Quando usar isso:

Latência p95 aumentando sem picos óbvios de erro.
CPU alta, mas você não consegue nomear a função quente.
Cadeias assíncronas - muitas chamadas await sequenciais adicionando latência.
Antes de migrar frameworks ou reescrever caminhos quentes.

Exemplo de Trabalho

# 1. Doctor - saúde geral (atraso do loop, CPU, memória)
clinic doctor -- node --import tsx src/server.ts
 
# 2. Flame - gráfico de chama de CPU (execute sob carga, depois pare)
clinic flame -- node --import tsx src/server.ts
 
# 3. Bubbleprof - visualização de atraso assíncrono
clinic bubbleprof -- node --import tsx src/server.ts

// src/server.ts - aplicativo mínimo para perfilar
import Fastify from "fastify";
 
const app = Fastify({ logger: false });
 
app.get("/health", async () => ({ ok: true }));
 
app.get("/users/:id", async (req) => {
  // Simula I/O sequencial - Bubbleprof destacará isso
  const profile = await fakeDb("profiles", req.params.id);
  const orders = await fakeDb("orders", req.params.id);
  return { profile, orders };
});
 
async function fakeDb(table: string, id: string) {
  await new Promise((r) => setTimeout(r, 20));
  return { table, id };
}
 
await app.listen({ port: 3000, host: "0.0.0.0" });

O que isso demonstra:

Doctor executa o processo e coleta métricas até você pará-lo.
Flame requer carga durante a captura - servidores ociosos produzem gráficos vazios.
Bubbleprof expõe cadeias await sequenciais que Promise.all poderia paralelizar.
Entrada TypeScript via --import tsx evita uma etapa de build separada durante a investigação.

Mergulho Profundo

Como Funciona

clinic.js envolve seu processo Node e injeta coletores de baixa sobrecarga.
Doctor correlaciona atraso do event loop, handles ativos e uso de CPU em uma única linha do tempo.
Flame amostra a pilha de chamadas em intervalos e renderiza um gráfico de chama no estilo V8.
Bubbleprof rastreia operações assíncronas desde a iniciação até a conclusão do callback.

Seleção de Ferramentas

Ferramenta	Melhor para	Não para
Doctor	Primeira passagem - "o loop está bloqueado?"	Identificar nomes exatos de funções
Flame	Caminhos quentes vinculados à CPU, JSON síncrono, loops apertados	Latência apenas de rede (sem queima de CPU)
Bubbleprof	HTTP/DB downstream lentos, awaits seriais	Matemática de CPU pura sem I/O

Executando Sob Carga

# Terminal 1
clinic flame -- node dist/server.js
 
# Terminal 2 - sustentar concorrência
npx autocannon -c 100 -d 60 http://localhost:3000/users/abc

Duração do perfil: 30-120 segundos de carga sustentada.
Corresponda à concorrência de produção (-c) e aos tamanhos de payload.
Desabilite o log detalhado durante a captura - o I/O de log distorce os resultados.

Notas TypeScript

clinic doctor -- node --import tsx src/main.ts
# ou compile primeiro para símbolos mais próximos da produção:
npm run build && clinic flame -- node dist/main.js

Mapas de origem na saída compilada melhoram a legibilidade do Flame.
Perfilar builds de staging, não dev com transporte pino-pretty.

Armadilhas

Perfilamento sem carga - gráficos Flame vazios. Correção: execute autocannon ou k6 concorrentemente.
Janelas de captura curtas - perdem pausas periódicas de GC. Correção: 60+ segundos em RPS alvo.
Logging em debug durante a captura - I/O domina o gráfico. Correção: LOG_LEVEL=warn.
Perfilamento local em um laptop - contagem de CPU diferente da produção. Correção: corresponder aos limites de CPU do k8s em staging.
Usar Doctor apenas uma vez - não nomeia a função. Correção: acompanhe com Flame no mesmo cenário.
Ignorar Bubbleprof para APIs "rápidas" - chamadas de banco de dados seriais ocultas adicionam 100ms+ cada. Correção: paralelizar consultas independentes.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
clinic.js	Serviços HTTP Node, problemas de event loop	Runtimes não Node
0x / flamegraph	Amostras de CPU rápidas e pontuais	Necessita de visualização de cascata assíncrona
OpenTelemetry traces	Amostragem contínua em produção	Atribuição profunda de CPU em nível V8
`--inspect` + Chrome DevTools	Depuração interativa de uma solicitação	Carga sustentada sob concorrência

FAQs

clinic.js é seguro para produção?

Não. Execute em staging com dados anonimizados. A sobrecarga é baixa, mas não zero; pare o tráfego para a instância perfilada.

Doctor diz "event loop delay" - e agora?

Execute Flame sob a mesma carga. Procure por barras largas em código síncrono: JSON.parse, bcrypt, chamadas *Sync do fs.

Posso usar clinic com NestJS?

Sim. Aponte o clinic para seu main.js compilado ou node --import tsx src/main.ts. Desabilite Swagger e logging detalhado durante a captura.

Como isso se compara ao OpenTelemetry?

clinic.js é para investigações profundas e com tempo limitado. OTel é para traces e métricas contínuas em produção. Use ambos.

O gráfico Flame é plano - sem picos?

Ou a carga é muito baixa ou o gargalo está fora do Node (DB, rede). Verifique Bubbleprof e EXPLAIN do DB.

clinic funciona no Node 24?

Sim. Instale o clinic mais recente globalmente. Fixe o Node 24.18.0 para corresponder à produção.

Posso automatizar o clinic em CI?

Possível, mas pesado. Prefira limites do k6 para portões de regressão; reserve o clinic para mergulhos profundos manuais em falhas.

E vazamentos de memória?

Doctor mostra o heap aumentando ao longo do tempo. Combine com writeHeapSnapshot de Otimização de Memória e GC.

Relacionado

Fundamentos de Performance - meça antes de otimizar
Teste de Carga - gere tráfego realista para perfilamento
Otimização de Memória e GC - limites de heap e snapshots
Detectando Bloqueio do Event-Loop - métricas de atraso do loop

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npm install -g clinic
clinic doctor -- node dist/server.js
# Em outro terminal, gere carga:
npx autocannon -c 50 -d 30 http://localhost:3000/health
# Pressione Ctrl+C no servidor - Doctor abre um relatório HTML

Quando usar isso:

Latência p95 aumentando sem picos óbvios de erro.
CPU alta, mas você não consegue nomear a função quente.
Cadeias assíncronas - muitas chamadas await sequenciais adicionando latência.
Antes de migrar frameworks ou reescrever caminhos quentes.

Exemplo de Trabalho

# 1. Doctor - saúde geral (atraso do loop, CPU, memória)
clinic doctor -- node --import tsx src/server.ts
 
# 2. Flame - gráfico de chama de CPU (execute sob carga, depois pare)
clinic flame -- node --import tsx src/server.ts
 
# 3. Bubbleprof - visualização de atraso assíncrono
clinic bubbleprof -- node --import tsx src/server.ts

// src/server.ts - aplicativo mínimo para perfilar
import Fastify from "fastify";
 
const app = Fastify({ logger: false });
 
app.get("/health", async () => ({ ok: true }));
 
app.get("/users/:id", async (req) => {
  // Simula I/O sequencial - Bubbleprof destacará isso
  const profile = await fakeDb("profiles", req.params.id);
  const orders = await fakeDb("orders", req.params.id);
  return { profile, orders };
});
 
async function fakeDb(table: string, id: string) {
  await new Promise((r) => setTimeout(r, 20));
  return { table, id };
}
 
await app.listen({ port: 3000, host: "0.0.0.0" });

O que isso demonstra:

Doctor executa o processo e coleta métricas até você pará-lo.
Flame requer carga durante a captura - servidores ociosos produzem gráficos vazios.
Bubbleprof expõe cadeias await sequenciais que Promise.all poderia paralelizar.
Entrada TypeScript via --import tsx evita uma etapa de build separada durante a investigação.

Mergulho Profundo

Como Funciona

clinic.js envolve seu processo Node e injeta coletores de baixa sobrecarga.
Doctor correlaciona atraso do event loop, handles ativos e uso de CPU em uma única linha do tempo.
Flame amostra a pilha de chamadas em intervalos e renderiza um gráfico de chama no estilo V8.
Bubbleprof rastreia operações assíncronas desde a iniciação até a conclusão do callback.

Seleção de Ferramentas

Ferramenta	Melhor para	Não para
Doctor	Primeira passagem - "o loop está bloqueado?"	Identificar nomes exatos de funções
Flame	Caminhos quentes vinculados à CPU, JSON síncrono, loops apertados	Latência apenas de rede (sem queima de CPU)
Bubbleprof	HTTP/DB downstream lentos, awaits seriais	Matemática de CPU pura sem I/O

Executando Sob Carga

# Terminal 1
clinic flame -- node dist/server.js
 
# Terminal 2 - sustentar concorrência
npx autocannon -c 100 -d 60 http://localhost:3000/users/abc

Duração do perfil: 30-120 segundos de carga sustentada.
Corresponda à concorrência de produção (-c) e aos tamanhos de payload.
Desabilite o log detalhado durante a captura - o I/O de log distorce os resultados.

Notas TypeScript

clinic doctor -- node --import tsx src/main.ts
# ou compile primeiro para símbolos mais próximos da produção:
npm run build && clinic flame -- node dist/main.js

Mapas de origem na saída compilada melhoram a legibilidade do Flame.
Perfilar builds de staging, não dev com transporte pino-pretty.

Armadilhas

Perfilamento sem carga - gráficos Flame vazios. Correção: execute autocannon ou k6 concorrentemente.
Janelas de captura curtas - perdem pausas periódicas de GC. Correção: 60+ segundos em RPS alvo.
Logging em debug durante a captura - I/O domina o gráfico. Correção: LOG_LEVEL=warn.
Perfilamento local em um laptop - contagem de CPU diferente da produção. Correção: corresponder aos limites de CPU do k8s em staging.
Usar Doctor apenas uma vez - não nomeia a função. Correção: acompanhe com Flame no mesmo cenário.
Ignorar Bubbleprof para APIs "rápidas" - chamadas de banco de dados seriais ocultas adicionam 100ms+ cada. Correção: paralelizar consultas independentes.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
clinic.js	Serviços HTTP Node, problemas de event loop	Runtimes não Node
0x / flamegraph	Amostras de CPU rápidas e pontuais	Necessita de visualização de cascata assíncrona
OpenTelemetry traces	Amostragem contínua em produção	Atribuição profunda de CPU em nível V8
`--inspect` + Chrome DevTools	Depuração interativa de uma solicitação	Carga sustentada sob concorrência

FAQs

clinic.js é seguro para produção?

Não. Execute em staging com dados anonimizados. A sobrecarga é baixa, mas não zero; pare o tráfego para a instância perfilada.

Doctor diz "event loop delay" - e agora?

Execute Flame sob a mesma carga. Procure por barras largas em código síncrono: JSON.parse, bcrypt, chamadas *Sync do fs.

Posso usar clinic com NestJS?

Sim. Aponte o clinic para seu main.js compilado ou node --import tsx src/main.ts. Desabilite Swagger e logging detalhado durante a captura.

Como isso se compara ao OpenTelemetry?

clinic.js é para investigações profundas e com tempo limitado. OTel é para traces e métricas contínuas em produção. Use ambos.

O gráfico Flame é plano - sem picos?

Ou a carga é muito baixa ou o gargalo está fora do Node (DB, rede). Verifique Bubbleprof e EXPLAIN do DB.

clinic funciona no Node 24?

Sim. Instale o clinic mais recente globalmente. Fixe o Node 24.18.0 para corresponder à produção.

Posso automatizar o clinic em CI?

Possível, mas pesado. Prefira limites do k6 para portões de regressão; reserve o clinic para mergulhos profundos manuais em falhas.

E vazamentos de memória?

Doctor mostra o heap aumentando ao longo do tempo. Combine com writeHeapSnapshot de Otimização de Memória e GC.

Relacionado

Fundamentos de Performance - meça antes de otimizar
Teste de Carga - gere tráfego realista para perfilamento
Otimização de Memória e GC - limites de heap e snapshots
Detectando Bloqueio do Event-Loop - métricas de atraso do loop

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

clinic.js Suite

Buscar na documentação

clinic.js Suite