Módulo OS no Node.js: Guia Prático

Aplicações de servidor frequentemente precisam conhecer memória disponível, quantidade de processadores, diretórios do usuário, interfaces de rede e características da plataforma. O módulo OS no Node.js reúne informações do sistema operacional em uma API nativa e multiplataforma.

Esses dados ajudam em diagnósticos, relatórios, decisões de concorrência e ferramentas de linha de comando. Entretanto, recursos vistos pelo processo podem ser diferentes dos recursos reais da máquina quando a aplicação roda em containers ou ambientes com limites.

Neste guia, você aprenderá a usar os.cpus(), availableParallelism(), freemem(), totalmem(), networkInterfaces(), homedir(), tmpdir() e outras funções com práticas seguras.

Importando o módulo OS

const os = require('node:os');

Em ES Modules:

import os from 'node:os';

A documentação oficial do módulo OS detalha formatos e disponibilidade. Para dados do processo atual, veja Objeto Process no Node.js e o que é Node.js.

Identificando a plataforma

console.log(os.platform());
console.log(os.type());
console.log(os.release());

platform() retorna valores como linux, win32 ou darwin. type() fornece o nome do sistema e release() mostra sua versão. Não use essas informações para bloquear plataformas sem necessidade.

Arquitetura da CPU

console.log(os.arch());

A arquitetura pode ser x64, arm64 e outros valores. Isso é útil ao escolher um binário nativo. Prefira pacotes que façam essa seleção automaticamente.

Informações dos processadores

const cpus = os.cpus();

console.log(cpus.length);
console.log(cpus[0]);

Cada entrada pode apresentar modelo, velocidade e tempos acumulados. O número de entradas não deve ser usado isoladamente para definir concorrência em containers.

Paralelismo disponível

os.availableParallelism() fornece uma estimativa mais adequada para quantidade de trabalho paralelo:

const workers = Math.max(
  1,
  os.availableParallelism() - 1
);

Deixar um núcleo livre não é uma regra universal. O valor ideal depende do tipo de trabalho, CPU, memória e outros processos. Faça testes de carga.

Worker Threads

Para tarefas intensivas em CPU, a quantidade de workers pode começar baseada no paralelismo disponível:

const workerCount = Math.min(
  os.availableParallelism(),
  MAX_WORKERS
);

Defina também um limite de configuração. Em servidores muito grandes, criar dezenas de workers pode consumir memória excessiva. Veja Worker Threads no Node.js.

Memória total e livre

const total = os.totalmem();
const free = os.freemem();

console.log({
  totalMB: Math.round(total / 1024 / 1024),
  freeMB: Math.round(free / 1024 / 1024)
});

Os valores são bytes. Em containers, versões e configurações podem influenciar se o runtime observa limites do container ou recursos do host. Compare com métricas do orquestrador.

Memória do sistema não é heap do Node.js

os.freemem() descreve memória do sistema. Para o processo:

const usage = process.memoryUsage();

Uma máquina com memória livre ainda pode ter um processo próximo do limite do heap. Monitore os dois níveis.

Uptime do sistema

console.log(os.uptime());

Esse valor representa segundos desde a inicialização do sistema operacional. process.uptime() representa o tempo do processo. Não confunda as métricas em health checks.

Hostname

console.log(os.hostname());

O hostname ajuda a identificar instâncias em logs. Em containers, ele pode ser um identificador efêmero. Use também um instance ID definido pela plataforma.

Diretório do usuário

const home = os.homedir();

O diretório inicial varia entre sistemas e usuários. Para configuração por usuário em uma CLI, combine essa função com convenções da plataforma. Em serviços, prefira diretórios explicitamente configurados.

Diretório temporário

const temp = os.tmpdir();

O diretório temporário pode ser compartilhado e limpo pelo sistema. Use nomes aleatórios, permissões restritas e remova arquivos após o uso.

const path = require('node:path');
const crypto = require('node:crypto');

const file = path.join(
  os.tmpdir(),
  `app-${crypto.randomUUID()}.tmp`
);

Riscos de arquivos temporários

Não construa nomes previsíveis com dados do usuário. Isso pode causar colisão ou ataques de symlink em ambientes compartilhados. Prefira APIs que criam diretórios temporários únicos.

const fs = require('node:fs/promises');
const path = require('node:path');

const directory = await fs.mkdtemp(
  path.join(os.tmpdir(), 'app-')
);

Interfaces de rede

const interfaces = os.networkInterfaces();
console.log(interfaces);

O resultado agrupa endereços por interface. Cada item pode incluir endereço, máscara, família, MAC, escopo e indicador internal.

Encontrando um endereço externo

function getAddresses() {
  return Object.values(os.networkInterfaces())
    .flat()
    .filter(Boolean)
    .filter(item => !item.internal)
    .map(item => ({
      address: item.address,
      family: item.family
    }));
}

Uma máquina pode ter vários endereços, VPN, interfaces virtuais, IPv4 e IPv6. Não assuma que o primeiro é o endereço público. Em cloud, o IP público pode nem estar configurado diretamente na interface.

Endianness

console.log(os.endianness());

O valor indica LE ou BE. A maioria dos ambientes comuns é little-endian, mas protocolos binários devem definir explicitamente a ordem, independentemente da máquina.

Prioridade de processos

Dependendo da plataforma e permissão, os.getPriority() e os.setPriority() consultam ou ajustam prioridade:

const current = os.getPriority();
os.setPriority(process.pid, 5);

Alterar prioridade pode falhar por permissão e afetar o sistema. Não use como substituto para limites de CPU e políticas do orquestrador.

Load average

const [one, five, fifteen] = os.loadavg();

Em sistemas Unix, os valores representam médias de carga. No Windows, podem ser zero. Interprete em relação à quantidade de CPUs e à plataforma.

Monitoramento simples

function systemSnapshot() {
  return {
    hostname: os.hostname(),
    platform: os.platform(),
    uptime: os.uptime(),
    totalMemory: os.totalmem(),
    freeMemory: os.freemem(),
    parallelism: os.availableParallelism(),
    loadAverage: os.loadavg()
  };
}

Esse snapshot pode ser usado em diagnóstico administrativo. Não exponha detalhes internos em um endpoint público.

Health checks

Memória livre baixa não significa automaticamente que a aplicação está indisponível, pois sistemas utilizam cache. Health checks devem medir capacidade real do serviço, não apenas um limite arbitrário do host.

Veja Health Checks no Node.js para liveness e readiness.

Containers e cgroups

Em containers, o host pode possuir 64 CPUs e o container estar limitado a duas. APIs modernas do runtime tentam respeitar limites, mas valide na versão utilizada. Use métricas da plataforma como fonte complementar.

Também considere memory limit, memory request e CPU throttling. Uma aplicação pode apresentar latência alta sem que o uso aparente de CPU alcance 100% do host.

Gerando relatório de diagnóstico

Combine dados do OS com informações não sensíveis do processo:

const report = {
  node: process.version,
  pid: process.pid,
  processUptime: process.uptime(),
  systemUptime: os.uptime(),
  platform: os.platform(),
  architecture: os.arch(),
  parallelism: os.availableParallelism(),
  memory: process.memoryUsage()
};

Evite incluir variáveis de ambiente, argumentos secretos ou interfaces completas sem controle de acesso.

Testes multiplataforma

Mockar o módulo OS pode testar decisões:

function chooseWorkerCount(available) {
  return Math.max(1, Math.min(available, 8));
}

Separe a regra da chamada ao sistema. Assim, você testa valores diferentes sem depender da máquina do CI.

Erros comuns

• Usar cpus().length em containers: o valor pode não refletir limite real.
• Assumir que o primeiro IP é público: existem várias interfaces.
• Expor diagnóstico publicamente: informações ajudam reconhecimento do ambiente.
• Confundir memória livre com heap: são níveis diferentes.
• Criar arquivo temporário previsível: pode causar colisões e ataques.
• Assumir loadavg no Windows: a métrica não funciona da mesma forma.
• Alterar prioridade sem necessidade: comportamento e permissões variam.

Boas práticas para produção

• Use availableParallelism como ponto inicial.
• Defina limites configuráveis de workers.
• Compare dados do OS com métricas do container.
• Proteja endpoints de diagnóstico.
• Use diretórios temporários únicos.
• Não assuma um único endereço de rede.
• Monitore processo e sistema separadamente.
• Teste em todas as plataformas suportadas.
• Normalize unidades antes de registrar.
• Evite decisões críticas com uma única métrica.

Conclusão

O módulo OS no Node.js oferece uma visão multiplataforma do ambiente onde o processo executa. CPU, memória, rede, diretórios e uptime ajudam a configurar e diagnosticar aplicações.

Esses valores precisam ser interpretados no contexto de containers, limites e múltiplas interfaces. Ao combinar o módulo OS com métricas do processo e da infraestrutura, você toma decisões mais seguras sem depender de suposições sobre a máquina.