Runbook: Horizontal Scaling

Overview

Propósito: Aumentar la capacidad de procesamiento del sistema para manejar mayor carga de usuarios o jobs.

Estrategia: Escalado horizontal (más instancias) y vertical (más recursos) gestionado por PM2.

Criticidad: 🟡 MEDIA - Afecta performance, no funcionalidad base

Tipos de Escalado

Tipo	Método	Uso
Vertical	Aumentar RAM/CPU de VM	Cuando un solo proceso necesita más recursos (ej: ETL pesado)
Horizontal	Aumentar réplicas (Cluster Mode)	Cuando hay muchos requests concurrentes (API traffic)
Database	Read Replicas / PGBouncer	Cuando la DB es el cuello de botella

Procedure - PM2 Cluster Mode

Node.js es single-threaded. Para utilizar todos los cores del CPU, usamos PM2 Cluster Mode.

Verificar estado actual
Terminal window
```
pm2 list
```
Verificar columnas mode (debe ser cluster) y instances.
Escalar servicio (Zero Downtime)

Para aumentar instancias de orchestrator a 4:
Terminal window
```
pm2 scale orchestrator 4
```
Para usar todos los CPU disponibles automágicamente:
Terminal window
```
pm2 scale orchestrator max
```
Verificar distribución de carga
Terminal window
```
pm2 monit
```
Observar que los requests se distribuyan entre las instancias.
Persistir cambios
Terminal window
```
pm2 save
```

Procedure - Vertical Scaling

Si el servidor se queda corto de RAM/CPU.

Preparar Downtime

Este proceso requiere reiniciar la VM. Notificar usuarios.
Upgrade de Servidor (Provider)
- Detener instancia VM
- Cambiar tipo de instancia (ej: AWS t3.medium -> t3.large)
- Iniciar instancia
Ajustar memoria de Node.js

Si aumentaste RAM, permite que Node use más heap:
Terminal window
```
# En ecosystem.config.js o comando de start
node_args: "--max-old-space-size=4096" # 4GB
```
Ajustar PostgreSQL

Actualizar postgresql.conf para aprovechar nueva RAM:
- shared_buffers: 25% de RAM total
- effective_cache_size: 75% de RAM total
- work_mem: (RAM total - shared_buffers) / (max_connections * 3)
Terminal window
```
sudo nano /etc/postgresql/16/main/postgresql.conf
sudo systemctl restart postgresql
```

Database Scaling (Connection Pooling)

El cuello de botella suele ser las conexiones a DB.

Diagnóstico

# Ver conexiones activas vs máximas
sudo -u postgres psql -c "show max_connections;"
sudo -u postgres psql -c "select count(*) from pg_stat_activity;"

Ajustar Pool en Orchestrator

Editar .env.production:
Terminal window
```
DB_MAX_CONNECTIONS=20 # Por instancia de PM2
```
Nota: Si tienes 4 instancias PM2, total conexiones = 4 * 20 = 80.
Implementar PgBouncer (Avanzado)

Si max_connections de Postgres se satura (ej: > 500), usar PgBouncer como proxy.
Terminal window
```
sudo apt install pgbouncer
# Configurar pgbouncer.ini
```

Troubleshooting

Error: “Javascript heap out of memory”

Causa: Proceso Node.js excedió límite de RAM (default ~2GB en 64-bit).

Solución:

Aumentar límite: --max-old-space-size=4096
Buscar memory leaks (ver Troubleshooting Guide)

CPU al 100% constante

Causa: Loop infinito o proceso bloqueante.

Diagnóstico:

pm2 monit
# Identificar proceso
pidstat -p <PID> 1