Noções Básicas de Operações em Tempo de Execução

Q: Devemos usar modo cluster em contêineres?

Não. Aumente as réplicas de pods em vez do módulo cluster do Node dentro de um único contêiner.

Q: Quanto tempo deve levar o desligamento?

Abaixo de terminationGracePeriodSeconds (geralmente 30-45s). Corresponda ao atraso de desregistro do LB + fechamento do pool de banco de dados.

10 exemplos para operar processos Node.js 24 de longa duração em produção - 7 básicos e 3 intermediários.

Pré-requisitos

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 padrões de desligamento e implantação, consulte Desligamento Gracioso e Implantações Sem Interrupção.

Exemplos Básicos

1. Modelo de Supervisão de Processo

Kubernetes / ECS / systemd / PM2
  -> inicia `node dist/main.js`
  -> reinicia em caso de falha com código de saída != 0
  -> envia SIGTERM na implantação ou redução de escala
  -> lê logs stdout

Seu aplicativo coopera com SIGTERM; a plataforma cuida das reinicializações
Não supervisione em duplicidade (PM2 dentro de um pod K8s)

2. Log de Inicialização Estruturado

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

Confirma a versão e a configuração no CloudWatch/Loki a cada início de pod
Nunca registre valores de variáveis de ambiente secretos

3. Saúde e Prontidão

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" });
});

O orquestrador usa estes para roteamento e reinicializações
Veja Sondas de Saúde e Prontidão

4. Política de `uncaughtException`

process.on("uncaughtException", (err) => {
  console.error(JSON.stringify({ event: "uncaughtException", message: err.message, stack: err.stack }));
  // Política A: sair e deixar o supervisor reiniciar (recomendado para APIs)
  process.exit(1);
});

Documente a Política A (sair) vs Política B (registrar e continuar) por serviço no runbook
Estado desconhecido do processo após uncaughtException; sair é mais seguro para APIs HTTP

5. Política de `unhandledRejection`

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

O Express 5 encaminha erros assíncronos; ainda assim, proteja os workers de nível superior
Falhe rapidamente para que os alertas sejam disparados

6. Visibilidade de Memória

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

Proteja rotas de admin com autenticação ou desative em produção
Prefira o exportador nodejs_heap_size_bytes do Prometheus para monitoramento real

7. Limite de Heap `NODE_OPTIONS`

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

Defina abaixo do limite de memória do contêiner para deixar espaço para buffers nativos e libuv
Derive dos dados RSS de teste de carga, não da estimativa padrão de 512 MB

Exemplos Intermediários

8. Esqueleto de Desligamento Gracioso

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"));

Veja Desligamento Gracioso para o padrão completo

9. PM2 em uma VM (Quando Não em 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 apenas para VMs - PM2 & systemd

10. Primeiras Perguntas em Plantão

Sintoma	Verificação
CPU Alta	Implantação recente? Pico de tráfego? Loop infinito nos logs?
Memória Alta	Vazamento de heap? `max-old-space-size` vs limite?
502 do LB	Pods prontos? Drenagem SIGTERM? Timeout do upstream?

Veja Iniciadores de Runbook de Plantão.

FAQs

Quem supervisiona o Node no Kubernetes?

kubelet + controlador de Deployment. Seu aplicativo manipula SIGTERM; o K8s reinicia contêineres com falha.

Devemos usar modo cluster em contêineres?

Não. Aumente as réplicas de pods em vez do módulo cluster do Node dentro de um único contêiner.

Quanto tempo deve levar o desligamento?

Abaixo de terminationGracePeriodSeconds (geralmente 30-45s). Corresponda ao atraso de desregistro do LB + fechamento do pool de banco de dados.

Registro em arquivo em produção?

Apenas stdout. Agentes enviam logs para fora do nó.

Qual versão do Node em produção?

Node 24 LTS, correspondendo ao CI e à imagem base do Docker.

Operações em tempo de execução vs implantação de plataforma?

A implantação de plataforma é onde/como você executa contêineres. As operações em tempo de execução são como o processo Node se comporta uma vez em execução.

Relacionados

Desligamento Gracioso - Drenagem SIGTERM
Implantações Sem Interrupção - atualizações contínuas
PM2 & systemd - supervisão de VM
Iniciadores de Runbook de Plantão - triagem de incidentes
Melhores Práticas de Operações em Tempo de Execução - lista de verificação da seção

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

Pré-requisitos

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 padrões de desligamento e implantação, consulte Desligamento Gracioso e Implantações Sem Interrupção.

Exemplos Básicos

1. Modelo de Supervisão de Processo

Kubernetes / ECS / systemd / PM2
  -> inicia `node dist/main.js`
  -> reinicia em caso de falha com código de saída != 0
  -> envia SIGTERM na implantação ou redução de escala
  -> lê logs stdout

Seu aplicativo coopera com SIGTERM; a plataforma cuida das reinicializações
Não supervisione em duplicidade (PM2 dentro de um pod K8s)

2. Log de Inicialização Estruturado

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

Confirma a versão e a configuração no CloudWatch/Loki a cada início de pod
Nunca registre valores de variáveis de ambiente secretos

3. Saúde e Prontidão

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" });
});

O orquestrador usa estes para roteamento e reinicializações
Veja Sondas de Saúde e Prontidão

4. Política de `uncaughtException`

process.on("uncaughtException", (err) => {
  console.error(JSON.stringify({ event: "uncaughtException", message: err.message, stack: err.stack }));
  // Política A: sair e deixar o supervisor reiniciar (recomendado para APIs)
  process.exit(1);
});

Documente a Política A (sair) vs Política B (registrar e continuar) por serviço no runbook
Estado desconhecido do processo após uncaughtException; sair é mais seguro para APIs HTTP

5. Política de `unhandledRejection`

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

O Express 5 encaminha erros assíncronos; ainda assim, proteja os workers de nível superior
Falhe rapidamente para que os alertas sejam disparados

6. Visibilidade de Memória

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

Proteja rotas de admin com autenticação ou desative em produção
Prefira o exportador nodejs_heap_size_bytes do Prometheus para monitoramento real

7. Limite de Heap `NODE_OPTIONS`

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

Defina abaixo do limite de memória do contêiner para deixar espaço para buffers nativos e libuv
Derive dos dados RSS de teste de carga, não da estimativa padrão de 512 MB

Exemplos Intermediários

8. Esqueleto de Desligamento Gracioso

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"));

Veja Desligamento Gracioso para o padrão completo

9. PM2 em uma VM (Quando Não em 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 apenas para VMs - PM2 & systemd

10. Primeiras Perguntas em Plantão

Sintoma	Verificação
CPU Alta	Implantação recente? Pico de tráfego? Loop infinito nos logs?
Memória Alta	Vazamento de heap? `max-old-space-size` vs limite?
502 do LB	Pods prontos? Drenagem SIGTERM? Timeout do upstream?

Veja Iniciadores de Runbook de Plantão.

FAQs

Quem supervisiona o Node no Kubernetes?

kubelet + controlador de Deployment. Seu aplicativo manipula SIGTERM; o K8s reinicia contêineres com falha.

Devemos usar modo cluster em contêineres?

Não. Aumente as réplicas de pods em vez do módulo cluster do Node dentro de um único contêiner.

Quanto tempo deve levar o desligamento?

Abaixo de terminationGracePeriodSeconds (geralmente 30-45s). Corresponda ao atraso de desregistro do LB + fechamento do pool de banco de dados.

Registro em arquivo em produção?

Apenas stdout. Agentes enviam logs para fora do nó.

Qual versão do Node em produção?

Node 24 LTS, correspondendo ao CI e à imagem base do Docker.

Operações em tempo de execução vs implantação de plataforma?

A implantação de plataforma é onde/como você executa contêineres. As operações em tempo de execução são como o processo Node se comporta uma vez em execução.

Relacionados

Desligamento Gracioso - Drenagem SIGTERM
Implantações Sem Interrupção - atualizações contínuas
PM2 & systemd - supervisão de VM
Iniciadores de Runbook de Plantão - triagem de incidentes
Melhores Práticas de Operações em Tempo de Execução - lista de verificação da seção

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

Noções Básicas de Operações em Tempo de Execução

Buscar na documentação

Noções Básicas de Operações em Tempo de Execução