From f0c5b5f34e03f72e42beb3eb0e583ddf914be5d9 Mon Sep 17 00:00:00 2001 From: tutosrive Date: Sun, 20 Jul 2025 20:44:41 -0500 Subject: [PATCH] Update chromologger docs, by JuManoel --- docs/chromologger/index.html | 477 ++++++++++++++++++++++++++++++----- 1 file changed, 408 insertions(+), 69 deletions(-) diff --git a/docs/chromologger/index.html b/docs/chromologger/index.html index 1e6cb53..7ebcd56 100644 --- a/docs/chromologger/index.html +++ b/docs/chromologger/index.html @@ -11,14 +11,14 @@ - + - + @@ -46,7 +46,7 @@
- + Logo youtube @@ -56,15 +56,15 @@ alt="Autor chromologger - Santiago Rivera Marin">

CHROMOLOGGER

+ href="https://github.com/tutosrive/chromologger/">CHROMOLOGGER Logo del proyecto 'ChromaLog'
- - Sponsor me on GitHub + + Sponsor me on GitHub GitHub License
-

"Chromologger" es un módulo diseñado para facilitar la creación de registros - (logs) en aplicaciones desarrolladas con Python. Proporciona una manera sencilla y - estructurada de documentar eventos, errores y actividades en los programas, - mejorando la capacidad de - monitoreo y - depuración del código. +

"Chromologger" es un módulo avanzado de logging diseñado para facilitar la creación de registros + (logs) profesionales en aplicaciones desarrolladas con Python. Proporciona una solución completa y + fácil de usar para documentar eventos, excepciones, y actividades del sistema, + mejorando significativamente la capacidad de + monitoreo, debugging y + mantenimiento del código. + +

🚀 Características Principales

+ 
Requerimientos:
-- chromolog>=0.2.0
+- chromolog==0.2.5 # Para salida colorizada en consola
 - # pip install chromolog
-- # Esto instalará la versión más reciente (v0.2.4)
+- # pip install chromologger

-

Ejemplo de registro: En una línea

+

📋 Formato de registro detallado

- 
2025-01-06 19:52:08.636560 - Exception: FileNotFoundError - File: c:\Users\srm\Desktop\msqlite\msqlite\__logger.py - ErrorLine: 35 - Messsage: [Errno 2] No such file or directory: './data/log'
+  
[INFO][2025-01-06 19:52:08.636560] - Aplicación iniciada correctamente
+[ERROR][2025-01-06 19:52:08.636560] - Exception: FileNotFoundError - File: c:\Users\srm\Desktop\app\main.py - ErrorLine: 35 - Message: [Errno 2] No such file or directory: './data/config.json'
 

-  
Para empezar a usar, iniciaría con una instancia de la clase Logger, la cual toma como
-    argumentos el siguiente parámetro:

-  
+
+  
🔧 Instalación y Uso Rápido

+  
+  
Instalación

+  
# Instalar chromologger
+pip install chromologger
+
+# Instalar dependencia (si no se instala automáticamente)
+pip install chromolog==0.2.5
+

+
+  
Uso Básico

+  
from chromologger import Logger
+
+# Crear logger (archivo por defecto: log.log en directorio del script)
+logger = Logger()
+
+# Registrar mensaje informativo
+logger.log('Aplicación iniciada correctamente')
+
+# Registrar excepción
+try:
+    resultado = 10 / 0
+except Exception as e:
+    logger.log_e(e)
+
+# Cerrar logger (liberar recursos)
+logger.close()
+

+
+  
Uso Avanzado con Archivo Personalizado

+  
from chromologger import Logger
+import os
+
+# Crear directorio si no existe
+os.makedirs('./logs', exist_ok=True)
+
+# Logger con archivo personalizado
+app_logger = Logger('./logs/mi_aplicacion.log')
+
+# Registrar diferentes tipos de eventos
+app_logger.log('Sistema iniciado')
+app_logger.log(f'Usuario {"admin"} conectado desde IP 192.168.1.100')
+
+# También acepta otros tipos de datos
+app_logger.log({'evento': 'login', 'usuario': 'admin', 'timestamp': '2025-01-06'})
+app_logger.log(42)  # Números también son válidos
+
+# Siempre cerrar el logger
+app_logger.close()
+

+
+  
📁 Ubicación del archivo: Si usa el nombre por defecto 'log.log', el archivo se creará en el mismo directorio del script que llama al Logger. Para rutas personalizadas, asegúrese de que el directorio exista.

+
   

-    
NOTA: Es necesario que el directorio donde se guardará el archivo esté creado, ÚNICAMENTE el
-      directorio, el archivo se creará dentro de automáticamente...
+    
💡 Tip: El logger detecta automáticamente la ubicación del script que lo llama y crea el archivo de log en ese directorio. No necesita especificar rutas complejas para uso básico.
     

   

-  
# Ejemplo de inicialización
-from chromologger import Logger
 
-# Teniendo creado el directorio "data"
-log = Logger('./data/log.log')
-# Creará un archivo log.log listo para usar...
+  
📚 Documentación de la API

+
+  
Clase Logger

+  
La clase principal que gestiona todos los registros con timestamps automáticos y manejo de excepciones.

+
+  
Constructor

+  
Logger(log_file_name: str = 'log.log')
 

-  
Métodos públicos disponibles:

   
    
-    
  • log: Permite guardar mensajes generales en el registro, es decir, NO
-        ERRORES, mensajes de información ordinaria (general).
+    
  • Parámetros:
       
      
-        
    • Parámetros:
+        
    • log_file_name (str, opcional): Nombre o ruta del archivo de log. 
           
        
-            
      • msg:any: Mensaje que se registrará en el archivo.
        • 
+            
      • Si es 'log.log': Se crea en el directorio del script llamador
        • 
+            
      • Si es otra ruta: Se respeta la ubicación especificada
        • 
           
      
         
      • 
       
    
     
    • 
   

-  
# Mensaje general (no error)
-log.log('Ejecución finalizada sin errores')
+  
🔧 Métodos Públicos Disponibles

+
+  
🗒️ log(msg: any) → None

+  
Registra mensajes informativos generales con nivel INFO y timestamp automático.

+  
    
+    
  • Parámetros:
+      
      
+        
    • msg (any): Mensaje a registrar. Acepta strings, números, diccionarios, listas, etc.
      • 
+      
    
+    
    • 
+    
  • Características:
+      
      
+        
    • Conversión automática a string
      • 
+        
    • Timestamp con precisión de microsegundos
      • 
+        
    • Nivel INFO por defecto
      • 
+        
    • Notificación en consola de la ubicación del archivo
      • 
+      
    
+    
    • 
+  

+
+  
# Diferentes tipos de mensajes
+logger.log('Operación completada exitosamente')
+logger.log(f'Procesados {count} elementos en {time} segundos')
+logger.log({'status': 'success', 'items': 150, 'time': 2.5})
+logger.log(['evento1', 'evento2', 'evento3'])
 

-  
Dentro del archivo de registro (log.log):

-  
2025-01-06 19:52:08.636560 - Ejecución finalizada sin errores
+
+  
📄 Resultado en el archivo de log:

+  
[INFO][2025-01-06 19:52:08.636560] - Operación completada exitosamente
+[INFO][2025-01-06 19:52:09.125430] - Procesados 150 elementos en 2.5 segundos
+[INFO][2025-01-06 19:52:09.332100] - {'status': 'success', 'items': 150, 'time': 2.5}
 

+
+  
⚠️ log_e(e: Exception) → None

+  
Registra excepciones con información detallada de traceback, incluyendo archivo, línea y mensaje completo.

   
    
-    
  • log_e: Permite registrar errores, es un registro más específico )Toma registros Exception(.
+    
  • Parámetros:
       
      
-        
    • Parámetros:
-          
        
-            
      • e:Exception: Únicamente se permiten excepciones, porque dentro del
-              módulo
-              se trabaja con el objeto Exception.
        • 
-          
      
-        
      • 
+        
    • e (Exception): Instancia de Exception o sus subclases (ValueError, FileNotFoundError, etc.)
      • 
+      
    
+    
    • 
+    
  • Información registrada automáticamente:
+      
      
+        
    • Tipo de excepción (ZeroDivisionError, FileNotFoundError, etc.)
      • 
+        
    • Ruta completa del archivo donde ocurrió
      • 
+        
    • Número de línea exacto del error
      • 
+        
    • Mensaje descriptivo de la excepción
      • 
+        
    • Nivel ERROR
      • 
+      
    
+    
    • 
+  

+
+  
# Ejemplo completo de manejo de errores
+try:
+    # Operación que puede fallar
+    with open('archivo_inexistente.txt', 'r') as f:
+        contenido = f.read()
+except FileNotFoundError as e:
+    logger.log_e(e)  # Registra error detallado
+
+try:
+    resultado = 10 / 0
+except ZeroDivisionError as e:
+    logger.log_e(e)
+
+try:
+    lista = [1, 2, 3]
+    elemento = lista[10]  # Índice fuera de rango
+except IndexError as e:
+    logger.log_e(e)
+

+
+  
📄 Resultado en el archivo de log:

+  
[ERROR][2025-01-06 20:21:30.744693] - Exception: FileNotFoundError - File: c:\Users\srm\Desktop\app\main.py - ErrorLine: 15 - Message: [Errno 2] No such file or directory: 'archivo_inexistente.txt'
+[ERROR][2025-01-06 20:21:30.756123] - Exception: ZeroDivisionError - File: c:\Users\srm\Desktop\app\main.py - ErrorLine: 19 - Message: division by zero
+

+
+  
🔒 close() → bool

+  
Cierra el archivo de log y libera los recursos del sistema.

+  
    
+    
  • Retorna:
+      
      
+        
    • True: Archivo cerrado exitosamente
      • 
+        
    • False: No había archivo válido para cerrar
      • 
+      
    
+    
    • 
+    
  • Recomendaciones:
+      
      
+        
    • Siempre llamar al finalizar el uso del logger
      • 
+        
    • Considerar el patrón context manager (with statement)
      • 
+        
    • Verificar el valor de retorno para confirmar el cierre
      • 
       
    
     
    • 
   

 
+  
# Uso recomendado
+logger = Logger('mi_app.log')
+logger.log('Iniciando operaciones')
 
-  
5  # En un bloque try
-6  try:
-7    # Soy literalmente un error
-8    tutosrivegamer
-9  except Exception as e:
-10   log.log_e(e)
+# ... lógica de la aplicación ...
+
+# Cerrar y verificar
+if logger.close():
+    print('Logger cerrado correctamente')
+else:
+    print('Advertencia: No se pudo cerrar el logger')
 

 
-  
Dentro del archivo de registro (log.log):

-  
2025-01-06 20:21:30.744693 - Exception: NameError - File: c:\Users\srm\Desktop\msqlite\test.py - ErrorLine: 8 - Messsage: name 'tutosrivegamer' is not defined
+  
🔥 Ejemplos Avanzados de Uso

+
+  
Aplicación Web con Logging Completo

+  
from chromologger import Logger
+import os
+from datetime import datetime
+
+# Configurar directorio de logs
+log_dir = './logs'
+os.makedirs(log_dir, exist_ok=True)
+
+# Logger para eventos de la aplicación
+app_logger = Logger(f'{log_dir}/app_{datetime.now().strftime("%Y%m%d")}.log')
+
+class WebApplication:
+    def __init__(self):
+        app_logger.log('Inicializando aplicación web')
+    
+    def handle_request(self, user_id, endpoint):
+        try:
+            app_logger.log(f'Usuario {user_id} accediendo a {endpoint}')
+            
+            # Simular procesamiento
+            if endpoint == '/api/data':
+                # Simular error ocasional
+                import random
+                if random.random() < 0.1:  # 10% de probabilidad de error
+                    raise ConnectionError('Database connection failed')
+                
+                app_logger.log(f'Datos enviados exitosamente a usuario {user_id}')
+            
+        except Exception as e:
+            app_logger.log_e(e)
+            app_logger.log(f'Error procesando request de usuario {user_id}')
+    
+    def shutdown(self):
+        app_logger.log('Cerrando aplicación web')
+        app_logger.close()
+
+# Uso
+app = WebApplication()
+app.handle_request('user123', '/api/data')
+app.handle_request('user456', '/api/profile')
+app.shutdown()
+

+  
Sistema de Monitoreo con Múltiples Loggers

+  
from chromologger import Logger
+import time
+
+# Diferentes loggers para diferentes propósitos
+access_logger = Logger('./logs/access.log')
+error_logger = Logger('./logs/errors.log')
+performance_logger = Logger('./logs/performance.log')
+
+def monitor_system():
+    start_time = time.time()
+    
+    try:
+        access_logger.log('Sistema de monitoreo iniciado')
+        
+        # Simular trabajo
+        time.sleep(2)
+        
+        # Registrar rendimiento
+        elapsed = time.time() - start_time
+        performance_logger.log(f'Operación completada en {elapsed:.2f} segundos')
+        
+        access_logger.log('Monitoreo completado exitosamente')
+        
+    except Exception as e:
+        error_logger.log_e(e)
+    
+    finally:
+        # Cerrar todos los loggers
+        access_logger.close()
+        error_logger.close()
+        performance_logger.close()
+
+monitor_system()
+

+
+  
⚙️ Características Técnicas

+
+  
Formato de Timestamp

+  
Los timestamps incluyen precisión hasta microsegundos para máxima precisión en el debugging:

+  
YYYY-MM-DD HH:MM:SS.microseconds
+2025-01-06 20:21:30.744693
 

-  
Métodos privados 🔏

+
+  
Niveles de Log Soportados

   
    
-    
  • __write: Escribe los mensages en el archivo cargado
    • 
-    
  • __date: Obtiene la fecha actual
    • 
-    
  • __log: Toma registro de errores internos, guarda los registros en el archivo
-      "./log.log" (En el directorio raíz del módulo)
    • 
+    
  • [INFO] - Mensajes informativos generales
    • 
+    
  • [ERROR] - Excepciones y errores del sistema
    • 
+    
  • � Futuros niveles: WARNING, DEBUG, CRITICAL
    • 
   

-  
# Solo de uso interno
+
+  
Gestión Inteligente de Rutas

+  
    
+    
  • Detección automática: El logger detecta el directorio del script llamador
    • 
+    
  • Rutas relativas: Soporte completo para rutas como ./logs/app.log
    • 
+    
  • Rutas absolutas: Compatible con rutas completas del sistema
    • 
+    
  • Creación automática: El archivo se crea si no existe
    • 
+  

+
+  
🔧 Solución de Problemas

+
+  
Errores Comunes

+
+  
1. FileNotFoundError al crear el logger

+  
# ❌ Error: directorio no existe
+logger = Logger('./logs_inexistentes/app.log')
+
+# ✅ Solución: crear directorio primero
+import os
+os.makedirs('./logs', exist_ok=True)
+logger = Logger('./logs/app.log')
+

+
+  
2. Logger no escribe al archivo

+  
# Verificar que el logger se inicializó correctamente
+logger = Logger()
+if hasattr(logger, 'file') and logger.file != -1:
+    logger.log('Logger funcionando correctamente')
+else:
+    print('Error: Logger no se inicializó correctamente')
+

+
+  
3. Archivos de log no se cierran

+  
# Siempre usar try/finally o context managers
+logger = None
+try:
+    logger = Logger('app.log')
+    logger.log('Trabajando...')
+finally:
+    if logger:
+        logger.close()
+

+
+  
Logging Interno del Módulo

+  
Chromologger mantiene su propio sistema de logging interno para diagnosticar problemas del módulo. Si encuentra errores, revise:

+  
# Ubicación del log interno
+./src/chromologger/log.log
+
+# También se muestran mensajes en consola con colores
+

+
+  
✨ Mejores Prácticas

+
+  
1. Organización de Logs

+  
# Organizar logs por fecha
+from datetime import datetime
+
+date_str = datetime.now().strftime("%Y%m%d")
+logger = Logger(f'./logs/app_{date_str}.log')
+
+# O por funcionalidad
+auth_logger = Logger('./logs/authentication.log')
+db_logger = Logger('./logs/database.log')
+api_logger = Logger('./logs/api_requests.log')
 

-  
+