Conceptos básicos de operaciones en tiempo de ejecución

Q: ¿Deberíamos usar el modo clúster en contenedores?

No. Escala las réplicas de pod en lugar del módulo cluster de Node dentro de un contenedor.

Q: ¿Cuánto tiempo debe tardar el apagado?

Menos de terminationGracePeriodSeconds (a menudo 30-45s). Coincide con el retraso de la anulación del registro de LB + el cierre del pool de DB.

10 ejemplos para operar procesos Node.js 24 de larga duración en producción: 7 básicos y 3 intermedios.

Requisitos previos

mkdir prod-api && cd prod-api
npm init -y
npm pkg set type=module
npm install express@5 pg
npm install -D typescript@5.6 @types/node

Para patrones de apagado y despliegue, consulta Apagado elegante y Despliegues sin tiempo de inactividad.

Ejemplos básicos

1. Modelo de supervisión de procesos

Kubernetes / ECS / systemd / PM2
  -> inicia `node dist/main.js`
  -> reinicia al salir con código de error != 0
  -> envía SIGTERM en despliegue o reducción de escala
  -> lee los logs de stdout

Tu aplicación coopera con SIGTERM; la plataforma maneja los reinicios
No hagas doble supervisión (PM2 dentro de un pod de K8s)

2. Log de arranque estructurado

console.log(JSON.stringify({
  event: "boot",
  node: process.version,
  env: process.env.NODE_ENV,
  pid: process.pid,
}));

Confirma la versión y la configuración en CloudWatch/Loki en cada inicio de pod
Nunca registres valores de entorno secretos

3. Salud y disponibilidad

app.get("/health", (_req, res) => res.json({ status: "ok" }));
app.get("/ready", async (_req, res) => {
  const ok = await pool.query("SELECT 1");
  res.status(ok ? 200 : 503).json({ status: ok ? "ready" : "not_ready" });
});

El orquestador los usa para enrutamiento y reinicios
Consulta Sondas de salud y disponibilidad

4. Política de `uncaughtException`

process.on("uncaughtException", (err) => {
  console.error(JSON.stringify({ event: "uncaughtException", message: err.message, stack: err.stack }));
  // Política A: salir y dejar que el supervisor reinicie (recomendado para APIs)
  process.exit(1);
});

Documenta la Política A (salir) vs la Política B (registrar y continuar) por servicio en el manual de operaciones
Estado del proceso desconocido después de uncaughtException; salir es más seguro para las APIs HTTP

5. Política de `unhandledRejection`

process.on("unhandledRejection", (reason) => {
  console.error(JSON.stringify({ event: "unhandledRejection", reason: String(reason) }));
  process.exit(1);
});

Express 5 reenvía errores asíncronos; aún así, protege a los workers de nivel superior
Falla rápidamente para que se activen las alertas

6. Visibilidad de la memoria

app.get("/metrics/memory", (_req, res) => {
  const m = process.memoryUsage();
  res.json({
    rss: m.rss,
    heapUsed: m.heapUsed,
    heapTotal: m.heapTotal,
    external: m.external,
  });
});

Protege las rutas de administración con autenticación o desactívalas en producción
Prefiere el exportador nodejs_heap_size_bytes de Prometheus para una monitorización real

7. Límite de heap de `NODE_OPTIONS`

NODE_OPTIONS="--max-old-space-size=384"

Establece un valor inferior al límite de memoria del contenedor para dejar espacio para búferes nativos y libuv
Deriva de los datos RSS de la prueba de carga, no de la suposición predeterminada de 512 MB

Ejemplos intermedios

8. Esqueleto de apagado elegante

const server = app.listen(port, "0.0.0.0");
 
function shutdown(signal: string) {
  console.log(JSON.stringify({ event: "shutdown", signal }));
  server.close(async () => {
    await pool.end();
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 30_000).unref();
}
 
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

Consulta Apagado elegante para ver el patrón completo

9. PM2 en una VM (cuando no estás en K8s)

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: "api",
    script: "dist/main.js",
    instances: 2,
    exec_mode: "cluster",
    max_memory_restart: "512M",
    kill_timeout: 30_000,
    listen_timeout: 10_000,
  }],
};

pm2 start ecosystem.config.cjs
pm2 save

PM2 solo para VMs - PM2 y systemd

10. Primeras preguntas de guardia

Síntoma	Comprobar
CPU alta	¿Despliegue reciente? ¿Pico de tráfico? ¿Bucle infinito en los logs?
Memoria alta	¿Fuga de heap? ¿`max-old-space-size` vs límite?
502 desde LB	¿Pods listos? ¿Drenaje SIGTERM? ¿Tiempo de espera del upstream?

Consulta Manuales de operaciones de guardia.

Preguntas frecuentes

¿Quién supervisa Node en Kubernetes?

kubelet + controlador de despliegue. Tu aplicación maneja SIGTERM; K8s reinicia los contenedores fallidos.

¿Deberíamos usar el modo clúster en contenedores?

No. Escala las réplicas de pod en lugar del módulo cluster de Node dentro de un contenedor.

¿Cuánto tiempo debe tardar el apagado?

Menos de terminationGracePeriodSeconds (a menudo 30-45s). Coincide con el retraso de la anulación del registro de LB + el cierre del pool de DB.

¿Registro de archivos en producción?

Solo stdout. Los agentes envían los logs fuera del nodo.

¿Qué versión de Node en producción?

Node 24 LTS, coincidiendo con CI y la imagen base de Docker.

¿Operaciones en tiempo de ejecución vs despliegue de plataforma?

El despliegue de plataforma es dónde/cómo ejecutas los contenedores. Las operaciones en tiempo de ejecución son cómo se comporta el proceso Node una vez que está en ejecución.

Relacionado

Apagado elegante - Drenaje SIGTERM
Despliegues sin tiempo de inactividad - Actualizaciones continuas
PM2 y systemd - Supervisión de VM
Manuales de operaciones de guardia - Clasificación de incidentes
Mejores prácticas de operaciones en tiempo de ejecución - Lista de verificación de la sección

Versiones de 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.

Requisitos previos

mkdir prod-api && cd prod-api
npm init -y
npm pkg set type=module
npm install express@5 pg
npm install -D typescript@5.6 @types/node

Para patrones de apagado y despliegue, consulta Apagado elegante y Despliegues sin tiempo de inactividad.

Ejemplos básicos

1. Modelo de supervisión de procesos

Kubernetes / ECS / systemd / PM2
  -> inicia `node dist/main.js`
  -> reinicia al salir con código de error != 0
  -> envía SIGTERM en despliegue o reducción de escala
  -> lee los logs de stdout

Tu aplicación coopera con SIGTERM; la plataforma maneja los reinicios
No hagas doble supervisión (PM2 dentro de un pod de K8s)

2. Log de arranque estructurado

console.log(JSON.stringify({
  event: "boot",
  node: process.version,
  env: process.env.NODE_ENV,
  pid: process.pid,
}));

Confirma la versión y la configuración en CloudWatch/Loki en cada inicio de pod
Nunca registres valores de entorno secretos

3. Salud y disponibilidad

app.get("/health", (_req, res) => res.json({ status: "ok" }));
app.get("/ready", async (_req, res) => {
  const ok = await pool.query("SELECT 1");
  res.status(ok ? 200 : 503).json({ status: ok ? "ready" : "not_ready" });
});

El orquestador los usa para enrutamiento y reinicios
Consulta Sondas de salud y disponibilidad

4. Política de `uncaughtException`

process.on("uncaughtException", (err) => {
  console.error(JSON.stringify({ event: "uncaughtException", message: err.message, stack: err.stack }));
  // Política A: salir y dejar que el supervisor reinicie (recomendado para APIs)
  process.exit(1);
});

Documenta la Política A (salir) vs la Política B (registrar y continuar) por servicio en el manual de operaciones
Estado del proceso desconocido después de uncaughtException; salir es más seguro para las APIs HTTP

5. Política de `unhandledRejection`

process.on("unhandledRejection", (reason) => {
  console.error(JSON.stringify({ event: "unhandledRejection", reason: String(reason) }));
  process.exit(1);
});

Express 5 reenvía errores asíncronos; aún así, protege a los workers de nivel superior
Falla rápidamente para que se activen las alertas

6. Visibilidad de la memoria

app.get("/metrics/memory", (_req, res) => {
  const m = process.memoryUsage();
  res.json({
    rss: m.rss,
    heapUsed: m.heapUsed,
    heapTotal: m.heapTotal,
    external: m.external,
  });
});

Protege las rutas de administración con autenticación o desactívalas en producción
Prefiere el exportador nodejs_heap_size_bytes de Prometheus para una monitorización real

7. Límite de heap de `NODE_OPTIONS`

NODE_OPTIONS="--max-old-space-size=384"

Establece un valor inferior al límite de memoria del contenedor para dejar espacio para búferes nativos y libuv
Deriva de los datos RSS de la prueba de carga, no de la suposición predeterminada de 512 MB

Ejemplos intermedios

8. Esqueleto de apagado elegante

const server = app.listen(port, "0.0.0.0");
 
function shutdown(signal: string) {
  console.log(JSON.stringify({ event: "shutdown", signal }));
  server.close(async () => {
    await pool.end();
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 30_000).unref();
}
 
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

Consulta Apagado elegante para ver el patrón completo

9. PM2 en una VM (cuando no estás en K8s)

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: "api",
    script: "dist/main.js",
    instances: 2,
    exec_mode: "cluster",
    max_memory_restart: "512M",
    kill_timeout: 30_000,
    listen_timeout: 10_000,
  }],
};

pm2 start ecosystem.config.cjs
pm2 save

PM2 solo para VMs - PM2 y systemd

10. Primeras preguntas de guardia

Síntoma	Comprobar
CPU alta	¿Despliegue reciente? ¿Pico de tráfico? ¿Bucle infinito en los logs?
Memoria alta	¿Fuga de heap? ¿`max-old-space-size` vs límite?
502 desde LB	¿Pods listos? ¿Drenaje SIGTERM? ¿Tiempo de espera del upstream?

Consulta Manuales de operaciones de guardia.

Preguntas frecuentes

¿Quién supervisa Node en Kubernetes?

kubelet + controlador de despliegue. Tu aplicación maneja SIGTERM; K8s reinicia los contenedores fallidos.

¿Deberíamos usar el modo clúster en contenedores?

No. Escala las réplicas de pod en lugar del módulo cluster de Node dentro de un contenedor.

¿Cuánto tiempo debe tardar el apagado?

Menos de terminationGracePeriodSeconds (a menudo 30-45s). Coincide con el retraso de la anulación del registro de LB + el cierre del pool de DB.

¿Registro de archivos en producción?

Solo stdout. Los agentes envían los logs fuera del nodo.

¿Qué versión de Node en producción?

Node 24 LTS, coincidiendo con CI y la imagen base de Docker.

¿Operaciones en tiempo de ejecución vs despliegue de plataforma?

El despliegue de plataforma es dónde/cómo ejecutas los contenedores. Las operaciones en tiempo de ejecución son cómo se comporta el proceso Node una vez que está en ejecución.

Relacionado

Apagado elegante - Drenaje SIGTERM
Despliegues sin tiempo de inactividad - Actualizaciones continuas
PM2 y systemd - Supervisión de VM
Manuales de operaciones de guardia - Clasificación de incidentes
Mejores prácticas de operaciones en tiempo de ejecución - Lista de verificación de la sección

Versiones de 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.

Conceptos básicos de operaciones en tiempo de ejecución

Buscar en la documentación

Conceptos básicos de operaciones en tiempo de ejecución