sincpro-log 1.0.0__tar.gz

sincpro_log-1.0.0/LICENSE.md

@@ -0,0 +1,61 @@
+Copyright (c) 2024 Sincpro S.R.L
+LICENCIA EMPRESARIAL DE USO DE SOFTWARE
+
+Términos y Condiciones
+
+1. Definiciones
+   
+   1.1. "Software" hace referencia a cualquier programa de computadora y su documentación relacionada desarrollados
+   por Sincpro Developers.
+
+   1.2. "Cliente" se refiere a cualquier entidad o individuo que obtiene una licencia para utilizar el Software bajo
+   los términos y condiciones establecidos en este documento.
+
+2. Concesión de Licencia
+   Sincpro Developers otorga al Cliente una licencia no exclusiva, no transferible y limitada para utilizar el Software
+   de acuerdo con los términos y condiciones establecidos en este documento.
+
+3. Propiedad y Derechos de Autor
+
+   3.1. El Software es propiedad exclusiva de Sincpro Developers y está protegido por leyes de derechos de autor y otras
+    leyes de propiedad intelectual.
+
+   3.2. El Cliente reconoce y acepta que no adquiere ningún derecho de propiedad sobre el Software, excepto los derechos
+   limitados otorgados por esta licencia.
+
+4. Alcance de Uso
+
+   4.1. El Cliente está autorizado a utilizar el Software únicamente para los fines y en la forma especificados en la
+   documentación proporcionada por Sincpro Developers.
+
+   4.2. El uso del Software por parte del Cliente está limitado al número de usuarios y ubicaciones geográficas
+   especificados en la documentación.
+
+5. Restricciones
+
+   5.1. Queda estrictamente prohibido al Cliente: (a) copiar, modificar o crear trabajos derivados del Software;
+   (b) sublicenciar, transferir o distribuir el Software a terceros;
+   (c) utilizar el Software de manera que infrinja las leyes aplicables.
+
+6. Sanciones y Consecuencias
+
+   6.1. El uso no autorizado o en violación de los términos de esta licencia puede resultar en acciones legales y
+   sanciones que Sincpro Developers considera necesarias y apropiadas.
+
+7. Protección Legal
+
+   7.1. Estos términos y condiciones están sujetos a las leyes y regulaciones aplicables. El Cliente acepta someterse
+   a la jurisdicción de los tribunales competentes en caso de disputa relacionada con el uso del Software.
+
+8. Cambios y Actualizaciones
+
+   8.1. Sincpro Developers se reserva el derecho de actualizar o modificar estos términos y condiciones en cualquier
+    momento. Dichos cambios serán efectivos a partir de la fecha de notificación al Cliente.
+
+9. Aceptación
+
+   9.1. Al utilizar el Software, el Cliente acepta y se compromete a cumplir con los términos y condiciones establecidos
+   en este documento.
+
+Para cualquier consulta sobre esta licencia o para solicitar permisos adicionales, comuníquese con Sincpro Developers
+en Bolivia, Cochabamba Mayor rocha #161 y ayacucho o informacion@sincpro.com.bo

sincpro_log-1.0.0/PKG-INFO

@@ -0,0 +1,342 @@
+Metadata-Version: 2.3
+Name: sincpro-log
+Version: 1.0.0
+Summary: A logging module for sincpro applications
+License: LICENSE.md
+Author: Andres Gutierrez
+Author-email: andru1236@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: structlog (>=25.4.0,<26.0.0)
+Description-Content-Type: text/markdown
+
+# SincPro Logger
+
+Biblioteca de logging estructurado para aplicaciones SincPro, construida sobre `structlog` con capacidades avanzadas de registro.
+
+## Características principales
+
+- **Logging estructurado**: formatos JSON (producción) y consola con colores (desarrollo)
+- **Integración con Grafana Loki**: envío de logs para centralización y alertas
+- **Contexto enriquecido**: bind/unbind de datos contextuales
+- **Tipado seguro**: interfaces completamente tipadas para Python 3.12+
+
+## 🚀 Optimizado para Kubernetes y Observabilidad
+
+**Sincpro Logger** está especialmente diseñado para aplicaciones containerizadas y sistemas de observabilidad modernos:
+
+### Integración con Kubernetes
+- **Formato JSON nativo**: Compatible directamente con FluentD, FluentBit y otros log aggregators
+- **Metadatos estructurados**: Facilita la correlación de logs entre pods y servicios
+- **Context propagation**: Soporte nativo para trace_id y request_id en microservicios
+- **Resource labeling**: Etiquetas automáticas para namespace, pod, container
+
+### Sistemas de Observabilidad
+- **Grafana Loki**: Integración directa con push automático y etiquetas dinámicas
+- **OpenTelemetry ready**: Compatible con estándares de trazabilidad distribuida
+- **Structured queries**: Logs optimizados para consultas en Grafana, Kibana y DataDog
+- **Alerting support**: Campos estructurados para configuración de alertas automáticas
+
+### Beneficios en Contenedores
+```python
+# Configuración típica para Kubernetes
+logger = create_logger(
+    "payment-service",
+    namespace="production",
+    pod_name=os.getenv("HOSTNAME"),
+    version=os.getenv("APP_VERSION", "unknown")
+)
+
+# Context tracing automático para microservicios
+with logger.tracing() as traced_logger:
+    traced_logger.info("Processing payment", amount=100.50)
+    # trace_id y request_id se propagan automáticamente
+```
+
+## Instalación rápida
+
+```bash
+pip install sincpro-logger
+# o con Poetry
+poetry add sincpro-logger
+```
+
+## 📋 Configuración inicial
+
+**⚠️ IMPORTANTE**: La configuración del logger debe ser lo **primero** que se haga en tu aplicación, antes de cualquier import o uso de logging.
+
+### 1. Configuración global del sistema de logging
+
+```python
+from sincpro_log import configure_global_logging
+
+# Para desarrollo (formato legible con colores)
+configure_global_logging(level="DEBUG")
+
+# Para producción (formato JSON estructurado)
+configure_global_logging(level="INFO")
+```
+
+### 2. Configuración típica en main.py o app.py
+
+```python
+# main.py
+import os
+from sincpro_log import configure_global_logging, create_logger
+
+
+def setup_logging():
+    """Configurar logging según el entorno."""
+    # Detectar entorno
+    environment = os.getenv("ENVIRONMENT", "development")
+
+    if environment == "production":
+        configure_global_logging(level="INFO")  # JSON estructurado
+    else:
+        configure_global_logging(level="DEBUG")  # Formato legible
+
+    return environment
+
+
+def main():
+    # PASO 1: Configurar logging ANTES que todo
+    env = setup_logging()
+
+    # PASO 2: Crear logger de la aplicación
+    logger = create_logger(
+        "mi-aplicacion",
+        environment=env,
+        version=os.getenv("APP_VERSION", "unknown")
+    )
+
+    logger.info("Aplicación iniciada", environment=env)
+
+    # Resto de la aplicación...
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## 🏗️ Creación y uso de loggers
+
+### Creación básica
+
+```python
+from sincpro_log import create_logger
+
+# Logger básico
+logger = create_logger("mi-app")
+
+# Logger con contexto inicial
+logger = create_logger(
+    "payment-service",
+    environment="production",
+    version="1.2.3",
+    component="api"
+)
+```
+
+### Añadir y remover contexto persistente
+
+```python
+# Añadir campos que persisten en todos los logs
+logger.bind(user_id="12345", session_id="abc-def")
+logger.info("Usuario autenticado")  # Incluirá user_id y session_id
+
+# Remover campos específicos
+logger.unbind("session_id")
+logger.info("Sesión terminada")  # Solo incluirá user_id
+
+# Contexto temporal (solo dentro del bloque)
+with logger.context(operation="payment", amount=100.50) as temp_logger:
+    temp_logger.info("Iniciando pago")  # Incluye operation y amount
+    temp_logger.error("Error en pago")  # Incluye operation y amount
+
+logger.info("Pago finalizado")  # NO incluye operation ni amount
+```
+
+### Niveles de logging disponibles
+
+```python
+logger.debug("Información de depuración")
+logger.info("Información general")
+logger.warning("Advertencia")
+logger.error("Error controlado")
+logger.critical("Error crítico")
+logger.exception("Error con stack trace")  # Usar dentro de except
+```
+
+## 🔍 Trazabilidad: trace_id y request_id
+
+### ¿Qué son y cuándo usarlos?
+
+- **`trace_id`**: Identificador único que sigue una operación completa a través de múltiples servicios
+- **`request_id`**: Identificador único para una petición HTTP específica
+
+**Casos de uso típicos:**
+- **Microservicios**: Rastrear una operación que pasa por varios servicios
+- **APIs REST**: Asociar todos los logs de una petición HTTP
+- **Procesamiento asíncrono**: Seguir trabajos en background
+- **Debugging**: Correlacionar logs relacionados en sistemas distribuidos
+
+### Uso con IDs existentes (recibidos)
+
+```python
+# Escenario: Recibir trace_id de otro servicio
+incoming_trace_id = request.headers.get("X-Trace-ID")
+incoming_request_id = request.headers.get("X-Request-ID")
+
+# Usar IDs existentes
+with logger.tracing(trace_id=incoming_trace_id, request_id=incoming_request_id) as traced_logger:
+    traced_logger.info("Procesando petición de otro servicio")
+    # Todos los logs tendrán estos IDs específicos
+```
+
+### Uso con IDs auto-generados (cuando no existen)
+
+```python
+# Generar automáticamente si no se proporcionan
+with logger.tracing() as traced_logger:
+    traced_logger.info("Nueva operación iniciada")
+    # Se generan automáticamente trace_id y request_id únicos
+    
+    # Obtener los IDs generados para enviar a otros servicios
+    current_trace = traced_logger.get_current_trace_id()
+    current_request = traced_logger.get_current_request_id()
+    
+    # Propagar a servicios downstream
+    headers = traced_logger.get_traceability_headers()
+    # headers = {"X-Trace-ID": "...", "X-Request-ID": "..."}
+```
+
+### Context managers individuales
+
+```python
+# Solo trace_id
+with logger.trace_id("existing-trace-123") as traced_logger:
+    traced_logger.info("Operación con trace específico")
+
+# Solo request_id
+with logger.request_id() as request_logger:  # Auto-genera si no se especifica
+    request_logger.info("Petición con ID único")
+
+# Combinados
+with logger.trace_id("trace-abc") as tl:
+    with tl.request_id("request-xyz") as full_logger:
+        full_logger.info("Con ambos IDs específicos")
+```
+
+### Integración con frameworks web
+
+```python
+# Flask
+from flask import request
+
+@app.before_request
+def setup_request_logging():
+    trace_id = request.headers.get("X-Trace-ID")
+    request_id = request.headers.get("X-Request-ID")
+    
+    g.logger = logger.tracing(trace_id=trace_id, request_id=request_id).__enter__()
+
+# FastAPI
+from fastapi import Request
+
+@app.middleware("http")
+async def logging_middleware(request: Request, call_next):
+    trace_id = request.headers.get("X-Trace-ID")
+    request_id = request.headers.get("X-Request-ID")
+    
+    with logger.tracing(trace_id=trace_id, request_id=request_id) as request_logger:
+        request.state.logger = request_logger
+        response = await call_next(request)
+        return response
+```
+
+### Propagar metadatos entre servicios
+
+```python
+# Servicio A: Enviar petición a Servicio B
+with logger.tracing() as traced_logger:
+    traced_logger.info("Llamando al servicio de pagos")
+    
+    # Obtener headers para propagación
+    headers = traced_logger.get_traceability_headers()
+    
+    # Hacer petición HTTP con headers de trazabilidad
+    response = requests.post(
+        "https://payment-service/process",
+        json={"amount": 100.50},
+        headers=headers  # {"X-Trace-ID": "...", "X-Request-ID": "..."}
+    )
+    
+    traced_logger.info("Respuesta del servicio de pagos", status=response.status_code)
+
+# Servicio B: Recibir y usar los IDs
+def process_payment(request):
+    # Extraer IDs del request
+    trace_id = request.headers.get("X-Trace-ID")
+    request_id = request.headers.get("X-Request-ID")
+    
+    # Usar los IDs recibidos
+    with logger.tracing(trace_id=trace_id, request_id=request_id) as payment_logger:
+        payment_logger.info("Procesando pago recibido")
+        # Todos los logs mantendrán la trazabilidad original
+```
+
+### Ejemplo completo: E-commerce checkout
+
+```python
+def checkout_process(user_id: str, cart_items: list):
+    """Proceso completo de checkout con trazabilidad."""
+    
+    # Iniciar nueva transacción
+    with logger.tracing() as checkout_logger:
+        checkout_logger.info(
+            "Iniciando checkout",
+            user_id=user_id,
+            items_count=len(cart_items)
+        )
+        
+        try:
+            # Validar inventario
+            with checkout_logger.context(step="inventory_check") as step_logger:
+                step_logger.info("Verificando inventario")
+                # validate_inventory(cart_items)
+                step_logger.info("Inventario validado")
+            
+            # Procesar pago (enviar a servicio externo)
+            payment_headers = checkout_logger.get_traceability_headers()
+            with checkout_logger.context(step="payment") as payment_logger:
+                payment_logger.info("Procesando pago")
+                # payment_response = call_payment_service(headers=payment_headers)
+                payment_logger.info("Pago procesado exitosamente")
+            
+            # Actualizar inventario
+            with checkout_logger.context(step="inventory_update") as inv_logger:
+                inv_logger.info("Actualizando inventario")
+                # update_inventory(cart_items)
+                inv_logger.info("Inventario actualizado")
+            
+            checkout_logger.info("Checkout completado exitosamente")
+            
+        except Exception as e:
+            checkout_logger.exception("Error en checkout", error_step="unknown")
+            raise
+```
+
+## Arquitectura
+
+Diseñado con Clean Architecture (Domain-Driven Design):
+- **Dominio**: Modelos y entidades centrales
+- **Casos de uso**: Lógica de negocio para logs
+- **Infraestructura**: Integración con servicios externos
+
+## Licencia
+
+Copyright © 2024 Sincpro S.R.L. Todos los derechos reservados.
+

sincpro_log-1.0.0/README.md

@@ -0,0 +1,326 @@
+# SincPro Logger
+
+Biblioteca de logging estructurado para aplicaciones SincPro, construida sobre `structlog` con capacidades avanzadas de registro.
+
+## Características principales
+
+- **Logging estructurado**: formatos JSON (producción) y consola con colores (desarrollo)
+- **Integración con Grafana Loki**: envío de logs para centralización y alertas
+- **Contexto enriquecido**: bind/unbind de datos contextuales
+- **Tipado seguro**: interfaces completamente tipadas para Python 3.12+
+
+## 🚀 Optimizado para Kubernetes y Observabilidad
+
+**Sincpro Logger** está especialmente diseñado para aplicaciones containerizadas y sistemas de observabilidad modernos:
+
+### Integración con Kubernetes
+- **Formato JSON nativo**: Compatible directamente con FluentD, FluentBit y otros log aggregators
+- **Metadatos estructurados**: Facilita la correlación de logs entre pods y servicios
+- **Context propagation**: Soporte nativo para trace_id y request_id en microservicios
+- **Resource labeling**: Etiquetas automáticas para namespace, pod, container
+
+### Sistemas de Observabilidad
+- **Grafana Loki**: Integración directa con push automático y etiquetas dinámicas
+- **OpenTelemetry ready**: Compatible con estándares de trazabilidad distribuida
+- **Structured queries**: Logs optimizados para consultas en Grafana, Kibana y DataDog
+- **Alerting support**: Campos estructurados para configuración de alertas automáticas
+
+### Beneficios en Contenedores
+```python
+# Configuración típica para Kubernetes
+logger = create_logger(
+    "payment-service",
+    namespace="production",
+    pod_name=os.getenv("HOSTNAME"),
+    version=os.getenv("APP_VERSION", "unknown")
+)
+
+# Context tracing automático para microservicios
+with logger.tracing() as traced_logger:
+    traced_logger.info("Processing payment", amount=100.50)
+    # trace_id y request_id se propagan automáticamente
+```
+
+## Instalación rápida
+
+```bash
+pip install sincpro-logger
+# o con Poetry
+poetry add sincpro-logger
+```
+
+## 📋 Configuración inicial
+
+**⚠️ IMPORTANTE**: La configuración del logger debe ser lo **primero** que se haga en tu aplicación, antes de cualquier import o uso de logging.
+
+### 1. Configuración global del sistema de logging
+
+```python
+from sincpro_log import configure_global_logging
+
+# Para desarrollo (formato legible con colores)
+configure_global_logging(level="DEBUG")
+
+# Para producción (formato JSON estructurado)
+configure_global_logging(level="INFO")
+```
+
+### 2. Configuración típica en main.py o app.py
+
+```python
+# main.py
+import os
+from sincpro_log import configure_global_logging, create_logger
+
+
+def setup_logging():
+    """Configurar logging según el entorno."""
+    # Detectar entorno
+    environment = os.getenv("ENVIRONMENT", "development")
+
+    if environment == "production":
+        configure_global_logging(level="INFO")  # JSON estructurado
+    else:
+        configure_global_logging(level="DEBUG")  # Formato legible
+
+    return environment
+
+
+def main():
+    # PASO 1: Configurar logging ANTES que todo
+    env = setup_logging()
+
+    # PASO 2: Crear logger de la aplicación
+    logger = create_logger(
+        "mi-aplicacion",
+        environment=env,
+        version=os.getenv("APP_VERSION", "unknown")
+    )
+
+    logger.info("Aplicación iniciada", environment=env)
+
+    # Resto de la aplicación...
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## 🏗️ Creación y uso de loggers
+
+### Creación básica
+
+```python
+from sincpro_log import create_logger
+
+# Logger básico
+logger = create_logger("mi-app")
+
+# Logger con contexto inicial
+logger = create_logger(
+    "payment-service",
+    environment="production",
+    version="1.2.3",
+    component="api"
+)
+```
+
+### Añadir y remover contexto persistente
+
+```python
+# Añadir campos que persisten en todos los logs
+logger.bind(user_id="12345", session_id="abc-def")
+logger.info("Usuario autenticado")  # Incluirá user_id y session_id
+
+# Remover campos específicos
+logger.unbind("session_id")
+logger.info("Sesión terminada")  # Solo incluirá user_id
+
+# Contexto temporal (solo dentro del bloque)
+with logger.context(operation="payment", amount=100.50) as temp_logger:
+    temp_logger.info("Iniciando pago")  # Incluye operation y amount
+    temp_logger.error("Error en pago")  # Incluye operation y amount
+
+logger.info("Pago finalizado")  # NO incluye operation ni amount
+```
+
+### Niveles de logging disponibles
+
+```python
+logger.debug("Información de depuración")
+logger.info("Información general")
+logger.warning("Advertencia")
+logger.error("Error controlado")
+logger.critical("Error crítico")
+logger.exception("Error con stack trace")  # Usar dentro de except
+```
+
+## 🔍 Trazabilidad: trace_id y request_id
+
+### ¿Qué son y cuándo usarlos?
+
+- **`trace_id`**: Identificador único que sigue una operación completa a través de múltiples servicios
+- **`request_id`**: Identificador único para una petición HTTP específica
+
+**Casos de uso típicos:**
+- **Microservicios**: Rastrear una operación que pasa por varios servicios
+- **APIs REST**: Asociar todos los logs de una petición HTTP
+- **Procesamiento asíncrono**: Seguir trabajos en background
+- **Debugging**: Correlacionar logs relacionados en sistemas distribuidos
+
+### Uso con IDs existentes (recibidos)
+
+```python
+# Escenario: Recibir trace_id de otro servicio
+incoming_trace_id = request.headers.get("X-Trace-ID")
+incoming_request_id = request.headers.get("X-Request-ID")
+
+# Usar IDs existentes
+with logger.tracing(trace_id=incoming_trace_id, request_id=incoming_request_id) as traced_logger:
+    traced_logger.info("Procesando petición de otro servicio")
+    # Todos los logs tendrán estos IDs específicos
+```
+
+### Uso con IDs auto-generados (cuando no existen)
+
+```python
+# Generar automáticamente si no se proporcionan
+with logger.tracing() as traced_logger:
+    traced_logger.info("Nueva operación iniciada")
+    # Se generan automáticamente trace_id y request_id únicos
+    
+    # Obtener los IDs generados para enviar a otros servicios
+    current_trace = traced_logger.get_current_trace_id()
+    current_request = traced_logger.get_current_request_id()
+    
+    # Propagar a servicios downstream
+    headers = traced_logger.get_traceability_headers()
+    # headers = {"X-Trace-ID": "...", "X-Request-ID": "..."}
+```
+
+### Context managers individuales
+
+```python
+# Solo trace_id
+with logger.trace_id("existing-trace-123") as traced_logger:
+    traced_logger.info("Operación con trace específico")
+
+# Solo request_id
+with logger.request_id() as request_logger:  # Auto-genera si no se especifica
+    request_logger.info("Petición con ID único")
+
+# Combinados
+with logger.trace_id("trace-abc") as tl:
+    with tl.request_id("request-xyz") as full_logger:
+        full_logger.info("Con ambos IDs específicos")
+```
+
+### Integración con frameworks web
+
+```python
+# Flask
+from flask import request
+
+@app.before_request
+def setup_request_logging():
+    trace_id = request.headers.get("X-Trace-ID")
+    request_id = request.headers.get("X-Request-ID")
+    
+    g.logger = logger.tracing(trace_id=trace_id, request_id=request_id).__enter__()
+
+# FastAPI
+from fastapi import Request
+
+@app.middleware("http")
+async def logging_middleware(request: Request, call_next):
+    trace_id = request.headers.get("X-Trace-ID")
+    request_id = request.headers.get("X-Request-ID")
+    
+    with logger.tracing(trace_id=trace_id, request_id=request_id) as request_logger:
+        request.state.logger = request_logger
+        response = await call_next(request)
+        return response
+```
+
+### Propagar metadatos entre servicios
+
+```python
+# Servicio A: Enviar petición a Servicio B
+with logger.tracing() as traced_logger:
+    traced_logger.info("Llamando al servicio de pagos")
+    
+    # Obtener headers para propagación
+    headers = traced_logger.get_traceability_headers()
+    
+    # Hacer petición HTTP con headers de trazabilidad
+    response = requests.post(
+        "https://payment-service/process",
+        json={"amount": 100.50},
+        headers=headers  # {"X-Trace-ID": "...", "X-Request-ID": "..."}
+    )
+    
+    traced_logger.info("Respuesta del servicio de pagos", status=response.status_code)
+
+# Servicio B: Recibir y usar los IDs
+def process_payment(request):
+    # Extraer IDs del request
+    trace_id = request.headers.get("X-Trace-ID")
+    request_id = request.headers.get("X-Request-ID")
+    
+    # Usar los IDs recibidos
+    with logger.tracing(trace_id=trace_id, request_id=request_id) as payment_logger:
+        payment_logger.info("Procesando pago recibido")
+        # Todos los logs mantendrán la trazabilidad original
+```
+
+### Ejemplo completo: E-commerce checkout
+
+```python
+def checkout_process(user_id: str, cart_items: list):
+    """Proceso completo de checkout con trazabilidad."""
+    
+    # Iniciar nueva transacción
+    with logger.tracing() as checkout_logger:
+        checkout_logger.info(
+            "Iniciando checkout",
+            user_id=user_id,
+            items_count=len(cart_items)
+        )
+        
+        try:
+            # Validar inventario
+            with checkout_logger.context(step="inventory_check") as step_logger:
+                step_logger.info("Verificando inventario")
+                # validate_inventory(cart_items)
+                step_logger.info("Inventario validado")
+            
+            # Procesar pago (enviar a servicio externo)
+            payment_headers = checkout_logger.get_traceability_headers()
+            with checkout_logger.context(step="payment") as payment_logger:
+                payment_logger.info("Procesando pago")
+                # payment_response = call_payment_service(headers=payment_headers)
+                payment_logger.info("Pago procesado exitosamente")
+            
+            # Actualizar inventario
+            with checkout_logger.context(step="inventory_update") as inv_logger:
+                inv_logger.info("Actualizando inventario")
+                # update_inventory(cart_items)
+                inv_logger.info("Inventario actualizado")
+            
+            checkout_logger.info("Checkout completado exitosamente")
+            
+        except Exception as e:
+            checkout_logger.exception("Error en checkout", error_step="unknown")
+            raise
+```
+
+## Arquitectura
+
+Diseñado con Clean Architecture (Domain-Driven Design):
+- **Dominio**: Modelos y entidades centrales
+- **Casos de uso**: Lógica de negocio para logs
+- **Infraestructura**: Integración con servicios externos
+
+## Licencia
+
+Copyright © 2024 Sincpro S.R.L. Todos los derechos reservados.

sincpro_log-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "sincpro-log"
+version = "1.0.0"
+description = "A logging module for sincpro applications"
+authors = ["Andres Gutierrez <andru1236@gmail.com>"]
+readme = "README.md"
+license = "LICENSE.md"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+structlog = "^25.4.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.1"
+black = "^25.1.0"
+jupyterlab = "^4.4.0"
+pyright = "^1.1.403"
+autoflake = "^2.3.1"
+isort = "^6.0.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]

sincpro_log-1.0.0/sincpro_log/__init__.py

@@ -0,0 +1,3 @@
+"""sincpro_logger: A logging library for sending logs to Loki."""
+
+from .logger import configure_global_logging, create_logger

sincpro_log-1.0.0/sincpro_log/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain layer for sincpro_logger."""

sincpro_log-1.0.0/sincpro_log/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure components for sincpro_logger."""

sincpro_log-1.0.0/sincpro_log/logger.py

@@ -0,0 +1,217 @@
+"""
+Clean structured logging library with direct kwargs support.
+
+Minimal and non-invasive core:
+- Does not modify root logger handlers (third-party loggers remain intact).
+- ``bind`` / ``unbind``.
+- Declarative context managers:
+  - ``logger.context(**fields)``
+  - ``logger.trace_id(trace_id: str | None = None)``
+  - ``logger.request_id(request_id: str | None = None)``
+  - ``logger.tracing(trace_id: str | None = None, request_id: str | None = None)``
+- Error tracebacks normalized to the ``traceback`` field in JSON output.
+- Context priority: per-log kwargs > temporary context > persistent fields.
+"""
+
+import logging
+from contextlib import contextmanager
+from functools import partial
+from typing import Any, Callable, Dict, Generator, Literal, Optional
+from uuid import uuid4
+
+import structlog
+
+LogMethod = Callable[..., None]
+
+
+class LoggerProxy:
+    """Proxy logger"""
+
+    __slots__ = ("_name", "_logger_fields", "_temporal_fields")
+
+    def __init__(self, app_name: str, **extra_fields: Any) -> None:
+        self._name = app_name
+        self._logger_fields: Dict[str, Any] = {"app_name": app_name, **extra_fields}
+        self._temporal_fields: Dict[str, Any] = dict()
+
+    def bind(self, **fields: Any) -> "LoggerProxy":
+        self._logger_fields.update(fields)
+        return self
+
+    def unbind(self, field: str) -> "LoggerProxy":
+        self._logger_fields.pop(field, None)
+        return self
+
+    @property
+    def logger_fields(self) -> Dict[str, Any]:
+        """Return the persistent fields attached to the logger."""
+        return {**self._logger_fields, **self._temporal_fields}
+
+    @property
+    def debug(self) -> Callable[..., None]:
+        return partial(structlog.get_logger(self._name).bind(**self.logger_fields).debug)
+
+    @property
+    def info(self) -> Callable[..., None]:
+        return partial(structlog.get_logger(self._name).bind(**self.logger_fields).info)
+
+    @property
+    def warning(self) -> Callable[..., None]:
+        return partial(structlog.get_logger(self._name).bind(**self.logger_fields).warning)
+
+    @property
+    def error(self) -> Callable[..., None]:
+        return partial(structlog.get_logger(self._name).bind(**self.logger_fields).error)
+
+    @property
+    def exception(self) -> Callable[..., None]:
+        return partial(structlog.get_logger(self._name).bind(**self.logger_fields).exception)
+
+    @property
+    def critical(self) -> Callable[..., None]:
+        return partial(structlog.get_logger(self._name).bind(**self.logger_fields).critical)
+
+    @contextmanager
+    def context(self, **extra_fields: Any) -> Generator["LoggerProxy", None, None]:
+        """Add temporal fields to the logger context."""
+        old = self._temporal_fields.copy()
+        try:
+            self._temporal_fields.update(extra_fields)
+            yield self
+        finally:
+            self._temporal_fields = old
+
+    @contextmanager
+    def trace_id(self, trace_id: Optional[str] = None) -> Generator["LoggerProxy", None, None]:
+        """Provide a ``trace_id`` within the context."""
+        value = trace_id or str(uuid4())
+        with self.context(trace_id=value) as logger:
+            yield logger
+
+    @contextmanager
+    def request_id(self, request_id: Optional[str] = None) -> Generator["LoggerProxy", None, None]:
+        """Provide a ``request_id`` within the context."""
+        value = request_id or str(uuid4())
+        with self.context(request_id=value) as logger:
+            yield logger
+
+    @contextmanager
+    def tracing(
+        self,
+        trace_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> Generator["LoggerProxy", None, None]:
+        """Provide both ``trace_id`` and ``request_id`` within the context.
+
+        Args:
+            trace_id (str | None): Trace identifier. Auto-generated if ``None``.
+            request_id (str | None): Request identifier. Auto-generated if ``None``.
+
+        Yields:
+            LoggerProxy: The same logger instance with both identifiers set.
+        """
+        resolved_trace_id = trace_id or str(uuid4())
+        resolved_request_id = request_id or str(uuid4())
+        with self.context(trace_id=resolved_trace_id, request_id=resolved_request_id) as logger:
+            yield logger
+
+    def get_traceability_headers(self) -> Dict[str, str]:
+        """Return HTTP headers for distributed tracing.
+
+        Returns:
+            Dict[str, str]: Mapping suitable for use as HTTP headers. Includes
+            ``X-Trace-ID`` and ``X-Request-ID`` when present in the current context.
+        """
+        ctx = {**self._logger_fields, **self._temporal_fields}
+        headers: Dict[str, str] = {}
+        if "trace_id" in ctx:
+            headers["X-Trace-ID"] = str(ctx["trace_id"])
+        if "request_id" in ctx:
+            headers["X-Request-ID"] = str(ctx["request_id"])
+        return headers
+
+    def get_current_trace_id(self) -> Optional[str]:
+        """Return the active ``trace_id`` if set, otherwise ``None``."""
+        return ({**self._logger_fields, **self._temporal_fields}).get("trace_id", None)
+
+    def get_current_request_id(self) -> Optional[str]:
+        """Return the active ``request_id`` if set, otherwise ``None``."""
+        return ({**self._logger_fields, **self._temporal_fields}).get("request_id", None)
+
+
+def _rename_exc_to_traceback(_: Any, __: str, event_dict: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalize exception fields to traceback.
+
+    structlog.processors.format_exc_info may place the formatted traceback in
+    exception or exc_info. This processor moves the value into a single
+    canonical traceback key, which simplifies querying in backends such as
+    Grafana/Loki.
+
+    Args:
+        _ (Any): Unused, required by structlog processor signature.
+        __ (str): Unused event name.
+        event_dict (Dict[str, Any]): Event payload to be mutated.
+
+    Returns:
+        Dict[str, Any]: The updated event payload.
+    """
+    if "exception" in event_dict and event_dict["exception"] is not None:
+        event_dict["traceback"] = event_dict.pop("exception")
+    elif "exc_info" in event_dict and event_dict["exc_info"] is not None:
+        event_dict["traceback"] = event_dict.pop("exc_info")
+    return event_dict
+
+
+def configure_global_logging(level: Literal["DEBUG", "INFO"] = "INFO") -> None:
+    """Configure structlog processors only.
+
+    This function is non-invasive: it does not alter root logger handlers. Third-party
+    logging configurations remain untouched. The configured processors control how
+    structlog events are rendered.
+
+    Args:
+        level (Literal["DEBUG", "INFO"]): Rendering level. ``DEBUG`` enables a
+            human-friendly console renderer. ``INFO`` outputs JSON.
+    """
+
+    processors = [
+        structlog.processors.CallsiteParameterAdder(
+            parameters=[
+                structlog.processors.CallsiteParameter.FUNC_NAME,
+                structlog.processors.CallsiteParameter.FILENAME,
+                structlog.processors.CallsiteParameter.LINENO,
+            ]
+        ),
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.format_exc_info,
+        _rename_exc_to_traceback,
+    ]
+
+    match level:
+        case "DEBUG":
+            log_level = logging.DEBUG
+            processors.append(structlog.dev.ConsoleRenderer())
+        case "INFO":
+            log_level = logging.INFO
+            processors.append(structlog.processors.JSONRenderer())
+        case _:
+            raise ValueError(f"Invalid log level: {level}")
+
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(log_level),
+    )
+
+
+def create_logger(name: str, **context: Any) -> LoggerProxy:
+    """Create a structured logger instance.
+
+    Args:
+        name (str): Logger name. Emitted as ``app_name`` and used by stdlib logger.
+        **context (Any): Persistent fields to attach to every log.
+
+    Returns:
+        LoggerProxy: Configured logger instance.
+    """
+    return LoggerProxy(name, **context)

sincpro_log-1.0.0/sincpro_log/use_cases/__init__.py

@@ -0,0 +1 @@
+"""Use cases for sincpro_logger."""