logger-tracker 1.0.11

Libreria estandar para manejo de logs estandar

Logger Tracker

Una librería de logging estandarizada para Python que proporciona trazabilidad mediante UUIDs únicos por hilo de ejecución, con soporte para salida enriquecida en consola.

Descripción

Logger Tracker es un módulo de logging diseñado para entornos concurrentes y aplicaciones web. Proporciona:

• UUIDs únicos por hilo: Cada log incluye un identificador único para trazabilidad en entornos multi-hilo
• Salida enriquecida: Usa Rich para tracebacks y formateo mejorado en consola
• Configuración automática: Se configura al importar el módulo
• Nivel de logging configurable: Soporte para variable de entorno LOG_LEVEL
• API simple: Funciones de logging estandarizadas con acceso directo
• Integración con frameworks: Soporte nativo para Flask/Werkzeug

Instalación

Instala desde PyPI:

pip install logguer-tracker

O desde el código fuente:

git clone https://github.com/tu-usuario/logguer-tracker.git
cd logguer-tracker
pip install -e .

Configuración

Nivel de Logging

El nivel de logging se puede configurar mediante la variable de entorno LOG_LEVEL. Si no se establece, por defecto es DEBUG.

Niveles disponibles: DEBUG, INFO, WARNING, ERROR, CRITICAL

Ejemplos de configuración:

En Linux/macOS:

export LOG_LEVEL=INFO
python tu_aplicacion.py

En Windows (Command Prompt):

set LOG_LEVEL=INFO
python tu_aplicacion.py

En Windows (PowerShell):

$env:LOG_LEVEL = 'INFO'
python tu_aplicacion.py

En un script Python:

import os
os.environ['LOG_LEVEL'] = 'WARNING'
import logger_tracker  # Importar después de configurar la variable

En un archivo .env (usando python-dotenv):

pip install python-dotenv

from dotenv import load_dotenv
load_dotenv()

import logger_tracker

Archivo .env:

LOG_LEVEL=INFO

En Docker:

ENV LOG_LEVEL=WARNING

En docker-compose.yml:

services:
  tu_app:
    environment:
      - LOG_LEVEL=ERROR

Uso Básico

Importación y configuración automática

Simplemente importa el módulo para configurar el logging automáticamente:

import logger_tracker

# El logging ya está configurado con UUIDs y Rich handler

Uso de la API principal

from logger_tracker import get_logger

# Obtener un logger con funciones de logging
logger = get_logger("mi_modulo")

logger["info"]("Mensaje informativo")
logger["debug"]("Mensaje de debug")
logger["warning"]("Mensaje de advertencia")
logger["error"]("Mensaje de error")
logger["critical"]("Mensaje crítico")

Uso de funciones legacy

Para compatibilidad con código existente:

from logger_tracker import logg_info, logg_debug, logg_warning, logg_error, logg_critical

logg_info("Mensaje informativo")
logg_debug("Mensaje de debug")
logg_warning("Mensaje de advertencia")
logg_error("Mensaje de error")
logg_critical("Mensaje crítico")

Características

• Thread-safe: UUIDs únicos por hilo de ejecución
• Trazabilidad: Cada log incluye un UUID para seguimiento
• Salida enriquecida: Tracebacks coloreados y formateados con Rich
• Configuración automática: No requiere configuración manual
• Nivel de logging configurable: Control del nivel mediante variable de entorno LOG_LEVEL
• Integración con Flask: Soporte automático para logging de Werkzeug
• API flexible: Tanto dict-based como funciones directas

API

Funciones principales

• setup_logging(): Configura el sistema de logging (llamado automáticamente al importar)
• get_logger(name: str) -> dict: Devuelve un diccionario con funciones de logging
• get_request_uuid() -> str: Obtiene el UUID único del hilo actual
• set_request_uuid(custom_uuid: str): Establece un UUID personalizado para el hilo actual
• attach_logger_to_werkzeug(): Integra el logging con Flask/Werkzeug

Funciones legacy

• logg_info(message)
• logg_debug(message)
• logg_warning(message)
• logg_error(message)
• logg_critical(message)

Ejemplos

En una aplicación Flask

from flask import Flask
from logger_tracker import get_logger, attach_logger_to_werkzeug

app = Flask(__name__)

# Configurar logging para Flask
attach_logger_to_werkzeug()

logger = get_logger("flask_app")

@app.route('/')
def hello():
    logger["info"]("Solicitud a la ruta principal")
    return "Hello World!"

if __name__ == '__main__':
    app.run()

En un script multi-hilo

import threading
import time
from logger_tracker import get_logger

def worker(worker_id):
    logger = get_logger(f"worker_{worker_id}")
    logger["info"](f"Trabajador {worker_id} iniciado")
    time.sleep(1)
    logger["info"](f"Trabajador {worker_id} finalizado")

# Crear múltiples hilos
threads = []
for i in range(3):
    t = threading.Thread(target=worker, args=(i,))
    threads.append(t)
    t.start()

for t in threads:
    t.join()

Cada hilo tendrá su propio UUID en los logs, permitiendo trazabilidad completa.

Acceso al UUID para correlacionar datos

El UUID de cada hilo es accesible mediante get_request_uuid(), permitiendo almacenar datos correlacionados:

from logger_tracker import get_logger, get_request_uuid, set_request_uuid

logger = get_logger("app")

# Opción 1: Usar el UUID auto-generado
logger["info"]("Iniciando procesamiento")
transaction_id = get_request_uuid()
# Almacenar datos con este UUID
db.save_transaction(uuid=transaction_id, status="started")

# Opción 2: Usar un UUID personalizado (e.g., de una request HTTP)
request_uuid = "req-12345-abc"
set_request_uuid(request_uuid)
logger["info"]("Procesando request")  # Los logs llevarán "req-12345-abc"
db.save_request_log(uuid=get_request_uuid(), action="processed")

Caso de uso en Flask:

from flask import Flask, request
from logger_tracker import get_logger, set_request_uuid, get_request_uuid

app = Flask(__name__)
logger = get_logger("flask_app")

@app.before_request
def set_uuid():
    # Usar el header X-Request-ID si existe, sino auto-generar
    request_id = request.headers.get('X-Request-ID', None)
    if request_id:
        set_request_uuid(request_id)
    logger["info"](f"Nuevo request: {request.method} {request.path}")

@app.route('/api/process')
def process():
    # El UUID está disponible en toda la request
    correlation_id = get_request_uuid()
    logger["info"](f"Procesando con ID: {correlation_id}")
    
    # Guardar logs correlacionados en BD
    db.save_audit_log(
        correlation_id=correlation_id,
        action="process_api",
        user_id=get_user_id()
    )
    
    return {"id": correlation_id}

Formato de salida

Los logs se muestran en el formato:

[UUID] Mensaje

Ejemplo:

[550e8400-e29b-41d4-a716-446655440000] Aplicación iniciada
[550e8400-e29b-41d4-a716-446655440000] Procesando solicitud
[6ba7b810-9dad-11d1-80b4-00c04fd430c8] Nuevo hilo iniciado

Requisitos

• Python >= 3.13
• rich
• pytest (para tests)

Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.