Mejoras en el Sistema de Logging - Pedidos Express

Resumen de Mejoras Implementadas

Este documento describe las mejoras implementadas en el sistema de logging del proyecto Pedidos Express.

1. Nuevo Sistema de Logging Estructurado

Archivo: `services/logging_service.py`

Se implementó un sistema de logging estructurado con las siguientes características:

Logging por categorías: ORDER, USER, PAYMENT, SECURITY, API, DATABASE, EMAIL, PRINT, CHAT, SYSTEM
Niveles de log: DEBUG, INFO, WARNING, ERROR, CRITICAL
Logs estructurados en JSON: Fáciles de procesar y analizar
Archivos de log específicos: Un archivo por categoría para mejor organización
Metadatos enriquecidos: Incluye user_id, user_email, timestamp, datos contextuales

Funciones principales:

log_order_event(): Para eventos relacionados con pedidos
log_user_event(): Para eventos de usuarios
log_security_event(): Para eventos de seguridad
log_api_event(): Para eventos de API
log_database_event(): Para eventos de base de datos
log_email_event(): Para eventos de email
log_print_event(): Para eventos de impresión
log_chat_event(): Para eventos de chat/LLM
log_system_event(): Para eventos del sistema

2. Mejoras por Archivo

`services/print_service.py`

✅ Logging detallado de operaciones de impresión
✅ Manejo robusto de errores con contexto
✅ Logging de status de impresora
✅ Timeouts en requests para evitar bloqueos
✅ Logging estructurado para troubleshooting

`auth/security.py`

✅ Logging de eventos de autenticación
✅ Logging de generación de tokens
✅ Logging de validación de tokens
✅ Logging de errores de JWT
✅ Logging de intentos de acceso no autorizado

`services/email_service.py`

✅ Logging de conexiones SMTP
✅ Logging de autenticación SMTP
✅ Logging de envío de emails
✅ Logging de reintentos automáticos
✅ Logging de errores de conexión

`routes/orders.py`

✅ Logging completo del flujo de pedidos
✅ Logging de validaciones de datos
✅ Logging de integración con Fudo
✅ Logging de creación de ventas
✅ Logging de actualización de recompensas
✅ Logging de impresión de pedidos
✅ Manejo robusto de errores con contexto

`routes/users.py`

✅ Logging de registro de usuarios
✅ Logging de intentos de login
✅ Logging de bloqueos por intentos fallidos
✅ Logging de validaciones RUT
✅ Logging de verificaciones por email
✅ Logging de eventos de seguridad

`routes/chat.py`

✅ Logging de requests de chat
✅ Logging de respuestas de OpenAI
✅ Logging de errores de procesamiento
✅ Logging de métricas de uso

`main.py`

✅ Logging de inicio de aplicación
✅ Logging de validación de configuración
✅ Logging de inicialización de componentes
✅ Logging de errores críticos de startup

`app.py`

✅ Logging de creación de app FastAPI
✅ Logging de configuración de middleware
✅ Logging de setup de rutas
✅ Logging de montaje de archivos estáticos

3. Beneficios del Nuevo Sistema

Troubleshooting Mejorado

Logs estructurados facilitan el análisis automático
Contexto enriquecido con user_id, emails, datos de request
Categorización permite filtrar por tipo de evento
Timestamps precisos para correlación temporal

Seguridad

Logging de eventos de seguridad (login failures, admin access attempts)
Tracking de intentos de acceso no autorizado
Logging de generación y validación de tokens

Monitoreo Operacional

Status de servicios externos (printer, SMTP)
Métricas de rendimiento y tiempo de respuesta
Tracking de errores con stack traces contextuales

Cumplimiento y Auditoría

Trazabilidad completa de acciones de usuario
Logs de transacciones de pedidos y pagos
Registro de accesos administrativos

4. Estructura de Archivos de Log

logs/
├── app.log              # Log principal de la aplicación
├── order.log            # Eventos de pedidos
├── user.log             # Eventos de usuarios
├── security.log         # Eventos de seguridad
├── api.log              # Eventos de API
├── database.log         # Eventos de base de datos
├── email.log            # Eventos de email
├── print.log            # Eventos de impresión
├── chat.log             # Eventos de chat/LLM
├── system.log           # Eventos del sistema
├── orders.csv           # Log legacy de pedidos (CSV)
└── llm_responses.txt    # Log legacy de respuestas LLM

5. Ejemplo de Log Estructurado

{
  "timestamp": "2025-08-07T10:30:15.123456",
  "category": "ORDER",
  "level": "INFO",
  "message": "Order completed successfully for table 5",
  "user_id": 123,
  "user_email": "user@example.com",
  "data": {
    "table": 5,
    "customer_id": 123,
    "total_amount": 25000,
    "items": [
      {"name": "Cerveza", "quantity": 2, "price": 5000},
      {"name": "Hamburguesa", "quantity": 1, "price": 15000}
    ],
    "sale_id": 456,
    "new_reward_progress": 85,
    "beers_for_promo": 2
  }
}

6. Compatibilidad con Sistema Anterior

✅ Funciones legacy mantenidas para evitar breaking changes
✅ Archivos CSV y TXT se siguen generando para compatibilidad
✅ Migración gradual sin afectar funcionalidad existente

7. Recomendaciones de Uso

Para Desarrollo

Utilizar nivel DEBUG para troubleshooting detallado
Revisar logs/security.log para eventos de autenticación
Monitorear logs/print.log para problemas de impresión

Para Producción

Configurar nivel INFO o WARNING para logs principales
Implementar rotación de logs para gestión de espacio
Configurar alertas para eventos ERROR y CRITICAL
Monitorear logs/system.log para salud de la aplicación

Para Análisis

Procesar logs JSON con herramientas como jq, ELK stack, o Datadog
Correlacionar eventos por user_id para tracking de usuario
Analizar métricas de performance y errores

8. Próximos Pasos Recomendados

Implementar rotación de logs con logrotate o similar
Configurar alertas para eventos críticos
Integrar con sistema de monitoreo (Grafana, Datadog, etc.)
Implementar dashboards para métricas operacionales
Configurar backup de logs importantes
Documentar alertas y procedimientos de respuesta

Comandos Útiles para Análisis de Logs

# Ver logs de errores en tiempo real
tail -f logs/app.log | grep ERROR

# Analizar logs de seguridad
jq '. | select(.category == "SECURITY")' logs/security.log

# Contar pedidos por usuario
jq '. | select(.category == "ORDER") | .user_email' logs/order.log | sort | uniq -c

# Ver errores de los últimos 30 minutos
jq '. | select(.level == "ERROR" and (.timestamp | fromdateiso8601) > (now - 1800))' logs/app.log

Esta implementación proporciona una base sólida para el monitoreo, troubleshooting y análisis operacional del sistema Pedidos Express.

LOGGING_IMPROVEMENTS.md 7.0 KB Historik Rå