Orquestador de Trabajos en Segundo Plano
Experto en diseñar e implementar sistemas de trabajos en segundo plano de nivel de producción que manejan tareas de larga duración sin bloquear las respuestas de la API.
Cuándo Usarlo
✅ Úselo para:
- Tareas de larga duración (envío de correos, generación de informes, procesamiento de imágenes)
- Operaciones por lotes (importaciones masivas, exportaciones, migraciones de datos)
- Tareas programadas (resúmenes diarios, trabajos de limpieza, informes recurrentes)
- Tareas que requieren lógica de reintentos (llamadas a API externas, operaciones inestables)
- Procesamiento basado en prioridades (usuarios premium primero, alertas críticas)
- Operaciones con límite de tasa (cuotas de API, límites de servicios de terceros)
❌ NO para:
- Comunicación bidireccional en tiempo real (use WebSockets)
- Requisitos de latencia de menos de un segundo (use caché en memoria)
- Retrasos simples (setTimeout es suficiente para <5 segundos)
- Respuestas de API síncronas (mantenga la lógica en el manejador de solicitudes)
Árbol de Decisión Rápido
¿Esta tarea:
├── Toma >5 segundos? → Trabajo en segundo plano
├── Necesita reintentos al fallar? → Trabajo en segundo plano
├── Se ejecuta en un horario? → Trabajo en segundo plano (patrón cron)
├── Bloquea la interacción del usuario? → Trabajo en segundo plano
├── Procesa en lotes? → Trabajo en segundo plano
└── Devuelve inmediatamente? → Mantener síncrono
Selección de Tecnología
Node.js: BullMQ (Recomendado 2024+)
Cuándo usarlo:
- Proyecto TypeScript
- Redis ya está en el stack
- Necesita funciones avanzadas (límites de tasa, prioridades, trabajos repetibles)
Por qué BullMQ en lugar de Bull:
- Bull (v3) → BullMQ (v4+): Reescritura completa en TypeScript
- Mejor manejo de la conexión con Redis
- Concurrencia y rendimiento mejorados
- Mantenimiento activo (Bull está en modo de mantenimiento)
Python: Celery
Cuándo usarlo:
- Proyecto Python/Django
- Necesita ejecución distribuida de tareas
- Flujos de trabajo complejos (cadenas, grupos, acordes)
Alternativas:
- RQ (Redis Queue): Más simple, menos funciones
- Dramatiq: Moderno, menos ecosistema
- Huey: Ligero, bueno para proyectos pequeños
Nativo de la Nube: AWS SQS, Google Cloud Tasks
Cuándo usarlos:
- Arquitectura serverless
- No quiere administrar Redis/RabbitMQ
- Necesita entrega garantizada y colas de mensajes fallidos (dead-letter queues)
Antipatrones Comunes
Antipatrón 1: Sin Cola de Mensajes Fallidos (Dead Letter Queue)
Pensamiento novato: "Reintentar 3 veces, luego fallar en silencio"
Problema: Los trabajos fallidos desaparecen sin visibilidad ni ruta de recuperación.
Enfoque correcto:
// BullMQ con dead letter queue
const queue = new Queue('cola-correo', {
connection: redis,
defaultJobOptions: {
attempts: 3,
backoff: {
type: 'exponential',
delay: 2000
},
removeOnComplete: 100, // Mantener los últimos 100 exitosos
removeOnFail: false // Mantener todos los fallidos para inspección
}
});
// Monitorear trabajos fallidos
const failedJobs = await queue.getFailed();
Cronología:
- Antes de 2020: Reintentar y olvidar
- 2020+: Las colas de mensajes fallidos se convierten en estándar
- 2024+: Se requiere observabilidad para fallos de trabajos
Antipatrón 2: Procesamiento Síncrono de Trabajos
Síntoma: El endpoint de la API espera a que el trabajo termine
Problema:
// ❌ INCORRECTO - Bloquea la respuesta de la API
app.post('/enviar-correo', async (req, res) => {
await sendEmail(req.body.to, req.body.subject);
res.json({ success: true });
});
Por qué está mal: Timeout, mala UX, desperdicia recursos del servidor
Enfoque correcto:
// ✅ CORRECTO - Encola y devuelve inmediatamente
app.post('/enviar-correo', async (req, res) => {
const job = await emailQueue.add('send', {
to: req.body.to,
subject: req.body.subject
});
res.json({
success: true,
jobId: job.id,
status: 'queued'
});
});
// Un worker separado procesa el trabajo
worker.process('send', async (job) => {
await sendEmail(job.data.to, job.data.subject);
});
Antipatrón 3: Sin Idempotencia
Problema: El trabajo se ejecuta dos veces → cargos duplicados, correos duplicados
Por qué ocurre:
- La conexión con Redis se cae durante el procesamiento
- El worker falla antes de completar el trabajo
- El timeout del trabajo activa un reintento mientras aún se está ejecutando
Enfoque correcto:
// ✅ Trabajo idempotente con clave de deduplicación
await queue.add('cobrar-pago', {
userId: 123,
amount: 50.00
}, {
jobId: `payment-${orderId}`, // Previene duplicados
attempts: 3
});
// En el worker: Verificar si ya se procesó
worker.process('cobrar-pago', async (job) => {
const { userId, amount } = job.data;
// Verificar idempotencia
const existing = await db.payments.findOne({
jobId: job.id
});
if (existing) {
return existing; // Ya procesado
}
// Procesar pago
const result = await stripe.charges.create({...});
// Almacenar registro de idempotencia
await db.payments.create({
jobId: job.id,
result
});
return result;
});
Antipatrón 4: Sin Límite de Tasa (Rate Limiting)
Problema: Sobrecargar APIs de terceros o agotar cuotas
Síntoma: Errores de "Rate limit exceeded" de Sendgrid, Stripe, etc.
Enfoque correcto:
// Límite de tasa en BullMQ
const queue = new Queue('llamadas-api', {
limiter: {
max: 100, // Máximo 100 trabajos
duration: 60000 // Por 60 segundos
}
});
// O: Límites de tasa basados en prioridad
await queue.add('enviar-correo', data, {
priority: user.isPremium ? 1 : 10,
rateLimiter: {
max: user.isPremium ? 1000 : 100,
duration: 3600000 // Por hora
}
});
Antipatrón 5: Olvidar el Escalado de Workers
Problema: Un solo worker no puede seguir el ritmo de la profundidad de la cola
Síntoma: La cola se acumula, los trabajos se retrasan horas/días
Enfoque correcto:
// Escalado horizontal con múltiples workers
const worker = new Worker('cola-correo', async (job) => {
await processEmail(job.data);
}, {
connection: redis,
concurrency: 5 // Procesar 5 trabajos concurrentemente por worker
});
// Ejecutar múltiples procesos de worker (PM2, Kubernetes, etc.)
// Cada worker procesa concurrencia * num_workers trabajos
Monitoreo:
// Configurar alertas para la profundidad de la cola
setInterval(async () => {
const waiting = await queue.getWaitingCount();
if (waiting > 1000) {
alert('¡La profundidad de la cola supera 1000, escalar workers!');
}
}, 60000);
Patrones de Implementación
Patrón 1: Campañas de Correo Electrónico
// Configuración de la cola
const emailQueue = new Queue('campaña-correo', { connection: redis });
// Encolar lote
async function sendCampaign(userIds: number[], template: string) {
const jobs = userIds.map(userId => ({
name: 'send',
data: { userId, template },
opts: {
attempts: 3,
backoff: { type: 'exponential', delay: 5000 }
}
}));
await emailQueue.addBulk(jobs);
}
// Worker con lógica de reintento
const worker = new Worker('campaña-correo', async (job) => {
const { userId, template } = job.data;
const user = await db.users.findById(userId);
const email = renderTemplate(template, user);
try {
await sendgrid.send({
to: user.email,
subject: email.subject,
html: email.body
});
} catch (error) {
if (error.code === 'ECONNREFUSED') {
throw error; // Reintentar
}
// Correo inválido, no reintentar
console.error(`Correo inválido para el usuario ${userId}`);
}
}, {
connection: redis,
concurrency: 10
});
Patrón 2: Informes Programados
// Informe diario a las 9 AM
await queue.add('informe-diario', {
type: 'ventas',
recipients: ['[email protected]']
}, {
repeat: {
pattern: '0 9 * * *', // Sintaxis cron
tz: 'America/New_York'
}
});
// El worker genera y envía el informe por correo
worker.process('informe-diario', async (job) => {
const { type, recipients } = job.data;
const data = await generateReport(type);
const pdf = await createPDF(data);
await emailQueue.add('send', {
to: recipients,
subject: `Informe diario de ${type}`,
attachments: [{ filename: 'report.pdf', content: pdf }]
});
});
Patrón 3: Tubería de Transcodificación de Video
// Trabajo de múltiples etapas con seguimiento de progreso
await videoQueue.add('transcode', {
videoId: 123,
formats: ['720p', '1080p', '4k']
}, {
attempts: 2,
timeout: 3600000 // Timeout de 1 hora
});
worker.process('transcode', async (job) => {
const { videoId, formats } = job.data;
for (let i = 0; i < formats.length; i++) {
const format = formats[i];
// Actualizar progreso
await job.updateProgress((i / formats.length) * 100);
// Transcodificar
await ffmpeg.transcode(videoId, format);
}
await job.updateProgress(100);
});
// El cliente consulta el progreso
app.get('/videos/:id/status', async (req, res) => {
const job = await queue.getJob(req.params.jobId);
res.json({
state: await job.getState(),
progress: job.progress
});
});
Monitoreo y Observabilidad
Métricas Esenciales
// Tablero de salud de la cola
async function getQueueMetrics() {
const [waiting, active, completed, failed, delayed] = await Promise.all([
queue.getWaitingCount(),
queue.getActiveCount(),
queue.getCompletedCount(),
queue.getFailedCount(),
queue.getDelayedCount()
]);
return {
waiting, // Trabajos esperando ser procesados
active, // Trabajos siendo procesados actualmente
completed, // Completados con éxito
failed, // Fallidos después de reintentos
delayed, // Programados para el futuro
health: waiting < 1000 && failed < 100 ? 'healthy' : 'degraded'
};
}
BullMQ Board (IU)
// Desarrollo: Monitorear trabajos visualmente
import { createBullBoard } from '@bull-board/api';
import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
import { ExpressAdapter } from '@bull-board/express';
const serverAdapter = new ExpressAdapter();
createBullBoard({
queues: [
new BullMQAdapter(emailQueue),
new BullMQAdapter(videoQueue)
],
serverAdapter
});
app.use('/admin/queues', serverAdapter.getRouter());
// Visite http://localhost:3000/admin/queues
Lista de Verificación para Producción
□ Cola de mensajes fallidos configurada
□ Estrategia de reintentos con retroceso exponencial
□ Límites de timeout de trabajo establecidos
□ Límite de tasa para APIs de terceros
□ Claves de idempotencia para operaciones críticas
□ Concurrencia de workers ajustada (núcleos de CPU * 2)
□ Escalado horizontal configurado (múltiples workers)
□ Monitoreo de profundidad de cola con alertas
□ Flujo de trabajo de inspección de trabajos fallidos
□ Los datos del trabajo no contienen PII en los registros
□ Persistencia de Redis habilitada (AOF o RDB)
□ Manejo de apagado graceful (SIGTERM)
Cuándo Usar vs Evitar
| Escenario | ¿Usar trabajos en segundo plano? |
|---|---|
| Enviar correo de bienvenida al registrarse | ✅ Sí - puede tomar 2-5 segundos |
| Cobrar tarjeta de crédito | ⚠️ Quizás - depende de la latencia del proveedor de pago |
| Generar informe PDF (30 segundos) | ✅ Sí - definitivamente en segundo plano |
| Obtener perfil de usuario de la BD | ❌ No - milisegundos, mantener síncrono |
| Procesar carga de video (5 minutos) | ✅ Sí - siempre en segundo plano |
| Validar entrada de formulario | ❌ No - validación síncrona |
| Trabajo cron diario | ✅ Sí - usar trabajos repetibles |
| Mensaje de chat en tiempo real | ❌ No - usar WebSockets |
Comparación de Tecnologías
| Característica | BullMQ | Celery | AWS SQS |
|---|---|---|---|
| Lenguaje | Node.js | Python | Cualquiera (API HTTP) |
| Backend | Redis | Redis/RabbitMQ/SQS | Gestionado |
| Prioridades | ✅ | ✅ | ✅ |
| Límite de tasa | ✅ | ❌ | ✅ (mediante atributos) |
| Repetir/Cron | ✅ | ✅ (celery-beat) | ❌ (usar EventBridge) |
| Panel de IU | Bull Board | Flower | CloudWatch |
| Flujos de trabajo | ❌ | ✅ (cadenas, grupos) | ❌ |
| Curva de aprendizaje | Media | Media | Baja |
| Costo | Hosting de Redis | Hosting de Redis | $0.40/millón de solicitudes |
Referencias
/references/bullmq-patterns.md- Patrones y ejemplos avanzados de BullMQ/references/celery-workflows.md- Cadenas, grupos y acordes de Celery/references/job-observability.md- Monitoreo, alertas y depuración
Scripts
scripts/setup_bullmq.sh- Inicializar BullMQ con Redisscripts/queue_health_check.ts- Panel de métricas de la colascripts/retry_failed_jobs.ts- Reintentar en lote trabajos fallidos
Este skill guía sobre: Implementación de trabajos en segundo plano | Arquitectura de colas | Estrategias de reintentos | Escalado de workers | Observabilidad de trabajos