pedidos-express/LOGGING_IMPROVEMENTS.md

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

1. Implementar rotación de logs con logrotate o similar
2. Configurar alertas para eventos críticos
3. Integrar con sistema de monitoreo (Grafana, Datadog, etc.)
4. Implementar dashboards para métricas operacionales
5. Configurar backup de logs importantes
6. 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.