Suite clinic.js

Perfila servicios Node.js con las herramientas clinic.js de NearForm: Doctor para la salud holística, Flame para los puntos calientes de la CPU y Bubbleprof para los retrasos de E/S asíncronas.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

npm install -g clinic
clinic doctor -- node dist/server.js
# En otra terminal, genera carga:
npx autocannon -c 50 -d 30 http://localhost:3000/health
# Presiona Ctrl+C en el servidor - Doctor abre un informe HTML

Cuándo usarlo:

• La latencia p95 aumenta sin picos de error obvios.
• La CPU está alta pero no puedes nombrar la función "caliente".
• Cascadas asíncronas: muchas llamadas await secuenciales que añaden latencia.
• Antes de migrar frameworks o reescribir rutas "calientes".

Ejemplo de trabajo

# 1. Doctor - salud general (retraso del bucle, CPU, memoria)
clinic doctor -- node --import tsx src/server.ts
 
# 2. Flame - gráfico de llama de CPU (ejecutar bajo carga, luego detener)
clinic flame -- node --import tsx src/server.ts
 
# 3. Bubbleprof - visualización de retrasos asíncronos
clinic bubbleprof -- node --import tsx src/server.ts

// src/server.ts - aplicación mínima para perfilar
import Fastify from "fastify";
 
const app = Fastify({ logger: false });
 
app.get("/health", async () => ({ ok: true }));
 
app.get("/users/:id", async (req) => {
  // Simula E/S secuencial - Bubbleprof lo destacará
  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" });

Lo que esto demuestra:

• Doctor ejecuta el proceso y recopila métricas hasta que lo detienes.
• Flame requiere carga durante la captura; los servidores inactivos producen gráficos vacíos.
• Bubbleprof expone cadenas await secuenciales que Promise.all podría paralelizar.
• La entrada de TypeScript a través de --import tsx evita un paso de compilación separado durante la investigación.

Análisis profundo

Cómo funciona

• clinic.js envuelve tu proceso Node e inyecta recolectores de bajo impacto.
• Doctor correlaciona el retraso del bucle de eventos, los manejadores activos y el uso de la CPU en una sola línea de tiempo.
• Flame muestrea la pila de llamadas a intervalos y renderiza un gráfico de llama estilo V8.
• Bubbleprof rastrea las operaciones asíncronas desde el inicio hasta la finalización de la devolución de llamada.

Selección de herramientas

Ejecución bajo carga

# Terminal 1
clinic flame -- node dist/server.js
 
# Terminal 2 - mantener la concurrencia
npx autocannon -c 100 -d 60 http://localhost:3000/users/abc

• Duración del perfilado: 30-120 segundos de carga sostenida.
• Coincide con la concurrencia de producción (-c) y los tamaños de carga útil.
• Deshabilita el registro verboso durante la captura; la E/S de registro distorsiona los resultados.

Notas de TypeScript

clinic doctor -- node --import tsx src/main.ts
# o compila primero para símbolos más cercanos a producción:
npm run build && clinic flame -- node dist/main.js

• Los mapas de origen en la salida compilada mejoran la legibilidad de Flame.
• Perfila las compilaciones de staging, no las de desarrollo con el transporte pino-pretty.

Errores comunes

• Perfilado sin carga: gráficos de llama vacíos. Solución: ejecuta autocannon o k6 concurrentemente.
• Ventanas de captura cortas: se pierden las pausas periódicas del GC. Solución: 60+ segundos al RPS objetivo.
• Registro en modo depuración durante la captura: la E/S domina el gráfico. Solución: LOG_LEVEL=warn.
• Perfilado localmente en un portátil: diferente número de CPU que en producción. Solución: iguala los límites de CPU de k8s en staging.
• Usar Doctor solo una vez: no nombra la función. Solución: sigue con Flame en el mismo escenario.
• Ignorar Bubbleprof para APIs "rápidas": llamadas a DB seriales ocultas añaden más de 100ms cada una. Solución: paraleliza consultas independientes.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de rendimiento - mide antes de optimizar
• Pruebas de carga - genera tráfico realista para perfilar
• Ajuste de memoria y GC - límites de la pila y snapshots
• Detección de bloqueo del bucle de eventos - métricas de retraso del bucle

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.