service_manager/workers

ServiceManagerWeb Workers

Workers asíncronos con Celery para el sistema de Mesa de Ayuda B2B.

Estructura

workers/
├── app/
│   ├── celery.py            # Configuración principal de Celery
│   ├── core/                # Configuración compartida
│   │   ├── config.py        # Settings para workers
│   │   └── logging.py       # Logging estructurado
│   └── tasks/               # Tareas por dominio
│       ├── email_tasks.py           # Envío de emails
│       ├── sla_tasks.py             # Monitoreo de SLAs
│       ├── maintenance_tasks.py     # Mantenimiento del sistema
│       └── notification_tasks.py    # Notificaciones y digests
├── requirements.txt         # Dependencias Python
└── README.md               # Esta documentación

Tareas Implementadas

Email Tasks (email_tasks.py)

• send_email_task: Envío básico de emails SMTP
• send_templated_email_task: Emails con plantillas Jinja2
• send_bulk_email_task: Envío masivo con progreso

SLA Tasks (sla_tasks.py)

• check_sla_violations: Monitoreo de violaciones SLA
• calculate_sla_metrics: Cálculo de métricas SLA
• send_sla_warnings: Alertas de SLAs próximos a vencer

Maintenance Tasks (maintenance_tasks.py)

• health_check: Health check de workers
• cleanup_old_logs: Limpieza de logs antiguos
• generate_weekly_reports: Reportes semanales
• cleanup_temp_files: Limpieza de archivos temporales
• database_maintenance: Mantenimiento de BD

Notification Tasks (notification_tasks.py)

• send_daily_digest: Digest diario para agentes
• send_ticket_notifications: Notificaciones de tickets
• send_system_alert: Alertas del sistema

Programación Automática (Celery Beat)

Tareas Periódicas Configuradas

# Cada 5 minutos
"check-sla-violations": check_sla_violations

# Diario a las 8:00 AM
"send-daily-digest": send_daily_digest

# Semanal los domingos a las 2:00 AM
"cleanup-old-logs": cleanup_old_logs

# Semanal los lunes a las 9:00 AM
"generate-weekly-reports": generate_weekly_reports

# Cada minuto (health check)
"worker-health-check": health_check

Quick Start

Desarrollo Local

# Instalar dependencias
pip install -r requirements.txt

# Variables de entorno (usar las del proyecto principal)
cp ../.env.example .env

# Ejecutar worker
celery -A app.celery worker --loglevel=info

# Ejecutar beat scheduler (en otra terminal)
celery -A app.celery beat --loglevel=info

# Monitoreo con Flower (opcional)
celery -A app.celery flower

Con Docker

# Worker y Beat se ejecutan automáticamente con docker-compose
docker-compose up worker beat

# Ver logs
docker-compose logs -f worker
docker-compose logs -f beat

Configuración

Variables de Entorno Importantes

# Celery
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Email
SMTP_HOST=mailhog
SMTP_PORT=1025
DEFAULT_FROM_EMAIL=noreply@servicemanager.local

# SLA
SLA_CHECK_ENABLED=true
SLA_WARNING_THRESHOLD=0.8

# Mantenimiento
LOG_RETENTION_DAYS=30
DIGEST_ENABLED=true

Colas de Trabajo

• default: Tareas generales
• email: Envío de emails
• sla: Monitoreo SLA
• maintenance: Mantenimiento
• notifications: Notificaciones

Monitoreo

Logs Estructurados

Todos los workers utilizan structured logging con:

• Task ID único
• Correlation ID para tracking
• Contexto de tenant
• Métricas de performance

Health Checks

# Health check manual
celery -A app.celery inspect ping

# Estadísticas de workers
celery -A app.celery inspect stats

# Tareas activas
celery -A app.celery inspect active

Métricas

• Task execution times
• Success/failure rates
• Queue lengths
• Worker load

Desarrollo

Agregar Nueva Tarea

1. Crear función en módulo apropiado:

@celery_app.task(bind=True, time_limit=300)
def new_task(self, param1: str, param2: int):
    logger = get_logger(__name__)
    # Implementation
    return result

2. Registrar en celery.py si es periódica:

beat_schedule = {
    "new-periodic-task": {
        "task": "app.tasks.module.new_task",
        "schedule": crontab(minute=0, hour=9),
    }
}

3. Agregar tests en tests/

Retry y Error Handling

@celery_app.task(
    bind=True,
    autoretry_for=(ConnectionError, TimeoutError),
    retry_kwargs={'max_retries': 3, 'countdown': 60}
)
def reliable_task(self):
    # Task que se reintenta automáticamente
    pass

Templates de Email

Los templates están definidos en código por ahora. En el futuro se moverán a base de datos para ser editables por tenants.

Templates disponibles:

• ticket_created
• ticket_assigned
• ticket_resolved
• sla_warning
• sla_violation
• daily_digest
• system_alert

Testing

# Ejecutar tests
pytest

# Tests específicos de workers
pytest tests/test_tasks/

# Ejecutar tarea manualmente para testing
celery -A app.celery call app.tasks.email_tasks.send_email_task --args='["test@example.com", "Test Subject", "<h1>Test</h1>"]'

Producción

Configuración Recomendada

# Múltiples workers por queue
celery -A app.celery worker --loglevel=info --concurrency=4 --queues=email
celery -A app.celery worker --loglevel=info --concurrency=2 --queues=sla,maintenance
celery -A app.celery worker --loglevel=info --concurrency=1 --queues=default

# Beat scheduler (solo una instancia)
celery -A app.celery beat --loglevel=info

# Con systemd o supervisor para auto-restart

Optimizaciones

• Pool de conexiones Redis
• Compresión de mensajes grandes
• Rate limiting por tarea
• Monitoring con Prometheus/Grafana

Troubleshooting

Problemas Comunes

1. Tasks stuck in queue:

   • Verificar workers activos
   • Revisar configuración de routing

2. Memory leaks:

   • Configurar worker_max_tasks_per_child
   • Monitorear uso de memoria

3. Email delivery failures:

   • Verificar configuración SMTP
   • Revisar logs de tareas email

4. SLA false positives:

   • Verificar timezones
   • Validar lógica de cálculo

Debug

# Ejecutar worker en modo debug
celery -A app.celery worker --loglevel=debug

# Inspeccionar tareas fallidas
celery -A app.celery inspect failed

# Purgar queue
celery -A app.celery purge -Q queue_name